OnceGate

Safe retries for irreversible AI-agent actions.

OnceGate is a durable safety interlock for agents that are about to send money, message a customer, book travel, deploy software, command a device, or perform another side effect. Before acting, an agent asks OnceGate whether this stable business operation may execute, must wait, has already completed, conflicts with earlier intent, or requires reconciliation.

Live service · 90-second hosted SkillMD · API docs · OpenAPI · Readiness · Source · Verified NANDA registry record

PostgreSQL concurrency proof: 20 simultaneous matching claims produce exactly 1 EXECUTE and 19 IN_PROGRESS decisions. After success, 20 matching retries return REPLAY with the same immutable result.

OnceGate grants at most one active execution permission per stable business key and fails closed when the downstream outcome is uncertain. It does not make an arbitrary downstream API literally exactly-once.

Judge it in 90 seconds

No signup, API key, SDK, repository checkout, or external provider is required.

1. Give a clean stock agent only this URL:

   https://oncegate.vercel.app/skill.md
   

2. Give it this task:

   Using only this SkillMD, demonstrate a harmless OnceGate operation. Prove that an active retry cannot execute twice and that a completed retry returns the stored result. Perform no real external side effect.

3. The hosted SkillMD guides the agent through one synthetic operation with one stable key. The deterministic pass oracle is:

   READY → EXECUTE → IN_PROGRESS → SUCCEEDED → REPLAY → USE_STORED_RESULT
   

The evaluator path constructs only a local simulated provider reference. It never calls a payment, messaging, booking, deployment, device, refund, customer, or other downstream provider. The execution token stays private and is discarded after resolution.

A safe read-only check is available immediately:

curl --no-location https://oncegate.vercel.app/readyz

{"status":"ok","database":"reachable","version":"1.0.0"}

NandaHack Phase 2 fit

The official Phase 2 rubric scores usefulness, creativity, ease of setup, and whether a stock agent succeeds using only SKILL.md.

Criterion	OnceGate evidence
Useful	Prevents concurrent retries from receiving duplicate execution permission and fails closed when the downstream result is uncertain.
Creative	Applies one provider-independent permission, resolution, replay, conflict, and ambiguity protocol across otherwise unrelated agent tools.
Easy to set up	The evaluator uses an anonymous public HTTPS API with no account, key, SDK, clone, or real provider action.
Skill-only success	The hosted SkillMD contains exact wire requests, expected decisions, token-safety rules, a real historical transcript, numbered instructions, and a deterministic pass oracle.

OnceGate is a service for agents, not another agent and not a wrapper around one specific provider.

Why agents need it

Agents retry after timeouts, crashes, and lost responses. Blindly repeating an irreversible call can create a second payment, booking, email, deployment, refund, or physical command. Downstream APIs expose inconsistent idempotency mechanisms, and a timeout still cannot prove what the provider did.

OnceGate gives every retry the same five-decision protocol:

Decision	Required agent behavior
EXECUTE	Perform the external action once, then resolve this attempt.
IN_PROGRESS	Do not act; another execution permission is active.
REPLAY	Do not act; use the stored successful result.
CONFLICT	Do not act; the stable key represents different action or intent.
AMBIGUOUS	Do not act; reconcile the provider outcome or ask a human.

Only EXECUTE authorizes an action. OnceGate itself never invokes the downstream provider.

Proof, not promises

The current release passes 98 automated tests, including six real PostgreSQL concurrency tests.

Property	Reproducible evidence
One active permission	PostgreSQL concurrency tests and 20-way demo
Replay, conflict, expiry, and ambiguity	State-machine tests and evaluation plan
Strict public contract and stable errors	API tests and API contract
Canonical SHA-256 intent fingerprints	Canonicalization tests
Durable schema and restart persistence	Migration tests
Evaluator-first instructions, token safety, and byte-identical SkillMD copies	SkillMD tests

The concurrency demo uses independent HTTP requests and randomized harmless data. It performs zero real external side effects and never prints execution tokens.

How it works

Agent ── anonymous HTTPS ──> Vercel
                              ├── /skill.md → static public/skill.md
                              └── FastAPI Python Function (iad1)
                                           │
                                           ▼
                                    Neon PostgreSQL

PostgreSQL is the sole coordination authority. A unique (scope, idempotency_key) constraint elects the operation; transactions and row locks serialize claims and resolutions; a partial unique index permits at most one active attempt. Vercel function memory, warm instances, and local files are never authoritative.

