Skip to content

Deploy and operate

Operations

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.

Start with a read-only explanation:

import {
class DurableAgentRuntime

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.

DurableAgentRuntime
} from "@yielded/agent/durable-agent-runtime";
import {
type ThreadId = string & Brand<"@effect-agent/core/ThreadId">
const ThreadId: Schema.brand<Schema.NonEmptyString, "@effect-agent/core/ThreadId">

Identity shared by runs that participate in one thread history.

ThreadId
} from "@yielded/agent/identifiers";
import {
import Effect
Effect
,
import Schema
Schema
} from "effect";
const
const inspect: Effect.Effect<readonly RecoveryExplanation[], DurableExplainFailure, DurableAgentRuntime>
inspect
=
import Effect
Effect
.
const gen: <Effect.Effect<readonly RecoveryExplanation[], DurableExplainFailure, never> | Effect.Effect<{
readonly bindingRegistryKey: string;
readonly workerHost: (request: {
readonly sourceThreadId: ThreadId;
readonly principal: Principal;
readonly sourceSubmissionId?: SubmissionId;
}) => Effect.Effect<SubagentHost["Service"], WorkerError>;
... 28 more ...;
readonly recoverWork: (request: WorkRecoveryRequest) => Effect.Effect<WorkRecoveryReport, DurableWorkerFailure>;
}, never, DurableAgentRuntime>, readonly RecoveryExplanation[]>(f: () => Generator<...>) => Effect.Effect<...> (+1 overload)

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.

Example (Sequencing effects with generators)

import { Data, Effect } from "effect"
class DiscountRateError extends Data.TaggedError("DiscountRateError")<{}> {}
const addServiceCharge = (amount: number) => amount + 1
const applyDiscount = (
total: number,
discountRate: number
): Effect.Effect<number, DiscountRateError> =>
discountRate === 0
? Effect.fail(new DiscountRateError())
: Effect.succeed(total - (total * discountRate) / 100)
const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))
const fetchDiscountRate = Effect.promise(() => Promise.resolve(5))
export const program = Effect.gen(function*() {
const transactionAmount = yield* fetchTransactionAmount
const discountRate = yield* fetchDiscountRate
const discountedAmount = yield* applyDiscount(
transactionAmount,
discountRate
)
const finalAmount = addServiceCharge(discountedAmount)
return `Final amount to charge: ${finalAmount}`
})
await Effect.runPromise(program) // => "Final amount to charge: 96"

@stability ― stable

@category ― constructors

@since ― 2.0.0

gen
(function* () {
const
const runtime: {
readonly bindingRegistryKey: string;
readonly workerHost: (request: {
readonly sourceThreadId: ThreadId;
readonly principal: Principal;
readonly sourceSubmissionId?: SubmissionId;
}) => Effect.Effect<SubagentHost["Service"], WorkerError>;
readonly messagingHost: (request: {
readonly sourceThreadId: ThreadId;
readonly principal: Principal;
}) => Effect.Effect<MessagingHost["Service"], MessagingError>;
... 27 more ...;
readonly recoverWork: (request: WorkRecoveryRequest) => Effect.Effect<WorkRecoveryReport, DurableWorkerFailure>;
}
runtime
= yield*
class DurableAgentRuntime

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.

DurableAgentRuntime
;
return yield*
const runtime: {
readonly bindingRegistryKey: string;
readonly workerHost: (request: {
readonly sourceThreadId: ThreadId;
readonly principal: Principal;
readonly sourceSubmissionId?: SubmissionId;
}) => Effect.Effect<SubagentHost["Service"], WorkerError>;
readonly messagingHost: (request: {
readonly sourceThreadId: ThreadId;
readonly principal: Principal;
}) => Effect.Effect<MessagingHost["Service"], MessagingError>;
... 27 more ...;
readonly recoverWork: (request: WorkRecoveryRequest) => Effect.Effect<WorkRecoveryReport, DurableWorkerFailure>;
}
runtime
.
explainThread: (threadId: ThreadId) => Effect.Effect<ReadonlyArray<RecoveryExplanation>, DurableExplainFailure>

explain for every nonterminal lane member of one Thread, in queue order.

explainThread
(
import Schema
Schema
.
const decodeSync: <Schema.brand<Schema.NonEmptyString, "@effect-agent/core/ThreadId">>(schema: Schema.brand<Schema.NonEmptyString, "@effect-agent/core/ThreadId">, options?: ParseOptions) => (input: string, options?: ParseOptions) => string & Brand<"@effect-agent/core/ThreadId">

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

@stability ― stable

@category ― decoding

@since ― 4.0.0

decodeSync
(
const ThreadId: Schema.brand<Schema.NonEmptyString, "@effect-agent/core/ThreadId">

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.

Use the Node scheduling example for runnable setup, and messaging for retained-send semantics.