Once

Once: your agent sent the refund. The response disappeared. Should it try again?

A provider can commit an action before the caller receives its response. Blind retry can refund twice. Once remembers one logical operation, replays confirmed results, and blocks another write while the original outcome is unknown.

See it happen in under five minutes

Node.js 24.15+. No account, API key, or financial transaction. The proof uses the published SDK and a controlled local HTTP provider with its own effect journal.

From this checkout:

npm install --no-save --package-lock=false @once-agent/sdk@0.1.25

node examples/first10/prove.mjs

WITHOUT ONCE: acknowledgement lost; fresh-process retry -> 2 provider writes

CONFIRMED: 1 provider write; restart replay; changed £50 -> £80: CONFLICT, 0 additional writes RETRY BLOCKED — ORIGINAL OUTCOME UNKNOWN The refund may already have succeeded. Once sent no second request. LOST-ACK: 1 provider write; UNKNOWN -> CONFIRMED; recovered refund_1 PASS

Every stage checks the separate provider's HTTP counter against its effect journal. Evidence is retained in the printed directory. This proves the controlled fixture, not a real payment provider. Complete instructions, download path and recording recipe.

Protect one of your own operations

Natural Placement: wrapTool replaces a host-owned async callback. You explicitly own identity and effect fields; no semantic decision is silently inferred.

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

const safeRefund = wrapTool(refundCustomer, { operationId: x => ${x.tenantId}:refund:${x.refundIntentId}, effect: x => ({ tool: "payments:reviewed-account:refund", args: x }), statePath: "./durable/operations.sqlite", reconcile: lookupAuthoritativeRefund, });

The callback and lookup are your reviewed provider functions. Inspect every argument, bind full account/tenant authority and all effect-bearing fields, and exclude Authorization credentials. Route every write through the wrapper. Internal callback retries remain outside the boundary. The lookup returns {status: "CONFIRMED", result} only from authoritative provider truth, otherwise {status: "UNKNOWN"}. If unsupported, omit reconciliation and UNKNOWN remains blocked.

Local SQLite requires a persistent shared file on one machine, Node 24.15+, and distinct IDs for genuine new intents. Multiple legitimate partial refunds need distinct refund-intent IDs. Complete integration guide.

The ledger is part of execution authority. Changing, deleting, replacing, resetting, rolling back or switching valid ledgers may permit an effect to execute again. The same filesystem path does not prove the same history. Fresh provisioning is separate from restart; preserve the original consistent SQLite state and do not reinitialize missing expected state. UNKNOWN blocking does not repair lost history. See MCP compatibility and continuity.

When you need Once — and when you do not

Evaluate Once when a consequential external write may be retried, its outcome can become ambiguous, and another effect would matter. Refunds, bookings, messages and tickets are examples, not automatic provider support.

If a provider idempotency key completely solves your operation, use it. If a Postgres unique constraint completely solves it, use it. If repetition is harmless, you probably do not need Once. Keep native idempotency even with Once. Once does not replace your database, framework, queue, or Temporal and does not promise universal exactly-once execution.

UNKNOWN is protection: the original action may have succeeded. Retain its identity and durable state; perform an authoritative read-only lookup. Never mint a new ID or bypass Once to force progress. Even an absence observation does not automatically permit local redispatch.

LangGraph checkpoint replay evidence

Deterministic local LangGraph JS checkpoint replay resumed the same checkpoint twice while the first tool call was still running. The unprotected path produced 2 provider effects; the Once-protected path produced 1, counted from a separate loopback HTTP provider's append-only log using published SDK 0.1.25.

Limits: this is not a LangGraph Cloud reproduction or a test of the reported ~180s sweeper. Protection used one persistent shared same-machine SQLite authority; separate ephemeral Cloud ledgers are outside this evidence. No universal exactly-once claim or Cloud bug fix is established.

Run and inspect the reproduction · Merged proof PR #295 · Volunteer for one bounded Cloud test. Independent Cloud evidence is still sought; a local fixture PASS is not adoption.

Find a candidate

SDK 0.1.25 includes read-only once check [directory] and once prove for the controlled refund fixture. Run npx --yes --package=@once-agent/sdk@0.1.25 once prove for the one-command proof. once doctor remains the detailed assessment path. Scan and installation do not activate protection; the fixture never executes your code.

Website · Quickstart · Evidence · FIRST 10 plan and ledger

Deeper semantics, integrations, architecture and historical evidence

@once-agent/sdk

Natural Placement (introduced in SDK 0.1.24): wrapTool(callback, semantics) protects a

host-owned tool callback using the existing local safety engine. Supply stable

logical identity, complete effect/account binding and authoritative reconciliation.

Requires Node.js 24.15+ and one durable same-machine SQLite authority; UNKNOWN

blocks redispatch. Opaque callback retries and connector-only model access remain

outside this boundary. See the integration examples.

Automatic Connect: @once-agent/sdk@0.1.25 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.

Start here: Run the ungated retry simulation or

verify your first protected action locally.

The simulation does not execute the SDK; the local guide uses the installed SDK

and a controlled fake provider, including fresh-process and UNKNOWN checks.

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.25
• Python SDK: once-agent-sdk==0.1.1
• MCP package: @once-agent/mcp@0.2.1

Existing OpenAI/Claude plugin launchers remain pinned to their previously reviewed MCP 0.1.5. This MCP release does not release a new plugin or enable the private experimental GitHub adapter.

• 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 integrati