stitchkit 0.62.0 → 0.63.0

package/llms-full.txt

@@ -3682,7 +3682,7 @@ the fourth row below is a behaviour it deliberately does not offer yet:
 | `queue` (default) | finishes first | kept |
 | `interrupt` | ends | kept, and marked as cut off |
 | `supersede` | ends | discarded from the prompt, kept in the record |
-| _inject_ | continues | — not supported; see below |
+| `inject` | continues | kept — it takes the new input at a step boundary |
 
 `interrupt` and `supersede` differ in exactly one thing, and the question that
 picks between them is **not** "was the run interrupted" but **"did anyone see
@@ -3766,15 +3766,37 @@ 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 supported
-
-**inject** — hand the input to the loop between tool calls and let the run
-continue — has no primitive. `loop.prepareStep` passes the AI SDK return type
-through, so an application *can* append messages between steps, but nothing
-hands `prepareStep` the pending inputs and nothing attaches an absorbed input to
-the running run's `inputMessageIds`. A run that answered two messages would
-carry a durable record claiming it answered one. It is reachable by hand, not
-supported.
+### The one that ends nothing
+
+**`inject`** hands the input to the loop between tool calls and lets the run keep
+going. It is right when the input *refines* rather than redirects — a correction
+arriving while a multi-step task is halfway through, where discarding the
+finished steps would be pure loss.
+
+It queues like `queue`, and a run already in flight takes it on at its next step
+boundary. That ordering is the whole design: the tempting shape, attaching a new
+input straight to a running run, has a loss case with no honest answer, because
+the run may terminate before the loop reaches a boundary and the input would then
+be recorded as answered by a turn that never saw it. Queue first and absorb
+opportunistically, and the fallback is simply that the successor runs — the
+behaviour every other policy already has.
+
+When a run does absorb one:
+
+- both inputs land in the answering run's `inputMessageIds`, so the durable
+  record matches what the model was actually asked;
+- both submissions' tickets resolve to the same terminal result;
+- the absorbed run is marked `absorbed` with `absorbedIntoRunId` pointing at the
+  run that answered. It is kept, not deleted — its admission receipt still points
+  at it, so a duplicate submission has to resolve to something. It leaves the
+  conversation snapshot, because a snapshot carries active runs plus those a
+  message references and an absorbed run never wrote an assistant message;
+- the next provider call carries the re-projected history. An application's own
+  `prepareStep` wins if it sets `messages` itself — it is the one that knows why.
+
+A step boundary is the only place this can happen: the provider is between calls,
+so the next request can carry the new message. A single-step run never reaches
+one, and its successor simply runs next.
 
 With `runs.coalescePending: true`, an active lane has at most one queued
 successor. Every later accepted input is atomically appended to that successor;
@@ -4028,6 +4050,35 @@ Usage is **not durable**. It reaches you on the operator and delivery event
 streams and in `AgentRuntimeResult.metrics`, and stitchkit writes no spend to the
 store — where a figure lives afterwards is the application's (→ ADR 0002).
 
+### Reconciling with the provider's own accounting
+
+Whether a provider bills for a call that was aborted mid-flight cannot be known
+inside the process: the authoritative number arrives later, from the provider's
+accounting. **stitchkit does not accept it back** (→ ADR 0110) — a terminal run
+is an absorbing state, and a write that reached it through the conversation
+aggregate could conflict a concurrent compaction into discarding a summary it had
+just paid a model to produce.
+
+The join is yours, and `runId` is the key:
+
+```ts
+// when the run terminates — write what the runtime observed
+await ledger.record({
+  runId: terminal.run.id,
+  conversationId: terminal.run.conversationId,
+  costUsd: terminal.metrics?.usage?.cost?.value ?? null,   // null when `unavailable`
+  provenance: terminal.metrics?.usage?.cost?.provenance ?? 'unavailable',
+})
+
+// later — the provider's accounting names the same generation
+await ledger.reconcile({ runId, costUsd: billed, provenance: 'provider-reported' })
+```
+
+Record the row even when the figure is `unavailable`: that row is the evidence
+that a run happened and cost something nobody has counted yet, and it is what the
+provider's later figure attaches to. A run with no row is a run you cannot
+reconcile.
+
 The sink deduplicates stable event IDs by default. Cross-crash exactly-once still requires a durable
 outbox.
 
