stitchkit 0.85.2 → 0.87.0

package/llms-full.txt

@@ -63,11 +63,12 @@ own, recorded as an ADR.
 | `stitchkit/tracking/server` | server (Bun or Node) | evolving | the decisions a tracking backend makes — dispositions, visit lease over an application-owned store, active intervals, presence; no database |
 | `stitchkit/release` | browser **and** server | evolving | a page follows the release it was built for — `createReleaseMarker` on the server, `createReleaseWatcher` in the browser, the `X-Build-Id` header and a socket event between them |
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 1 of the 30 minors since 0.56.2, most recently 0.83.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 1 of the 32 minors since 0.56.2, most recently 0.83.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the store and managed-resource conformance kits |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 16 of the 30 minors since 0.56.2, most recently 0.85.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 18 of the 32 minors since 0.56.2, most recently 0.87.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults and deterministic race controls |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
 | `stitchkit/agent-runtime/coding-tools` | server (Bun or Node) | evolving | bounded host-authorized direct file and shell tools; a root boundary, not an OS sandbox |
 | `stitchkit/agent-runtime/openrouter` | server | evolving | isolated OpenRouter language-model adapter |
@@ -75,7 +76,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 7 of the 30 minors since 0.56.2, most recently 0.83.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 7 of the 32 minors since 0.56.2, most recently 0.83.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
@@ -4854,8 +4855,14 @@ and supplies atomicity; Stitchkit owns transition validation and revision
 arithmetic. The executable reference is
 [`examples/agent-store-prisma/adapter.ts`](../../examples/agent-store-prisma/adapter.ts).
 `compareAndSwap` returns either `{ outcome: 'applied' }` or
-`{ outcome: 'conflict', actualVersion }`. The head contains only schema version,
-conversation identity and monotonic version. Runs and admission receipts are normalized records;
+`{ 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.
@@ -4884,7 +4891,7 @@ const sqlite = createNodeSqliteAgentRuntimeStore({ filename: './agent-runtime.sq
 ```
 
 Initialization creates only `stitchkit_agent_runtime_*` tables and records
-schema version 1 in `stitchkit_agent_runtime_meta`; it does not use
+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.
@@ -4908,6 +4915,136 @@ 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:
+
+```ts
+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 first message it replaced, so it appears at the head of the block it
+stands for. 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.
+
+### Event ledger, projections and durable capabilities
+
+`AgentRuntimeStore` exposes bounded `readEvents`, declared `appendEvent`,
+canonical `exportConversation` and empty-target `importConversation`. Runtime
+transitions and exact provider requests enter the same append-only ledger; the
+normalized head/run/message tables remain the fast operational projection.
+
+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:
+
+```ts
+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. `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.
+`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
@@ -5261,6 +5398,12 @@ transaction. Drivers without this guarantee must leave the capability absent. Se
 
 ## 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
