Agent application runtime

Maturity: evolving. This surface is still finding its shape and may be redefined in any minor release — always with a ### ⚠️ Breaking changes entry and a migration section, never silently. If your application already owns the conversation loop, mountAgent from stitchkit/tools is the stable path.

stitchkit/agent-runtime is the server-only, opinionated layer above mountAgent. Use it when the application wants Stitchkit to own conversation mechanics: durable acceptance, history projection, the AI SDK stream loop, checkpoints, keyed interruption, terminal commit and stable application events.

If the application already owns that loop, continue importing mountAgent from stitchkit/tools. stitchkit/tools does not depend on this entrypoint at all; this entrypoint uses the tool executor from it, but pulls no MCP peer, so choosing mountAgent alone costs you nothing from here.

UI and shared DTO code must import canonical records and delivery validation from stitchkit/agent-runtime/browser, not from the server runtime barrel:

import {
  AgentRunSchema,
  AgentRuntimeEventSchema,
  advanceAgentRuntimeEventCursor,
} from 'stitchkit/agent-runtime/browser'

This browser-safe entrypoint re-exports the same schemas and inferred types used by the runtime. It intentionally excludes model construction, execution, persistence, event sinks and every Node context dependency.

Install

bun add stitchkit ai zod

mountAgent from stitchkit/tools — used in the composition below — additionally needs the MCP peer, which that entrypoint imports statically:

bun add @modelcontextprotocol/server

OpenRouter is isolated so other runtime users do not resolve its package:

bun add @openrouter/ai-sdk-provider

Minimal composition

import { z } from 'zod'
import {
  AgentContextOverflowError,
  composeAgentPrompt,
  createAgentRuntime,
  createMemoryAgentRuntimeStore,
  defineAgentProtocol,
  defineModelRegistry,
} from 'stitchkit/agent-runtime'
import { openRouterProvider } from 'stitchkit/agent-runtime/openrouter'
import { composeToolLifecycle, mountAgent } from 'stitchkit/tools'

const protocol = defineAgentProtocol({
  context: z.object({ userId: z.string() }),
  inputMetadata: z.object({}),
})

const models = defineModelRegistry({
  providers: {
    openrouter: openRouterProvider({ apiKey: env.OPENROUTER_API_KEY }),
  },
  models: {
    fast: {
      provider: 'openrouter',
      modelId: 'provider/model',
      contextWindow: 128_000,
      capabilities: ['tools'],
    },
  },
})

const prompt = composeAgentPrompt<{ userId: string }>([
  {
    name: 'product',
    stability: 'stable',
    render: ({ context }) => `Help user ${context.userId}.`,
  },
])

const runtime = createAgentRuntime({
  protocol,
  store: createMemoryAgentRuntimeStore(),
  models: {
    preflight: () => models.preflight('fast', ['tools']),
    resolve: () => models.resolve('fast', ['tools']),
  },
  prompt: ({ context, signal, model }) =>
    prompt({
      context,
      signal,
      budget: {
        contextWindow: model.descriptor.contextWindow,
        reservedOutput: 8_000,
        toolSchemas: { provenance: 'unavailable' },
        attachments: { value: 0, provenance: 'measured' },
        providerOverhead: { provenance: 'unavailable' },
      },
    }),
  tools: ({ context, toolFenceLifecycle }) =>
    mountAgent(service, {
      context,
      lifecycle: composeToolLifecycle(authLifecycle, toolFenceLifecycle),
    }),
  runs: { inputPolicy: 'interrupt', coalescePending: true },
  loop: {
    idleTimeoutMs: 60_000,
    prepareStep: ({ context, steps }) => ({
      activeTools: steps.some((step) => step.toolCalls.length > 0)
        ? ['lookup']
        : ['lookup', 'discover'],
      instructions: `Current account: ${context.userId}`,
    }),
    stopPolicies: [
      {
        name: 'repeated-tool-error',
        when: ({ steps }) => hasRepeatedToolError(steps),
      },
    ],
  },
})

const ticket = runtime.submit({
  conversationId: 'conversation-id',
  idempotencyKey: 'request-id',
  context: { userId: 'user-id' },
  parts: [{ type: 'text', text: 'Hello' }],
  recordIds: {
    inputMessageId: 'user-message-id',
    runId: 'run-id',
    assistantMessageId: 'assistant-message-id',
  },
})

const admission = await ticket.admission
await ticket.accepted
const terminal = await ticket.result

Bounded deferred tool catalogs

Use createDeferredAgentToolSurface when a measured large catalog makes sending every schema on every provider step expensive. The controller mounts the complete executable surface in process, but initially advertises only its search tool, explicit alwaysOn tools and bounded policy pins:

import { createDeferredAgentToolSurface } from 'stitchkit/agent-runtime'
import { composeToolLifecycle } from 'stitchkit/tools'

const deferred = createDeferredAgentToolSurface({
  surfaces: {
    member: { services: memberServices, runtimeTools, alwaysOn: ['ask_user'] },
    broadcast: { services: broadcastServices, runtimeTools },
  },
  selectSurface: ({ context }) => context.mode,
  pins: ({ context }) => context.skillTools,
  search: {
    name: 'tool_search',
    maxQueryBytes: 1_024,
    maxResults: 8,
    maxResultBytes: 8_192,
    select: ({ query, manifest }) => rankCatalog(query, manifest),
  },
  activation: {
    maxSelectedTools: 8,
    maxActiveTools: 16,
    maxSchemaBytes: 32_768,
  },
  observe: event => recordDeferredToolEvidence(event),
})

const runtime = createAgentRuntime({
  // protocol, store, models and prompt...
  tools: runContext => deferred.mount(runContext, {
    context: runContext.context,
    lifecycle: composeToolLifecycle(authLifecycle, runContext.toolFenceLifecycle),
  }),
  loop: { prepareStep: deferred.prepareStep(applicationPrepareStep) },
})

The built-in selector deterministically ranks exact name, prefix/token and description matches. A custom async selector returns names only; unknown and duplicate output is removed against the local canonical manifest. Search never executes the selected operation and never returns its schema. A later provider step receives the real selected tools by name, so their direct lifecycle, fencing, hooks, errors and present.agent output remain unchanged.

Selection is a versioned receipt in the ordinary durable tool-result history. The latest valid same-run search replaces the earlier selection; parallel searches in one step merge in call order. Recovery reconstructs it, while a different run or finite surface cannot inherit it. Known inactive calls take a recoverable SEARCH_REQUIRED search round; unknown names still fail.

Every ceiling is required. maxSchemaBytes measures UTF-8 bytes over canonical name, description and presentation schema. It is useful for before/after comparison, but provider serialization and tokenization differ: use existing provider-reported input usage and cost to decide whether the extra search round is beneficial. Controller evidence intentionally omits query text, prompts, arguments and application context. → ADR 0129.

Published headless harness and structured runner

stitchkit/agent-runtime/harness publishes the resource-aware composition over createAgentRuntime. createHeadlessAgentHarness accepts the existing protocol and store, caller-provided model resolution, bounded instruction/skill/resource loading, direct tools and a prompt-budget callback. Resource names are unique; count, UTF-8 bytes and diagnostics are bounded. Invalid resources fail before a provider request. Diagnostics are evidence for the caller: their observer is isolated, and the loader decides whether a reported condition is fatal.

createAgentHarnessFileResources is the optional filesystem implementation. It reads only caller-declared absolute roots, refuses symlinks and reports provenance as rootId:relative/path. Instructions enter the prompt immediately. Skills and ordinary resources enter as bounded name/description summaries; read_resource loads one exact body later as a normal direct typed tool. Custom loaders remain supported unchanged.

Each run may resolve a different provider adapter without changing the harness. The profile-applied observation records the actual AgentModelDescriptor, resource kind/name/ provenance and sorted direct tool names; it intentionally contains no resource text, prompts, arguments or credentials. Observer failure never changes the canonical run outcome.

packages/core/examples/agent-runtime/headless-agent-runner.ts is a reference structured control loop for submit, interrupt, snapshot and bounded close. It starts no process and chooses no framing, authentication or transport. Importing either example has no side effect; an external supervisor owns process placement and restart.

createAgentHarnessControlServer adds transport-neutral correlated requests, shared observers and one exclusive controller lease per conversation. close() on a connection detaches only that client; it never closes the harness. Normal event delivery stays serialized. A bounded slow consumer is detached and receives resync-required through the required synchronous onOverflow callback; that callback closes/aborts the underlying transport, which then reconnects and requests a fresh snapshot. It never writes a second frame concurrently with a blocked deliver. Browser code uses createAgentControlView, reduceAgentControlSnapshot and reduceAgentControlEvent; the reducer owns no renderer and marks a conversation resyncRequired after a transient sequence gap.

