stitchkit 0.68.2 → 0.68.4

package/dist/testing.js

@@ -25,11 +25,11 @@ import {
 import {
   createClient,
   createClients
-} from "./index-2ve29dzn.js";
-import"./index-v5bayx1z.js";
+} from "./index-thcy3w8c.js";
+import"./index-r5s4wqb5.js";
 import {
   joinRoutePath
-} from "./index-9ky9hhg3.js";
+} from "./index-bmmtz6r9.js";
 import {
   isRecord
 } from "./index-smpbdg6k.js";
@@ -145,7 +145,7 @@ function requireOutcome(actual, expected) {
 async function runAgentStoreConformance(config) {
   const run = `conformance-${crypto.randomUUID()}`;
   const context = {
-    conversationIds: [run, `${run}-recovery`, `${run}-absorb`]
+    conversationIds: [run, `${run}-recovery`, `${run}-absorb`, `${run}-causal-history`]
   };
   const store = await config.createStore(context);
   let failure;
@@ -165,9 +165,14 @@ async function runAgentStoreConformance(config) {
     throw failure;
 }
 async function conformanceScenario(store, conversationIds) {
-  const [conversationId, recoveryConversationId, absorbConversationId] = conversationIds;
-  if (!conversationId || !recoveryConversationId || !absorbConversationId) {
-    throw new Error("Agent store conformance requires three conversation identities");
+  const [
+    conversationId,
+    recoveryConversationId,
+    absorbConversationId,
+    causalHistoryConversationId
+  ] = conversationIds;
+  if (!conversationId || !recoveryConversationId || !absorbConversationId || !causalHistoryConversationId) {
+    throw new Error("Agent store conformance requires four conversation identities");
   }
   const absentConversationId = `${conversationId}-absent`;
   const firstInput = userMessage(conversationId, "input-1");
@@ -548,8 +553,59 @@ async function conformanceScenario(store, conversationIds) {
   if (terminalRun?.state !== "abandoned" || terminalMessage?.status !== "failed") {
     throw new Error("Abandon recovery did not atomically terminalize its assistant record");
   }
+  await assertCausalHistoryOrder(store, causalHistoryConversationId);
   await assertAbsorptionIsAtomic(store, absorbConversationId);
 }
+async function assertCausalHistoryOrder(store, conversationId) {
+  const leadInput = userMessage(conversationId, "causal-input-1");
+  const leadRun = queuedRun(conversationId, leadInput.id, "causal-run-1");
+  requireOutcome(await store.acceptInputAndAssignRun({
+    idempotencyKey: "causal-request-1",
+    input: leadInput,
+    run: leadRun
+  }), "applied");
+  const acquired = await store.acquireRun({
+    conversationId,
+    runId: leadRun.id,
+    expectedRevision: leadRun.revision,
+    ownerId: "causal-owner"
+  });
+  requireOutcome(acquired, "applied");
+  const running = acquired.snapshot.runs.find((run) => run.id === leadRun.id);
+  if (!running)
+    throw new Error("Causal-order run disappeared after acquisition");
+  const successorInput = userMessage(conversationId, "causal-input-2");
+  const successorRun = queuedRun(conversationId, successorInput.id, "causal-run-2");
+  requireOutcome(await store.acceptInputAndAssignRun({
+    idempotencyKey: "causal-request-2",
+    input: successorInput,
+    run: successorRun
+  }), "applied");
+  const assistant = AgentMessageSchema.parse({
+    schemaVersion: 1,
+    id: running.assistantMessageId,
+    conversationId,
+    runId: running.id,
+    role: "assistant",
+    status: "streaming",
+    parts: [{ type: "text", text: "causal answer" }],
+    createdAt: "2026-08-28T00:00:00.000Z",
+    updatedAt: "2026-08-28T00:00:01.000Z"
+  });
+  const checkpoint = await store.checkpointRunAssistant({
+    conversationId,
+    runId: running.id,
+    expectedRevision: running.revision,
+    ownerId: "causal-owner",
+    ...running.fencingToken !== undefined && { fencingToken: running.fencingToken },
+    assistant
+  });
+  requireOutcome(checkpoint, "applied");
+  const order = checkpoint.snapshot.messages.map((message) => message.id).join(",");
+  if (order !== `${leadInput.id},${assistant.id},${successorInput.id}`) {
+    throw new Error(`Agent history is not in causal run order: ${order}`);
+  }
+}
 async function assertAbsorptionIsAtomic(store, conversationId) {
   const leadInput = userMessage(conversationId, "absorb-input-1");
   const leadRun = queuedRun(conversationId, leadInput.id, "absorb-run-1");

package/dist/tool-invoker.js

@@ -1,13 +1,13 @@
 import {
   createToolInvoker
-} from "./index-g2j2m6vv.js";
-import"./index-7etq650s.js";
-import"./index-cz32amcb.js";
-import"./index-69m2278y.js";
+} from "./index-9t2tdk1x.js";
+import"./index-88yyydag.js";
+import"./index-04agqrs8.js";
+import"./index-51a19y3v.js";
 import"./index-vkk06pv1.js";
 import"./index-6djpbnda.js";
 import"./index-cby4ar3v.js";
-import"./index-9ky9hhg3.js";
+import"./index-bmmtz6r9.js";
 import"./index-smpbdg6k.js";
 import"./index-0w9abg87.js";
 import"./index-6k1937bx.js";

package/dist/tools.js

@@ -1,10 +1,10 @@
 import {
   redact
-} from "./index-dafax5md.js";
+} from "./index-hmfpjnh7.js";
 import {
   signJwt,
   verifyPkce
-} from "./index-wqyrvhzz.js";
+} from "./index-3ydx9j01.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS,
   DEFAULT_PROCESS_SIGNALS,
@@ -12,10 +12,10 @@ import {
   defaultSignalSource,
   guardSignalCallback,
   reportSignalError
-} from "./index-pr0qsmjy.js";
+} from "./index-z575awm9.js";
 import {
   createToolInvoker
-} from "./index-g2j2m6vv.js";
+} from "./index-9t2tdk1x.js";
 import {
   WaitTimeoutError,
   collectToolSurface,
@@ -27,24 +27,24 @@ import {
   fetchPinnedDocument,
   readCapped,
   runWaitOperation
-} from "./index-cszjsxy5.js";
+} from "./index-1bmpkhj2.js";
 import {
   collectTools,
   createToolRunner,
   formatToolError
-} from "./index-7etq650s.js";
+} from "./index-88yyydag.js";
 import {
   ToolExecutionControlError,
   coerceJsonArgs,
   executeToolMethod,
   isToolExecutionControlError,
   toolResultFromError
-} from "./index-cz32amcb.js";
+} from "./index-04agqrs8.js";
 import {
   getRequestContext,
   getTraceId,
   runWithRequestContext
-} from "./index-69m2278y.js";
+} from "./index-51a19y3v.js";
 import {
   ManagedFileError
 } from "./index-bfcpjw20.js";
