stitchkit 0.56.0 → 0.56.2

package/llms-full.txt

@@ -47,6 +47,8 @@ keeping server-only code (`Bun.serve`, the MCP SDK) out of browser bundles.
 | `stitchkit/remote` | browser **and** server | peer-free `implementRemote` for thin HTTP proxy processes |
 | `stitchkit/files` | server (Bun or Node) | peer-free managed local-file boundary |
 | `stitchkit/observability` | server | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/agent-runtime` | server | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime/openrouter` | server | isolated OpenRouter language-model adapter |
 | `stitchkit/testing` | tests on Bun or Node | in-process generated clients over a real Fetch handler, without a TCP port |
 | `stitchkit/react` | browser | `createCursorQuery`, `createCacheBridge` |
 
@@ -146,6 +148,8 @@ map — feature → packages:
 | `createServer` (Bun) | — (uses `Bun.serve`) |
 | `serveNode` (Node ≥ 22) | `srvx` (+ `@types/bun` dev) |
 | MCP / agent tools (`stitchkit/tools`) | `@modelcontextprotocol/server` `ai` |
+| Agent application runtime (`stitchkit/agent-runtime`) | `ai` |
+| OpenRouter runtime adapter (`stitchkit/agent-runtime/openrouter`) | `ai` `@openrouter/ai-sdk-provider` |
 | MCP host/client tests | `@modelcontextprotocol/client` |
 | MCP Apps UI widgets | `@modelcontextprotocol/ext-apps` |
 | React data layer (`stitchkit/react`) | `@tanstack/react-query` `react-query-kit` |
