stitchkit 0.61.0 → 0.63.0

package/dist/{index-vtjgx3vv.js → index-b1k33127.js}

@@ -68,6 +68,7 @@ var AgentMessageStatusSchema = z.enum([
   "streaming",
   "completed",
   "interrupted",
+  "superseded",
   "failed"
 ]);
 var AgentMessageSchema = z.object({
@@ -97,6 +98,8 @@ var AgentRunStateSchema = z.enum([
   "interrupt_requested",
   "completed",
   "interrupted",
+  "superseded",
+  "absorbed",
   "failed",
   "cancelled",
   "abandoned"
@@ -104,7 +107,9 @@ var AgentRunStateSchema = z.enum([
 var AgentTerminalReasonSchema = z.enum([
   "success",
   "policy_stop",
+  "provider_stop",
   "interrupted",
+  "superseded",
   "cancelled",
   "timeout",
   "shutdown",
@@ -112,6 +117,23 @@ var AgentTerminalReasonSchema = z.enum([
   "tool_failure",
   "abandoned"
 ]);
+var AgentUsageValueSchema = z.object({
+  value: z.number().nonnegative().optional(),
+  provenance: z.enum(["provider-reported", "computed", "estimated", "unavailable"])
+});
+var AgentCostValueSchema = z.object({
+  value: z.number().nonnegative().optional(),
+  currency: z.string().length(3).optional(),
+  provenance: z.enum(["provider-reported", "computed", "estimated", "unavailable"])
+});
+var AgentUsageSchema = z.object({
+  inputTokens: AgentUsageValueSchema,
+  outputTokens: AgentUsageValueSchema,
+  reasoningTokens: AgentUsageValueSchema.optional(),
+  cacheReadTokens: AgentUsageValueSchema.optional(),
+  cacheWriteTokens: AgentUsageValueSchema.optional(),
+  cost: AgentCostValueSchema.optional()
+});
 var AgentRunSchema = z.object({
   schemaVersion: z.literal(1),
   id: AgentRecordIdSchema,
@@ -124,6 +146,8 @@ var AgentRunSchema = z.object({
   fencingToken: AgentRecordVersionSchema.optional(),
   terminalReason: AgentTerminalReasonSchema.optional(),
   terminalPolicyName: z.string().min(1).optional(),
+  absorbedIntoRunId: AgentRecordIdSchema.optional(),
+  usage: AgentUsageSchema.optional(),
   createdAt: AgentTimestampSchema,
   updatedAt: AgentTimestampSchema
 });
@@ -134,23 +158,6 @@ var AgentSnapshotSchema = z.object({
   messages: z.array(AgentMessageSchema),
   runs: z.array(AgentRunSchema)
 });
-var AgentUsageValueSchema = z.object({
-  value: z.number().nonnegative().optional(),
-  provenance: z.enum(["provider-reported", "computed", "estimated", "unavailable"])
-});
-var AgentCostValueSchema = z.object({
-  value: z.number().nonnegative().optional(),
-  currency: z.string().length(3).optional(),
-  provenance: z.enum(["provider-reported", "computed", "estimated", "unavailable"])
-});
-var AgentUsageSchema = z.object({
-  inputTokens: AgentUsageValueSchema,
-  outputTokens: AgentUsageValueSchema,
-  reasoningTokens: AgentUsageValueSchema.optional(),
-  cacheReadTokens: AgentUsageValueSchema.optional(),
-  cacheWriteTokens: AgentUsageValueSchema.optional(),
-  cost: AgentCostValueSchema.optional()
-});
 var AgentRunMetricsSchema = z.object({
   partial: z.boolean(),
   usage: AgentUsageSchema.optional(),
@@ -158,4 +165,4 @@ var AgentRunMetricsSchema = z.object({
   ttftMs: z.number().nonnegative().optional()
 });
 
-export { AgentRecordIdSchema, AgentRecordVersionSchema, AgentTimestampSchema, AgentJsonObjectSchema, AgentProviderEnvelopeSchema, AgentTextPartSchema, AgentReasoningPartSchema, AgentFilePartSchema, AgentSourcePartSchema, AgentToolCallPartSchema, AgentToolResultPartSchema, AgentOpaquePartSchema, AgentControlPartSchema, AgentMessagePartSchema, AgentMessageRoleSchema, AgentMessageStatusSchema, AgentMessageSchema, AgentAssistantPlaceholderSchema, AgentRunStateSchema, AgentTerminalReasonSchema, AgentRunSchema, AgentSnapshotSchema, AgentUsageValueSchema, AgentCostValueSchema, AgentUsageSchema, AgentRunMetricsSchema };
+export { AgentRecordIdSchema, AgentRecordVersionSchema, AgentTimestampSchema, AgentJsonObjectSchema, AgentProviderEnvelopeSchema, AgentTextPartSchema, AgentReasoningPartSchema, AgentFilePartSchema, AgentSourcePartSchema, AgentToolCallPartSchema, AgentToolResultPartSchema, AgentOpaquePartSchema, AgentControlPartSchema, AgentMessagePartSchema, AgentMessageRoleSchema, AgentMessageStatusSchema, AgentMessageSchema, AgentAssistantPlaceholderSchema, AgentRunStateSchema, AgentTerminalReasonSchema, AgentUsageValueSchema, AgentCostValueSchema, AgentUsageSchema, AgentRunSchema, AgentSnapshotSchema, AgentRunMetricsSchema };

package/dist/testing/agent-store-conformance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-store-conformance.d.ts","sourceRoot":"","sources":["../../src/testing/agent-store-conformance.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,MAAM,WAAW,2BAA2B;IAC1C,WAAW,IAAI,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC/D;AAwCD,gFAAgF;AAChF,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,2BAA2B,GAClC,OAAO,CAAC,IAAI,CAAC,CAmRf"}
+{"version":3,"file":"agent-store-conformance.d.ts","sourceRoot":"","sources":["../../src/testing/agent-store-conformance.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,MAAM,WAAW,2BAA2B;IAC1C,WAAW,IAAI,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC/D;AAwCD,gFAAgF;AAChF,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,2BAA2B,GAClC,OAAO,CAAC,IAAI,CAAC,CA4Sf"}

package/dist/testing.js

@@ -1,7 +1,7 @@
 import {
   AgentMessageSchema,
   AgentRunSchema
-} from "./index-vtjgx3vv.js";
+} from "./index-b1k33127.js";
 import {
   createApplication
 } from "./index-eabpd4tb.js";
@@ -283,12 +283,20 @@ async function runAgentStoreConformance(config) {
       parts: [{ type: "text", text: "checkpoint" }],
       createdAt: "2026-08-22T00:00:00.000Z",
       updatedAt: "2026-08-22T00:00:01.000Z"
-    })
+    }),
+    usage: {
+      inputTokens: { value: 1000, provenance: "provider-reported" },
+      outputTokens: { value: 100, provenance: "provider-reported" },
+      cost: { value: 0.25, currency: "USD", provenance: "provider-reported" }
+    }
   });
   requireOutcome(checkpoint, "applied");
   const checkpointedRun = checkpoint.snapshot.runs.find((run) => run.id === running.id);
   if (!checkpointedRun)
     throw new Error("Checkpointed run disappeared");
+  if (checkpointedRun.usage?.cost?.value !== 0.25) {
+    throw new Error("Checkpoint did not persist the run usage it was given");
+  }
   const terminalAssistant = AgentMessageSchema.parse({
     schemaVersion: 1,
     id: running.assistantMessageId,
@@ -307,7 +315,12 @@ async function runAgentStoreConformance(config) {
       expectedRevision: checkpointedRun.revision,
       ownerId: "conformance-owner",
       assistant: terminalAssistant,
-      reason: "success"
+      reason: "success",
+      usage: {
+        inputTokens: { value: 3000, provenance: "computed" },
+        outputTokens: { value: 300, provenance: "computed" },
+        cost: { value: 1.5, currency: "USD", provenance: "computed" }
+      }
     }),
     store.commitRunTerminal({
       conversationId,
@@ -315,7 +328,12 @@ async function runAgentStoreConformance(config) {
       expectedRevision: checkpointedRun.revision,
       ownerId: "conformance-owner",
       assistant: terminalAssistant,
-      reason: "success"
+      reason: "success",
+      usage: {
+        inputTokens: { value: 3000, provenance: "computed" },
+        outputTokens: { value: 300, provenance: "computed" },
+        cost: { value: 1.5, currency: "USD", provenance: "computed" }
+      }
     })
   ]);
   const terminalOutcomes = terminalResults.map((result) => result.outcome).sort();
@@ -326,6 +344,10 @@ async function runAgentStoreConformance(config) {
   if (terminalApplied?.outcome !== "applied") {
     throw new Error("Terminal race produced no applied result");
   }
+  const settledRun = terminalApplied.snapshot.runs.find((run) => run.id === running.id);
+  if (settledRun?.usage?.cost?.value !== 1.5) {
+    throw new Error("Terminal commit did not persist the run usage it was given");
+  }
   const compactedTerminal = await store.replaceCompactedRange({
     conversationId,
     expectedVersion: terminalApplied.snapshot.version,

package/llms-full.txt

@@ -3672,6 +3672,132 @@ process-local coordinator releases its lane only after terminal commit.
 input + queued run → running → execution settled → terminal CAS → successor
 ```
 
+## What happens to a run when new input arrives
+
+`runs.inputPolicy` decides. It takes three values (or a function returning one);
+the fourth row below is a behaviour it deliberately does not offer yet:
+
+| policy | the run in flight | what it already produced |
+|--------|-------------------|--------------------------|
+| `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 | 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
+what it produced"**:
+
+- The user pressed **stop**. The partial answer was streamed to their screen and
+  they read it. It belongs in the conversation — dropping it makes the history
+  lie to the model about what the human has seen. That is `interrupt`.
+- A newer message **superseded** the run. Whether the partial reached anyone
+  depends on the delivery surface: a token stream shows it as it is produced, a
+  surface that sends nothing until the run is done never showed it at all. When
+  it reached nobody, it is not part of the conversation. That is `supersede`.
+
+**Stitchkit cannot answer that question for you** — delivery belongs to the
+transport, and the runtime sees an abort, not a screen. Hence a declared policy
+(→ ADR 0108), and hence `inputPolicy` accepting a function, so one application
+can hold two surfaces with different rules without the core learning which is
+which:
+
+```ts
+runs: {
+  inputPolicy: (input) =>
+    protocol.parseContext(input.context).surface === 'operator' ? 'queue' : 'supersede',
+}
+```
+
+`input.context` is the **raw** context here — admission runs before the runtime
+parses it, so the callback narrows it itself with the protocol it already has.
+
+A superseded run ends with `terminalReason: 'superseded'`, run state
+`'superseded'` and an assistant message of status `'superseded'`. **The record
+is kept** — excluded from the projection, not deleted — so an operator can see
+what was thrown away, and run identity, admission receipts and the terminal CAS
+keep the row they depend on. Compaction leaves it alone for the same reason: a
+turn whose answer is never spoken is not a turn that may be summarised into one,
+because that would both feed the discarded text to the summariser and drop the
+record in `replacedMessageIds`.
+
+It is also outside the token budget. `selectAgentHistory` removes it with reason
+`'superseded'` and does not count it, so an abandoned fragment cannot push a
+real turn out of a context it never occupies.
+
+### How an interrupted turn reaches the model
+
+An interrupted turn is projected, and says so:
+
+```text
+{ role: 'assistant', content: [
+    { type: 'text', text: 'We are the team, where would you like' },
+    { type: 'text', text: '[interrupted: this turn was cut off before it finished]' },
+]}
+```
+
+`history.interruptedAssistant` chooses the form, and the difference between the
+first two is structural rather than cosmetic. **An assistant turn in provider
+history is a commitment**: the model reads its own previous turn as something it
+said and stays consistent with it. A system line is context.
+
+| value | form | right when |
+|-------|------|-----------|
+| `assistant-marked` (default) | assistant turn plus a marker | the human read the text |
+| `system-note` | `[interrupted] partial response: …` as a system line | the fragment reached nobody |
+| `omit` | not projected at all | you want it gone from the request |
+
+There is deliberately no value that reproduces what the projection used to do,
+which was to send the partial as an ordinary assistant turn and drop its
+`control` marker on the way. That was the defect, not a behaviour to stay
+compatible with.
+
+`projectAgentHistoryDetailed` reports what reached the provider, including part
+types that no projected content stands for:
+
+```ts
+const { decisions } = await projectAgentHistoryDetailed(snapshot.messages)
+// → { messageId: 'assistant-2', action: 'projected', reason: 'projected',
+//      omittedParts: ['source', 'provider'] }
+// → { messageId: 'assistant-1', action: 'omitted', reason: 'superseded' }
+```
+
+`runtime.stop(key, 'supersede')` is the same decision taken by hand: the
+process-local escape hatch chooses the reason, so a caller that knows the answer
+was never delivered can discard it without a newer input arriving.
+
+### 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;
 its `AgentRun.inputMessageIds` records the whole batch and every input ticket
@@ -3722,8 +3848,12 @@ coordinator signal. If provider completion races that revision change, the termi
 the canonical snapshot. An already-terminal winner settles the ticket directly; a still-owned
 `interrupt_requested` run is committed as `interrupted`, and unrelated aggregate-head conflicts
 remain retriable while the run is active with the same owner and fencing token. A stale owner or
-fencing token remains a conflict. Only the execution that applies the terminal mutation emits the
-terminal event and operator metrics; a loser settles from canonical state without republishing it.
+fencing token remains a conflict. Only the execution that applies the terminal mutation publishes the
+**delivery** `terminal` event — a loser settles from canonical state without republishing the turn,
+and its `AgentRuntimeResult.metrics` is `undefined`. The **operator** `run-terminal` event is not
+gated that way: a losing execution still ran, and still spent whatever it spent, so it reports its
+own usage. The two channels answer to different readers — delivering a turn twice is a user's
+problem, and omitting a run's cost is an operator's.
 `runtime.stop(key)` is the process-local signal-only escape hatch.
 
 ## Store operations
@@ -3882,10 +4012,72 @@ sending new event kinds to existing request sinks. Product events omit provider
 causes. Operator `internalCause` is also redacted by default; an operator-only sink must explicitly
 set `includeInternalCause` and own its retention policy.
 
-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.
+### What a run says it spent
+
+Usage values carry `provider-reported`, `computed`, `estimated` or `unavailable`
+provenance, **per field**. Cost additionally carries an ISO currency code;
+OpenRouter-reported cost is normalized as USD.
+
+Read the provenance before the number (→ ADR 0109):
+
+- **`provider-reported`** — the provider handed us exactly this. On
+  `step-finished`, that is what a step's figures are.
+- **`computed`** — a total, added up over steps. **Every figure on a terminal
+  event is this**, tokens included: the AI SDK's `totalUsage` is a sum it
+  performed, not a number a provider reported for the run. It is not a figure to
+  bill against unchanged.
+- **`unavailable`** — nobody reported it. Not zero.
+
+Two rules follow from that last one, and they differ by field on purpose:
+
+- **A token total with an unreported step is a floor**, labelled `computed`. A
+  token count is a diagnostic, and a floor is a useful one.
+- **A cost with an unreported step is `unavailable`, not a floor.** Money is what
+  people bill against, and "at least $1.00" reported as `$1.00` is the same class
+  of lie this whole section exists to remove. One step that did not report its
+  cost makes the run's cost unknown — not smaller. It also stays unknown: later
+  steps reporting normally cannot revive it.
+
+**A terminal event always carries `usage`.** A run that ended before the provider
+reported anything — superseded, interrupted, timed out, shut down, failed —
+carries every field `unavailable`. That is deliberately different from a run that
+spent nothing, and an omitted object could not tell you which one you had.
+
+Two costs in different currencies do not add: the sum reports `unavailable`
+rather than picking a label. The core records a currency and never converts one.
+
+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.
@@ -7609,6 +7801,190 @@ 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
+strictly additive — and every item changes what a running system reports or
+sends, which is what this heading is for. One of them changes a number you may
+already be billing against.
+
+### A run reports what it spent
+
+Three changes to what the runtime says about cost and tokens. Nothing moves an
+export; all three change numbers a running system reports, and one of them
+changes a number you may already be billing against.
+
+#### Multi-step cost was under-reported and is now summed
+
+No code change is needed to get the fix — but check any predicate that reads
+`provenance`:
+
+```ts
+// before — accepted a number that was one step's cost, not the run's
+if (usage.cost?.provenance === 'provider-reported') bill(usage.cost.value)
+
+// after — a sum stitchkit performed says so
+if (usage.cost && usage.cost.provenance !== 'unavailable') bill(usage.cost.value)
+```
+
+`'computed'` means stitchkit added up provider-reported parts. It is not a guess
+— `'estimated'` is the word for that — but it is deliberately not
+`'provider-reported'`, because that label is what a caller filters on when it
+wants a figure it can bill against unchanged, and a sum is not one.
+
+Token totals moved with it. The AI SDK's `totalUsage` is a sum *it* performed
+over per-step provider figures — not a run total any provider handed over — so
+labelling it `provider-reported` was the same overstatement. **A run total on a
+terminal event is always `computed`.** If you want a figure with the provider's
+own word on it, read `step-finished`: each step carries what that call reported.
+
+#### `usage` is always present on a terminal event
+
+```ts
+// before — absent when the run ended before the provider's `finish`
+const spent = event.usage?.cost?.value ?? 0        // silently 0 for a real spend
+
+// after — present, and it says what it does not know
+event.usage?.cost?.provenance === 'unavailable'    // we spent, and cannot say how much
+```
+
+Keep the optional chaining: one `AgentRunEvent` shape covers `run-started`,
+`step-finished` and `run-terminal`, so `usage` stays optional on the type. The
+guarantee is about terminal events, and a schema shared with `run-started`
+cannot express it.
+
+**Do not read `unavailable` as zero.** A run aborted mid-stream has spent real
+money that nobody has counted; a run that never reached the provider has not.
+Both used to look the same and now do not.
+
+#### A losing executor reports its own spend
+
+An execution that loses the terminal compare-and-swap now emits an operator
+`run-terminal` event, because it ran and it spent. If a sink treated those events
+as "runs this process committed", that is no longer true — `AgentRuntimeResult.metrics`
+is still `undefined` for a losing executor and remains the way to tell.
+
+The *delivery* `terminal` event is unchanged and still fires only for the winner,
+so nothing delivers a turn twice.
+
+### An interrupted answer stops passing as a finished one
+
+Two behaviour changes, one shared cause: a run ended by a newer input used to
+leave its half-written answer in the conversation with no sign that it was cut
+off, and the next request to the provider carried it as an ordinary assistant
+turn.
+
+#### The projection marks an interrupted turn
+
+Nothing to change to adopt the fix — the default is the fixed behaviour. What to
+check is whether the marker is the *right* form for your surface, and the
+question that decides it is not "was the run interrupted" but **"did anyone see
+what it produced"**.
+
+```ts
+// after — pick the form; the default is 'assistant-marked'
+createAgentRuntime({ history: { interruptedAssistant: 'system-note' } })
+```
+
+- **The user pressed stop and the text was on their screen** — keep
+  `'assistant-marked'`. The assistant turn is the truthful record of what the
+  human read, and the model should stay consistent with it.
+- **The partial never reached anyone** — a surface that sends nothing until the
+  run is done — prefer `'system-note'`. An assistant turn in provider history is
+  a commitment the model stays consistent with; a system line is context.
+
+If you pass `history.project` you own the projection outright and none of this
+applies — but the same question does.
+
+#### A run ended by a newer input can now say so
+
+```ts
+// before
+runs: { inputPolicy: 'interrupt' }   // ends the run, keeps its partial answer
+
+// after — for a surface where a follow-up message invalidates the answer
+// in flight rather than merely stopping it
+runs: { inputPolicy: 'supersede' }   // ends the run, discards its partial answer
+```
+
+`inputPolicy` also accepts `(input) => policy`, which is how one application
+gives two conversation surfaces different rules without the runtime learning
+which is which.
+
+A superseded run terminates with `terminalReason: 'superseded'`, state
+`'superseded'` and an assistant message of status `'superseded'`. **If you switch
+exhaustively on any of those enums, add the arm** — that is the part of this
+release that can break a build rather than a behaviour. The record itself is
+kept: it is excluded from the projection, not deleted, so an operator can still
+see what was thrown away.
+
 ## Released migration: 0.61.0
 
 Three behaviour changes between versions. None moves an export — the surface is
@@ -9938,7 +10314,7 @@ Server-only optional application runtime. See the
 | `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 |
+| `createAgentSessionCoordinator` | function | strict process-local queue/interrupt/supersede 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 |
 | `AgentRuntimeRecordIds` | _type_ | optional caller-provided input, run and assistant IDs for stable application records |
@@ -9949,7 +10325,7 @@ Server-only optional application runtime. See the
 | `AgentRuntimeConflictError` | class | thrown when a store mutation loses to a concurrent writer — catchable by type from `stitchkit/agent-runtime` |
 | `AgentSessionCloseOptions` | _type_ | `gracePeriodMs` for natural settlement, then abort, then `forceTimeoutMs` for bounded settlement after it |
 | `AgentSessionCloseResult` | _type_ | what `close()` achieved: `settled`, or `timedOut` with `remaining` runs still in flight. Only omitting `forceTimeoutMs` guarantees nothing is in flight on return |
-| `AgentHistoryProjectionOptions` | _type_ | storage-neutral file resolver and explicit unresolved-file behavior |
+| `AgentHistoryProjectionOptions` | _type_ | storage-neutral file resolver, explicit unresolved-file behavior, and how an interrupted turn reaches the model (`interruptedAssistant`) |
 | `createAgentToolFenceLifecycle` | function | pre-effect and post-effect run ownership fence for `mountAgent` |
 | `AgentRuntimeEventSchema` | schema | transient stream lifecycle plus post-commit admission/checkpoint/run-state/terminal projections |
 | `createAgentObservability` | function | separate agent-run sink over the shared bounded observability lifecycle |
@@ -9979,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.61.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",