@@ -66,7 +66,7 @@ import {
   defineContract,
   normalizeError,
   resolvePropagationContext
-} from "./index-9ky9hhg3.js";
+} from "./index-bmmtz6r9.js";
 import {
   isRecord
 } from "./index-smpbdg6k.js";

package/llms-full.txt

@@ -1574,6 +1574,27 @@ multipart or tool exposure. They do not provide replay, cursors or durable
 subscriptions. Keep using `streamingRoute` for an application-owned protocol and
 `rawResponse` for arbitrary response bodies. → ADR 0117.
 
+For an existing schema-owned NDJSON protocol, opt into direct item frames and
+terminal-owned completion:
+
+```ts
+stream: {
+  item: Item,
+  framing: 'item',
+  completion: 'terminal',
+  terminal: z.object({ kind: z.literal('complete') }).loose(),
+  finalLine: 'require-newline',
+}
+```
+
+`item` framing is NDJSON-only and requires terminal completion. The server
+writes each validated item directly, stops the source after the terminal and
+never reads trailing producer values. Because this wire has no framework error
+envelope, any producer/lifetime failure before terminal closes the response;
+the typed client reports `STREAM_TERMINAL_MISSING`. The terminal item therefore
+proves success without weakening safe post-header failure semantics. Existing
+streams retain the envelope and explicit end frame by default. → ADR 0126.
+
 ### SSE streaming
 
 `streamSSE` returns a `Response`, so its endpoint declares