Execution tokens are returned only to the one EXECUTE caller, stored only as 32-byte SHA-256 digests, and excluded from inspection responses and logs.

Read the full architecture and product requirements.

Public interface

Base URL: https://oncegate.vercel.app

Method	Path	Purpose
GET	/	Service manifest and canonical links
POST	/v1/operations/claim	Request EXECUTE, IN_PROGRESS, REPLAY, CONFLICT, or AMBIGUOUS
POST	/v1/operations/{operation_id}/resolve	Record SUCCEEDED, NOT_EXECUTED, or UNKNOWN using the private token
GET	/v1/operations/{operation_id}	Inspect durable state without granting permission
GET	/healthz	Function liveness without a database query
GET	/readyz	PostgreSQL readiness
GET	/docs	Interactive FastAPI documentation
GET	/openapi.json	Machine-readable API contract
GET	/skill.md	Static agent instructions

The complete request, response, validation, size, cache, and error contract is in docs/API.md.

Local development

Requirements:

• macOS or Linux
• Python 3.12
• uv
• PostgreSQL 14 or newer

Install the locked project dependencies and create isolated databases:

uv sync --locked --all-groups
createdb oncegate_dev
createdb oncegate_test

Copy .env.example to .env only for local use. Never commit .env or a database URL.

Apply the schema:

DATABASE_URL_UNPOOLED='postgresql+psycopg:///oncegate_dev' \
  uv run alembic upgrade head

Start the local API:

DATABASE_URL='postgresql+psycopg:///oncegate_dev' \
PUBLIC_BASE_URL='http://127.0.0.1:8000' \
  uv run uvicorn src.oncegate.main:app --host 127.0.0.1 --port 8000

Then inspect the local service:

curl -fsS http://127.0.0.1:8000/healthz
curl -fsS http://127.0.0.1:8000/readyz
open http://127.0.0.1:8000/docs

Vercel, not FastAPI, serves /skill.md from public/skill.md.

Local verification

Run the locked quality gate:

DATABASE_URL_UNPOOLED='postgresql+psycopg:///oncegate_dev' \
  uv run alembic check
uv run ruff format --check .
uv run ruff check .
uv run mypy src tests scripts app.py
ONCEGATE_TEST_DATABASE_URL='postgresql+psycopg:///oncegate_test' \
  uv run pytest -q
ONCEGATE_TEST_DATABASE_URL='postgresql+psycopg:///oncegate_test' \
  uv run pytest -q -s tests/test_concurrency_postgres.py
git diff --check

Run the harmless concurrency demonstration against a disposable local environment:

uv run python scripts/concurrency_demo.py \
  --base-url http://127.0.0.1:8000 \
  --claims 20

SkillMD and production delivery

SKILL.template.md is the source of truth. SKILL.md and public/skill.md must remain byte-for-byte identical, while Vercel serves the public copy as a static Markdown asset.

The tracked generator captures a real harmless operation and therefore creates one public database record. Run it only with explicit public-write approval; it retains the execution token in memory, resolves immediately, redacts the token, validates transcript consistency, and refuses unsafe output.

Production is deployed from main through Vercel's Git integration. The service runs as one Fluid Compute FastAPI function in iad1; runtime traffic uses a pooled Neon PostgreSQL connection. Database migrations remain explicit release actions and never run during import, build, or invocation.

Security and limitations

• The public hackathon service has no tenant authentication. Use harmless demo data only.
• Never put passwords, API tokens, card data, or unnecessary personal information in keys, intent, or result objects.
• OnceGate grants execution permission but never performs the downstream action.
• An expired or explicitly uncertain attempt becomes AMBIGUOUS; it never silently grants another permission.
• Downstream reconciliation or human review remains necessary when the provider outcome is unknown.
• OnceGate does not provide literal exactly-once execution across arbitrary external systems.

Repository map

app.py                  Vercel ASGI entrypoint
src/oncegate/           FastAPI, validation, and transactional service
migrations/             Alembic schema
tests/                  API, state, migration, SkillMD, and concurrency tests
scripts/                Safe smoke, concurrency, and generation tools
SKILL.template.md       Agent-instruction source template
SKILL.md                Repository agent instructions
public/skill.md         Byte-identical static Vercel copy
docs/                   Product, API, architecture, and evaluation references

Built by Raj Patil for NandaHack 2026.