Configure loop.toolApproval to use the installed AI SDK approval policy and loop.toolApprovalSecret to sign exact requests. A request is stored on the terminal assistant before any effect. pendingApprovals() derives unresolved requests from canonical messages; respondToApproval() writes one tool-role approval response and queues a successor. The SDK revalidates the signature/tool call/input before the original direct tool reaches its existing fence. Reconnect and SQLite reopen require no promise registry. Remembered policy and a stronger cross-crash exactly-once guarantee remain application concerns.

Approval requests suspend a call; they do not settle its result. History carries exact call and approval identity across assistant/tool records, so an approved result can precede the next signed request in a successor run. Automatic decisions follow the same chronology. Unknown/duplicate responses and results with a different call or tool name are invalid; dropping an invalid active approval input fails the run with a private diagnostic rather than starting a fresh model turn.

stitchkit/agent-runtime/coding-tools returns ordinary direct runtime tools named read_file, write_file, edit_file, list_directory, glob, search_files, run_command and optional read_output. Every call passes a required host authorization callback. An optional async/sync authorizePath({ path }) is the one operation-independent policy for direct file access and discovery: direct read/write/edit refuses a denied path, while listing, glob and search omit it. Denial is recursive on every surface — direct access and discovery base paths ask about . and each ancestor, outermost first, stopping at the first refusal, so denying credentials denies everything under it. The comparison is segment-wise, so it does not deny credentials-backup, and a path of depth N costs N+1 questions. Directory decisions happen before descent; file decisions and search_files.include happen before opening content. Requested paths use /: a backslash is refused rather than normalised, because the workspace walk reads it as a separator and every authorization callback would otherwise be asked about a different decomposition than the one opened. File paths are relative, bounded and contained after descriptor-relative resolution: each ancestor is opened without following symlinks and remains pinned through authorization and the filesystem effect. Reads revalidate the pinned file identity; writes and patches revalidate the pinned parent identity; search and resource discovery descend only through opened directories. Linux traverses /proc/self/fd; macOS uses the package’s architecture-specific Node-API openat backend. Unsupported platforms, including FreeBSD until a real backend is qualified, fail closed. The package needs no install-time compiler or script. Other platforms fail these filesystem operations closed because Node exposes no equivalent portable directory-handle-relative API. Writes/edits reject symlink targets, content is strict UTF-8 and retained bytes are finite. Shell accepts a finite alias mapped by the host to an absolute executable plus an argument array — never a shell command string — and uses only the explicitly supplied environment. Arguments, output and time are bounded, while cancellation terminates the child. The configured root and cwd are path boundaries, not a security sandbox: isolate the process when an executable must not access the rest of the machine. Path admission does not constrain run_command; an executable requires process isolation for that guarantee. → ADR 0172

An absolute path is still refused. When it is inside the canonical workspace root, the refusal includes the exact workspace-relative recoveryPath; an absolute path outside the root has no suggested replacement. Applying the suggestion still passes the same descriptor-relative containment and symlink checks.

