@once-agent/sdk

Automatic Connect: @once-agent/sdk@0.1.13 publishes the tested @once-agent/sdk/connect path for classifying supported agent tools as BYPASS, PROTECT, or fail-closed UNKNOWN, then wiring whole local tool registries with trusted logical identity and effect binding. It also includes direct OpenAI Agents FunctionTool wrapping. See the automatic Connect guide.

Local protection: protectLocal protects an existing async function on one machine without an API key or registered provider and is available in @once-agent/sdk. See the local function guide for its exact safety boundary and a first effect-count check.

Once — AI Agent Execution Safety

MCP idempotency and safe retries for consequential AI agent writes.

Once helps protect supported refunds, bookings, payments and other externally visible side effects from unsafe duplicate execution after ambiguous timeouts, lost responses and retries.

• Website: https://onceexec.com/
• Automatic Connect guide: docs/CONNECT_AUTO.md
• MCP idempotency guide: https://onceexec.com/mcp-idempotency/
• AI agent retry safety: https://onceexec.com/ai-agent-retry-safety/
• TypeScript SDK: @once-agent/sdk@0.1.13
• Python SDK: once-agent-sdk==0.1.1
• MCP package: @once-agent/mcp@0.1.4
• MCP Registry: io.github.stringsofthemind-oss/once

npx -y @once-agent/mcp

If an agent can change external state and may retry after an ambiguous outcome, evaluate Once.

Automatic agent-tool protection

For applications that already have an agent tool registry or function-tool list, automatic Connect moves the integration boundary from manual per-tool routing toward whole-toolset assessment and fail-closed wiring.

import {
  connectLocalAgentToolsetAuto
} from "@once-agent/sdk/connect";

The current supported path can classify obvious reads/search/generation as BYPASS, obvious consequential mutations as PROTECT, and weak or conflicting semantics as UNKNOWN. UNKNOWN is never treated as permission to bypass Once. Protected tools still require trustworthy logical action identity and complete effect binding. Automatic local protection uses durable same-machine SQLite on Node.js 24.15+; it is not a multi-host or universal exactly-once guarantee.

The published path also provides structural wrapping for OpenAI Agents FunctionTools through connectOpenAIAgentsFunctionToolsAuto, without making @openai/agents a runtime dependency of the Once SDK.

Reproduced across frameworks

Different framework. Different retry machinery. Same one-effect invariant.

Once's framework-neutral safety boundary has been exercised against independent execution models and retry mechanisms.

The LangGraph and CrewAI labs also exercise the ambiguous-outcome path:

external effect commits
        ↓
acknowledgement / process is lost
        ↓
provider truth unavailable
        ↓
UNKNOWN
        ↓
execution fails closed
        ↓
provider truth later returns
        ↓
UNKNOWN → CONFIRMED
        ↓
no second external effect

The recovery core used by those experiments is the same framework-neutral implementation under sdk/python/src/once_agent/.

Checkpoint state tells you what the workflow remembers. Reconciliation tells you what reality did.

What this demonstrates

The tested safety boundary preserved the one-effect invariant under the measured framework failure models without requiring the framework itself to stop retrying.

This is not a claim of universal "exactly once" execution. Safe recovery still depends on durable operation identity, durable state, and authoritative provider reconciliation or equivalent downstream guarantees where the outcome is ambiguous.

Framework integrations

• OpenAI Agents — safe retries for consequential tool calls
• Vercel AI SDK — safe retries for consequential tool calls
• LangChain / LangGraph — safe retries for consequential agent tools
• CrewAI — safe retries for consequential agent tools
• Microsoft Agent Framework — safe retries for consequential agent tools
• Agno — hostile-retry evidence

MCP host integrations

• Codex — install the Once execution-safety plugin from this GitHub marketplace
• Claude Code — add Once as a project-scoped MCP server
• Cursor — add Once as a project-scoped MCP server

Codex plugin

Install Once — Execution Safety from the public GitHub marketplace:

codex plugin marketplace add stringsofthemind-oss/once --ref main
codex plugin add once@once-agent

The plugin teaches Codex the Once four-condition routing rule, cross-agent operation identity, read-only assessment-first workflow, and explicit approval boundary before source mutation. It also exposes the pinned local @once-agent/mcp server.

Plugin source: plugins/openai/once

Claude Code plugin

Install Once from the public GitHub marketplace:

claude plugin marketplace add stringsofthemind-oss/once
claude plugin install once@once-agent

This installs the Once Claude Code plugin, which exposes @once-agent/mcp through MCP.

Plugin source: plugins/claude-code/once

[!IMPORTANT]

ONCE is currently in Stripe Sandbox / Test Mode

ONCE billing is currently connected to a Stripe sandbox. No real payment is taken and no real money moves while this beta is running in sandbox mode.

Do not enter real card details.

If Stripe asks for payment details during testing, use:

• Card number: 4242 4242 4242 4242
• Name: John Doe (or any name)
• Expiry: 12/34 (or any future date)
• CVC: 123 (or any 3 digits)
• Postcode / ZIP: any valid-looking value

These are Stripe test credentials only.

ONCE will clearly announce when billing moves from sandbox to live payments.

Make side-effecting AI agent tools safe to retry.

Once helps prevent an AI agent, workflow, or application from accidentally performing the same consequential action twice when the outcome of the first request is uncertain.

Typical examples include:

• payments and refunds
• bookings and reservations
• emails and messages
• account changes
• order creation
• webhook-triggered actions
• other irreversible or externally visible writes

Install

TypeScript / JavaScript:

npm install @once-agent/sdk

Python:

pip install once-agent-sdk

Published packages:

• npm: https://www.npmjs.com/package/@once-agent/sdk
• PyPI: https://pypi.org/project/once-agent-sdk/

The standard TypeScript client requires Node.js 18 or later. Automatic same-machine local protection requires Node.js 24.15+.

Configure

Set your Once API key:

ONCE_API_KEY=your_api_key

Node note: saving ONCE_API_KEY in .env does not make vanilla Node load it automatically. Use your framework/runtime's environment loader, export the variable before starting the process, or on supported Node versions run your application with node --env-file=.env <your-entry-file>.

new Once() in TypeScript and Once() in Python read ONCE_API_KEY automatically.

Do not commit API keys to source control.

60-second quick start

First configure a provider with once setup ., or use a provider alias already registered with your Once account.

TypeScript

import { Once } from "@once-agent/sdk";

async function main() {
  const once = new Once();

  const operationId = Once.id(
    "refund",
    "order_123"
  );

  const result = await once.execute({
    operationId,
    provider: "my-provider",
    action: {
      type: "refund",
      order_id: "123"
    }
  });

  console.log(result.state);
}

main().catch(console.error);

Python

from once_agent import Once

once = Once()
operation_id = Once.id("refund", "order_123")

result = once.execute(
    operation_id=operation_id,
    provider="my-provider",
    action={
        "type": "refund",
        "order_id": "123",
    },
)

print(result["state"])

Replace my-provider with the provider alias configured for your Once account.

The important part: operation ID

For the same logical operation, reuse the same operation ID on every retry.

TypeScript:

const operationId = Once.id(
  "refund",
  "order_123"
);

Python:

operation_id = Once.id("refund", "order_123")

The same supported inputs produce the same deterministic ID in both SDKs.

Different logical operations should use different semantic inputs:

Once.id("refund", "order_123");
Once.id("refund", "order_124");