stitchkit 0.112.0 → 0.112.1

package/CHANGELOG.md

@@ -15,6 +15,13 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.112.1] - 2026-10-25
+
+### Fixed
+
+- `stitchkit/agent-runtime` — an empty or control-only failed assistant now retains its non-success marker when explicitly included with `evidencePolicy.failedAssistant: 'assistant-marked'`. The default still omits failed evidence. The compaction guide explains the existing failed-prefix recovery policy, status-aware summarization, and why a closed tool exchange cannot settle an external effect. → ADR 0269
+  **Affects:** `stitchkit/agent-runtime` projectAgentHistory, projectAgentHistoryDetailed
+
 ## [0.112.0] - 2026-10-24
 
 ### ⚠️ Breaking changes

package/dist/agent-runtime/history.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/history.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAsB,MAAM,IAAI,CAAC;AAO1E,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAyB,MAAM,WAAW,CAAC;AACvF,OAAO,EACL,KAAK,0BAA0B,EAEhC,MAAM,mBAAmB,CAAC;AAE3B,KAAK,QAAQ,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;AAEzC,MAAM,WAAW,6BAA6B;IAC5C,cAAc,CAAC,EAAE,0BAA0B,CAAC;IAC5C,WAAW,CAAC,CACV,IAAI,EAAE,OAAO,CAAC,gBAAgB,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,EACjD,OAAO,EAAE,YAAY,GACpB,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IAChD;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC3C,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IAC9C,kBAAkB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACtC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,oBAAoB,CAAC,EAAE,kBAAkB,GAAG,aAAa,GAAG,MAAM,CAAC;CACpE;AAED,MAAM,WAAW,8BAA8B;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,MAAM,EACF,WAAW,GACX,iBAAiB,GACjB,OAAO,GACP,mBAAmB,GACnB,sBAAsB,GACtB,aAAa,GACb,YAAY,CAAC;IACjB;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAClC,SAAS,EAAE,SAAS,8BAA8B,EAAE,CAAC;IACrD;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAyMD,wEAAwE;AACxE,wBAAsB,2BAA2B,CAC/C,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,OAAO,GAAE,6BAAkC,GAC1C,OAAO,CAAC,4BAA4B,CAAC,CA4GvC;AAED,4EAA4E;AAC5E,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,OAAO,GAAE,6BAAkC,GAC1C,OAAO,CAAC,YAAY,EAAE,CAAC,CAEzB"}
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/history.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAsB,MAAM,IAAI,CAAC;AAO1E,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAyB,MAAM,WAAW,CAAC;AACvF,OAAO,EACL,KAAK,0BAA0B,EAEhC,MAAM,mBAAmB,CAAC;AAE3B,KAAK,QAAQ,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;AAEzC,MAAM,WAAW,6BAA6B;IAC5C,cAAc,CAAC,EAAE,0BAA0B,CAAC;IAC5C,WAAW,CAAC,CACV,IAAI,EAAE,OAAO,CAAC,gBAAgB,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,EACjD,OAAO,EAAE,YAAY,GACpB,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IAChD;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC3C,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IAC9C,kBAAkB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACtC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,oBAAoB,CAAC,EAAE,kBAAkB,GAAG,aAAa,GAAG,MAAM,CAAC;CACpE;AAED,MAAM,WAAW,8BAA8B;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,MAAM,EACF,WAAW,GACX,iBAAiB,GACjB,OAAO,GACP,mBAAmB,GACnB,sBAAsB,GACtB,aAAa,GACb,YAAY,CAAC;IACjB;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAClC,SAAS,EAAE,SAAS,8BAA8B,EAAE,CAAC;IACrD;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AA2MD,wEAAwE;AACxE,wBAAsB,2BAA2B,CAC/C,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,OAAO,GAAE,6BAAkC,GAC1C,OAAO,CAAC,4BAA4B,CAAC,CA4GvC;AAED,4EAA4E;AAC5E,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,OAAO,GAAE,6BAAkC,GAC1C,OAAO,CAAC,YAAY,EAAE,CAAC,CAEzB"}

package/dist/entrypoints/agent-runtime/harness.js

