stitchkit 0.65.1 → 0.66.1

package/llms-full.txt

@@ -58,7 +58,7 @@ own, recorded as an ADR.
 | `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` | build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser | stable | `createCursorQuery`, `createCacheBridge` |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 8 of the 10 minors since 0.56.2, most recently 0.65.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 9 of the 11 minors since 0.56.2, most recently 0.66.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/openrouter` | server | evolving | isolated OpenRouter language-model adapter |
 | `stitchkit/application` | server | evolving | managed resource graph, readiness, admission, schedules and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
@@ -3683,15 +3683,14 @@ input + queued run → running → execution settled → terminal CAS → succes
 
 ## What happens to a run when new input arrives
 
-`runs.inputPolicy` decides. It takes three values, or a function returning one;
-the fourth row is a behaviour that shipped and was withdrawn:
+`runs.inputPolicy` decides. It takes four values, or a function returning one:
 
 | policy | the run in flight | what it already produced |
 |--------|-------------------|--------------------------|
 | `queue` (default) | finishes first | kept |
+| `inject` | continues, and answers the new input too | kept, and built on |
 | `interrupt` | ends | kept, and marked as cut off |
 | `supersede` | ends | discarded from the prompt, kept in the record |
-| _inject_ | continues | withdrawn in 0.65.0 — see below |
 
 `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
@@ -3775,19 +3774,53 @@ const { decisions } = await projectAgentHistoryDetailed(snapshot.messages)
 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.
 
-### The one that is not offered
+### 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.
 
-**inject** — hand the input to the loop between tool calls and let the run
-continue — shipped in 0.63.0 and was **withdrawn in 0.65.0**. It committed the
-absorption durably at a step boundary, before the answer existed, and everything
-downstream of that ordering was wrong: an accepted input could end up in a state
-that was neither active, recoverable nor terminal, so `close()` could report
-`settled: true` while leaving it permanently unanswerable, and a duplicate
-submission of the same idempotency key was refused forever.
+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.
 
