The contract

The first contract is background execution: acknowledgement follows durable admission, execution does not belong to the request handler, and clients recover authoritative state by durable ID or a scope-bound cursor.

Admit durable work

POST /v1/invocations
{
  "agent_key": "support-triage",                 // Account-wide identity only
  "tenant_key": "customer-482",                  // optional Session partition
  "session_key": "thread-8813",                  // yours; resolved or created
  "idempotency_key": "thread-8813:message-7",    // safe retry identity
  "input": "why was I charged twice?",
  "spec": {
    "instructions": "You are a billing support agent…",
    "model": { "provider": "anthropic", "id": "claude-sonnet-5" }
  }
}

202 Accepted
{
  "agent_id": "agnt_…",
  "session_id": "sesn_…",
  "invocation_id": "invk_…",
  "status": "queued",
  "deduplicated": false,
  "deadline_at": "2026-07-23T16:30:00Z"
}

Acknowledgement follows durable admission. Keep the same idempotency_key and request after an uncertain response — a safe retry is deduplicated, never double-run.

Read the authoritative result

The answer is one read away:

GET /v1/invocations/{invocation_id}/result

It returns the authoritative Invocation, the turn's canonical messages, and the assistant text as one output_text string.

Stream the same Invocation

The same POST streams one Invocation when the client sends Accept: text/event-stream. output_text.delta previews are id-less, while durable invocation.update and invocation.result frames carry resume cursors. A Session SSE stream exposes the same vocabulary across turns. Disconnecting either stream never affects execution.

Control and recovery

Hosts can bound or idempotently cancel accepted work; Postgres decides the terminal winner. If an execution owner is lost, the same Invocation is requeued and continues from its last validated checkpoint.

• A host tool parks an Invocation without holding compute; the host recovers the pending call by ID, submits its result idempotently, and lets any engine continue it.
• A callback tool instead lets nvoken deliver the same durable call to a public host HTTPS endpoint with a stable ToolCall idempotency key and a versioned HMAC signature.

Payment binding

Each Invocation binds its model provider to one explicit payment and credential source: caller-ephemeral, reusable Account BYOK, tenant BYOK, or a platform-funded key; self-hosted installations retain installation BYOK as the default. The binding is durable for recovery, encrypted when it contains secret material, rechecked before every provider call, and never falls through to a different payer when unavailable.

The exact surface is in openapi/runtime.yaml.