@@ -7750,6 +7801,73 @@ current one *up to* your target, and apply each snippet.
    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.63.0
+
+Four changes to what a running system reports and how an input reaches a run
+in flight. Nothing moves an export except one added store member, and only an
+application implementing `AgentRuntimeStore` directly has to touch code.
+
+### A spend figure that survives, and an input that joins
+
+### `AgentRuntimeStore` has a ninth member
+
+Only if you implement the aggregate interface directly — an adapter built on
+`AgentRuntimeStoreDriver` needs no change, and the public conformance kit covers
+the new operation.
+
+```ts
+// after
+absorbQueuedRun(input: AbsorbQueuedRun): Promise<AgentStoreMutationResult>
+```
+
+It moves a queued successor's inputs into the run already answering, in one
+mutation, and marks the successor `absorbed`. Two run records change in one
+transaction — if your driver persists them one at a time, persist both.
+
+### A provider failure says so
+
+```ts
+// before — an upstream error arrived as a policy stop with no policy
+if (terminal.reason === 'policy_stop') retryLater()
+
+// after
+if (terminal.reason === 'provider_failure') retryLater()
+if (terminal.reason === 'provider_stop') { /* a length cap or content filter */ }
+```
+
+`policy_stop` now always carries the `policyName` that caused it. If you switch
+exhaustively on `AgentTerminalReason` or `AgentRunState`, add `'provider_stop'`
+and `'absorbed'`.
+
+### `partial` changed meaning
+
+It used to tell you which event kind you were holding. It now tells you whether
+the figure beside it is a confirmed total:
+
+```ts
+// after — true when the provider never reported the run finished
+if (metrics.partial) treatAsFloor(metrics.usage)
+```
+
+Terminal events for runs that were superseded, interrupted, timed out or failed
+before the provider finished now report `partial: true` where they reported
+`false`.
+
+### Checkpoint metrics are a running total
+
+```ts
+// wrong, and now wrong by more than it used to be
+const spent = checkpoints.reduce((total, c) => total + (c.metrics.usage?.cost?.value ?? 0), 0)
+// right
+const spent = checkpoints.at(-1)?.metrics.usage?.cost?.value
+```
+
+### You can read a run's spend back from the store
+
+`AgentRun.usage` is written at every checkpoint and with the terminal record, so
+a dropped observability event no longer loses the number, and a process that dies
+mid-stream leaves behind what it had already spent.
+
 ## Released migration: 0.62.0
 
 Two groups of behaviour changes. Nothing moves an export — the surface is
@@ -10237,7 +10355,8 @@ Canonical protocol exports are `AgentProtocol`, `AgentProtocolConfig`, `AgentRec
 Store command/result exports are `AcceptInputAndAssignRun`, `AcceptInputAndAssignRunSchema`,
 `AcquireAgentRun`, `AcquireAgentRunSchema`, `CheckpointRunAssistant`,
 `CheckpointRunAssistantSchema`, `CommitRunTerminal`, `CommitRunTerminalSchema`,
-`RequestRunInterrupt`, `RequestRunInterruptSchema`, `RecoverAgentRun`, `ReplaceCompactedRange`,
+`RequestRunInterrupt`, `RequestRunInterruptSchema`, `AbsorbQueuedRun`, `AbsorbQueuedRunSchema`,
+`RecoverAgentRun`, `ReplaceCompactedRange`,
 `ReplaceCompactedRangeSchema`, `AgentStoreMutationResult`, `AgentStoreMutationResultSchema`,
 `AgentStoreAppliedSchema`, `AgentStoreConflictSchema`, `AgentStoreDuplicateSchema`,
 `AgentStoreNotFoundSchema`, `AgentAdmissionReceipt`, `AgentAdmissionReceiptSchema`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.62.0",
+  "version": "0.63.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",