-The redesign is tracked in the backlog and is not a patch to what shipped: the
-absorption has to commit atomically **with** the terminal record, so that a run
-which ends first simply leaves an ordinary queued successor behind.
+(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;
@@ -3850,7 +3883,7 @@ problem, and omitting a run's cost is an operator's.
 ## Store operations
 
 `AgentRuntimeStore` remains the runtime-facing aggregate. Application adapters
-implement the smaller `AgentRuntimeStoreDriver` rather than these nine members:
+implement the smaller `AgentRuntimeStoreDriver` rather than these eleven members:
 
 - `acceptInputAndAssignRun`
 - `acquireRun`
@@ -3859,11 +3892,37 @@ implement the smaller `AgentRuntimeStoreDriver` rather than these nine members:
 - `recoverRun`
 - `commitRunTerminal`
 - `replaceCompactedRange`
-- `loadSnapshot`
+- `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.
@@ -4112,8 +4171,14 @@ outbox.
 `stitchkit/testing` exports `createAgentRaceBarrier`, `createAgentRaceDriver` and
 `createAgentRaceTrace`. 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, compaction and recovery
-invariants against any fresh durable adapter.
+coalescing, collision, stale checkpoint, replay safety, terminal race, absorption, bounded reads,
+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.
 
 
 ==============================================================================
@@ -7797,9 +7862,28 @@ Prisma adapter, an in-memory one, anything — run the conformance kit against i
 ```ts
 import { runAgentStoreConformance } from 'stitchkit/testing'
 
-await runAgentStoreConformance({ store: yourStore, conversationId: 'conformance' })
+await runAgentStoreConformance({ createStore: () => yourStore })
 ```
 
+The kit picks the conversation identities itself and hands them over **before**
+the first mutation, so a store whose runtime rows hang off an application-owned
+conversation row can provision the parents — and take them away again:
+
+```ts
+await runAgentStoreConformance({
+  createStore: (context) => {
+    for (const conversationId of context.conversationIds) createConversationRow(conversationId)
+    return yourStore
+  },
+  cleanup: (context) => {
+    for (const conversationId of context.conversationIds) deleteConversationRow(conversationId)
+  },
+})
+```
+
+`cleanup` runs exactly once, after the scenario, whether it passed or failed —
+and a failure in it never replaces the scenario's own.
+
 Green before and red after tells you the contract grew and where, in one run,
 instead of one failure at a time in production. Green both times means the
 upgrade owes you nothing on that surface — which is the usual answer if you
@@ -7844,6 +7928,149 @@ implement `AgentRuntimeStoreDriver` and compose the aggregate with
    runtime): bootstrap the server, one HTTP request, and any feature you rely on
    (Socket.IO connect, an MCP tool call, a multipart upload, …).
 
+## Released migration: 0.66.0
+
+Three changes, and only one of them is a feature. The other two are shapes that
+would have had to break later: a vocabulary that described one fact with two
+words, and a store whose only read was the whole conversation.
+
+The compiler points at most of it. Two things change with no compile error —
+what a **total** says about its own provenance, and the fact that token counts
+are now validated where they were not.
+
+### An input that joins a run in flight
+
+#### If you matched exhaustively on `AgentTerminalReason`
+
+`'absorbed'` is new. A run ends this way when a run already in flight took its
+input on and answered it; its state is `'superseded'`, and `absorbedIntoRunId`
+names the run that has the answer.
+
+```ts
+// after
+switch (run.terminalReason) {
+  // …
+  case 'absorbed':
+    // no assistant message of its own — follow run.absorbedIntoRunId
+    break
+}
+```
+
+A run record with `terminalReason: 'absorbed'` and no `absorbedIntoRunId` is
+refused at parse time, and so is `absorbedIntoRunId` on any other reason.
+
+#### If you render or export runs
+
+An absorbed run has **no assistant message**. Anything that assumes "every
+terminal run has one" needs the `absorbed` case — the answer is on the run
+`absorbedIntoRunId` names, and `store.loadRun` resolves it.
+
+#### If you want the policy
+
+```ts
+// after
+runs: { inputPolicy: 'inject' }
+```
+
+It was withdrawn in 0.65.0 and is back with the ordering corrected: the
+absorption commits with the terminal record, not at the step boundary. Read
+*An input that joins a run in flight* in the agent-runtime guide before turning
+it on — in particular what happens when the absorbing run does not complete, and
+how it composes with `coalescePending`.
+
+#### If you implement a store driver
+
+Nothing to do, but know what changed underneath: one terminal commit can now
+save **two** run records, and they must land in the same transaction. A driver
+that persists one of the pair fails `runAgentStoreConformance`.
+
+### A run read without its conversation
+
+#### If you implement `AgentRuntimeStore` by hand
+
+Two members to add. **If your adapter is an `AgentRuntimeStoreDriver` passed to
+`createAgentRuntimeStore`, there is nothing to do** — the driver already had
+everything both need.
+
+```ts
+// after
+loadRun(input: { conversationId: string; runId: string }): Promise<AgentRunView | undefined>
+listActiveRuns(conversationId: string): Promise<readonly AgentRun[]>
+```
+
+`AgentRunView` is `{ snapshotVersion, run, assistant? }`. `assistant` is the
+retained terminal answer, so it is present exactly when the run has ended and
+absent while it is live — a store that returns a live run's draft here lets the
+terminal path resolve a run that has not finished. `listActiveRuns` orders by
+`createdAt` then `id`, and must not report a run that has ended.
+`runAgentStoreConformance` covers both, including the boundary cases.
+
+#### If you have a store **double** in your tests
+
+The runtime now reads `loadRun` where it used to read `loadSnapshot`. A double
+that simulates a condition — a run drifting to another owner, a stale fencing
+token — must apply it to both reads, or the code under test will not see it.
+This is not hypothetical: it turned one of this repository's own fixtures into
+an infinite retry loop, which is how the bounded retry below was found.
+
+#### Nothing else changes
+
+`loadSnapshot` behaves exactly as before, and still returns the whole
+conversation — as does every mutation result. What it costs, and what bounds it,
+is now written down in *Reading a conversation* in the agent-runtime guide.
+
+### One provenance vocabulary, and integral tokens
+
+#### If you match on `'measured'`
+
+A **total** now says `computed`, because it is a sum this code performed rather
+than a count it took — the same rule `AgentUsage` has always applied to a run's
+spend. Two values change with no compile error:
+
+```ts
+// before
+if (result.totalTokens.provenance === 'measured') { /* exact */ }
+// after
+if (result.totalTokens.provenance === 'computed') { /* exact, and derived */ }
+```
+
+It affects `AgentHistoryBudgetResult.totalTokens` and
+`ComposedAgentPrompt.instructionTokens`. A per-message or per-section count is
+still `measured` — only the totals moved. When any part was estimated the total
+is still `estimated`: an estimate survives arithmetic, and that is the weaker
+claim, so it wins.
+
+#### If you produce token counts
+
+They are validated now, in the places they were not. A fractional count throws
+where it used to flow into the context-window arithmetic:
+
+```ts
+// refused from this release on
+estimateTokens: (text) => ({ value: text.length / 4, provenance: 'estimated' })
+// after
+estimateTokens: (text) => ({ value: Math.ceil(text.length / 4), provenance: 'estimated' })
+```
+
+The same applies to `ComposeAgentPromptOptions.estimateFallback` and
+`.historyTokens`, to `AgentPromptBudget.toolSchemas` / `.attachments` /
+`.providerOverhead`, and to `AgentPromptBudget.contextWindow` /
+`.reservedOutput`, which must now be non-negative safe integers.
+
+`AgentUsageValue.value` is `z.int()` too, which matters if you build usage
+records by hand or in a store double. A figure arriving from a **provider** is
+not thrown — `normalizeSdkUsage` and the OpenRouter adapter turn a non-integer
+into `{ provenance: 'unavailable' }`, so a run that already answered is not
+failed over its own bookkeeping.
+
+#### The new export
+
+`AgentProvenanceSchema` / `AgentProvenance` is the whole vocabulary:
+`provider-reported`, `measured`, `computed`, `estimated`, `unavailable`. Each
+surface declares its subset, so nothing widened — `AgentUsageValue` still refuses
+`measured` and `AgentTokenCount` still refuses `provider-reported`. Use it when
+you want one switch over the question instead of two.
+
 ## Released migration: 0.65.0
 
 The largest migration of the pre-1.0 line, and most of it is the compiler
@@ -10511,10 +10738,41 @@ Canonical protocol exports are `AgentProtocol`, `AgentProtocolConfig`, `AgentRec
 `AgentUsageValueSchema`, `AgentCostValueSchema`, `AgentUsageSchema`, `AgentUsage` and
 `AgentRunMetrics`.
 
+`AgentProvenanceSchema` / `AgentProvenance` is the entrypoint's single vocabulary for **how a
+number came to be known**: `provider-reported` (the provider stated it about a request it served),
+`measured` (this process counted it exactly, before any request was made), `computed` (arithmetic
+over other values — a sum of exact numbers is still `computed`), `estimated` (a heuristic) and
+`unavailable` (not known, so `value` is absent, which is a different fact from a reported zero).
+Each surface declares the subset it can produce: `AgentUsageValueSchema` and `AgentCostValueSchema`
+describe a request that has already happened and never say `measured`; `AgentTokenCountSchema`
+describes a prompt being composed and never says `provider-reported`. Every token count is an
+integer — `AgentUsageValueSchema` and `AgentTokenCountSchema` refuse a fractional `value`, and a
+provider figure that is not a whole number is normalised to `unavailable` rather than thrown.
+`AgentCostValueSchema.value` stays fractional, because money is.
+
+`runs.inputPolicy` takes `queue` (default), `inject`, `interrupt` or `supersede`, or a function of
+the raw input returning one. `inject` lets a run in flight take a newly arrived input into its prompt
+at a step boundary and answer it too; the absorption is committed in the **same transaction** as that
+run's terminal record, via `CommitRunTerminal.absorb`, so a run that ends any other way leaves an
+ordinary queued successor. The absorbed run ends with `terminalReason: 'absorbed'`, run state
+`'superseded'`, `absorbedIntoRunId` naming the run that answered it, and **no assistant message of
+its own**; a submission on its idempotency key resolves through that pointer to the answer
+(→ ADR 0113).
+
+`AgentRuntimeStore` has two **bounded** reads beside `loadSnapshot`:
+`loadRun({ conversationId, runId })` returns an `AgentRunView` — the run, the conversation version it
+was read at, and the retained answer once the run is terminal — or `undefined`; `listActiveRuns(conversationId)`
+returns the runs that have not ended, ordered by `createdAt` then `id`. Neither reads history, so
+neither grows with the length of the conversation, and neither needs anything new from
+`AgentRuntimeStoreDriver`. `loadSnapshot` and every mutation result still carry the whole
+conversation — that is what the store's reducer validates against, and what the runtime builds a
+prompt from (→ ADR 0112).
+
 Store command/result exports are `AcceptInputAndAssignRun`, `AcceptInputAndAssignRunSchema`,
 `AcquireAgentRun`, `AcquireAgentRunSchema`, `CheckpointRunAssistant`,
 `CheckpointRunAssistantSchema`, `CommitRunTerminal`, `CommitRunTerminalSchema`,
-`RequestRunInterrupt`, `RequestRunInterruptSchema`, `runStateForTerminalReason`,
+`RequestRunInterrupt`, `RequestRunInterruptSchema`, `AgentRunView`, `AgentRunViewSchema`,
+`runStateForTerminalReason`,
 `ACTIVE_AGENT_RUN_STATES`, `RecoverAgentRun`, `ReplaceCompactedRange`,
 `ReplaceCompactedRangeSchema`, `AgentStoreMutationResult`, `AgentStoreMutationResultSchema`,
 `AgentStoreAppliedSchema`, `AgentStoreConflictSchema`, `AgentStoreDuplicateSchema`,
@@ -10893,7 +11151,8 @@ handler pipeline without opening a TCP port.
 | `createHandlerTestClient` | function | one contract client backed by an in-process `FetchHandler` |
 | `createHandlerTestClients` | function | exact contract-registry batch form |
 | `runAgentStoreConformance` | function | reusable black-box duplicate/coalescing/stale/recovery contract for durable agent-store adapters |
-| `AgentStoreConformanceConfig` | _type_ | factory configuration for running the same contract against a fresh adapter |
+| `AgentStoreConformanceConfig` | _type_ | `{ createStore(context), cleanup?(context) }` — the factory the contract runs against, plus a teardown that runs once whether the scenario passed or failed |
+| `AgentStoreConformanceContext` | _type_ | `{ conversationIds }` — every conversation the scenario will mutate, handed over **before** the first mutation so an adapter can provision application-owned parent rows; a zero-argument factory stays valid |
 | `runManagedResourceConformance` | function | run the canonical deterministic lifecycle matrix against a fresh consumer-owned `ManagedResource` fixture; resolves `void` or throws `ManagedResourceConformanceError` with a stable scenario ID and normalized trace |
 | `ManagedResourceConformanceScenarioIdSchema` / `ManagedResourceConformanceScenarioId` | schema / _type_ | stable clean, rollback, readiness/completion, activation, shutdown-race and forced-cleanup scenario vocabulary |
 | `ManagedResourceConformanceScenarioSchema` / `ManagedResourceConformanceScenario` | schema / _type_ | discriminated scenario record including whether the controlled resource is required |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.65.1",
+  "version": "0.66.1",
   "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",