@@ -5,7 +5,7 @@ import"../../index-8kzct1d6.js";
 import {
   composeAgentPrompt2,
   createAgentRuntime2
-} from "../../index-5as18gs2.js";
+} from "../../index-a0vj9edp.js";
 import"../../index-qaet40b2.js";
 import"../../index-mnkk1ffz.js";
 import"../../index-fynr93w4.js";

package/dist/entrypoints/agent-runtime.js

@@ -123,7 +123,7 @@ import {
   agentGoalStateSlot2,
   agentTodoStateSlot2,
   createAgentRuntime2
-} from "../index-5as18gs2.js";
+} from "../index-a0vj9edp.js";
 import {
   AgentConversationSummarySchema2,
   AgentConversationPageSchema2,

package/dist/{index-5as18gs2.js → index-a0vj9edp.js}

@@ -490,7 +490,7 @@ function assistantMessages(message, marker) {
       rendered.add("tool-approval-response");
     }
   }
-  if (marker && (messages.length > 0 || content.length > 0)) {
+  if (marker === "failed" || marker && (messages.length > 0 || content.length > 0)) {
     append("assistant", {
       type: "text",
       text: marker === "interrupted" ? INTERRUPTION_NOTE : FAILURE_NOTE

package/llms/agent-runtime.2.txt

@@ -7,7 +7,7 @@
 Parts of this slice:
 - `llms/agent-runtime.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md)
 - `llms/agent-runtime.2.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md)
-- `llms/agent-runtime.3.txt`: API reference: `stitchkit/agent-runtime`  (docs/api/reference.md) · API reference: `stitchkit-tui`  (docs/api/reference.md)
+- `llms/agent-runtime.3.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md) · API reference: `stitchkit/agent-runtime`  (docs/api/reference.md) · API reference: `stitchkit-tui`  (docs/api/reference.md)
 
 ==============================================================================
 # Guide: Agent application runtime  (docs/guide/agent-runtime.md)  (continued)
@@ -615,6 +615,62 @@ replace a leading summary on the next compaction.
 Set `maxAttempts` to allow bounded conflict recovery. Every retry reloads the snapshot, reselects the
 eligible range and recomputes the summary; the stale summary is never retried.
 
+### Recovering a prefix after a failed turn
+
+The default evidence policy omits failed assistants. A failed turn therefore stops the
+compactable prefix, including completed turns after it. A terminal failure is not an
+unanswered tool call, but opting its partial evidence into a summary is an explicit host
+decision. Use the existing `evidencePolicy: { failedAssistant: 'assistant-marked' }` on
+`structuredCompaction` (or `selectCompactableHistory`) when that evidence is wanted.
+The same policy belongs on the summarizer's history projection and on any corresponding
+token-budget selection. Stored statuses remain unchanged.
+
+The summarizer receives **raw** `eligibleMessages`, not provider messages and not an
+automatic failure marker. Project them with the same policy before sending them to a
+model, and preserve failed outcomes in the application's structured summary and prompt:
+
+```ts
+const evidencePolicy: AgentHistoryEvidencePolicy = {
+  failedAssistant: 'assistant-marked',
+}
+
+// Inside structuredCompaction({ evidencePolicy, ... }).summarize:
+const projected = await projectAgentHistoryDetailed(eligibleMessages, {
+  evidencePolicy,
+  incompleteToolTurn: 'error',
+})
+const failedMessageIds = eligibleMessages
+  .filter(message => message.role === 'assistant' && message.status === 'failed')
+  .map(message => message.id)
+// Pass projected.messages, projected.system and failedMessageIds to the host's
+// summarizer. Its schema/prompt must retain failures and uncertain effects as
+// such, merge previousSummary, and never describe partial output as success.
+```
+
+An opted-in failed assistant projects an explicit non-success marker even when it has
+no text or only control parts. A dangling call, unresolved approval, invalid result
+chronology or a user input with no assistant remains a barrier under either policy.
+Raw whole-turn completeness does not guarantee that every record can be projected:
+for example, a call and its result split across records may be rejected by the projector.
+`incompleteToolTurn: 'error'` makes that rejection stop summarization; the original history
+stays canonical. A host with such records must use a status-aware summarizer that explicitly
+represents every relevant record, or retain the range. Do not silently summarize an omitted
+exchange, filter the failed record out of the replacement range, rewrite its status or skip
+over an incomplete turn. The replacement remains one contiguous prefix under snapshot CAS.
+
+Provider chronology and external effect authority answer different questions (ADR 0269).
+A matching `tool-result` with `outcome: 'error'` and an application code such as `UNKNOWN`
+closes the provider exchange; it does **not** prove the external effect failed or succeeded.
+Compaction changes the model-history projection, not the canonical event journal or the
+retained terminal admission receipt. The `durability/effect` intent, accepted proof and
+uncertain outcome remain available after compaction and archive restore. A reconstructed
+`createLocalStepDurability` using the original `(conversationId, runId, effectName)` returns
+the accepted proof, reconciles a bare intent, or returns `uncertain` without calling `run`
+again. It does not deduplicate a new run or a newly named effect. Standalone effect callers
+still own the exclusive execution lease; sharing a ledger is not an atomic claim.
+An application-owned receipt outside that journal retains its own recovery rules and must
+not be discarded because a history turn became compactable.
+
 ### Compacting without the store
 
 The *selection* inside compaction needs no store, no version and no runtime, so
@@ -772,105 +828,3 @@ first mutation**, so an adapter whose runtime rows reference an application-owne
 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.
-
-## Plain completions and shared invocation receipts
-
-Use `createModelInvocationLedger` from `stitchkit/agent-runtime` when a direct text
-completion and an agent must share causal provider evidence. It uses the existing
-runtime store, not a second database. The completion path sends exactly one user
-prompt, no framework instructions and no tools. It never starts an agent loop.
-
-```ts
-import { createModelInvocationLedger } from 'stitchkit/agent-runtime';
-
-const invocations = createModelInvocationLedger({
-  store, // the same AgentRuntimeStore object passed to createAgentRuntime
-  models, // an existing defineModelRegistry result
-  payloadKey, // 32 bytes from the host's secret store; retain separately from archives
-  authorize: async ({ context, conversationId, action, trace }) => {
-    const session = await authenticate(context);
-    await authorizeConversation(session, conversationId, action, trace);
-    return { subject: session.subject }; // verified identity, never a body field
-  },
-});
-
-const completion = await invocations.complete({
-  conversationId: 'evaluation-42',
-  idempotencyKey: 'summary-case-3',
-  trace: {
-    operationId: 'summary-42', purpose: 'summarize', project: 'example',
-    parent: { traceId: 'trace-42' }, experiment: 'evaluation', case: 'case-3',
-  },
-  prompt: 'Summarize these supplied facts.',
-  models: ['primary', 'fallback'], // registry keys; repeat a key for an explicit retry
-  settings: { maxOutputTokens: 500 },
-  timeoutMs: 30_000,
-}, authenticatedContext);
-
-// Add to the existing createAgentRuntime configuration:
-const receiptConfig = {
-  ledger: invocations,
-  trace: ({ run }) => ({
-    operationId: run.id, purpose: 'assistant-turn', project: 'example',
-  }),
-};
-// createAgentRuntime({ ...existingConfig, invocations: receiptConfig });
-
-const page = await invocations.read({
-  conversationId: 'evaluation-42', limit: 100,
-}, authenticatedContext);
-// Continue with fromSeq: page.nextSeq while it is defined.
-```
-
-`complete` returns `invocationId`, `outcome` and, on success, `text`. `duplicate`
-returns the existing ID without provider execution or replaying plaintext. Changed
-input, trace or caller under the same key is a conflict. Model attempts are explicit
-and bounded to eight; SDK retries are disabled. Only provider failures trigger the
-next attempt. Abort, audit refusal and configuration errors do not. An admitted call
-whose process died stays claimed: inspect the receipt before choosing a new key.
-
-The agent retains its existing prompt, tools and loop. Both modes produce
-`invocation/started`, `provider/request`, `provider/response` and
-`invocation/finished` records through `read`. Each attempt has its own ID; response
-usage is counted once and keeps `unavailable` distinct from measured zero. Requested
-registry selection, sent adapter identity and effective provider identity are
-separate. Effective identity is null when not reported. A gateway's hidden retries
-are not visible as additional attempts.
-
-`currentModelInvocationAttempt()` returns the causal context inside a provider's
-`fetch` callback or streamed read. Use it to join a host transport audit to
-`operationId`, `invocationId`, `attemptId`, optional `runId` and `step`.
-`onAttempt` is an awaited admission hook; a rejected hook prevents the provider call.
-SDK payload hashes are not represented as hashes of HTTP wire bytes.
-
-Prompts and output are AES-256-GCM payload artifacts. `read` returns references and
-hashes; `readPayload({ conversationId, artifactId }, context)` separately authorizes
-`read-payload` and checks authentication tags and hashes. `payloadKey` must be 32
-bytes and is copied at construction. Keep it outside the event store/backups; retain
-the appropriate key when restoring an archive. `maxPayloadBytes` defaults to 4 MiB
-(range 1 KiB–64 MiB). Streaming output evidence keeps parts up to half of it; past
-that the evidence carries `truncated: { parts, sha256 }` over the whole stream, and
-the answer itself is never cut. A receipt that cannot be written never changes an
-outcome: `complete()` returns it with `receiptError` beside it, and a succeeded
-answer keeps its `text`. Request headers
-are excluded. Protect existing agent history independently: enabling receipts does
-not encrypt its ordinary conversation records.
-
-The built-in memory and SQLite stores implement `appendEventOnce`. Custom stores
-must implement its once-only check and append atomically, returning the original
-event on a duplicate key scoped by conversation and kind. A factory without this
-capability refuses receipt setup. The driver-backed implementation finds the keyed
-event by its identity through the driver's optional `events.find` — one index probe
-in SQLite — so admission costs the same on a long conversation as on a new one; a
-custom driver without `find` falls back to paging the log in one transaction.
-`store.findEventOnce({ conversationId, kind, key })` reads the same event back.
-Invocation payload artifacts are keyed by their artifact id the same way.
-
-### Migration from direct SDK completions
-
-**Who must act:** applications opting into shared completion/agent receipts.
-Replace the direct `generateText` call with `invocations.complete`, configure host
-authorization and a retained payload key, and pass the same ledger in the agent's
-`invocations` option. Use the returned invocation ID and the paginated `read` method
-for receipt queries; do not import runtime internals. Available since 0.100.0;
-existing runtime configurations need no migration.

package/llms/agent-runtime.3.txt

@@ -6,7 +6,113 @@
 Parts of this slice:
 - `llms/agent-runtime.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md)
 - `llms/agent-runtime.2.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md)
-- `llms/agent-runtime.3.txt`: API reference: `stitchkit/agent-runtime`  (docs/api/reference.md) · API reference: `stitchkit-tui`  (docs/api/reference.md)
+- `llms/agent-runtime.3.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md) · API reference: `stitchkit/agent-runtime`  (docs/api/reference.md) · API reference: `stitchkit-tui`  (docs/api/reference.md)
+
+==============================================================================
+# Guide: Agent application runtime  (docs/guide/agent-runtime.md)  (continued)
+==============================================================================
+
+## Plain completions and shared invocation receipts
+
+Use `createModelInvocationLedger` from `stitchkit/agent-runtime` when a direct text
+completion and an agent must share causal provider evidence. It uses the existing
+runtime store, not a second database. The completion path sends exactly one user
+prompt, no framework instructions and no tools. It never starts an agent loop.
+
+```ts
+import { createModelInvocationLedger } from 'stitchkit/agent-runtime';
+
+const invocations = createModelInvocationLedger({
+  store, // the same AgentRuntimeStore object passed to createAgentRuntime
+  models, // an existing defineModelRegistry result
+  payloadKey, // 32 bytes from the host's secret store; retain separately from archives
+  authorize: async ({ context, conversationId, action, trace }) => {
+    const session = await authenticate(context);
+    await authorizeConversation(session, conversationId, action, trace);
+    return { subject: session.subject }; // verified identity, never a body field
+  },
+});
+
+const completion = await invocations.complete({
+  conversationId: 'evaluation-42',
+  idempotencyKey: 'summary-case-3',
+  trace: {
+    operationId: 'summary-42', purpose: 'summarize', project: 'example',
+    parent: { traceId: 'trace-42' }, experiment: 'evaluation', case: 'case-3',
+  },
+  prompt: 'Summarize these supplied facts.',
+  models: ['primary', 'fallback'], // registry keys; repeat a key for an explicit retry
+  settings: { maxOutputTokens: 500 },
+  timeoutMs: 30_000,
+}, authenticatedContext);
+
+// Add to the existing createAgentRuntime configuration:
+const receiptConfig = {
+  ledger: invocations,
+  trace: ({ run }) => ({
+    operationId: run.id, purpose: 'assistant-turn', project: 'example',
+  }),
+};
+// createAgentRuntime({ ...existingConfig, invocations: receiptConfig });
+
+const page = await invocations.read({
+  conversationId: 'evaluation-42', limit: 100,
+}, authenticatedContext);
+// Continue with fromSeq: page.nextSeq while it is defined.
+```
+
+`complete` returns `invocationId`, `outcome` and, on success, `text`. `duplicate`
+returns the existing ID without provider execution or replaying plaintext. Changed
+input, trace or caller under the same key is a conflict. Model attempts are explicit
+and bounded to eight; SDK retries are disabled. Only provider failures trigger the
+next attempt. Abort, audit refusal and configuration errors do not. An admitted call
+whose process died stays claimed: inspect the receipt before choosing a new key.
+
+The agent retains its existing prompt, tools and loop. Both modes produce
+`invocation/started`, `provider/request`, `provider/response` and
+`invocation/finished` records through `read`. Each attempt has its own ID; response
+usage is counted once and keeps `unavailable` distinct from measured zero. Requested
+registry selection, sent adapter identity and effective provider identity are
+separate. Effective identity is null when not reported. A gateway's hidden retries
+are not visible as additional attempts.
+
+`currentModelInvocationAttempt()` returns the causal context inside a provider's
+`fetch` callback or streamed read. Use it to join a host transport audit to
+`operationId`, `invocationId`, `attemptId`, optional `runId` and `step`.
+`onAttempt` is an awaited admission hook; a rejected hook prevents the provider call.
+SDK payload hashes are not represented as hashes of HTTP wire bytes.
+
+Prompts and output are AES-256-GCM payload artifacts. `read` returns references and
+hashes; `readPayload({ conversationId, artifactId }, context)` separately authorizes
+`read-payload` and checks authentication tags and hashes. `payloadKey` must be 32
+bytes and is copied at construction. Keep it outside the event store/backups; retain
+the appropriate key when restoring an archive. `maxPayloadBytes` defaults to 4 MiB
+(range 1 KiB–64 MiB). Streaming output evidence keeps parts up to half of it; past
+that the evidence carries `truncated: { parts, sha256 }` over the whole stream, and
+the answer itself is never cut. A receipt that cannot be written never changes an
+outcome: `complete()` returns it with `receiptError` beside it, and a succeeded
+answer keeps its `text`. Request headers
+are excluded. Protect existing agent history independently: enabling receipts does
+not encrypt its ordinary conversation records.
+
+The built-in memory and SQLite stores implement `appendEventOnce`. Custom stores
+must implement its once-only check and append atomically, returning the original
+event on a duplicate key scoped by conversation and kind. A factory without this
+capability refuses receipt setup. The driver-backed implementation finds the keyed
+event by its identity through the driver's optional `events.find` — one index probe
+in SQLite — so admission costs the same on a long conversation as on a new one; a
+custom driver without `find` falls back to paging the log in one transaction.
+`store.findEventOnce({ conversationId, kind, key })` reads the same event back.
+Invocation payload artifacts are keyed by their artifact id the same way.
+
+### Migration from direct SDK completions
+
+**Who must act:** applications opting into shared completion/agent receipts.
+Replace the direct `generateText` call with `invocations.complete`, configure host
+authorization and a retained payload key, and pass the same ledger in the agent's
+`invocations` option. Use the returned invocation ID and the paginated `read` method
+for receipt queries; do not import runtime internals. Available since 0.100.0;
+existing runtime configurations need no migration.
 
 ==============================================================================
 # API reference: `stitchkit/agent-runtime`  (docs/api/reference.md)
@@ -244,6 +350,16 @@ projection, budgeting and structured compaction; `isAssistantHistoryEvidence` ap
 compatibility default omits it. Approval message schemas are
 `AgentToolApprovalRequestPartSchema` and `AgentToolApprovalResponsePartSchema`.
 
+With `failedAssistant: 'assistant-marked'`, `selectCompactableHistory` and
+`structuredCompaction` admit a failed prefix only when the entire turn's tool chronology
+is complete. `eligibleMessages` stays raw: the summarizer must use the same policy in
+`projectAgentHistoryDetailed` and preserve non-success/uncertain outcomes in its summary.
+Even an empty opted-in failed assistant carries a non-success marker in that projection.
+Use `incompleteToolTurn: 'error'` to refuse a range the projector cannot represent.
+Compaction never deletes canonical effect events or the retained terminal receipt;
+chronological completeness does not settle an external effect. See the
+[failed-prefix recovery contract](../guide/agent-runtime.md#recovering-a-prefix-after-a-failed-turn).
+
 Model exports are `AgentLanguageModelProvider`, `AgentModelCapability`,
 `AgentModelCapabilitySchema`, `AgentModelDescriptor`,
 `AgentModelDescriptorSchema`, `AgentModelRegistry`, `AgentModelRegistryConfig`,

package/llms/agent-runtime.txt

@@ -7,7 +7,7 @@
 Parts of this slice:
 - `llms/agent-runtime.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md)
 - `llms/agent-runtime.2.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md)
-- `llms/agent-runtime.3.txt`: API reference: `stitchkit/agent-runtime`  (docs/api/reference.md) · API reference: `stitchkit-tui`  (docs/api/reference.md)
+- `llms/agent-runtime.3.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md) · API reference: `stitchkit/agent-runtime`  (docs/api/reference.md) · API reference: `stitchkit-tui`  (docs/api/reference.md)
 
 ==============================================================================
 # Guide: Agent application runtime  (docs/guide/agent-runtime.md)

package/llms-full.txt

@@ -6706,6 +6706,62 @@ replace a leading summary on the next compaction.
 Set `maxAttempts` to allow bounded conflict recovery. Every retry reloads the snapshot, reselects the
 eligible range and recomputes the summary; the stale summary is never retried.
 
+### Recovering a prefix after a failed turn
+
+The default evidence policy omits failed assistants. A failed turn therefore stops the
+compactable prefix, including completed turns after it. A terminal failure is not an
+unanswered tool call, but opting its partial evidence into a summary is an explicit host
+decision. Use the existing `evidencePolicy: { failedAssistant: 'assistant-marked' }` on
+`structuredCompaction` (or `selectCompactableHistory`) when that evidence is wanted.
+The same policy belongs on the summarizer's history projection and on any corresponding
+token-budget selection. Stored statuses remain unchanged.
+
+The summarizer receives **raw** `eligibleMessages`, not provider messages and not an
+automatic failure marker. Project them with the same policy before sending them to a
+model, and preserve failed outcomes in the application's structured summary and prompt:
+
+```ts
+const evidencePolicy: AgentHistoryEvidencePolicy = {
+  failedAssistant: 'assistant-marked',
+}
+
+// Inside structuredCompaction({ evidencePolicy, ... }).summarize:
+const projected = await projectAgentHistoryDetailed(eligibleMessages, {
+  evidencePolicy,
+  incompleteToolTurn: 'error',
+})
+const failedMessageIds = eligibleMessages
+  .filter(message => message.role === 'assistant' && message.status === 'failed')
+  .map(message => message.id)
+// Pass projected.messages, projected.system and failedMessageIds to the host's
+// summarizer. Its schema/prompt must retain failures and uncertain effects as
+// such, merge previousSummary, and never describe partial output as success.
+```
+
+An opted-in failed assistant projects an explicit non-success marker even when it has
+no text or only control parts. A dangling call, unresolved approval, invalid result
+chronology or a user input with no assistant remains a barrier under either policy.
+Raw whole-turn completeness does not guarantee that every record can be projected:
+for example, a call and its result split across records may be rejected by the projector.
+`incompleteToolTurn: 'error'` makes that rejection stop summarization; the original history
+stays canonical. A host with such records must use a status-aware summarizer that explicitly
+represents every relevant record, or retain the range. Do not silently summarize an omitted
+exchange, filter the failed record out of the replacement range, rewrite its status or skip
+over an incomplete turn. The replacement remains one contiguous prefix under snapshot CAS.
+
+Provider chronology and external effect authority answer different questions (ADR 0269).
+A matching `tool-result` with `outcome: 'error'` and an application code such as `UNKNOWN`
+closes the provider exchange; it does **not** prove the external effect failed or succeeded.
+Compaction changes the model-history projection, not the canonical event journal or the
+retained terminal admission receipt. The `durability/effect` intent, accepted proof and
+uncertain outcome remain available after compaction and archive restore. A reconstructed
+`createLocalStepDurability` using the original `(conversationId, runId, effectName)` returns
+the accepted proof, reconciles a bare intent, or returns `uncertain` without calling `run`
+again. It does not deduplicate a new run or a newly named effect. Standalone effect callers
+still own the exclusive execution lease; sharing a ledger is not an atomic claim.
+An application-owned receipt outside that journal retains its own recovery rules and must
+not be discarded because a history turn became compactable.
+
 ### Compacting without the store
 
 The *selection* inside compaction needs no store, no version and no runtime, so
@@ -22288,6 +22344,16 @@ projection, budgeting and structured compaction; `isAssistantHistoryEvidence` ap
 compatibility default omits it. Approval message schemas are
 `AgentToolApprovalRequestPartSchema` and `AgentToolApprovalResponsePartSchema`.
 
+With `failedAssistant: 'assistant-marked'`, `selectCompactableHistory` and
+`structuredCompaction` admit a failed prefix only when the entire turn's tool chronology
+is complete. `eligibleMessages` stays raw: the summarizer must use the same policy in
+`projectAgentHistoryDetailed` and preserve non-success/uncertain outcomes in its summary.
+Even an empty opted-in failed assistant carries a non-success marker in that projection.
+Use `incompleteToolTurn: 'error'` to refuse a range the projector cannot represent.
+Compaction never deletes canonical effect events or the retained terminal receipt;
+chronological completeness does not settle an external effect. See the
+[failed-prefix recovery contract](../guide/agent-runtime.md#recovering-a-prefix-after-a-failed-turn).
+
 Model exports are `AgentLanguageModelProvider`, `AgentModelCapability`,
 `AgentModelCapabilitySchema`, `AgentModelDescriptor`,
 `AgentModelDescriptorSchema`, `AgentModelRegistry`, `AgentModelRegistryConfig`,

package/llms.txt

@@ -25,7 +25,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/primitives**: [llms/primitives.txt](llms/primitives.txt) 11.7 KB
 - **stitchkit/server**: [llms/server.txt](llms/server.txt) 44.2 KB → [llms/server.2.txt](llms/server.2.txt) 20.5 KB → [llms/server.3.txt](llms/server.3.txt) 45.6 KB → [llms/server.4.txt](llms/server.4.txt) 38.3 KB → [llms/server.5.txt](llms/server.5.txt) 22.9 KB
 - **stitchkit/observability**: [llms/observability.txt](llms/observability.txt) 46.9 KB
-- **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 42.7 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 46.7 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 35.6 KB
+- **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 42.7 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 44.8 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 42.1 KB
 - **stitchkit/agent-runtime/testing**: [llms/agent-runtime-testing.txt](llms/agent-runtime-testing.txt) 2.6 KB
 - **stitchkit/agent-runtime/harness**: [llms/agent-runtime-harness.txt](llms/agent-runtime-harness.txt) 11.0 KB
 - **stitchkit/agent-runtime/coding-tools**: [llms/agent-runtime-coding-tools.txt](llms/agent-runtime-coding-tools.txt) 5.0 KB

package/package.json

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