A durable host owes every accepted submission a terminal outcome. Your application must make
pending work visible, authorize operator actions, and keep recovery running. Route each Thread
to one owner process; storage does not coordinate multiple workers competing for that Thread.
Put the host behind authenticated ingress. Receipts, Thread IDs, principal strings, and audit
authors identify work; they grant no access. Yielded Agent does not supply tenant authentication
or automatic row-level tenant isolation.
Authorize admission before submit. Install OperationAuthorizer when constructing the runtime
for observation, settlement waits, abort, resolution, and administrative operations. Its default
trusts service holders. Direct store reads bypass that boundary, so keep raw stores and RPCs
inside the trusted host. Use tenant-qualified addresses or separate storage domains consistently.
RunToolAuthorization separately protects application tool
execution. Approval and subagent grants do not replace current resource authorization.
Durable Agent Runtime coordinator (deployment class DN; D1/D2). It coordinates the
SubmissionLedger, ThreadStore, and WakeScheduler ports so that once submit returns a
Receipt, the Submission settles exactly once (DUR-001/DUR-002) while every external effect
remains at-least-once (DUR-003) — this runtime never claims exactly-once side effects.
Construction requires work discovery, streaming verification, worker-capacity reads and
peer-message counts; a missing port fails with ThreadStoreError before exposing the runtime.
Prompt checkpoints and fresh-admission accelerators remain optional.
submit(agent, input, options) — durable admission → Thread materialization →
ThreadCreated → readiness → Receipt, with failpoints between the steps; a retry with
the same (thread, principal, idempotencyKey) resumes and returns the same Receipt.
awaitSettlement(receipt) — authorized once before the first ledger read, for the lifetime
of this wait; interrupting it detaches the caller only and never cancels accepted work.
observe(receipt, {after}) — canonical record observation from a stored offset.
abort(command) — authorized before ledger access; durable idempotent abort intent; inactive work settles aborted through
recovery, an active worker makes the command canonical before interrupting its Run (§13),
settled work fails with SettlementConflict (DUR-012). A joined Submission fails with a
typed JoinedToHost conflict carrying the host identity — it settles with its host, so the
abort target is the host; aborting a joining Submission records the intent, honored only
if the host has not consumed the input (revert-then-abort, plan §2.5).
resolveUnknown(command) — the authorized DUR-017 resolution path for Unknown Outcomes:
the durable intent is idempotent per (submission, tool call) and conflicts typed on
divergence; the canonical resolution records are applied by recovery or the next Attempt,
and the lane wakes once every marked call is covered.
resolveApproval(command) — the durable approval decision path (plan §2.6): the intent is
idempotent per (submission, tool call) with a typed ApprovalConflict on divergence; once
every pending call of the suspension reason is decided the lane wakes
(suspended → input-applied) and the next Attempt resumes the declared batch without model
re-invocation, appending the canonical ToolApprovalDecided before honoring the decision.
processThread(agent, threadId) — drain one lane: fenced FIFO-head claims,
canonical input apply, split response/results Turn commits (plan §2.1),
reconcile-then-mark for open ordinary Tool Calls (DUR-009, never an automatic replay),
declared-batch resume without model re-invocation (§15), and terminalization. An active
host Run claims the contiguous ready prefix of later queued Submissions at every safe Turn
seam (Joining/Joined, plan §2.5): the queued input becomes canonical (input:{sid}) before
the next model request, reattaches through the prompt-coverage rule after a crash, and the
joined Submissions settle with the host outcome (DUR-002/DUR-016).
processThreadResolved(threadId) / runResolvedWorker — drain or continuously process
lanes using registrations owned by the runtime Layer: each stable agentId selects
one current Binding. Unfinished operation contracts gate handler execution independently
of immutable admission evidence; missing bindings release the claim with a typed refusal.
discoverWork() / discoverWorkThreads() — enumerate native metadata without granting
execution authority. Missing or incomplete indexes fail explicitly; rebuildWorkIndex()
reconstructs them in bounded, resumable pages independently of ordinary recovery.
runRecovery() — repair at most 32 native owners per pass, returning a cursor for remaining
work. Follow that cursor to finish the sweep. Selected admissions use classifyRecovery;
ready input and model work remain deferred for a fenced worker claim. Terminal Runs can
retain factual tool closures, frozen deliveries, child accounting and worker acknowledgements.
These repairs use original evidence and never invoke a Tool handler or reopen a settled Run.
explain/explainThread, verify, retry, wake, scanObligations — the P7
administrative operations (plan §3) over the same two ports, identical on DN and DC.
explain and verify are strictly read-only; retry re-drives exactly one classified
repair with mandatory author/reason audit and typed refusals; scanObligations is the
scan-based DUR-017/OPS-001 obligation surface. Every one of them (plus observe,
resolveUnknown, resolveApproval) consults the OperationAuthorizer reference
fail-closed — the default Layer preserves the service-possession behavior, and a
host-supplied authorizer turns denials into the typed OperationDenied.
Provides a way to write effectful code using generator functions, simplifying
control flow and error handling.
When to use
Use when you want to write effectful code that looks and behaves like
synchronous code, while still handling asynchronous tasks, errors, and complex
control flow such as loops and conditions.
Generator functions work similarly to async/await but keep errors,
requirements, and interruption in the Effect type. You can yield* values
from effects and return the final result at the end.
Durable Agent Runtime coordinator (deployment class DN; D1/D2). It coordinates the
SubmissionLedger, ThreadStore, and WakeScheduler ports so that once submit returns a
Receipt, the Submission settles exactly once (DUR-001/DUR-002) while every external effect
remains at-least-once (DUR-003) — this runtime never claims exactly-once side effects.
Construction requires work discovery, streaming verification, worker-capacity reads and
peer-message counts; a missing port fails with ThreadStoreError before exposing the runtime.
Prompt checkpoints and fresh-admission accelerators remain optional.
submit(agent, input, options) — durable admission → Thread materialization →
ThreadCreated → readiness → Receipt, with failpoints between the steps; a retry with
the same (thread, principal, idempotencyKey) resumes and returns the same Receipt.
awaitSettlement(receipt) — authorized once before the first ledger read, for the lifetime
of this wait; interrupting it detaches the caller only and never cancels accepted work.
observe(receipt, {after}) — canonical record observation from a stored offset.
abort(command) — authorized before ledger access; durable idempotent abort intent; inactive work settles aborted through
recovery, an active worker makes the command canonical before interrupting its Run (§13),
settled work fails with SettlementConflict (DUR-012). A joined Submission fails with a
typed JoinedToHost conflict carrying the host identity — it settles with its host, so the
abort target is the host; aborting a joining Submission records the intent, honored only
if the host has not consumed the input (revert-then-abort, plan §2.5).
resolveUnknown(command) — the authorized DUR-017 resolution path for Unknown Outcomes:
the durable intent is idempotent per (submission, tool call) and conflicts typed on
divergence; the canonical resolution records are applied by recovery or the next Attempt,
and the lane wakes once every marked call is covered.
resolveApproval(command) — the durable approval decision path (plan §2.6): the intent is
idempotent per (submission, tool call) with a typed ApprovalConflict on divergence; once
every pending call of the suspension reason is decided the lane wakes
(suspended → input-applied) and the next Attempt resumes the declared batch without model
re-invocation, appending the canonical ToolApprovalDecided before honoring the decision.
processThread(agent, threadId) — drain one lane: fenced FIFO-head claims,
canonical input apply, split response/results Turn commits (plan §2.1),
reconcile-then-mark for open ordinary Tool Calls (DUR-009, never an automatic replay),
declared-batch resume without model re-invocation (§15), and terminalization. An active
host Run claims the contiguous ready prefix of later queued Submissions at every safe Turn
seam (Joining/Joined, plan §2.5): the queued input becomes canonical (input:{sid}) before
the next model request, reattaches through the prompt-coverage rule after a crash, and the
joined Submissions settle with the host outcome (DUR-002/DUR-016).
processThreadResolved(threadId) / runResolvedWorker — drain or continuously process
lanes using registrations owned by the runtime Layer: each stable agentId selects
one current Binding. Unfinished operation contracts gate handler execution independently
of immutable admission evidence; missing bindings release the claim with a typed refusal.
discoverWork() / discoverWorkThreads() — enumerate native metadata without granting
execution authority. Missing or incomplete indexes fail explicitly; rebuildWorkIndex()
reconstructs them in bounded, resumable pages independently of ordinary recovery.
runRecovery() — repair at most 32 native owners per pass, returning a cursor for remaining
work. Follow that cursor to finish the sweep. Selected admissions use classifyRecovery;
ready input and model work remain deferred for a fenced worker claim. Terminal Runs can
retain factual tool closures, frozen deliveries, child accounting and worker acknowledgements.
These repairs use original evidence and never invoke a Tool handler or reopen a settled Run.
explain/explainThread, verify, retry, wake, scanObligations — the P7
administrative operations (plan §3) over the same two ports, identical on DN and DC.
explain and verify are strictly read-only; retry re-drives exactly one classified
repair with mandatory author/reason audit and typed refusals; scanObligations is the
scan-based DUR-017/OPS-001 obligation surface. Every one of them (plus observe,
resolveUnknown, resolveApproval) consults the OperationAuthorizer reference
fail-closed — the default Layer preserves the service-possession behavior, and a
host-supplied authorizer turns denials into the typed OperationDenied.
Decodes a typed input (the schema's Encoded type) against a schema
synchronously, returning the decoded value or throwing a
SchemaError
for schema mismatches.
When to use
Use when you already have input typed as the schema's Encoded type and
want schema mismatches to throw SchemaError synchronously.
Details
For unknown input use decodeUnknownSync.
Only service-free schemas can be decoded synchronously. Options may be
provided either when creating the decoder or when applying it; application
options override creation options.
Gotchas
Non-schema failures may throw a runtime failure instead of SchemaError.
@see ― SchemaParser.decodeSync for the adapter that throws an Error whose cause is SchemaIssue.Issue
Identity shared by runs that participate in one thread history.
ThreadId)("support-42"));
});
Run this through the application’s existing host Layer. explain(submissionId) narrows the view
to one submission. An explanation identifies the recovery decision and what an operator can do.
Operation
Use
verify
Check retained history and active execution checkpoints
scanObligations
Find aging or blocked accepted work
retry
Reapply recovery after fixing a recoverable problem
wake
Send a droppable hint that work may be ready
Verification checks schema, identity, order, and original context consistency. It is not tamper
evidence or proof of discarded checkpoint revisions. A Run’s current continuation is mutable
operational state and is deleted at settlement; unresolved operations retain their own evidence.
Schedule scanObligations from your monitoring service or host alarm. Watch Unknown outcomes,
approval waits, waiting children, and aging ready/running work. The library does not send alerts
for you. Generic retry refuses work awaiting approval or Unknown resolution; use their specific
authorized operations.
An ordinary mutating call with an uncertain outcome is not blindly replayed. Inspect the external
system and use resolveUnknown to record the appropriate evidence and decision. Explicit Unknown
remains unresolved until that resolution is processed; readonly or idempotent recovery rules do
not erase it.
abort ends the submission’s execution obligation without proving whether an external effect
happened. Preserve unresolved evidence after abort. A safe-to-retry decision is permission to
proceed, not proof that a previous effect never occurred.
observe(receipt) follows canonical records and can resume from an observation offset;
awaitSettlement(receipt) waits for the terminal outcome. Disconnecting either observer does not
cancel accepted work. Retain the receipt and reconnect. Use a persisted abort command when
cancellation is intended.
Take a file-consistent SQLite backup through the owning host connection or while the host is
stopped. Stop the original owner before serving a restored copy. Keep exports idle and the source
quiescent until every page is captured; import into an empty destination Thread.
After restore, reconcile effects and receipts created after the backup. Restoring data cannot undo
external writes. Run verification before reopening admission. Apply the same caution to Cloudflare
point-in-time restoration and cross-Object work.
Schedules and event subscriptions retain delivery obligations separately from Agent execution.
A retained event or message is not a submission receipt, and a receipt does not prove processing.
Inspect parked deliveries and preserve their original idempotency keys when retrying.
Custom hosts provide PreparedInputAdmission for schedules, subscriptions, and worker messages.
Schedule and subscription limits count active or pending work, including paused registrations,
parked deliveries and settlement observation. Settled history does not consume these slots.