stitchkit 0.68.3 → 0.68.4

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,
@@ -4199,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:
 
@@ -10909,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 |
@@ -10987,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 |
@@ -11444,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 |

package/package.json

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