@@ -5382,8 +5525,12 @@ prepareStep: (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: every other `prepareStep` or provider error remains
-`provider_failure`, and operator-only observability retains its original cause.
+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:
@@ -10096,6 +10243,38 @@ sink never escapes into application code.
 stitchkit's own test suite runs on `bun:test`. The contract makes most of an
 API testable without a live socket.
 
+### Agent runtime faults and replay
+
+`stitchkit/agent-runtime/testing` is a credential-free test entrypoint for Bun
+and Node. It provides a local OpenAI-compatible SSE server with a deterministic
+fault plan, a replay provider for model fixtures, and named race barriers for
+event-order assertions:
+
+```ts
+import {
+  createFaultProviderServer,
+  createReplayAgentProvider,
+} from 'stitchkit/agent-runtime/testing'
+
+const server = await createFaultProviderServer({
+  scenario: [
+    { kind: 'stream-cut', afterBytes: 50 },
+    { kind: 'pass', text: 'recovered' },
+  ],
+})
+
+const provider = createReplayAgentProvider({
+  attempts: { primary: [firstModel, recoveredModel] },
+})
+```
+
+The fault vocabulary also covers connection refusal, timeout before the first
+byte, HTTP errors, malformed JSON, slow streams and missing usage. Configure
+runtime retry explicitly through `loop.retry`. A retry is recorded at the
+durable provider-step boundary; once a tool has executed, the runtime will not
+replay that attempt automatically. Always close the local server in test
+teardown with `await server.close()`.
+
 ### Test generated clients in process
 
 `createHandlerTestClient` runs the real generated client against the real Fetch
@@ -11048,6 +11227,143 @@ of the range if you want a different one.
 So upgrading is: read the `### ⚠️ Breaking changes` of every version *above* your
 current one *up to* your target, and apply each snippet.
 
+## Released migration: 0.87.0
+
+Only if your project implements `AgentConversationReader` itself. A message page
+now names which of its messages compaction removed:
+
+```ts
+// before
+return { items, ...(nextCursor && { nextCursor }) }
+
+// after
+return { items, compacted: [], ...(nextCursor && { nextCursor }) }
+```
+
+An empty array is the honest answer for a reader that pages only the active
+history; it is what the SQLite reader returns unless the caller asks for
+`includeCompacted`. Calling the reader needs no change, and no data migration is
+involved.
+
+## Released migration: 0.86.0
+
+Only if you branch on `AgentTerminalReason` or show it to a person. Three
+failures that used to arrive as `provider_failure` now arrive as themselves:
+
+```ts
+// before
+if (run.terminalReason === 'provider_failure') showOutage()
+
+// after
+switch (run.terminalReason) {
+  case 'provider_failure':
+    showOutage()
+    break
+  case 'storage_conflict':
+    // Another writer took this run's revision, or the store refused the write.
+    retryOrReport()
+    break
+  case 'output_rejected':
+    // Your own `protocol.acceptTerminal` refused the finished message.
+    reportRejectedAnswer()
+    break
+  case 'runtime_failure':
+    // The runtime, or a check the SDK ran on what it was handed, failed
+    // before the provider was reached.
+    reportInternal()
+    break
+}
+```
+
+A run that never reached the provider can no longer report `provider_failure`,
+so an alert keyed on that value stops firing for causes that were never the
+provider's.
+
+If you implement `AgentRuntimeStore` directly, add the event-ledger surface:
+
+```ts
+const store: AgentRuntimeStore = {
+  // existing normalized operations
+  appendEvent,
+  readEvents,
+  exportConversation,
+  importConversation,
+}
+```
+
+If you implement an `AgentRuntimeStoreDriver` (Prisma, Postgres, any external
+database), the ledger is yours to keep: `events` is a required member, and it
+needs a table.
+
+```ts
+// before
+const driver: AgentRuntimeStoreDriver<Tx> = { transaction, head, runs, admissions, history, scanRecoverable }
+
+// after
+const driver: AgentRuntimeStoreDriver<Tx> = {
+  transaction, head, runs, admissions, history, scanRecoverable,
+  events: {
+    // One row per event; `seq` is per conversation, starts at 1, and is
+    // assigned inside the caller's transaction so concurrent appends cannot
+    // share or skip a number.
+    append: async (tx, draft) => {
+      // Two transactions that both read max(seq) and both insert max + 1
+      // collide on the primary key; under SERIALIZABLE the snapshot predates
+      // any lock you take here. Treat a unique violation on this table as a
+      // serialization conflict and re-run the whole transaction — see
+      // `runTransaction` in examples/agent-store-prisma/adapter.ts.
+      const seq = (await tx.event.aggregate({ _max: { seq: true }, where: { conversationId: draft.conversationId } }))._max.seq ?? 0
+      await tx.event.create({ data: { ...draft, seq: seq + 1, payload: JSON.stringify(draft.payload) } })
+      return { ...draft, seq: seq + 1 }
+    },
+    // Ordered by `seq`, bounded by `fromSeq`/`toSeq`/`limit`; `nextSeq` when
+    // more remain.
+    list: async (tx, input) => { /* see examples/agent-store-prisma/adapter.ts */ },
+  },
+}
+```
+
+The table carries `eventId` (unique), `conversationId`, `seq`, `schemaVersion`,
+`kind`, `occurredAt`, `ignorable` and `payload`. `runAgentStoreConformance`
+from `stitchkit/testing` now exercises it — contiguous `seq` under twenty
+concurrent appends, bounded reads, the `ignorable` flag, a byte-stable export
+— so run it against your driver before deploying. Expect one more insert per
+run operation (`runtime/transition`) and one per model step
+(`provider/request`) on the hot path; there is no opt-out.
+
+If you operate a built-in SQLite store file:
+
+1. Back the file up. The first open by 0.86.0 migrates it to schema 2 in one
+   transaction and there is no way back: a 0.85.x package refuses a migrated
+   file with `Unsupported Stitchkit agent-runtime SQLite schema version 2`.
+2. Check the build for FTS5 before deploying:
+
+   ```sql
+   SELECT sqlite_compileoption_used('ENABLE_FTS5');
+   ```
+
+   A build without it is refused at open with `requires FTS5 support`. On the
+   machine this was verified, Bun 1.3 `bun:sqlite` and Node 24.18 `node:sqlite`
+   both carry it; verify your own build rather than assuming — the table of
+   supported runtimes says Node ≥ 22.5, and FTS5 there is not verified here.
+3. Know what the migration wrote. Each existing conversation becomes one
+   `runtime/baseline` event at `seq 1`, dated when the migration ran, with
+   `asOf` inside the payload naming the last message it describes. Event
+   search and projections address that conversation's pre-migration history as
+   one snapshot at `seq 1`; event-level precision begins with the first event
+   after the migration.
+
+If you subscribe to `AgentRuntimeEvent` and switch over `event.type`
+exhaustively, add the transient `attempt-reset` case — drop the run's
+transient text — or the reducer stops compiling; a reducer that ignores it
+keeps a failed attempt's partial text on screen.
+
+New in this release, not a migration: child runs cascade only when the manager
+is given to the runtime —
+`createAgentRuntime({ ...config, children: createSqliteAgentChildManager({ sqlite, spawn }) })`
+— and the SQLite companions take the store handle (`{ sqlite }`), whose
+`database` and `transaction` they share.
+
 ## Released migration: 0.85.0
 
 Only if you implement `AgentRuntimeStore` directly. Add the new durable
@@ -15144,7 +15460,8 @@ Server-only optional application runtime. See the
 | `AgentRunQueuePrioritySchema` | schema | durable opt-in priority for queued `interrupt-next` runs |
 | `AgentRuntimeStore` | _type_ | aggregate CAS transaction boundary for message, run and compaction mutations |
 | `createAgentRuntimeStore` | function | build the aggregate store from one coherent transaction driver; framework owns every state transition |
-| `AgentRuntimeStoreDriver` | _type_ | ORM-neutral transaction over a bounded head, normalized runs/admissions, product history and indexed run recovery; optional `{ access: 'read' }` selects a coherent read transaction while absent options remain write-safe |
+| `AgentRuntimeStoreDriver` | _type_ | ORM-neutral transaction over a bounded head, normalized runs/admissions, product history, a **required** `events: { append, list }` ledger table, an optional `archive: { export, import }` for driver-owned durable payloads, and indexed run recovery; optional `{ access: 'read' }` selects a coherent read transaction while absent options remain write-safe |
+| `recordAgentRetryDecision` / `AgentRetryPolicy` | function / _type_ | `loop.retry` policy and the ledger record of a retry decision: explicit retryability and backoff at a durable provider-step boundary |
 | `AgentRuntimeHeadSchema` | schema | constant-size conversation identity plus monotonic runtime version |
 | `AgentStoredRunSchema` | schema | canonical normalized run with an optional retained terminal assistant |
 | `AgentAdmissionReceiptSchema` | schema | durable idempotency receipt with canonical input and assigned run/assistant identities |
@@ -15169,7 +15486,7 @@ Server-only optional application runtime. See the
 | `searchAgentModelCatalog` | function | deterministic bounded search over a loaded canonical catalog |
 | `AgentModelSelectionSchema` / `AgentModelSelection` / `AgentModelSelectionStore` | schema / _type_ | durable per-conversation model choice; runtime resolvers receive run and snapshot to recover the model pinned to input metadata |
 | `createMemoryAgentModelSelectionStore` | function | process-local selection reference adapter |
-| `AgentConversationReader` | _type_ | optional bounded conversation-summary and message-history reader; not part of the required runtime store contract |
+| `AgentConversationReader` | _type_ | optional bounded conversation-summary and message-history reader; `messages` takes `includeCompacted` and every page names its `compacted` ids; not part of the required runtime store contract |
 | `AgentConversationSummarySchema` / `AgentConversationSummary` | schema / _type_ | bounded durable conversation list item with version, activity and preview |
 | `AgentConversationPageSchema` / `AgentConversationPage` | schema / _type_ | cursor-paged conversation summaries |
 | `AgentConversationMessagePageSchema` / `AgentConversationMessagePage` | schema / _type_ | cursor-paged durable message history |
@@ -15196,6 +15513,29 @@ Server-only optional application runtime. See the
 | `RecordRunOperationSchema` / `RecordRunOperation` | schema / _type_ | owner/fencing/revision-checked mutation of `AgentRun.lastOperation` |
 | `createAgentObservability` | function | separate agent-run sink over the shared bounded observability lifecycle |
 
+### Durable capability layer
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `AgentConversationArchiveSchema` / `AgentConversationArchive` / `encodeAgentConversationArchive` / `decodeAgentConversationArchive` / `canonicalAgentJson` | schema / _type_ / functions | canonical validated conversation archive with exact ledger events, recovery projection and durable spill payloads |
+| `AgentStoreEventEnvelopeSchema` / `AgentStoreEventEnvelope` / `AgentStoreEventKindSchema` / `AgentStoreEventKind` / `AgentStoreEventPageSchema` / `AgentStoreEventPage` | schema / _type_ | append-only event envelope, closed current vocabulary and bounded page |
+| `AppendAgentStoreEventSchema` / `AppendAgentStoreEvent` / `ReadAgentStoreEventsSchema` / `ReadAgentStoreEvents` | schema / _type_ | required append and bounded-read store contracts |
+| `AgentStoreTransitionSchema` / `AgentStoreTransition` / `AgentStoreEventDraft` / `AgentStoreEventDecodeAccepted` / `AgentStoreEventDecodeIgnored` / `AgentStoreEventDecodeResult` / `decodeAgentStoreEvent` | schema / _types_ / function | normalized runtime mutations, append drafts and strict current/ignorable future-event decoding outcomes |
+| `defineAgentProjection` / `AgentProjectionDefinition` / `AgentProjectionValue` / `createAgentProjectionRegistry` / `createSqliteAgentProjectionStore` | functions / _type_ | deterministic folds with persisted version and honest `uptoSeq` checkpoints |
+| `agentSummaryProjection` / `agentUsageProjection` / `agentOutlineProjection` | constants | built-in list summary, provenance-carrying usage and request outline projections |
+| `agentConversationCardProjection` / `agentStateSlotsProjection` / `agentScheduleSummaryProjection` | constants | focused card, durable-state and schedule lifecycle projections |
+| `defineStateSlot` / `AgentStateSlotDefinition` / `AgentStateSlotStore` / `AgentStateSlotValue` / `AnyAgentStateSlot` / `createAgentStateSlotStore` / `renderAgentStateSlots` | functions / _types_ | typed durable state written as ledger events and injected on every provider request |
+| `agentGoalStateSlot` / `agentTodoStateSlot` / `createAgentStateTools` | constants / function | built-in goal/todo state and bound `goal_*` / `todo_write` Agent tools |
+| `AgentSandboxGradeSchema` / `AgentSandboxGrade` / `AgentSandboxRestrictionSchema` / `AgentSandboxRestriction` / `AgentProcessSandbox` | schema / _type_ | host-provided process sandbox capability and explicit restriction vocabulary |
+| `probeAgentProcessSandbox` / `missingSandboxRestrictions` / `recordAgentSandboxProbe` | functions | process-cached probe, fail-closed required-gap calculation and durable probe record |
+| `AgentEventSearchResultSchema` / `AgentEventSearchResult` / `createSqliteAgentEventSearch` / `createAgentEventSearchTools` | schema / _type_ / functions | authorized FTS5 search with exact event addresses and `session_*` tools |
+| `createSqliteAgentSpillStore` | function | durable content-address-checked artifact storage, bounded read/search, retention facts and archive participation |
+| `AgentScheduleSchema` / `AgentSchedule` / `AgentScheduleService` / `createAgentScheduleService` / `createAgentScheduleTools` | schema / _types_ / functions | durable `at`/`after`/timezone-explicit `every`, stable dispatch identity and Agent tools |
+| `AgentChildBudgetSchema` / `AgentChildBudget` / `AgentChildStateSchema` / `AgentChildState` / `AgentChildRecordSchema` / `AgentChildRecord` | schema / _type_ | durable child graph, bounded seed and measured budget state |
+| `AgentChildHandle` / `AgentChildManager` / `createSqliteAgentChildManager` / `createAgentChildTools` / `agentChildBudgetStopPolicy` | _type_ / functions | host execution port, child lifecycle, cascade (given to `createAgentRuntime` as `children`), messaging, Agent tools, and the child runtime's own budget stop policy — `recordStepUsage` at every step boundary, `policy_stop` as `child-budget` when spent |
+| `AgentToolDefinition` | _type_ | peer-neutral shape returned by the bound agent-only state, search, schedule and child tool factories |
+| `AgentProviderStreamCutError` | class | explicit retryable provider stream truncation evidence |
+
 ### Complete runtime inventory
 
 The entrypoint deliberately exports the schemas beside their inferred types so persistence and
@@ -15322,7 +15662,7 @@ Model exports are `AgentLanguageModelProvider`, `AgentModelCapability`,
 provider and required capabilities without constructing the model; runtime `models.preflight`
 runs before durable admission.
 
-Delivery exports are `AgentAdmissionEventSchema`, `AgentCheckpointEventSchema`,
+Delivery exports are `AgentAdmissionEventSchema`, `AgentAttemptResetEventSchema`, `AgentCheckpointEventSchema`,
 `AgentRunStateEventSchema`, `AgentRunOperationEventSchema`, `AgentTerminalEventSchema`,
 `AgentTransientDeltaEventSchema`,
 `AgentReasoningStartEventSchema`, `AgentReasoningDeltaEventSchema`,
@@ -15340,6 +15680,20 @@ Managed effects and operator telemetry additionally export `AgentToolFenceConfig
 may accompany checkpoint/terminal writes and tool context; internal causes are redacted unless an
 operator-only observability sink explicitly opts in.
 
+## `stitchkit/agent-runtime/testing`
+
+Credential-free provider and concurrency fixtures for Bun and Node tests.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createFaultProviderServer` | function | start an OpenAI-compatible local SSE endpoint with deterministic pass, connection-refused, timeout, stream-cut, HTTP, malformed JSON, slow-stream and missing-usage steps |
+| `AgentFaultStepSchema` / `AgentFaultStep` | schema / _type_ | strict fault-plan step vocabulary |
+| `defineAgentFaultPlan` | function | validate a non-empty deterministic fault sequence |
+| `createReplayAgentProvider` | function | serve a declared sequence of credential-free language-model fixtures per model ID |
+| `createAgentRaceBarrier` / `AgentRaceBarrier` | function / _type_ | named bounded deterministic concurrency barrier |
+| `createAgentRaceTrace` / `AgentRaceTrace` / `AgentRaceTraceEntry` | function / _type_ | record and assert exact event order without wall-clock guesses |
+| `createAgentRaceDriver` / `AgentRaceDriver` | function / _type_ | collect named barriers and release their teardown together |
+
 ## `stitchkit/agent-runtime/harness`
 
 Server-only evolving facade over the canonical Agent runtime. It requires the optional `ai` peer
@@ -15411,7 +15765,8 @@ not path filtering, to constrain its filesystem access. → ADR 0172.
 
 Browser-safe canonical agent data. It re-exports the run, message, part, usage,
 terminal and provider-envelope schemas/types listed under
-`stitchkit/agent-runtime`, together with all runtime delivery event schemas,
+`stitchkit/agent-runtime`, together with all runtime delivery event schemas (durable and transient,
+including `AgentAttemptResetEventSchema` for `attempt-reset`),
 `AgentRuntimeEventCursorSchema`, `advanceAgentRuntimeEventCursor`,
 `AgentControlRequestSchema` / `AgentControlRequest`, `AgentControlResponseSchema` /
 `AgentControlResponse`, `AgentControlDeliverySchema` / `AgentControlDelivery`, `AgentMultiSessionCursorSchema` /
@@ -15442,12 +15797,12 @@ loaded by the neutral, browser or Node runtime surfaces.
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `createBunSqliteAgentRuntimeStore` | function | open an owned Bun SQLite connection, initialize/validate schema v1 and return `{ store, conversations, close }` |
+| `createBunSqliteAgentRuntimeStore` | function | open an owned Bun SQLite connection, initialize/validate schema v2, migrate v1 transactionally and return `{ store, conversations, database, transaction, close }` |
 | `BunSqliteAgentRuntimeStoreConfig` | _type_ | database filename plus optional create and initialization policies |
 | `createSqliteAgentRuntimeStore` | function | build the normalized store over an injected synchronous SQLite boundary |
 | `initializeAgentRuntimeSqlite` | function | initialize or validate only Stitchkit's namespaced SQLite schema |
 | `SqliteDatabase` / `SqliteStatement` / `SqliteValue` | _type_ | minimal runtime-neutral synchronous SQLite boundary |
-| `SqliteAgentRuntimeStore` / `SqliteAgentRuntimeStoreConfig` | _type_ | durable store handle, owned connection lifecycle and initialization policy |
+| `SqliteAgentRuntimeStore` / `SqliteAgentRuntimeStoreConfig` / `SqliteStoreTransaction` | _type_ | durable store handle — `store`, `conversations`, `database`, `transaction`, `close` — owned connection lifecycle, initialization policy, and the one write transaction the SQLite companions share |
 
 ---
 
@@ -15498,11 +15853,11 @@ the Bun leaf but imports only `node:sqlite`.
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `createNodeSqliteAgentRuntimeStore` | function | open an owned Node `DatabaseSync`, initialize/validate schema v1 and return `{ store, close }` |
+| `createNodeSqliteAgentRuntimeStore` | function | open an owned Node `DatabaseSync`, initialize/validate schema v2, migrate v1 transactionally and return `{ store, conversations, database, transaction, close }` |
 | `NodeSqliteAgentRuntimeStoreConfig` | _type_ | database filename plus optional read-only and initialization policies; read-only requires an initialized schema |
 | `createSqliteAgentRuntimeStore` / `initializeAgentRuntimeSqlite` | function | shared normalized adapter and namespaced schema lifecycle |
 | `SqliteDatabase` / `SqliteStatement` / `SqliteValue` | _type_ | minimal runtime-neutral synchronous SQLite boundary |
-| `SqliteAgentRuntimeStore` / `SqliteAgentRuntimeStoreConfig` | _type_ | durable store handle, owned connection lifecycle and initialization policy |
+| `SqliteAgentRuntimeStore` / `SqliteAgentRuntimeStoreConfig` / `SqliteStoreTransaction` | _type_ | durable store handle — `store`, `conversations`, `database`, `transaction`, `close` — owned connection lifecycle, initialization policy, and the one write transaction the SQLite companions share |
 
 ## `stitchkit/observability`
 
@@ -15621,6 +15976,8 @@ payload.
 | `validateMcpSchemas` | function | object-shaped assertion over the exact advertised schema surface — compatibility, typed properties and portable formats ([guide](../guide/mcp-and-agents.md#mcp-schema-validation-profile)) |
 | `listToolNames` | function | every contract/runtime tool name with origin, identity and transports — for stable snapshots — [guide](../guide/mcp-and-agents.md#pinning-tool-names--listtoolnames) |
 | `listContractToolNames` | function | the same listing straight from contracts — no handlers or stub services needed |
+| `describeToolCatalog` | function | inspect the exact model-facing names, source identities, schema byte sizes and deferred state; an explicit total byte budget fails closed |
+| `ToolCatalogConfig` / `ToolCatalogEntry` | _type_ | catalog source, transport, optional explicit schema budget and one inspectable result row |
 | `McpHandlerConfig` | _type_ | server surface plus stateless HTTP transport config |
 | `McpHttpConfig` | _type_ | HTTP auth, protected-resource, legacy-era and security options |
 | `McpHttpHandler` | _type_ | framework-owned `{ fetch(request), close() }` lifecycle |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.85.2",
+  "version": "0.87.0",
   "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",
@@ -101,6 +101,10 @@
       "types": "./dist/agent-runtime.d.ts",
       "import": "./dist/agent-runtime.js"
     },
+    "./agent-runtime/testing": {
+      "types": "./dist/agent-runtime-testing.d.ts",
+      "import": "./dist/agent-runtime-testing.js"
+    },
     "./agent-runtime/harness": {
       "types": "./dist/agent-runtime-harness.d.ts",
       "import": "./dist/agent-runtime-harness.js"
@@ -198,6 +202,7 @@
     "smoke:next-ssr": "node scripts/next-ssr-retry-smoke.mjs",
     "consumer-lane": "bun scripts/consumer-lane/run.mjs",
     "bench:mcp-preparation": "bun scripts/benchmark-mcp-preparation.ts",
+    "bench:durable-store": "bun scripts/bench-durable-store.ts",
     "build:entrypoints": "bun scripts/build-entrypoints.mjs"
   },
   "peerDependencies": {