@@ -2407,6 +2428,26 @@ wire `end` frame and, when declared, at least one matching terminal item; EOF is
 converge on the request operation. See the
 [server half](./server.md#contract-first-streams). → ADR 0117.
 
+An established NDJSON protocol may keep its item schema as the complete wire
+frame. This mode requires a terminal item because an unwrapped response has no
+separate safe error/end envelope:
+
+```ts
+stream: {
+  item: Progress,
+  framing: 'item',
+  completion: 'terminal',
+  terminal: z.object({ kind: z.literal('complete') }).loose(),
+  finalLine: 'require-newline',
+}
+```
+
+The matching terminal item ends the operation. Before `next()` returns that
+item, the client aborts the owned request and cancels its body reader; trailing
+frames are not read. EOF first is `STREAM_TERMINAL_MISSING`. The defaults remain
+`framing: 'envelope'`, `completion: 'stream-end'` and `finalLine: 'allow'`.
+→ ADR 0126.
+
 ## SSE
 
 For a streaming endpoint, consume the response with `parseSSE`:
@@ -2460,6 +2501,10 @@ implementations. One line is bounded by `maxLineBytes` (default 1 MiB), UTF-8 is
 decoded strictly and malformed input throws. Passing `onParseError` explicitly
 selects tolerant skip-and-report behaviour.
 
+Set `finalLine: 'require-newline'` when the final newline is part of the
+protocol's truncation proof. The default `allow` continues to accept one valid
+final JSON document without a newline.
+
 
 ==============================================================================
 # Guide: MCP & agents  (docs/guide/mcp-and-agents.md)
@@ -3721,6 +3766,7 @@ bun add @openrouter/ai-sdk-provider
 ```ts
 import { z } from 'zod'
 import {
+  AgentContextOverflowError,
   composeAgentPrompt,
   createAgentRuntime,
   createMemoryAgentRuntimeStore,
@@ -3882,6 +3928,13 @@ assistant, so physical product-history compaction cannot break idempotent retrie
 acquisition, revision-checked assistant checkpoints and one terminal CAS. The
 process-local coordinator releases its lane only after terminal commit.
 
+A queued admission is durable immediately, even if its predecessor is still awaiting ownership
+or its first checkpoint. Snapshots expose causal turn order rather than physical append order:
+the predecessor's assigned input(s) and assistant come before the successor input(s). Execution
+uses the same run boundary, so neither `prompt({ snapshot })` nor default/custom history
+projection can see inputs assigned to a later run. `inject` remains the explicit path that moves
+a successor input into the run already in flight.
+
 ```text
 input + queued run → running → execution settled → terminal CAS → successor
 ```
@@ -4192,6 +4245,25 @@ is the reserved built-in policy name. `loop.prepareStep` is the controlled AI
 SDK step boundary for changing active tools, model, instructions or messages.
 It cannot replace the managed tool set or bypass its lifecycle fence.
 
+Context can grow between steps as tool results and deferred schemas enter the
+provider prompt. When application budgeting can prove that the next assembled
+step exceeds the selected model window, refuse it by type before that provider
+call:
+
+```ts
+prepareStep: (step) => {
+  if (wouldExceedSelectedModelWindow(step)) {
+    throw new AgentContextOverflowError('Prepared step exceeds the selected model window')
+  }
+  return chooseProductStepOptions(step)
+}
+```
+
+That deliberate refusal ends the run as `context_overflow` on the durable
+record, delivery terminal and operator event. Stitchkit does not inspect error
+messages: every other `prepareStep` or provider error remains
+`provider_failure`, and operator-only observability retains its original cause.
+
 Completion validity belongs to the protocol and is checked before the terminal
 CAS. Protocols that require a visible answer opt in explicitly:
 
@@ -4398,7 +4470,7 @@ outbox.
 `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, absorption, bounded reads,
-compaction and recovery invariants against any fresh durable adapter.
+causal queued-history order, 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
@@ -10902,8 +10974,10 @@ The browser-and-server entrypoint. Re-exports everything from
 | `bindRealtimeClient` | function | bind contract validation and typed acknowledgements to an existing Stitchkit client transport without owning its lifecycle |
 | `createRetainedTopics` | function | retained last-value store for sticky events — [guide](../guide/realtime.md#sticky-events) |
 | `parseSSE` | function | parse an SSE `Response` into an async generator — [guide](../guide/client.md#sse) |
-| `parseNDJSON` | function | parse an NDJSON `Response`; blank keep-alive lines are skipped — [guide](../guide/client.md#ndjson) |
-| `ContractStreamFrameSchema` / `ContractStreamFrame` | schema / _type_ | internal-on-the-wire `data` / safe `error` / `end` envelope of a contract-first stream |
+| `parseNDJSON` | function | parse bounded fatal-UTF-8 NDJSON; blank keep-alives are skipped and `finalLine: 'require-newline'` can make the delimiter mandatory — [guide](../guide/client.md#ndjson) |
+| `ContractStreamFrameSchema` / `ContractStreamFrame` | schema / _type_ | default on-the-wire `data` / safe `error` / `end` envelope of a contract-first stream |
+| `ContractStreamFraming` / `ContractStreamCompletion` | _types_ | opt-in item-vs-envelope framing and terminal-vs-stream-end completion policies |
+| `StreamFinalLinePolicy` | _type_ | permissive or newline-required final NDJSON line policy |
 | `DEFAULT_CONTRACT_STREAM_FRAME_BYTES` | const | default maximum encoded contract-stream frame: 256 KiB |
 | `SocketIOClient` | _type_ | low-level client handle; `emit` reports disconnected drops and `emitWithAck` exposes the native Promise primitive used by validated `request()` |
 | `SocketIOClientPeerLoaders` | _type_ | inject `socket.io-client` so a bundler can put it in a self-contained artifact |
@@ -10980,7 +11054,7 @@ from the root `stitchkit`.
 | `ContractDef` | _type_ | a defined contract |
 | `ContractMeta` | _type_ | a contract's `prefix` + optional `scope` and `meta` (a default every endpoint shallow-merges over) |
 | `EndpointDef` | _type_ | a single endpoint definition; `output` declares JSON response presence (`null` is data, `undefined` is invalid) |
-| `EndpointStreamDescriptor` | _type_ | HTTP-only schema-derived stream declaration: item schema, NDJSON/SSE framing, frame/lifetime/heartbeat/idle bounds and optional terminal predicate — [guide](../guide/server.md#contract-first-streams) |
+| `EndpointStreamDescriptor` | _type_ | HTTP-only schema-derived stream declaration: item schema, envelope/item framing, stream-end/terminal completion, NDJSON/SSE encoding and frame/lifetime/heartbeat/idle bounds — [guide](../guide/server.md#contract-first-streams) |
 | `HeadEndpointDef` | _type_ | explicit HTTP-only, bodyless `HEAD` endpoint definition |
 | `EndpointResponseMeta` | _type_ | static success metadata declared by an HTTP-only typed-data endpoint |
 | `ResponseMetadata` | _type_ | per-request outbound collector exposed as `ctx.response` only for a `responseMeta` endpoint |
@@ -11437,6 +11511,7 @@ Server-only optional application runtime. See the
 | `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 |
+| `AgentContextOverflowError` | class | deliberate application budget refusal thrown from `loop.prepareStep`; terminalizes as `context_overflow` without classifying arbitrary error text |
 | `AgentRuntimeRecordIds` | _type_ | optional caller-provided input, run and assistant IDs for stable application records |
 | `AgentRuntimeAdmission` | _type_ | canonical committed input, assigned run, pending assistant projection, compatibility IDs and snapshot version |
 | `AgentAdmissionEventSchema` | schema | post-commit admission projection; removes store rereads but does not imply exactly-once delivery |
@@ -11494,6 +11569,11 @@ ordinary queued successor. The absorbed run ends with `terminalReason: 'absorbed
 its own**; a submission on its idempotency key resolves through that pointer to the answer
 (→ ADR 0113).
 
+With `queue`, a durable successor admission is not prompt eligibility: the current executor sees
+only records through its own run boundary. Snapshot history is normalized to causal turn order
+(assigned input(s), assistant, then successor input(s)) even when the storage codec physically
+appended the successor before the predecessor checkpoint.
+
 `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)`

package/package.json

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