@@ -989,6 +993,18 @@ createServer({
 | `'pretty'` | two coloured lines per request — `→` on arrival, `←` on completion | no — a line sized for a terminal is not a record |
 | `'json'` | one structured line per completed request | yes |
 
+Status `499` has one framework-wide meaning: the client closed the request. It
+is logged at `info`, not under the ordinary `4xx → warn` rule. A confirmed
+disconnect is not sent through project `onError`, `normalizeError` or the
+request-error recorder; an `AbortError` while the request signal is still active
+remains an internal failure. A runtime abort reason may be preserved by identity
+through at most eight cycle-safe standard `cause` links; error messages and codes
+are never classifiers. The same rule applies when the disconnect happens while
+Stitchkit is reading a JSON upload body: bounded reads race every pending stream
+read against the request signal and never parse a cancelled partial body. `499`
+is transport telemetry, not a response declared in the contract or generated
+OpenAPI document.
+
 Unset, `format` follows `NODE_ENV`: `json` under `production`, `pretty`
 otherwise. That default is read **per request** — not at import, not when this
 package was built — so it reflects the environment your app actually runs in.
@@ -1159,7 +1175,9 @@ createServer({
 - **`afterHandle`** — receives the handler result; return a replacement to
   transform it.
 - **`onError`** — receives any thrown error; return a `Response` to customise
-  the error body. Without it, errors render through the standard envelope.
+  the error body. Without it, errors render through the standard envelope. A
+  confirmed client disconnect is a transport cancellation rather than an
+  application error and deliberately bypasses this hook.
 
 Hooks see `RuntimeContext` (loose types); handlers see `HandlerContext` (typed).
 That split is deliberate — see [ADR 0003](../decisions/0003-two-context-types.md).
@@ -2822,6 +2840,10 @@ list.
 
 ## AI agents — `mountAgent`
 
+`mountAgent` remains the low-level path when the application owns its own model
+loop and conversation state. For the optional Stitchkit-owned run/history loop,
+see [Agent application runtime](./agent-runtime.md).
+
 `mountAgent` turns a service into a Vercel AI SDK `ToolSet`, ready for
 `generateText` / `streamText`:
 
@@ -3326,6 +3348,288 @@ the rest of the context (`params`, `input`, anything `context` injects) is
 identical. Write the handler once; it serves every surface.
 
 
+==============================================================================
+# Guide: Agent application runtime  (docs/guide/agent-runtime.md)
+==============================================================================
+
+---
+title: "Agent application runtime"
+description: Configure Stitchkit's optional durable history, stream loop, run coordination and managed-tool fencing.
+type: architecture
+status: active
+created: 2026-08-22
+updated: 2026-08-22
+---
+
+# Agent application runtime
+
+`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`. Neither path depends on the other at runtime.
+
+## Install
+
+```sh
+bun add stitchkit ai zod
+```
+
+OpenRouter is isolated so other runtime users do not resolve its package:
+
+```sh
+bun add @openrouter/ai-sdk-provider
+```
+
+## Minimal composition
+
+```ts
+import { z } from 'zod'
+import {
+  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([
+  {
+    name: 'product',
+    stability: 'stable',
+    render: ({ context }) => `Help user ${context.userId}.`,
+  },
+])
+
+const runtime = createAgentRuntime({
+  protocol,
+  store: createMemoryAgentRuntimeStore(),
+  models: { 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' }],
+})
+
+await ticket.accepted
+const terminal = await ticket.result
+```
+
+The in-memory store is a reference adapter and has process-local durability
+only. Production applications implement `AgentRuntimeStore` with their own
+database transaction and, when needed, distributed lease/fencing token.
+
+## 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.
+
+```text
+input + queued run → running → execution settled → terminal CAS → successor
+```
+
+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.
+
+Use `await runtime.interrupt({ conversationId, runId })` when the interruption
+must be durable: it first commits `interrupt_requested`, then aborts the local
+coordinator signal. `runtime.stop(key)` is the process-local signal-only escape
+hatch.
+
+## Store operations
+
+An adapter implements the aggregate `AgentRuntimeStore`, not separate message
+and run CRUD stores:
+
+- `acceptInputAndAssignRun`
+- `acquireRun`
+- `checkpointRunAssistant`
+- `requestRunInterrupt`
+- `recoverRun`
+- `commitRunTerminal`
+- `replaceCompactedRange`
+- `loadSnapshot` and `scanRecoverable`
+
+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.
+
+On startup, `scanRecoverable` returns queued/acquired records. `recoverRun`
+may abandon them, or requeue an already acquired run only with explicit
+`replaySafe: true` evidence. The framework never guesses that an external
+side effect is replayable. After an application reconstructs its typed context,
+`runtime.resume({ conversationId, runId, context })` admits that queued record
+through the same acquisition CAS and coordinator lane; it never creates a
+second input message.
+
+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.
+
+## Events and reconnect
+
+`publish` receives event classes with different guarantees:
+
+- `assistant-delta` is transient and ordered by
+  `(runId, runtimeEpoch, sequence)`;
+- `assistant-checkpoint` follows a successful checkpoint CAS;
+- `run-state` follows durable queue/acquire/interrupt transitions;
+- `tool-status` is transient lifecycle presentation with JSON-safe input on
+  start and output on completion; internal tool failures remain generic;
+- `terminal` follows the winning terminal CAS.
+
+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.
+
+`loop.idleTimeoutMs` is inactivity, not total duration: the deadline resets on
+every model stream event. A stalled call aborts with durable reason `timeout`;
+user interruption and shutdown remain distinct.
+
+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
+
+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.
+
+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. Provider-required metadata is kept
+in a versioned opaque envelope and omitted from product delivery by default.
+
+`ComposedAgentPrompt.instructions` accepts the AI SDK `Instructions` contract.
+Use `adaptInstructions` when a provider needs metadata on the system message:
+
+```ts
+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 explicit
+`unresolvedFile` policy is `text` by default; choose `omit` or `error` when a
+placeholder would be incorrect.
+
+## 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.
+
+## 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; the operator terminal event may include `internalCause`, so its sink
+must use internal retention and redaction policy.
+
+Usage values carry `provider-reported`, `computed`, `estimated` or
+`unavailable` provenance. Cost additionally carries an ISO currency code;
+OpenRouter-reported cost is normalized as USD. Missing values remain absent,
+never zero-filled.
+
+In-memory sink delivery is at-most-once per execution. Stable event IDs allow
+consumer dedupe; cross-crash exactly-once requires a durable outbox.
+
+
 ==============================================================================
 # Guide: CLI  (docs/guide/cli.md)
 ==============================================================================
@@ -4685,22 +4989,36 @@ error round-trips without adding correlation data to the response body.
 ### Stitch codes vs your codes
 
 A `code` is a free string — your app codes (`BOT_NOT_FOUND`, …) are yours and the
-core never models them (ADR 0002). But stitchkit itself emits a fixed set:
+core never models them (ADR 0002). But stitchkit itself emits a set of its own:
 `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`,
-`CONFLICT`, `RATE_LIMITED`, `VALIDATION_ERROR`, `INTERNAL_SERVER_ERROR`. They are
+`CONFLICT`, `RATE_LIMITED`, `VALIDATION_ERROR`, `FILE_INVALID_PATH`,
+`FILE_OUTSIDE_ROOT`, `FILE_NOT_FOUND`, `FILE_NOT_REGULAR`,
+`FILE_INSPECTION_REJECTED`, `FILE_TOO_LARGE`, `FILE_EXISTS`,
+`REALTIME_CONTRACT_VIOLATION`, `INTERNAL_SERVER_ERROR` — a set that grows in
+ordinary releases, each addition named in the changelog. They are
 published as **`STITCH_ERROR_STATUS`** (the `code → status` map) and
 **`StitchErrorCode`** (its `keyof`), with **`isStitchErrorCode()`** (→ ADR 0026).
 
 If you translate stitch's framework errors into your own wire codes in an
-`onError` hook, key the map by `StitchErrorCode` so it stays exhaustive — a code
-stitch adds or renames becomes a compile error, not a silent `500`:
+`onError` hook, you choose how the set's growth reaches you. Keying the map by
+`StitchErrorCode` makes it exhaustive, so a code stitch adds or renames becomes
+a compile error rather than an unfamiliar code on your wire — worth it when the
+envelope is a published contract, at the cost of an edit on those releases:
 
 ```ts
+// Exhaustive on purpose: the annotation is what turns a new stitch code into a
+// compile error here. Drop it (or use `satisfies` on a partial map) to let an
+// unmapped code travel as itself instead.
 const STITCH_TO_APP: Record<StitchErrorCode, AppCode> = {
   NOT_FOUND: 'NOT_FOUND', METHOD_NOT_ALLOWED: 'METHOD_NOT_ALLOWED',
   BAD_REQUEST: 'VALIDATION_ERROR', VALIDATION_ERROR: 'VALIDATION_ERROR',
   UNAUTHORIZED: 'UNAUTHORIZED', FORBIDDEN: 'FORBIDDEN', CONFLICT: 'CONFLICT',
   RATE_LIMITED: 'RATE_LIMITED', INTERNAL_SERVER_ERROR: 'INTERNAL_SERVER_ERROR',
+  REALTIME_CONTRACT_VIOLATION: 'INTERNAL_SERVER_ERROR',
+  FILE_INVALID_PATH: 'VALIDATION_ERROR', FILE_OUTSIDE_ROOT: 'VALIDATION_ERROR',
+  FILE_NOT_FOUND: 'NOT_FOUND', FILE_NOT_REGULAR: 'VALIDATION_ERROR',
+  FILE_INSPECTION_REJECTED: 'VALIDATION_ERROR', FILE_TOO_LARGE: 'VALIDATION_ERROR',
+  FILE_EXISTS: 'CONFLICT',
 }
 onError: (ctx, err) => {
   if (AppError.is(err) && isStitchErrorCode(err.code)) {
@@ -4776,20 +5094,20 @@ codes and schemas remain application-owned; Stitchkit stays domain-free.
 
 ## `createErrorHook`
 
-`createErrorHook` is the code-map above, packaged — you supply the exhaustive
-`codeMap` and the envelope shape, it does the normalisation (including the
+`createErrorHook` is the code-map above, packaged — you supply a `codeMap` and
+the envelope shape, it does the normalisation (including the
 never-leak-an-internal-message rule for a raw throw):
 
 ```ts
 const onError = createErrorHook({
+  // Map the codes you have an opinion about; the rest travel as themselves.
   codeMap: {
     BAD_REQUEST: 'bad_request', VALIDATION_ERROR: 'bad_request',
     UNAUTHORIZED: 'unauthenticated', FORBIDDEN: 'forbidden',
     NOT_FOUND: 'not_found', METHOD_NOT_ALLOWED: 'not_found',
     CONFLICT: 'conflict', RATE_LIMITED: 'rate_limited',
     INTERNAL_SERVER_ERROR: 'internal',
-    REALTIME_CONTRACT_VIOLATION: 'internal',
-  } satisfies Record<StitchErrorCode, string>,
+  },
   // `ctx` is the request's RuntimeContext — read `ctx.traceId` for a
   // correlation id in the envelope. Declaring it is optional.
   render: (info, ctx) => ({
@@ -4802,8 +5120,24 @@ const onError = createErrorHook({
 createServer({ services, hooks: { onError } })
 ```
 
-Codes you threw yourself (not stitchkit's) pass through `codeMap` unchanged; the
-`satisfies Record<StitchErrorCode, …>` keeps the map exhaustive across upgrades.
+`codeMap` is partial: map the codes you have an opinion about. A stitchkit code
+you did not list travels as itself — the same thing a code you threw yourself
+always did. That is what keeps a code added by a future release from being a
+compile break for every project that translates codes at all.
+
+One `satisfies` is the **opt-in** to the stricter deal:
+
+```ts
+codeMap: { /* … every code … */ } satisfies Record<StitchErrorCode, string>,
+```
+
+That makes the map exhaustive on your side, so a release that adds a code stops
+your build until you decide what the new code is called on your wire. Take it
+when your envelope is a published contract and a code surfacing in stitchkit's
+spelling would violate it; leave it off when passing one through is fine.
+Neither choice is silent — the changelog names every added code. For a single
+catch-all instead of either, decide it in `render`, where `info.code` is the
+resolved value.
 
 Both `onError` and `render` may be asynchronous and receive the matched endpoint
 as their final argument. The observer is awaited before rendering, so it can
@@ -4878,9 +5212,11 @@ a request context, and event projections — and you usually touch only the last
 ### createObservability
 
 `createObservability` configures request and tool projections independently.
-Every completed call is normalised into one `RequestEvent`; HTTP completion is
-owned directly by `createHandler`, while MCP/Agent completion uses the canonical
-`ToolCallHooks` runner. There is no nested HTTP audit wrapper.
+Every completed application call is normalised into one `RequestEvent`; HTTP
+completion is owned directly by `createHandler`, while MCP/Agent completion uses
+the canonical `ToolCallHooks` runner. Confirmed HTTP client cancellation stays
+in the access log by default and becomes a structured event only when the
+request sink opts in. There is no nested HTTP audit wrapper.
 
 ```ts
 import { createObservability } from 'stitchkit/observability'
@@ -4901,6 +5237,7 @@ export const observability = createObservability({
   request: {
     write,
     includePayload: false, // default: no Request.clone(), payload is null
+    includeCancelled: false, // default: keep client closes in access logs only
     filter: (event) => event.method !== 'GET',
   },
   tools: {
@@ -4923,6 +5260,40 @@ Each sink runs fire-and-forget and fails independently: a slow or broken request
 sink cannot block the response, suppress operational logging or break the tool
 sink.
 
+#### Client cancellation
+
+A physical client close is classified only when the request's own signal is
+aborted and the thrown value is either an `AbortError` or contains the exact
+`request.signal.reason` by identity at the top level or within at most eight
+standard `cause` links. Cause traversal is cycle-safe. No message or error-code
+matching is used; active requests and unrelated/deeper causes remain application
+failures. The access completion is always `499/info`, without application error
+fields or project `onError`.
+
+Structured request sinks are default-preserving: existing sinks receive no row
+for this outcome. Opt in when cancellation frequency belongs in the durable
+stream:
+
+```ts
+const observability = createObservability({
+  request: {
+    includeCancelled: true,
+    write: (event) => {
+      if (event.outcome === 'cancelled') return recordClientClose(event)
+      return recordApplicationRequest(event)
+    },
+  },
+})
+```
+
+An opted-in row has `outcome: 'cancelled'`, `ok: false`, `statusCode: 499`, the
+ordinary identity/trace/timing fields and no `errorCode`, `errorMessage` or
+`errorDetail`. `ok` remains the legacy success bit: branch on `outcome` first.
+Cancellation rows use the same filter, capacity, diagnostics, ordering,
+`flush()` and `close()` machinery as every request event. MCP protocol
+cancellation remains represented by `event.mcp.outcome`; Agent and CLI have no
+generic client-disconnect signal and are not inferred from error text.
+
 The fire-and-forget work has an explicit bounded lifecycle:
 
 ```ts
@@ -5003,7 +5374,8 @@ queryable across all three:
 | `httpMethod` | the contract verb on **tool** events (their `method` is `TOOL`) — filter reads vs writes across both surfaces with `(event.httpMethod ?? event.method) !== 'GET'` |
 | `dimensions` | app-defined domain dimensions (tenant / project / entity id) — see [request context](#request-context) |
 | `traceId` / `spanId` / `parentSpanId` | [W3C trace context](#trace-context) |
-| `ok` / `statusCode` | outcome — real HTTP status, or `200`/`400` for a tool |
+| `outcome` | optional `'cancelled'` on explicitly enabled HTTP client-close rows; ordinary rows omit it |
+| `ok` / `statusCode` | legacy success bit plus real HTTP status, or `200`/`400` for a tool; an opted-in cancellation is `false` / `499` |
 | `durationMs` / `startedAt` | timing |
 | `errorCode` / `errorMessage` / `errorDetail` | failures only — `errorDetail` carries the structure the message flattens (e.g. Zod issues) |
 | `payload` | sanitised tool arguments; HTTP is `null` unless request `includePayload` is enabled |
@@ -5253,6 +5625,10 @@ success and error alike — carrying the tool name, the arguments, the result, t
 duration, the call context, the endpoint identity, and (only when the call failed
 by throwing) the raw thrown value.
 
+A confirmed HTTP client disconnect is the exception to the raw-hook table: it
+is transport cancellation, so neither `afterHandle` nor project `onError` runs.
+Use the `499/info` access completion or opt-in request cancellation event above.
+
 ```ts
 createMcpHandler({
   serverInfo, auth, services,
@@ -7526,6 +7902,38 @@ Also re-exports the error helpers from `stitchkit/contract`.
 
 ---
 
+## `stitchkit/agent-runtime`
+
+Server-only optional application runtime. See the
+[agent runtime guide](../guide/agent-runtime.md).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createAgentRuntime` | function | compose durable acceptance, stream loop, checkpoints, coordination, managed tools and terminal publication |
+| `defineAgentProtocol` | function | declare and validate context, input metadata and canonical message parts |
+| `AgentMessageSchema` / `AgentRunSchema` / `AgentSnapshotSchema` | schema | versioned canonical engine records |
+| `AgentRuntimeStore` | _type_ | aggregate CAS transaction boundary for message, run and compaction mutations |
+| `RecoverAgentRunSchema` | schema | explicit abandon/requeue recovery decision; acquired runs require replay-safe evidence |
+| `createMemoryAgentRuntimeStore` | function | process-local reference adapter, not production durability |
+| `projectAgentHistory` | function | asynchronously project canonical records and resolved multimodal files into provider-valid AI SDK messages |
+| `defineModelRegistry` | function | typed language-model descriptors, capabilities and provider construction |
+| `composeAgentPrompt` | function | ordered prompt contributions and provenance-aware context budget |
+| `structuredCompaction` | function | summarize a provider-valid snapshot range and replace it through CAS |
+| `createAgentSessionCoordinator` | function | strict process-local queue/interrupt lifecycle |
+| `AgentRuntimeStopPolicy` | _type_ | named custom AI SDK stop condition persisted and published on policy stop |
+| `AgentRuntimePrepareStep` | _type_ | per-run controlled step callback with typed domain context and managed run signal/fence |
+| `AgentHistoryProjectionOptions` | _type_ | storage-neutral file resolver and explicit unresolved-file behavior |
+| `createAgentToolFenceLifecycle` | function | pre-effect and post-effect run ownership fence for `mountAgent` |
+| `AgentRuntimeEventSchema` | schema | transient delta, durable checkpoint/run-state/tool and terminal event union |
+| `createAgentObservability` | function | separate agent-run sink over the shared bounded observability lifecycle |
+
+## `stitchkit/agent-runtime/openrouter`
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `openRouterProvider` | function | isolated `@openrouter/ai-sdk-provider` language-model factory |
+| `OpenRouterProviderSettings` | _type_ | official provider settings accepted by the factory |
+
 ## `stitchkit/observability`
 
 Server-only. The audit layer one level above the raw hooks — W3C trace context,
@@ -7537,7 +7945,7 @@ audit event. See the [Observability guide](../guide/observability.md).
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createObservability` | function | configure framework-owned request completion and canonical tool event sinks — [guide](../guide/observability.md#createobservability) |
-| `RequestEvent` | _type_ | the normalised audit event handed to the sink |
+| `RequestEvent` | _type_ | the normalised audit event handed to the sink; opt-in HTTP cancellation rows carry `outcome: 'cancelled'` |
 | `ObservabilityConfig` | _type_ | independent request and tool sink configuration |
 | `Observability` | _type_ | `{ request?, toolCall, getStatus(), flush(), close() }` with bounded sink lifecycle |
 | `ObservabilitySinkStatus` | _type_ | immutable counters for one bounded request/tool sink |
@@ -7545,11 +7953,11 @@ audit event. See the [Observability guide](../guide/observability.md).
 | `ObservabilityDrainReport` | _type_ | final closed/drained snapshot plus duration |
 | `ObservabilitySinkStatusSchema` / `ObservabilityStatusSchema` / `ObservabilityDrainReportSchema` | schema | runtime schemas for status/report integration boundaries |
 | `RequestEventSinkConfig` | _type_ | `write`, filter/sanitisation, `maxPending`, `onSinkError` and `onDrop` |
-| `RequestObservabilityConfig` | _type_ | request sink plus opt-in payload capture |
+| `RequestObservabilityConfig` | _type_ | request sink plus opt-in payload capture and default-off `includeCancelled` rows |
 | `SinkDropReason` | _type_ | `'capacity' \| 'closed'` |
 | `SinkError` | _type_ | isolated sink/projection failure and optional event |
 | `SinkDrop` | _type_ | rejected event, reason and current pending count |
-| `HttpRequestCompletion` | _type_ | the single framework-owned HTTP outcome projected to logging and request events |
+| `HttpRequestCompletion` | _type_ | the single framework-owned HTTP outcome, including optional neutral cancellation, projected to logging and request events |
 | `HttpRequestObserver` | _type_ | server-facing projection consumed by `HandlerConfig.observability` |
 
 ### Request context
@@ -7699,6 +8107,9 @@ payload.
 | `Toolkit` | _type_ | the context-pinned tool surface from `createToolkit` |
 | `ToolExtend` | _type_ | extra-args extension for `mountMcp` / `mountAgent` |
 | `ToolLifecycle` | _type_ | `beforeHandle` / `afterHandle` gate for tool calls — [guide](../guide/mcp-and-agents.md#guarding-tools--lifecycle) |
+| `ToolExecutionControlReason` | _type_ | internal managed-execution stop reason: stale run or requested interruption |
+| `ToolExecutionControlError` | class | control-flow error used to unwind a superseded managed tool call without presenting it as a model-facing tool failure |
+| `isToolExecutionControlError` | function | narrow an unknown thrown value to the managed execution control error |
 | `ToolOperation` | _type_ | executable path-free operation shape shared by contract and framework-native runners |
 | `ToolCallHooks` | _type_ | object-shaped `beforeToolCall` / `afterToolCall` / `onToolError` observability hooks; the raw thrown value reaches the last two as `error` ([guide](../guide/observability.md#the-cause-behind-a-failed-tool-call)) |
 | `BeforeToolCallOptions` | _type_ | `{ toolName, args, context, endpoint }` passed before execution |

package/llms.txt

@@ -10,6 +10,7 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 - [HTTP server](https://github.com/max-listov/stitchkit/blob/master/docs/guide/server.md): createServer/createHandler, implement, lifecycle hooks, raw routes + raw-response endpoints + helpers, scopePrefixes, serveFile, primitives
 - [Typed client](https://github.com/max-listov/stitchkit/blob/master/docs/guide/client.md): createClient/createHttpClient, the typed call surface, scoped clients, SSE
 - [MCP & agents](https://github.com/max-listov/stitchkit/blob/master/docs/guide/mcp-and-agents.md): contracts as MCP tools (createMcpHandler) and AI-agent tools (mountAgent); tool lifecycle, extend, identity
+- [Agent application runtime](https://github.com/max-listov/stitchkit/blob/master/docs/guide/agent-runtime.md): optional durable history, prompt/model composition, stream loop, coordination, fencing and events
 - [CLI](https://github.com/max-listov/stitchkit/blob/master/docs/guide/cli.md): contracts as a command-line program
 - [Realtime](https://github.com/max-listov/stitchkit/blob/master/docs/guide/realtime.md): Socket.IO server/client wrappers, handshake auth, the cache bridge, a raw WebSocket lane
 - [Auth & errors](https://github.com/max-listov/stitchkit/blob/master/docs/guide/auth-and-errors.md): scopes, createAuthHook, JWT/cookies, the AppError model, the stitch error-code registry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.56.0",
+  "version": "0.56.2",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",
@@ -76,6 +76,14 @@
       "types": "./dist/observability/index.d.ts",
       "import": "./dist/observability/index.js"
     },
+    "./agent-runtime": {
+      "types": "./dist/agent-runtime.d.ts",
+      "import": "./dist/agent-runtime.js"
+    },
+    "./agent-runtime/openrouter": {
+      "types": "./dist/agent-runtime-openrouter.d.ts",
+      "import": "./dist/agent-runtime-openrouter.js"
+    },
     "./testing": {
       "types": "./dist/testing.d.ts",
       "import": "./dist/testing.js"
@@ -95,7 +103,7 @@
   "scripts": {
     "check": "bun x tsc --noEmit",
     "build:browser": "bun build src/index.ts src/react.ts src/contract/index.ts --outdir dist --target node --packages external --splitting --root src",
-    "build:server": "bun build src/server/index.ts src/node.ts src/tools.ts src/cli.ts src/remote.ts src/files.ts src/testing.ts src/observability/index.ts --outdir dist --target node --packages external --splitting --root src",
+    "build:server": "bun build src/server/index.ts src/node.ts src/tools.ts src/cli.ts src/remote.ts src/files.ts src/testing.ts src/observability/index.ts src/agent-runtime.ts src/agent-runtime-openrouter.ts --outdir dist --target node --packages external --splitting --root src",
     "build:js": "bun run build:browser && bun run build:server",
     "build:types": "bun x tsc -p tsconfig.build.json --emitDeclarationOnly",
     "build": "rm -rf dist && bun run build:js && bun run build:types && bun scripts/check-browser-clean.mjs && bun scripts/check-env-live.mjs && bun scripts/check-public-types.mjs",
@@ -110,6 +118,7 @@
   "peerDependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.2",
     "@modelcontextprotocol/server": "^2.0.0",
+    "@openrouter/ai-sdk-provider": "^3.0.0",
     "@types/bun": "^1.3.14",
     "@socket.io/bun-engine": "^0.1.1",
     "@socket.io/component-emitter": "^3.1.2",
@@ -132,6 +141,9 @@
     "@modelcontextprotocol/server": {
       "optional": true
     },
+    "@openrouter/ai-sdk-provider": {
+      "optional": true
+    },
     "@socket.io/bun-engine": {
       "optional": true
     },
@@ -164,9 +176,10 @@
     "ky": "^2.0.2"
   },
   "devDependencies": {
-    "@modelcontextprotocol/ext-apps": "^1.7.5",
     "@modelcontextprotocol/client": "^2.0.0",
+    "@modelcontextprotocol/ext-apps": "^1.7.5",
     "@modelcontextprotocol/server": "^2.0.0",
+    "@openrouter/ai-sdk-provider": "^3.0.0",
     "@socket.io/bun-engine": "^0.1.1",
     "@socket.io/component-emitter": "^3.1.2",
     "@tanstack/react-query": "5.101.4",