edit_file replaces one exact snippet. It inserts newText literally in both single and replaceAll modes, including JavaScript replacement tokens such as $$, $&, $` and $'. oldText is itself the freshness guard for the region it changes, so the digest is the optional expectedSha256 and an edit is one call; pass the digest read_file returned when you want the whole-file guarantee, and read the sha256 it returns to chain the next edit without re-reading. The read, the occurrence count and the construction of the new content all happen inside one per-target lock, so two concurrent edits of different snippets in one file cannot each build a file from the same base and have the second erase the first — the lock is process-local, which covers many agents in one process and not two processes over one workspace. It authorizes the exact replacement count, result digest and byte size, and deliberately does not claim multi-file atomicity.

write_file creates missing parent directories inside the root and names them in createdDirectories; the walk that finds them runs before authorization and reports them in the authorization payload, so no directory is created before a host approves it.

Every ordinary outcome is a refusal a model can act on — a missing file is NOT_FOUND, an existing file without overwrite is CONFLICT, an ambiguous snippet is CONFLICT carrying its occurrence count, a path outside the root is FORBIDDEN, an unknown spilled-output reference is SPILL_REFERENCE_UNKNOWN — each with a hint naming the next move. Host-level causes stay scrubbed to INTERNAL_SERVER_ERROR and name nothing outside the workspace. Every refusal code is a member of STITCH_ERROR_STATUS, so its status survives an envelope that crosses a process boundary and is rebuilt from the wire. → ADR 0139

list_directory marks excluded directories rather than hiding them, and glob reports skippedDirectories beside its matches: an empty result from a tree whose files all live under an excluded directory is not “no files”, and a model told only “nothing found” concludes the wrong thing. search_files takes regex, context lines and an anchored include pattern matched against the whole workspace-relative path. * does not cross /, so files in subdirectories need **/; scannedFiles counts files admitted by both that filter and host authorization. A hint explains the zero only when the filter produced it, rejecting every file the scan reached; an empty tree and a host refusal return the same empty result without blaming the pattern. Regex is bounded by refusing backreferences and lookaround and capping line length rather than by a timeout, because a JavaScript RegExp cannot be interrupted once it starts backtracking. With an optional AgentCodingArtifactStore, shell output beyond the inline preview continues into an opaque bounded artifact and read_output reads slices without exposing a host path. Without a store, the previous finite output-limit behavior is unchanged.

run_command treats every invocation as finite. shellTimeoutMs bounds normal execution and shellTerminationGraceMs bounds settlement after timeout, caller cancellation, output overflow or parent exit. POSIX hosts launch a dedicated process group and kill every descendant remaining in that group; a process that deliberately escapes the group is outside the guarantee. Node’s portable Windows child-process API cannot kill a complete descendant tree without invoking a second host executable, so Windows kills the direct child, destroys retained pipes at the grace deadline and makes no descendant-cleanup claim. A signal already aborted before execution returns cancelled without spawning.

Coding commands compose the shared native execution owner. Artifact retention and UTF-8 previews remain coding-tool policy; normal leader exit still forcibly stops remaining POSIX group members before draining. A structural sandbox launcher uses the same settlement owner with a finite output queue. Sandbox shutdown waits for actual owned completion and surfaces cleanup refusal rather than treating it as successful teardown.

One createAgentHarnessFileResources instance represents one immutable discovery generation: concurrent and repeated load() calls share it, so a direct resource read cannot cross into a new catalog unexpectedly. Discovery uses the same descriptor-anchored traversal as coding search; construct a new loader to refresh after filesystem changes.

Runtime events preserve reasoning/text/tool lifecycle order. Durable admission, checkpoint, run-state and terminal events carry stable identities; transient deltas carry one runtime epoch and monotonic sequence. On a transient gap, reload the canonical snapshot and resume from the durable record instead of persisting deltas as a second history.

Prompt contextWindow budgeting is a pre-request decision over the assembled context. AgentRun.usage is cumulative measured/provider-reported execution evidence across attempts and compaction. They answer different questions and must not be substituted for each other. TTFT and throughput require timestamps from the actual provider stream plus a provider-reported or tokenizer-measured token count; character counts cannot produce exact token or throughput figures.

recordIds is optional. Supply stable application record IDs when an accepted-response transport must return durable placeholders before the run finishes. ticket.admission resolves after the store acceptance CAS and reports the canonical committed input, assigned run, a typed pending assistant projection, compatibility IDs and snapshot version. Those assigned IDs can differ from the proposal when an input coalesces into an existing queued successor. Reuse the same inputMessageId for retries carrying the same idempotency key; input identity is caller-stable, while the receipt reports the run/assistant identities that assignment may change. Await admission first on the immediate accepted-response path. ticket.accepted remains the signal-only compatibility surface and additionally waits for admission publication.

The in-memory store is a reference adapter and has process-local durability only. Production applications normally call createAgentRuntimeStore() and provide one database transaction driver:

const store = createAgentRuntimeStore({
  transaction: (work, options) =>
    options?.access === 'read'
      ? db.readTransaction(tx => work(tx))
      : db.writeTransaction(tx => work(tx)),
  head: {
    load: (tx, conversationId) => loadRuntimeHead(tx, conversationId),
    compareAndSwap: (tx, operation) => casRuntimeHead(tx, operation),
  },
  runs: {
    load: (tx, identity) => loadRun(tx, identity),
    loadByAssistantMessageId: (tx, identity) => loadRunByAssistant(tx, identity),
    loadMany: (tx, identities) => loadRuns(tx, identities),
    listActive: (tx, conversationId) => listActiveRuns(tx, conversationId),
    save: (tx, record) => saveRun(tx, record),
  },
  admissions: {
    load: (tx, identity) => loadAdmission(tx, identity),
    loadByInputMessageId: (tx, identity) => loadAdmissionByInput(tx, identity),
    create: (tx, receipt) => createAdmission(tx, receipt),
  },
  history: {
    load: (tx, conversationId) => loadCanonicalMessages(tx, conversationId),
    apply: (tx, mutation) => applyCanonicalHistoryMutation(tx, mutation),
  },
  scanRecoverable: page => scanRecoverableRuns(page),
})

Prompt budgeting keeps reservation deficits signed. If instructions, reservedOutput, tool schemas, attachments and provider overhead already exceed contextWindow, composeAgentPrompt returns contextDecision: 'oversized' and a negative availableHistoryTokens even when history is empty. A compact policy is returned only when removing history could actually make the prompt fit. Exact equality (including a zero window with zero reservations/history) fits; any unavailable component keeps the decision unavailable.

The same opaque tx reaches head, run, admission and history callbacks. The adapter maps rows and supplies atomicity; Stitchkit owns transition validation and revision arithmetic. The executable reference is examples/agent-store-prisma/adapter.ts. compareAndSwap returns either { outcome: 'applied' } or { outcome: 'conflict', actualVersion }. Decide that outcome by reading the version, comparing it and then writing unconditionally — inside the transaction the adapter supplies, that is atomic. A conditional upsert is the shorter thing to write and it is wrong twice: ON CONFLICT ... WHERE guards the update branch only, so the first write to a conversation applies whatever expectedVersion it was given, and the affected-row count that would report the outcome is the driver’s, which need not be the rows the statement moved. The head contains only schema version, conversation identity and monotonic version. Runs and admission receipts are normalized records; recovery queries active run states directly instead of maintaining a second projection. An admission receipt retains its canonical input, and a terminal run retains its canonical assistant, so physical product-history compaction cannot break idempotent retries.

Built-in SQLite persistence

Use the runtime-specific leaf; the neutral agent runtime never imports either SQLite built-in:

// Bun
import { createBunSqliteAgentRuntimeStore } from 'stitchkit/agent-runtime/sqlite/bun'

const sqlite = createBunSqliteAgentRuntimeStore({ filename: './agent-runtime.sqlite' })
const runtime = createAgentRuntime({ ...config, store: sqlite.store })

await runtime.close()
await sqlite.close()

// Node 22.5+
import { createNodeSqliteAgentRuntimeStore } from 'stitchkit/agent-runtime/sqlite/node'

const sqlite = createNodeSqliteAgentRuntimeStore({ filename: './agent-runtime.sqlite' })

Initialization creates only stitchkit_agent_runtime_* tables and records schema version 2 in stitchkit_agent_runtime_meta; it does not use PRAGMA user_version or mutate application tables. An unknown schema version or unversioned partial Stitchkit schema is refused. The connection is owned by the returned handle and closes only after accepted operations drain.

Each handle serializes its transactions. Separate connections use busy_timeout = 0: a competing synchronous writer fails promptly with SQLite’s lock error, so an awaited transaction can resume and commit or roll back. Retry that explicit error with an application-owned bounded policy; do not configure a blocking busy timeout on the same JavaScript thread.

Aggregate reads and catalog pages use BEGIN, so a WAL writer may remain active while the reader sees one committed snapshot. Mutations and purge use BEGIN IMMEDIATE: they reserve the writer slot before reading state for CAS and never attempt a deferred read-to-write upgrade. A custom driver may inspect the additive transaction option { access: 'read' }; ignoring it preserves the previous write-safe behavior.

The adapter proves canonical durability across reopen and process restart. It does not make external tool effects exactly once, join application projections atomically or replace an application outbox. If a product row must commit with an agent transition, implement AgentRuntimeStoreDriver over the application’s own transaction boundary instead.

Opening a version 1 store migrates it in one transaction, forward only — back the file up first, a 0.85.x package refuses a migrated file. Existing normalized state becomes one runtime/baseline event per conversation, dated when the migration ran and carrying asOf for the last message it describes; search and projections address that pre-migration history as one snapshot at seq 1. New transitions continue the monotonic conversation sequence. Version 2 requires SQLite FTS5 because event search is an advertised capability, so a build without FTS5 is a startup error (requires FTS5 support) rather than an empty search result; check with SELECT sqlite_compileoption_used('ENABLE_FTS5').

The handle returned by createBunSqliteAgentRuntimeStore / createNodeSqliteAgentRuntimeStore is { store, conversations, database, transaction, close }. database is the shared connection and transaction is one write transaction in the store’s own serialization: the SQLite companions — createSqliteAgentProjectionStore, createSqliteAgentSpillStore, createSqliteAgentChildManager, createAgentScheduleService — take { sqlite } and write their rows and events through it, so a row and its event land together or not at all.

conversations.messages pages the model’s history: what compaction removed is not in it, which is the point of compaction. A person reading back their own conversation needs the other view, and asks for it explicitly:

const page = await conversations.messages({
  conversationId,
  limit: 50,
  direction: 'after',
  includeCompacted: true,
})
const removed = new Set(page.compacted)

items stays one sequence in the order it happened, and compacted names the ids inside it that the model no longer sees — the boundary is a mark on the conversation, not a second list. A compaction summary sits at the position of the last message it replaced, so the block reads through and the summary arrives after it, where it was written; in the model’s history, where every replaced message is gone, it occupies the block’s place either way. Without the flag the page is exactly what it was, compacted empty. The v1 → v2 migration baseline records the same thing: the whole sequence, with compacted naming what had been folded away. A file migrated by 0.86.0 has a baseline built from the active history only — the messages themselves are still in the store and this read reaches them, but that one event cannot be rewritten after the fact.

Retried provider streams

With loop.retry set, a provider stream that fails before any tool call in the attempt is retried at the step boundary. Subscribers see attempt-reset for the run before the next attempt’s first delta and drop what the failed attempt streamed; the durable draft is checkpointed after that output is discarded; an input injected into the failed attempt is taken again by the retry; and the failed attempt’s reported usage stays in the run’s spend. Transient events — deltas, reasoning, attempt-reset — are numbered from 1 per run, counting only what was published, so a cursor sees no gap on an ordinary stream.

Branch or restore with a new identity

Use store.branchConversation() to create an independent conversation. importConversation() restores the original identity and is not a fork. The built-in memory and SQLite stores and createAgentRuntimeStore() expose branching; a hand-written AgentRuntimeStore can advertise this optional capability. The host authorizes the caller’s source/archive access and destination creation before calling this trusted store boundary.

const copy = await sqlite.store.branchConversation({
  requestKey: 'branch-request-1',
  destinationConversationId: 'new-conversation',
  source: { kind: 'conversation', conversationId: 'original', throughRunId: 'finished-run' },
  // Required when selected history has spills: an explicit policy for this destination.
  artifactAuthorization: { operation: 'read', path: 'approved-destination-workspace' },
})

const restored = await sqlite.store.branchConversation({
  requestKey: 'restore-request-1',
  destinationConversationId: 'restored-as-new',
  source: { kind: 'archive', bytes: archiveBytes },
})

throughRunId selects its exact terminal/abandon event. Omit it to include the settled tip and compaction recorded after the last run. The selected prefix must contain no queued or acquired runs. A later active source run does not prevent branching an earlier settled prefix. A migrated baseline has no earlier per-run event boundary; it can be copied at its settled tip.

The result is { outcome: 'created' | 'duplicate', receipt }. Keep the receipt: it binds source and destination identity, source kind, exact sourceSeq/sourceVersion, sourceDigest, request fingerprint and creation time. A retry with the same destination/key and selector returns the original receipt even after the source advances or the destination continues. Changing the request conflicts; no existing destination is overwritten. Archive fingerprints bind the supplied bytes. The source digest binds the selected canonical events, artifacts and reconstructed snapshot. Run update timestamps reconstructed from events use their recorded occurredAt. Abandon transitions retain the full failed assistant in the same event; a legacy archive must retain that exact assistant in its runtime snapshot, otherwise copying refuses instead of inventing historical content or time.

No provider or tool runs during copying. The next ordinary runtime submit continues the copied history. All engine identities and typed references are new, including repeated references to one spill. Compacted content stays in the event history and SQLite inactive rows; the model reads the same active summaries. A hash-only checkpoint is historical digest evidence, marked sourceSha256; a later full terminal record must settle its content.

Recorded provider options and canonical reasoning/tool-call provider metadata are retained. Provider message hashes and request references remain consistent after rekey. Metadata is data, subject to the opaque JSON reference guard: an undocumented runtime reference key refuses instead of carrying a source identity into the destination. Unknown message fields and malformed request/message digests also refuse before any destination writes.

A branch grants no source authority. Terminal run owners/fences and approval signatures are removed. State, schedules, children, retries, sandbox, approval rejection and durability facts are retained as inert runtime/branch-observation records; they cannot repopulate operational state or pending effects. Spills discard source authorization and require the explicit fresh artifactAuthorization; normal destination read authorization still applies. No cached projection, schedule row or child relation is cloned. Ordinary companion projections in the export have { name, version, uptoSeq, value, updatedAt } envelopes. Branch validates their envelopes, unique names and checkpoints within the supplied journal, then discards their values. They are derived application caches, including ones containing source references; their values are never replayed as state or copied as authority. Rebuild destination projections with createSqliteAgentProjectionStore().advance(...) over the destination ledger. An exact earlier boundary never inherits a later cache value.

The store validates the complete archive before writing: contiguous events, a matching runtime snapshot, known typed forms, reference closure, and spill bytes/digests. Unsupported provider envelopes, encrypted invocation payloads, unknown event versions, malformed projection envelopes, missing artifacts and undocumented reference fields in opaque JSON refuse atomically. They need an owner-defined transfer codec; never recursively rewrite internal JSON in the application. Third-party drivers must provide atomic write transactions and archive support for spills; history.restore is required for migrated baselines with inactive rows.

Event ledger, projections and durable capabilities

AgentRuntimeStore exposes bounded readEvents, declared appendEvent, canonical exportConversation and empty-target importConversation. Runtime transitions, exact provider requests and completed provider response identities enter the same append-only ledger. A provider/response payload binds response: { id, provider? } to its runId, retry attempt and stepNumber; step-finished.response projects the same object to the operator sink. The optional upstream name comes from the model provider’s own resolveResponseProvider — openRouterProvider supplies it — so the runtime carries the fact without learning any gateway’s metadata key. The normalized head/run/message tables remain the fast operational projection.

For runtime/transition payload inspection, use AgentStoreTransitionRecordSchema and its inferred AgentStoreTransitionRecord type. A checkpoint record may hold either the full assistant message or { id, status: 'streaming', sha256?, sourceSha256?, parts: number, bytes: number }; exactly one digest is present. Numeric parts counts parts; it is not an array of message parts. sourceSha256 preserves a branch’s historical source digest. These hash-only records are observations, not executable checkpoint inputs. AgentStoreTransitionSchema describes full store mutations. Shape inspection does not replace branch’s complete replay/reference validation. Schema v4 archives written by 0.109.4 use the same journal representation.

Use defineAgentProjection with createSqliteAgentProjectionStore for a deterministic versioned fold. Every value reports uptoSeq, so a caller can distinguish current data from a projection that still has events to consume. Changing the projection version folds from sequence one.

The built-ins are agentSummaryProjection, agentUsageProjection and agentOutlineProjection; focused card, state-slot and schedule projections are also available. list(projection) reads all materialized conversation rows in one SQLite query instead of reopening their event logs.

Durable state is declared once and injected on every provider request:

const goal = defineStateSlot({
  name: 'goal',
  schema: z.object({ objective: z.string(), status: z.string() }),
})

const slots = createAgentStateSlotStore({ store: sqlite.store, definitions: [goal] })
await slots.set({
  conversationId,
  name: 'goal',
  value: { objective: 'finish migration', status: 'active' },
  actor: 'human',
})

const runtime = createAgentRuntime({ ...config, store: sqlite.store, stateSlots: [goal] })

createAgentStateTools binds create_goal, update_goal, get_goal and todo_write to one conversation. Human changes call the same slot store with actor: 'human'; they remain structured state/set facts rather than forged chat messages.

createSqliteAgentSpillStore persists oversized output separately and records its locator, hash and lifecycle in the ledger. read_output and search_output re-run both locator authorization and the originating tool authorization before reading bytes. A reference the store does not hold is a refusal like any other — SPILL_REFERENCE_UNKNOWN / 404, naming the reference and pointing at the one the spilling command returned. The lookup is scoped by conversation, so a reference belonging to another conversation is absent rather than forbidden, and the refusal cannot tell a model that it exists elsewhere. createSqliteAgentEventSearch returns the exact conversation and event sequence; cross-conversation results are denied unless authorizeConversation approves each target. createAgentEventSearchTools supplies session_search, session_trace and session_event over the same bounded APIs.

For credential-free failure tests, import createFaultProviderServer and createReplayAgentProvider from stitchkit/agent-runtime/testing. Runtime loop.retry applies an explicit AgentRetryPolicy: each decision is recorded as retry/scheduled, each new attempt as retry/started, and an attempt that has invoked a tool is never automatically replayed.

createAgentScheduleService persists at, after and every input. Repeating schedules require an explicit IANA time zone. Dispatch uses a stable schedule:<id>:<occurrence> idempotency key, and restart lateness is recorded. Resolve after durable admission; return { status: 'retry', reason } for a transient refusal or { status: 'terminal', reason } to stop the entire schedule in failed state. Only those two shapes are failures: any other returned value — a queue length, a receipt — means the callback returned, so it delivered. Throws retry too. maxAttempts (default 1000, about sixteen hours at the retry ceiling) bounds one occurrence: a one-off schedule then becomes failed, a recurring one gives up that occurrence (schedule/failed with skipped: true and the nextAt it moves to) and keeps its cadence. A failure reason is kept to 1000 characters. Backoff is 1, 2, 4, 8, 16, 32, then 60 seconds, capped at 60 seconds and persisted across restart. retryAt, attempts and lastError show retry diagnostics; success resets them. nextAt and lateByMs retain the original occurrence time. Recurring schedules fire once after an idle stretch and advance to the next future slot on their original cadence.

Dispatch receives an AbortSignal, has a 30-second deadline and holds a unique 60-second lease. A late or cancelled attempt cannot settle or emit firing events. Honor the signal and durably deduplicate the key: a crash after admission but before settlement can replay delivery. This is at-least-once, not exactly-once. Due selection is indexed, limited to 32 parallel deliveries per tick; one hung batch can delay newly due work by at most its deadline. The service keeps one nearest-due timer plus per-attempt deadline timers. Storage failures use a bounded recovery timer; idle ticks do not write. SQLite v4 migration preserves due times and claims; stop older scheduler processes before migration. See ADR 0202. createAgentScheduleTools exposes the exact schedule_after, schedule_at, schedule_every, schedule_list and schedule_cancel surface.

createSqliteAgentChildManager seeds a child from the parent’s ledger through an exact sequence, stores the graph, clamps requested limits to a durable parent remainder and stops budget overruns at the next step boundary as policy_stop. That enforcement runs inside the child’s own runtime: the host that spawns it gives the child loop.stopPolicies: [agentChildBudgetStopPolicy({ manager, childConversationId })], which calls recordStepUsage at every step boundary; recordStepUsage alone measures and decides, and reports enforced: false when the deciding process holds no handle to stop. Given to createAgentRuntime as children, the manager stops the parent’s children after the parent’s terminal is durable — interrupted, cancelled, timed out or shut down; a successful, policy-stopped, superseded or failed parent leaves them to the conversation (ADR 0175 carries the table); without children nothing cascades; an unreachable child is recorded as lost, not misreported as a provider failure. createAgentChildTools adds subagent, subagent_fork, list_agents, send_message and interrupt_agent; final output stays behind its bounded result locator.

Durable order

acceptInputAndAssignRun is one atomic operation. It is followed by ownership acquisition, revision-checked assistant checkpoints and one terminal CAS. The process-local coordinator releases its lane only after terminal commit.

A queued admission is durable immediately, even if its predecessor is still awaiting ownership or its first checkpoint. Snapshots expose causal turn order rather than physical append order: the predecessor’s assigned input(s) and assistant come before the successor input(s). Execution uses the same run boundary, so neither prompt({ snapshot }) nor default/custom history projection can see inputs assigned to a later run. inject remains the explicit path that moves a successor input into the run already in flight.

input + queued run → running → execution settled → terminal CAS → successor

What happens to a run when new input arrives

runs.inputPolicy decides. It takes five values, or a function returning one:

interrupt-next is the explicit priority path for an urgent input. If A is running, ordinary B is queued, and urgent C arrives, the coordinator aborts A, waits for A to settle and then runs C before B. B keeps its durable identity and eventually runs. Urgent inputs remain FIFO among themselves. They do not coalesce into an ordinary pending run: that would erase the priority boundary.

interrupt and supersede differ in exactly one thing, and the question that picks between them is not “was the run interrupted” but “did anyone see what it produced”:

• The user pressed stop. The partial answer was streamed to their screen and they read it. It belongs in the conversation — dropping it makes the history lie to the model about what the human has seen. That is interrupt.
• A newer message superseded the run. Whether the partial reached anyone depends on the delivery surface: a token stream shows it as it is produced, a surface that sends nothing until the run is done never showed it at all. When it reached nobody, it is not part of the conversation. That is supersede.

Stitchkit cannot answer that question for you — delivery belongs to the transport, and the runtime sees an abort, not a screen. Hence a declared policy (→ ADR 0108), and hence inputPolicy accepting a function, so one application can hold two surfaces with different rules without the core learning which is which:

runs: {
  inputPolicy: (input) =>
    protocol.parseContext(input.context).surface === 'operator' ? 'queue' : 'supersede',
}

input.context is the raw context here — admission runs before the runtime parses it, so the callback narrows it itself with the protocol it already has.

A superseded run ends with terminalReason: 'superseded', run state 'superseded' and an assistant message of status 'superseded'. The record is kept — excluded from the projection, not deleted — so an operator can see what was thrown away, and run identity, admission receipts and the terminal CAS keep the row they depend on. Compaction leaves it alone for the same reason: a turn whose answer is never spoken is not a turn that may be summarised into one, because that would both feed the discarded text to the summariser and drop the record in replacedMessageIds.

It is also outside the token budget. selectAgentHistory removes it with reason 'superseded' and does not count it, so an abandoned fragment cannot push a real turn out of a context it never occupies.

How an interrupted turn reaches the model

An interrupted turn is projected, and says so:

{ role: 'assistant', content: [
    { type: 'text', text: 'We are the team, where would you like' },
    { type: 'text', text: '[interrupted: this turn was cut off before it finished]' },
]}

history.interruptedAssistant chooses the form, and the difference between the first two is structural rather than cosmetic. An assistant turn in provider history is a commitment: the model reads its own previous turn as something it said and stays consistent with it. A system line is context.

There is deliberately no value that reproduces what the projection used to do, which was to send the partial as an ordinary assistant turn and drop its control marker on the way. That was the defect, not a behaviour to stay compatible with.

projectAgentHistoryDetailed reports what reached the provider, including part types that no projected content stands for:

const { decisions } = await projectAgentHistoryDetailed(snapshot.messages)
// → { messageId: 'assistant-2', action: 'projected', reason: 'projected',
//      omittedParts: ['source', 'provider'] }
// → { messageId: 'assistant-1', action: 'omitted', reason: 'superseded' }

runtime.stop(key, 'supersede') is the same decision taken by hand: the process-local escape hatch chooses the reason, so a caller that knows the answer was never delivered can discard it without a newer input arriving.

An input that joins a run in flight

inject is right when the new input refines rather than redirects, and the steps already taken are still worth something: “summarise this thread… actually, in bullet points” should not throw away the reading the first message paid for.

What happens:

1. The input is admitted exactly like any other — a committed user message and a queued run, durable before anything else happens.
2. At the running loop’s next step boundary, that input joins its prompt. Only that input: an unrelated queued submission is never carried in.
3. When the run finishes, its terminal commit — one transaction — records the input as one the run answered and settles the queued successor with terminalReason: 'absorbed' and absorbedIntoRunId naming the run that answered it. Every ticket for that successor resolves to the same answer.

Nothing durable happens between 1 and 3, and that is the design (→ ADR 0113). A run that crashes, is closed, or is interrupted after taking an input on commits no absorption at all, so what is left behind is an ordinary queued successor — the state every other policy already produces and recovery already handles. There is no ordering in which an accepted input becomes unanswerable. Only a run that completes may absorb; an interrupted one took the input into its prompt and then stopped, and does not get to say it answered it.

An absorbed run has no assistant message of its own — it produced none, and writing an empty one would be a record claiming otherwise. Its answer is reachable through absorbedIntoRunId, and the store follows that pointer itself when a submission arrives on the absorbed run’s idempotency key, so a retry after a restart returns the answer rather than an empty terminal record.

It does publish one more run-state event, carrying 'superseded'. It never enters the run executor, so that event is the only thing that tells a delivery surface following its runId that it is no longer queued.

With coalescePending, one successor can carry several inputs, and an absorption covers a successor whole or not at all — a partial one would leave a terminal run with inputs nobody answered. Inputs that coalesce before the absorbing run’s last step boundary join the same absorption. One that arrives after it cancels the absorption: the successor then answers all of its inputs itself, and the absorbing run has answered one of them too. A duplicate answer, never a missing one.

(0.63.0 shipped a version of this that committed the absorption at the step boundary, before the answer existed, and it was withdrawn in 0.65.0. ADR 0113 records what that ordering broke.)

With runs.coalescePending: true, an active lane has at most one queued successor. Every later accepted input is atomically appended to that successor; its AgentRun.inputMessageIds records the whole batch and every input ticket resolves to the same terminal run. Coalescing never mutates the active run.

AbortSignal.aborted is only a cooperation request. A successor does not begin while the predecessor still owns managed callbacks. A hung predecessor blocks the lane in the first version.

Shutdown is two-phase, and both budgets carry the names they carry everywhere else in Stitchkit:

const closed = await runtime.close({ gracePeriodMs: 30_000, forceTimeoutMs: 5_000 })
if (!closed.settled) {
  console.warn(`exiting with ${closed.remaining} run(s) still in flight`)
}

close first rejects new process-local admissions and gives active runs gracePeriodMs to finish on their own. Only after that budget expires does it abort them with reason shutdown; forceTimeoutMs then bounds the settlement wait for a non-cooperative model or tool, measured from the abort — the two budgets add up rather than overlapping.

close() reports what it achieved rather than promising an outcome it cannot reach. The result is { settled, timedOut, remaining }: settled when every in-flight run finished, timedOut with a remaining count when the force budget expired first. There is no combination of budgets that is both bounded and guaranteed to leave nothing in flight — that is the trade the budgets exist to make, and the result is where you read which side of it you got:

A caller that wants the old shape still writes await runtime.close(…) and ignores the result. A caller deciding whether to exit the process reads it. Durably queued records rejected from the local queue remain recoverable through scanRecoverable; close never marks them terminal on its own.

Use await runtime.interrupt({ conversationId, runId }) when the interruption must be durable: it first commits interrupt_requested, then aborts the local coordinator signal. If provider completion races that revision change, the terminal path reloads the canonical snapshot. An already-terminal winner settles the ticket directly; a still-owned interrupt_requested run is committed as interrupted, and unrelated aggregate-head conflicts remain retriable while the run is active with the same owner and fencing token. A stale owner or fencing token remains a conflict. Only the execution that applies the terminal mutation publishes the delivery terminal event — a loser settles from canonical state without republishing the turn, and its AgentRuntimeResult.metrics is undefined. The operator run-terminal event is not gated that way: a losing execution still ran, and still spent whatever it spent, so it reports its own usage. The two channels answer to different readers — delivering a turn twice is a user’s problem, and omitting a run’s cost is an operator’s. runtime.stop(key) is the process-local signal-only escape hatch.

When an operator has positive evidence that another process owning one known run is gone, close that run through the runtime boundary rather than updating an adapter table or JSON payload directly:

await runtime.abandon({
  conversationId,
  runId,
  expectedRevision: run.revision,
  staleOwner: true,
})

The revision protects against stale operator evidence. The mutation updates the canonical run and failed assistant atomically, removes the run from recovery indexes, and publishes the resulting run-state. A run that moved since it was read returns a conflict; staleOwner: true is mandatory evidence, not a default.

Store operations

AgentRuntimeStore remains the runtime-facing aggregate. Application adapters implement the smaller AgentRuntimeStoreDriver rather than these eleven members:

• acceptInputAndAssignRun
• acquireRun
• checkpointRunAssistant
• requestRunInterrupt
• recoverRun
• commitRunTerminal
• replaceCompactedRange
• loadSnapshot — the whole conversation; see Reading a conversation below
• loadRun — one run by id, with the answer it produced if it has ended
• listActiveRuns — the runs of one conversation that have not ended
• scanRecoverable — one bounded page of recoverable runs; recover() calls this and nothing else, so an adapter that implements the interface has everything recovery needs

Reading a conversation

Two shapes of read, and the difference matters as a conversation grows.

Bounded. loadRun and listActiveRuns read run records and the conversation head. Neither touches history, so neither grows with the length of the conversation. loadRun is how you resolve the runId that submit().admission hands back — it returns the run, the version it was read at, and, once the run is terminal, the answer it produced.

Unbounded. loadSnapshot returns every message and every run, and so does every mutation result: the store’s reducer validates its invariants against the whole conversation, and the runtime builds the next prompt from the snapshot the mutation returns. Ask for it when you need the conversation — composing a prompt, or compacting — and not to look one run up.

So the cost of a run scales with the length of its conversation, not with the length of the turn. Configure compaction (see below) for anything long-running: it is the only thing in the framework that makes a conversation smaller, and without it a year-old assistant thread is read in full on every turn. This is a known limit, held deliberately rather than by omission — paged history would have to change what a snapshot is, and the store’s invariants with it, and that is a decision on its own (→ ADR 0112).

Every mutation carries an expected run revision or snapshot version. Input assignment additionally carries an idempotency identity. A conflict is a control outcome; stale data is never silently overwritten.

Acquisition increments an optional monotonic fencingToken. The managed runtime carries it through checkpoint/terminal CAS and tool context, so a distributed adapter can reject an old owner even if an owner label is reused. Lease expiry and renewal remain application-owned.

On startup, runtime.recover({ resolveContext }) consumes bounded lightweight pages, then restores each conversation’s durable execution order before any run acquires. Persisted executionSequence orders work that started; queued interrupt-next work precedes ordinary queued work with FIFO preserved inside each class. Scan identifiers, equal timestamps and page boundaries therefore never become queue order. Its safe default resumes queued runs and reports acquired or interrupt_requested runs as skipped. A policy may requeue acquired work only with explicit replay-safe evidence, or abandon it only with stale-owner evidence. Each attempted run returns its own outcome/error; a resumed or requeued outcome also exposes the terminal result promise. The outcome is reported only after durable acquisition, so a lost acquisition is failed rather than a successful-looking handoff. pageSize, maxRuns, and signal bound the pass. runtime.resume(...) remains available for one known queued record; its accepted promise likewise means that the recovered run acquired durable ownership, while result carries terminal completion.

Canonical records currently write schemaVersion: 1. A durable adapter owns read-time migration of older rows: migrate to the current shape at its storage boundary, validate with the exported schema, and write only the current version. Core deliberately does not guess an application’s database migration or silently accept an unknown future version.

Purging a conversation

import { purgeAgentConversation } from 'stitchkit/agent-runtime';

const result = await purgeAgentConversation(store, {
  conversationId,
  expectedVersion: snapshot.version, // optional stale-intent protection
});

The optional AgentRuntimeStore.purgeConversation capability is implemented by the memory and initialized Bun/Node SQLite stores. The helper returns unsupported for stores without it; it never pretends deletion succeeded. Other outcomes are purged, already_purged, active (with runIds), or conflict (with actualVersion). Storage failures reject.

Purge refuses queued, running and interrupt-requested runs. It does not interrupt, force-abandon or wait for a provider. Authorize the destructive request in the host, close its conversation ingress/attachments, then settle runs through normal interruption or explicitly justified recovery. Retry purge after they are terminal. An optional expected version must match the current snapshot; a version conflict requires a fresh deletion decision, not blind retry with a new version.

Successful purge atomically removes messages (including compacted inactive rows), all runs and retained terminal assistants, admissions/idempotency receipts, conversation heads and their owned indexes. It retains only a permanent conversation-ID tombstone. Purging an unknown ID reserves it as well, so a submit paused before admission cannot create it later. Repeating the call returns already_purged, regardless of the original expected version. A lost response is safely retried with the same ID; new chats require a new ID.

Every later runtime mutation rejects with AgentConversationPurgedError, including fresh and duplicate admissions, checkpoints, recovery and compaction. Existing controller leases grant no exception. Existing reads return empty snapshots, absent runs and empty message pages; purged conversations disappear from the SQLite catalog and recovery scans. Snapshots retain their existing empty version: 0 shape; use the purge result, not an empty snapshot, as deletion evidence.

SQLite commits the tombstone and all deletions in one BEGIN IMMEDIATE transaction. Failure before commit rolls everything back; reopen/recovery cannot restore committed deleted records. Same-thread connection contention rejects promptly without effects; retry after the competing operation settles. Initialization adds the tombstone table and write guards to schema v1 transactionally, without changing application tables or user_version. Guards also fence older writers. initialize: false on an original v1 database does not add purge capability; open an initialized writer first.

Consumer-owned model selections, projections, attachment files, delivery/outbox records and event logs remain outside this boundary. Retain an authorized cleanup intent plus any needed opaque file references in consumer storage, purge first, then retry idempotent consumer cleanup. Invalidate local caches/subscriptions so an old delivered event cannot repopulate a UI. The library never traverses paths, revokes remote artifacts or claims a cross-store transaction. Nor does logical purge securely wipe database free pages, WAL or backups. Memory tombstones last only for that store instance.

Custom normalized drivers may opt in through AgentConversationPurgeDriver on driver.conversations. Their transaction must serialize isPurged, head/active-run checks, remove, and all mutations for the same ID, including absent-ID admission. An optimistic head CAS alone is insufficient. remove must delete every owned payload/index and preserve the tombstone; errors must roll back the entire transaction. Drivers without this guarantee must leave the capability absent. See ADR 0138.

Events and reconnect

A subscriber that switches over event.type handles one transient event beyond deltas and reasoning: attempt-reset, published when loop.retry starts a new attempt, meaning everything this run streamed before it is withdrawn. reduceAgentControlEvent does that; a hand-written reducer must, or it keeps the failed attempt’s partial text on screen.

publish receives event classes with different guarantees:

• admission follows a successful acceptance CAS and carries the same complete projection as ticket.admission;

• assistant-delta is transient and ordered by (runId, runtimeEpoch, sequence);

• reasoning-start, reasoning-delta and reasoning-end are transient and ordered by the same identity; delta carries only the current text fragment, while provider metadata stays inside a validated canonical envelope;

• assistant-checkpoint follows a successful checkpoint CAS;

• run-state follows durable queue/acquire/interrupt transitions;

• run-operation follows a successful operation CAS. Its operation is the durable AgentRun.lastOperation: model-request or compaction, with started, first-output, completed, failed or cancelled phase and the original timestamps. Concrete models use SDK call identity in an awaited model middleware; global provider IDs use a runtime-generated identity during awaited step preparation. Both durably admit the request before entering doStream, so a failed write prevents the provider call. This does not claim HTTP transmission is measured. First output is a non-empty text/reasoning/tool-argument delta or complete tool call; metadata, usage, files and sources do not count;

• tool-status is transient lifecycle presentation with JSON-safe input on start and output on completion. A mounted typed failure carries the same safe { error, retryable, details?, _hint? } envelope as the durable result; an unknown internal cause remains generic and stays in local observability only;

• terminal follows the winning terminal CAS.

loop.checkpointEveryEvents batches ordinary stream parts (default 20) and does not batch live event delivery. Tool call/result/error/denial, approval request/response and step-finish boundaries force an assistant checkpoint and reset that batch. The checkpoint is awaited after the managed loop observes the normalized boundary. It does not promise persistence before a tool side effect: tool fencing supplies the real ownership checks around execution, while cross-crash effect idempotency stays application-owned. The following model step waits for the previous step-finish checkpoint before its own durable request admission and provider invocation. → ADR 0174.

compaction names invocation of the configured callback, including a not_needed context-budget check; it does not by itself say that history was summarized. Operation timestamps are retained wall-clock observations and may move backwards after a clock correction. Do not subtract them for duration; phase order comes from durable snapshot versions/event order.

These are post-commit notifications, not a transactional outbox: a process can crash between the database commit and publish. Reconnect should load canonical state. Exactly-once external delivery remains an application-owned outbox.

External channel ingress and delivery

The executable external-channel-harness.ts is the reference composition for webhooks, polling transports and local-device adapters. Its generic boundary injects a runtime, durable store and delivery adapter; the optional external-channel-grammy.ts attaches the same ingress function to grammY polling or webhook lifecycle without putting provider types in the agent runtime.

Inbound update identity, principal resolution, conversation mapping and reply target are application policy. Persist and deduplicate the update before runtime.submit, use the stored idempotency key on crash recovery, then persist the admitted runId. A duplicate arriving after restart resolves to that same mapping instead of creating another model turn.

For output, choose terminal-only or streaming explicitly. Stable durable eventId values and transient (runtimeEpoch, sequence) identities become outbox keys; the application store assigns causal ordinals. A bounded channel is only a process-local wakeup and never the durable authority. Before sending, persist one of these states:

The agent terminal event and the adapter’s delivery receipt are intentionally different records. A successful run does not prove that a reply reached its channel, and a delivery failure never rewrites the canonical agent result. Shutdown stops ingress, drains accepted process-local work and leaves ambiguous outbox records visible for a later reconciliation pass. Stitchkit does not own a channel database, durable broker, provider payload schema or application identity policy.

Durable event IDs are derived from run, event type and snapshot version. Use advanceAgentRuntimeEventCursor to classify delivery.

gap is reported for transient events only, where sequence is a per-run counter the runtime really does increment once per event. Durable events carry the conversation’s version, which advances on every mutation including the many that publish nothing — checkpoints, compaction, an acceptance that has not started — so two consecutive durable events are routinely several versions apart and adjacency says nothing. A durable loss is not detectable from the cursor; reload on reconnect, which is what a bounded fire-and-forget sink asks of you anyway. createAgentRuntimeEventSink adds a bounded failure-isolated lifecycle and typed projection/redaction hook. onPublishError records direct publisher failures without changing the already committed run.

A named custom stop condition terminalizes with policy_stop; its policyName is persisted on the run and included in the terminal event/result. max-steps is the reserved built-in policy name. loop.prepareStep is the controlled AI SDK step boundary for changing active tools, model, instructions or messages. It cannot replace the managed tool set or bypass its lifecycle fence.

Context can grow between steps as tool results and deferred schemas enter the provider prompt. When application budgeting can prove that the next assembled step exceeds the selected model window, refuse it by type before that provider call:

prepareStep: (step) => {
  if (wouldExceedSelectedModelWindow(step)) {
    throw new AgentContextOverflowError('Prepared step exceeds the selected model window')
  }
  return chooseProductStepOptions(step)
}

That deliberate refusal ends the run as context_overflow on the durable record, delivery terminal and operator event. Stitchkit does not inspect error messages — it recognises failures by identity, not by text. A store refusing an owned mutation ends the run storage_conflict; protocol.acceptTerminal refusing a finished message ends it output_rejected; a check the SDK runs on what this runtime handed it ends it runtime_failure. Every error the runtime cannot identify as its own remains provider_failure, and operator-only observability retains its original cause in all of them.

Completion validity belongs to the protocol and is checked before the terminal CAS. Protocols that require a visible answer opt in explicitly:

const protocol = defineAgentProtocol({
  context: ContextSchema,
  inputMetadata: InputMetadataSchema,
  terminalAcceptance: 'require-output',
})

The built-in rule accepts non-blank text, generated files, structured provider parts, and a named tool-only policy_stop. The default is allow-empty for protocols where an empty acknowledgement is meaningful. Pass a callback when the product has a narrower definition; it receives the candidate message, terminal reason and optional policy name, and runs before persistence. A false result fails the candidate instead of rewriting an already committed success.

loop.idleTimeoutMs measures provider silence. It starts immediately before the provider call, resets on stream activity, and pauses while local tools execute. Resource preparation, child waits and approval waiting do not spend this budget. The host gives tools their own deadlines. A stalled provider still aborts with durable reason timeout; caller interruption and shutdown reach tools directly.

Reconnect loads the durable snapshot. Missing transient deltas do not mean the canonical result was lost. Exactly-once external delivery requires the application’s transactional outbox or stable-ID deduplication.

Managed tools

Durable step bodies return lossless JSON: finite numbers (excluding negative zero), strings, booleans, null, dense arrays and plain data objects. Return null explicitly for effect-only bodies and convert Date values to strings. Unsupported values are refused after the body, so external effects still require idempotency. First results and replay are detached snapshots; mutating a returned object cannot rewrite a record. The optional sandbox coding profile reuses the same tool mounting, authorization and output handling for namespace-backed commands.

Always compose toolFenceLifecycle into mountAgent. It checks ownership before a managed side effect and again before accepting its result. Fence loss uses an internal control signal: it stops the old loop and is not sent to the model as a tool error.

mountAgent sends failed runner outcomes through the AI SDK’s tool-error channel. AgentRuntime persists them with outcome: 'error', publishes the same safe envelope, and replays them as an error result on later turns. Classification comes from the execution channel, never from inspecting output fields: a valid successful result such as { error: 'domain value' } remains successful. Typed AppError codes and safe details may reach the model; arbitrary thrown causes are retained for local hooks and reduced to INTERNAL_SERVER_ERROR outside.

The framework cannot undo an already-started non-cooperative external effect. Pass the stable call/run idempotency identity into business mutations when the effect must be replay-safe.

History, provider metadata and files

projectAgentHistory converts canonical engine records into provider-valid AI SDK messages and pairs tool calls/results in persisted causal order. Adjacent parallel calls stay in one assistant round and their adjacent results stay in one tool round; a dependent call after those results starts a new assistant round, and trailing final text remains after the last tool result. Provider-required metadata is kept in a versioned opaque envelope and omitted from product delivery by default. projectAgentHistoryDetailed additionally returns one inspectable decision per canonical record; leading assistant records, crash drafts and unmatched tool chronology are never silently passed to the provider.

selectAgentHistory is the non-destructive context-window selector. It removes only whole oldest complete turns, protects system/summary, incomplete and configured recent turns, and reports every keep/remove reason with measured/estimated/unavailable token provenance. An oversized protected turn returns oversized; unavailable accounting returns unavailable without invented arithmetic.

ComposedAgentPrompt.instructions accepts the AI SDK Instructions contract. Use adaptInstructions when a provider needs metadata on the system message:

prompt({
  context,
  signal,
  adaptInstructions: (content) => ({
    role: 'system',
    content,
    providerOptions: { openrouter: { cacheControl: { type: 'ephemeral' } } },
  }),
})

Attachments and generated files remain application-owned. The runtime only stores a reference returned by persistGeneratedFile; it never silently puts base64 blobs into the neutral history store.

To send a stored attachment back to a multimodal model, configure history.resolveFile. It maps the neutral file reference to AI SDK file data (URL, bytes, provider reference or text). Without a resolver the unresolvedFile policy applies, and it is omit by default: the file part simply does not reach the provider. Choose text for a describing placeholder — the filename or media type, never the storage reference, because that string is an address inside your infrastructure and this content travels upstream — or error to fail loudly. The error message does name the reference: it is thrown into your process, where you are owed the whole story.

Compaction

structuredCompaction summarizes complete provider-valid turn groups outside the store lock, then calls replaceCompactedRange against the exact snapshot version. A concurrent input produces conflict; the stale summary is not applied. Summary records use the dedicated summary role and project to a provider system message. The consumer supplies the structured summary schema and prompt. Pass previousSummary for a direct call, or configure readPreviousSummary for runtime-managed compaction, to merge and atomically replace a leading summary on the next compaction. Set maxAttempts to allow bounded conflict recovery. Every retry reloads the snapshot, reselects the eligible range and recomputes the summary; the stale summary is never retried.

Compacting without the store

The selection inside compaction needs no store, no version and no runtime, so it is published on its own as selectCompactableHistory — for an application that drives the model itself and keeps its own history (→ ADR 0142):

import { selectCompactableHistory } from 'stitchkit/agent-runtime'

const { leadingSummary, compactable, retained } = selectCompactableHistory({
  messages,
  keepRecentTurns: 3,
})
if (compactable.length > 0) {
  const summary = await summarize(compactable, leadingSummary)
  messages = [summary, ...retained]     // replace the old summary, never stack one
}

compactable is the oldest whole complete turns and retained is everything the model must still hear; together they are the input, in order. A turn holding a tool call whose result never arrived is never eligible, and neither is anything after it: half a turn hands the provider a call with no result, which most of them refuse outright.

structuredCompaction calls this same function, so the published selection and the runtime’s cannot drift into two behaviours. What it adds is the part that does need the store — writing the result back under a version check.

Deciding when to compact is yours: AgentRuntimeRunContext.contextUsage carries the last step’s prompt size beside the model’s window, and dividing them is one line where the threshold is decided. The core does not own that ratio, on purpose — see ADR 0142 for what it publishes and what it declines to.

Observability

createAgentObservability emits a separate operator-only AgentRunEvent. It reuses the same bounded sink lifecycle as request/tool observability without sending new event kinds to existing request sinks. Product events omit provider causes. Operator internalCause is also redacted by default; an operator-only sink must explicitly set includeInternalCause and own its retention policy.

What a run says it spent

Usage values carry provider-reported, computed, estimated or unavailable provenance, per field. Cost additionally carries an ISO currency code; OpenRouter-reported cost is normalized as USD.

Read the provenance before the number (→ ADR 0109):

• provider-reported — the provider handed us exactly this. On step-finished, that is what a step’s figures are.
• computed — a total, added up over steps. Every figure on a terminal event is this, tokens included: the AI SDK’s totalUsage is a sum it performed, not a number a provider reported for the run. It is not a figure to bill against unchanged.
• unavailable — nobody reported it. Not zero.

Two rules follow from that last one, and they differ by field on purpose:

• A token total with an unreported step is a floor, labelled computed. A token count is a diagnostic, and a floor is a useful one.
• A cost with an unreported step is unavailable, not a floor. Money is what people bill against, and “at least $1.00” reported as $1.00 is the same class of lie this whole section exists to remove. One step that did not report its cost makes the run’s cost unknown — not smaller. It also stays unknown: later steps reporting normally cannot revive it.

A terminal event always carries usage. A run that ended before the provider reported anything — superseded, interrupted, timed out, shut down, failed — carries every field unavailable. That is deliberately different from a run that spent nothing, and an omitted object could not tell you which one you had.

Two costs in different currencies do not add: the sum reports unavailable rather than picking a label. The core records a currency and never converts one.

step-finished.response identifies the provider response for that one step. The terminal event does not copy the last response: response identity remains per-step, while every terminal usage figure remains a computed aggregate.

A run’s figure is durable, and that is where to read it when a channel loses it. AgentRun.usage is written at every checkpoint and again with the terminal record, so a crashed process leaves behind what it had already spent and a dropped event is not a lost number:

const snapshot = await store.loadSnapshot(conversationId)
const spent = snapshot.runs.find((run) => run.id === runId)?.usage

Two gaps are open and are stated rather than left to be discovered:

• Both event sinks are bounded and drop under load, by arrival order — the event carrying the money is exactly as droppable as the one carrying nothing. The run record is the recovery, and this paragraph is the only place that says so.
• AgentRuntimeResult.metrics is undefined when this executor did not win the terminal race. Read result.run.usage — the durable figure — rather than result.metrics, which is the channel that can go missing.
• Compaction spend is invisible unless you report it. config.history.compact calls a model inside the turn and produces no step and no event of its own. Return usage from AgentCompactionResult and it joins the run’s figure; omit it and the run under-reports by whatever summarising cost.

What stitchkit does not keep is a ledger: one figure, on the run that produced it, never aggregated and never reconciled against a provider invoice (→ ADR 0110).

Reconciling with the provider’s own accounting

Whether a provider bills for a call that was aborted mid-flight cannot be known inside the process: the authoritative number arrives later, from the provider’s accounting. stitchkit does not accept it back (→ ADR 0110) — a terminal run is an absorbing state, and a write that reached it through the conversation aggregate could conflict a concurrent compaction into discarding a summary it had just paid a model to produce.

The join is yours, and runId is the key:

// when the run terminates — write what the runtime observed
await ledger.record({
  runId: terminal.run.id,
  conversationId: terminal.run.conversationId,
  // The durable figure, not `terminal.metrics` — that one is absent whenever
  // this executor did not win the terminal race.
  costUsd: terminal.run.usage?.cost?.value ?? null,        // null when `unavailable`
  provenance: terminal.run.usage?.cost?.provenance ?? 'unavailable',
})

// later — the provider's accounting names the same generation
await ledger.reconcile({ runId, costUsd: billed, provenance: 'provider-reported' })

Record the row even when the figure is unavailable: that row is the evidence that a run happened and cost something nobody has counted yet, and it is what the provider’s later figure attaches to. A run with no row is a run you cannot reconcile.

The sink deduplicates stable event IDs by default. Cross-crash exactly-once still requires a durable outbox.

Deterministic race and adapter proof

stitchkit/agent-runtime/testing exports createAgentRaceBarrier, createAgentRaceDriver, createAgentRaceTrace and runAgentStoreConformance — agent testing tools live beside the agent runtime, and stitchkit/testing imports none of it. Barriers have bounded teardown, traces assert exact partial order, and the helpers are exercised from packed Bun and Node consumers. runAgentStoreConformance runs duplicate, coalescing, collision, stale checkpoint, replay safety, terminal race, absorption, bounded reads, causal queued-history order, durable interrupt priority, compaction and recovery invariants against any fresh durable adapter.

It picks its conversation identities itself and passes them to createStore(context) before the first mutation, so an adapter whose runtime rows reference an application-owned conversation row can provision those parents; the optional cleanup(context) removes them again, and runs once whether the scenario passed or failed. A factory that owns no fixture state ignores the argument and keeps working unchanged.

Plain completions and shared invocation receipts

Use createModelInvocationLedger from stitchkit/agent-runtime when a direct text completion and an agent must share causal provider evidence. It uses the existing runtime store, not a second database. The completion path sends exactly one user prompt, no framework instructions and no tools. It never starts an agent loop.

import { createModelInvocationLedger } from 'stitchkit/agent-runtime';

const invocations = createModelInvocationLedger({
  store, // the same AgentRuntimeStore object passed to createAgentRuntime
  models, // an existing defineModelRegistry result
  payloadKey, // 32 bytes from the host's secret store; retain separately from archives
  authorize: async ({ context, conversationId, action, trace }) => {
    const session = await authenticate(context);
    await authorizeConversation(session, conversationId, action, trace);
    return { subject: session.subject }; // verified identity, never a body field
  },
});

const completion = await invocations.complete({
  conversationId: 'evaluation-42',
  idempotencyKey: 'summary-case-3',
  trace: {
    operationId: 'summary-42', purpose: 'summarize', project: 'example',
    parent: { traceId: 'trace-42' }, experiment: 'evaluation', case: 'case-3',
  },
  prompt: 'Summarize these supplied facts.',
  models: ['primary', 'fallback'], // registry keys; repeat a key for an explicit retry
  settings: { maxOutputTokens: 500 },
  timeoutMs: 30_000,
}, authenticatedContext);

// Add to the existing createAgentRuntime configuration:
const receiptConfig = {
  ledger: invocations,
  trace: ({ run }) => ({
    operationId: run.id, purpose: 'assistant-turn', project: 'example',
  }),
};
// createAgentRuntime({ ...existingConfig, invocations: receiptConfig });

const page = await invocations.read({
  conversationId: 'evaluation-42', limit: 100,
}, authenticatedContext);
// Continue with fromSeq: page.nextSeq while it is defined.

complete returns invocationId, outcome and, on success, text. duplicate returns the existing ID without provider execution or replaying plaintext. Changed input, trace or caller under the same key is a conflict. Model attempts are explicit and bounded to eight; SDK retries are disabled. Only provider failures trigger the next attempt. Abort, audit refusal and configuration errors do not. An admitted call whose process died stays claimed: inspect the receipt before choosing a new key.

The agent retains its existing prompt, tools and loop. Both modes produce invocation/started, provider/request, provider/response and invocation/finished records through read. Each attempt has its own ID; response usage is counted once and keeps unavailable distinct from measured zero. Requested registry selection, sent adapter identity and effective provider identity are separate. Effective identity is null when not reported. A gateway’s hidden retries are not visible as additional attempts.

currentModelInvocationAttempt() returns the causal context inside a provider’s fetch callback or streamed read. Use it to join a host transport audit to operationId, invocationId, attemptId, optional runId and step. onAttempt is an awaited admission hook; a rejected hook prevents the provider call. SDK payload hashes are not represented as hashes of HTTP wire bytes.

Prompts and output are AES-256-GCM payload artifacts. read returns references and hashes; readPayload({ conversationId, artifactId }, context) separately authorizes read-payload and checks authentication tags and hashes. payloadKey must be 32 bytes and is copied at construction. Keep it outside the event store/backups; retain the appropriate key when restoring an archive. maxPayloadBytes defaults to 4 MiB (range 1 KiB–64 MiB). Streaming output evidence keeps parts up to half of it; past that the evidence carries truncated: { parts, sha256 } over the whole stream, and the answer itself is never cut. A receipt that cannot be written never changes an outcome: complete() returns it with receiptError beside it, and a succeeded answer keeps its text. Request headers are excluded. Protect existing agent history independently: enabling receipts does not encrypt its ordinary conversation records.

The built-in memory and SQLite stores implement appendEventOnce. Custom stores must implement its once-only check and append atomically, returning the original event on a duplicate key scoped by conversation and kind. A factory without this capability refuses receipt setup. The driver-backed implementation finds the keyed event by its identity through the driver’s optional events.find — one index probe in SQLite — so admission costs the same on a long conversation as on a new one; a custom driver without find falls back to paging the log in one transaction. store.findEventOnce({ conversationId, kind, key }) reads the same event back. Invocation payload artifacts are keyed by their artifact id the same way.

Migration from direct SDK completions

Who must act: applications opting into shared completion/agent receipts. Replace the direct generateText call with invocations.complete, configure host authorization and a retained payload key, and pass the same ledger in the agent’s invocations option. Use the returned invocation ID and the paginated read method for receipt queries; do not import runtime internals. Available since 0.100.0; existing runtime configurations need no migration.