stitchkit 0.68.0 → 0.68.2

package/llms-full.txt

@@ -51,6 +51,7 @@ own, recorded as an ADR.
 | `stitchkit/server` | server (Bun) | stable | `createServer`, `implement`, hooks, auth, Socket.IO server, server primitives |
 | `stitchkit/node` | server (Node ≥ 22) | stable | `serveNode` + the runtime-agnostic core — the Node mirror of `/server` |
 | `stitchkit/tools` | server | stable | `createMcpHandler`, `mountMcp`, `mountAgent`, the OAuth provider, native tools |
+| `stitchkit/tools/invoker` | server | stable | peer-free `createToolInvoker` over the canonical contract tool runner |
 | `stitchkit/cli` | server | stable | `createCli` — the CLI transport, light (no MCP SDK / `ai`) |
 | `stitchkit/remote` | browser **and** server | stable | peer-free `implementRemote` for thin HTTP proxy processes |
 | `stitchkit/files` | server (Bun or Node) | stable | peer-free managed local-file boundary |
@@ -159,7 +160,8 @@ map — feature → packages:
 | anything (validation) | `zod` |
 | `createServer` (Bun) | — (uses `Bun.serve`) |
 | `serveNode` (Node ≥ 22) | `srvx` (+ `@types/bun` dev) |
-| MCP / agent tools (`stitchkit/tools`) | `@modelcontextprotocol/server` `ai` |
+| In-process contract tools (`stitchkit/tools/invoker`) | — |
+| MCP / agent adapters (`stitchkit/tools`) | `@modelcontextprotocol/server` `ai` |
 | Agent application runtime (`stitchkit/agent-runtime`) | `ai` |
 | OpenRouter runtime adapter (`stitchkit/agent-runtime/openrouter`) | `ai` `@openrouter/ai-sdk-provider` |
 | MCP host/client tests | `@modelcontextprotocol/client` |
@@ -167,7 +169,7 @@ map — feature → packages:
 | React data layer (`stitchkit/react`) | `@tanstack/react-query` `react-query-kit` |
 | **Socket.IO server on Bun** | `socket.io` `@socket.io/bun-engine` |
 | **Socket.IO server on Node** | `socket.io` |
-| Socket.IO client | `socket.io-client` (brings `@socket.io/component-emitter`, which the browser declarations reference for types only) |
+| Socket.IO client | `socket.io-client` (runtime peer; unrelated root declarations remain peer-free) |
 | grammY lifecycle adapters (`stitchkit/application/grammy`) | `grammy` |
 | OpenTelemetry gauges (`stitchkit/application/opentelemetry`) | `@opentelemetry/api` |
 
@@ -1914,12 +1916,43 @@ socket, and a missing socket cannot fall through to that host over TCP. Defaults
 are 16 MiB request/response bodies, 64 KiB headers, 30 s to response headers,
 eight connections and five redirects.
 
+`maxHeaderBytes` is enforced before exposing a response. Bun's owned parser
+counts the complete response head in wire bytes, including the status line and
+terminating blank line. Node passes the same configured integer unchanged to
+`http.request({ maxHeaderSize })`, so its native parser's documented header-size
+accounting is authoritative there. Exceeding either ceiling yields
+`UNIX_HEADERS_TOO_LARGE` with `delivery: 'response-received'`. A stalled body
+pauses its socket, and resuming preserves the exact chunked body.
+
 `UnixClientTransportError` carries a stable `code` and `delivery`:
 `not-dispatched`, `possibly-dispatched` or `response-received`. Only the first
 proves that the remote operation did not begin; Stitchkit never silently retries
 an ambiguous write. Response consumption/cancellation belongs to the operation,
 and `close()` interrupts active work and destroys owned connections.
 
+The response total is a unary-body policy, not a stream-buffer measurement. A
+long-lived NDJSON/SSE client opts into streaming explicitly instead of choosing
+an arbitrarily large integer:
+
+```ts
+const streamTransport = createUnixClientTransport({
+  socketPath: '/run/my-daemon.sock',
+  responseBodyMode: 'streaming',
+})
+const streamClient = createClient(streamContract, {
+  baseUrl: 'http://my-daemon',
+  fetch: streamTransport.fetch,
+})
+```
+
+`streaming` removes only the cumulative lifetime response limit. It cannot be
+combined with `maxResponseBytes`; request/header/connection bounds, socket
+pause/resume, cancellation and strict HTTP framing remain active. The stream
+descriptor's `maxFrameBytes` bounds each protocol frame, and the application
+still owns any queue it builds after consuming those frames. Use a separate
+default transport for finite calls that must retain the 16 MiB unary ceiling.
+The adapter never infers this policy from `Content-Type`. → ADR 0125.
+
 The legacy `createHttpClient({ unix: '/absolute/path' })` spelling remains a
 Bun-only convenience. On a non-Bun runtime it now refuses before dispatch
 instead of ignoring the selection and dialing TCP. `unix` and an injected
@@ -2028,12 +2061,58 @@ Abort and timeout do not emit `network_error` and are not retried. The same
 options work for query, JSON, multipart and raw-response calls. Stitchkit does
 not expose upload progress: Fetch has no portable upload-progress primitive.
 
+An injected transport failure is normalized to `UNKNOWN_ERROR` while its exact
+object remains available as `ApiError.cause`. This is how a bounded adapter can
+preserve facts the generic client cannot invent — for example a Unix transport's
+`not-dispatched`, `possibly-dispatched` or `response-received` state. Never replay
+an effect from `UNKNOWN_ERROR` alone; inspect the owned adapter's cause and retry
+only when it proves that dispatch did not happen.
+
 For an endpoint without contract arguments, pass only the options object:
 
 ```ts
 await api.health.withOptions({ signal: controller.signal })
 ```
 
+### Injected delivery adapters
+
+`ClientFetch` is the narrow composition seam for application-owned delivery.
+The contract still owns operation identity, request serialization and response
+validation; the adapter owns I/O, bounds and dispatch certainty:
+
+```ts
+import { type ClientFetch, createClient } from 'stitchkit'
+
+const delivery: ClientFetch = async (input, init) => {
+  // Fixed deployment destination and policy are chosen here, not by caller data.
+  return boundedFetch(input, { ...init, signal: init?.signal })
+}
+
+const query = createClient(queryContract, {
+  baseUrl: 'https://service.internal',
+  fetch: delivery,
+})
+const work = createClient(requestWorkContract, {
+  baseUrl: 'https://service.internal',
+  fetch: delivery,
+})
+```
+
+The same adapter accepts unrelated contract shapes without learning their DTOs
+or operation inventory. `createClient` chooses method/path from the contract,
+serializes only the declared arguments, forwards `.withOptions(..., { signal })`
+and validates the response through the endpoint's output schema. A caller payload
+cannot replace the configured base URL or reserved operation path.
+
+Contract metadata describes an effect; it does not authorize one. Authentication,
+scope and destination policy remain in the application/server boundary. A schema
+mismatch is an explicit validation failure and is not retried automatically. A
+timeout means the caller stopped waiting, not that the remote effect did not run.
+
+Published declarations are checked from a clean tarball under both bundler and
+NodeNext resolution. The HTTP-only NodeNext proof uses `skipLibCheck: false` and
+installs no Socket.IO peer. → ADR 0120.
+
 ### Many contracts at once
 
 ```ts
@@ -2170,6 +2249,7 @@ try {
     err.details  // structured details, if any
     err.hint     // optional hint
     err.traceId  // x-request-id — correlate this failure with backend logs
+    err.cause    // concrete injected transport failure, when delivery failed
   }
 }
 ```
@@ -2468,7 +2548,7 @@ AI SDK `ToolSet` and call its transport adapter manually. Compile an in-process
 invoker once and call the shared framework runner directly:
 
 ```ts
-import { createToolInvoker } from 'stitchkit/tools'
+import { createToolInvoker } from 'stitchkit/tools/invoker'
 
 const invoker = createToolInvoker(services, {
   transport: 'AGENT',       // required exposure policy
@@ -2497,6 +2577,11 @@ recursive calls without retaining request state. Every invocation gets a fresh
 tool-call context and runs the same extension resolution, input/output
 validation, lifecycle, hooks and output-strip reporter as mounted tools.
 
+The dedicated entrypoint needs only the normal `stitchkit`/`zod` install. Use
+the broader `stitchkit/tools` barrel when the same program also mounts MCP or AI
+adapters and has installed their optional peers. Both imports reach the same
+runner; this is dependency isolation, not a second execution implementation.
+
 `invoke` returns the canonical discriminated `ToolResult`, not an AI SDK or MCP
 presentation envelope. `invokeOrThrow` returns validated data and throws the
 runner's normalized `AppError` on failure, preserving an application error's
@@ -3772,6 +3857,14 @@ const store = createAgentRuntimeStore({
 })
 ```
 
+Prompt budgeting keeps reservation deficits signed. If instructions,
+`reservedOutput`, tool schemas, attachments and provider overhead already exceed
+`contextWindow`, `composeAgentPrompt` returns `contextDecision: 'oversized'`
+and a negative `availableHistoryTokens` even when history is empty. A `compact`
+policy is returned only when removing history could actually make the prompt
+fit. Exact equality (including a zero window with zero reservations/history)
+fits; any unavailable component keeps the decision `unavailable`.
+
 The same opaque `tx` reaches head, run, admission and history callbacks. The adapter maps rows
 and supplies atomicity; Stitchkit owns transition validation and revision
 arithmetic. The executable reference is
@@ -4099,6 +4192,24 @@ 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.
 
+Completion validity belongs to the protocol and is checked before the terminal
+CAS. Protocols that require a visible answer opt in explicitly:
+
+```ts
+const protocol = defineAgentProtocol({
+  context: ContextSchema,
+  inputMetadata: InputMetadataSchema,
+  terminalAcceptance: 'require-output',
+})
+```
+
+The built-in rule accepts non-blank text, generated files, structured provider
+parts, and a named tool-only `policy_stop`. The default is `allow-empty` for
+protocols where an empty acknowledgement is meaningful. Pass a callback when
+the product has a narrower definition; it receives the candidate message,
+terminal reason and optional policy name, and runs before persistence. A false
+result fails the candidate instead of rewriting an already committed success.
+
 `loop.idleTimeoutMs` is inactivity, not total duration: the deadline resets on
 every model stream event. A stalled call aborts with durable reason `timeout`;
 user interruption and shutdown remain distinct.
@@ -4121,7 +4232,10 @@ effect must be replay-safe.
 ## History, provider metadata and files
 
 `projectAgentHistory` converts canonical engine records into provider-valid AI
-SDK messages and pairs tool calls/results. Provider-required metadata is kept
+SDK messages and pairs tool calls/results in persisted causal order. Adjacent
+parallel calls stay in one assistant round and their adjacent results stay in
+one tool round; a dependent call after those results starts a new assistant
+round, and trailing final text remains after the last tool result. Provider-required metadata is kept
 in a versioned opaque envelope and omitted from product delivery by default.
 `projectAgentHistoryDetailed` additionally returns one inspectable decision per canonical record;
 leading assistant records, crash drafts and unmatched tool chronology are never silently passed to
@@ -4358,10 +4472,12 @@ const cleanup = createManagedSchedule({
 const http = managedServerResource({
   id: 'http',
   dependsOn: [database],
-  // Called during `start`, after `database` is ready — which is how "bind the
-  // port once the database is up" is expressed. Pass an already-running server
-  // instead when the application created it itself.
-  server: () => createServer({ port: env.PORT, services }),
+  // Called during `start`, after `database` is ready. The factory receives the
+  // same declared-dependency and startup-signal context as any resource.
+  server: (context) => {
+    const db = context.use(database)
+    return createServer({ port: env.PORT, services: createServices(db) })
+  },
 })
 
 const app = createApplication({
@@ -4449,6 +4565,12 @@ Declare the dependency with the **resource**, not its id, whenever you intend to
 read from it: that is the form `use` can type, and it keeps the declaration and
 the read from drifting apart. A string still works when all you need is order.
 
+`managedServerResource` follows the same rule. Its factory receives this context
+during `start`, so constructing routes from a database/service/socket value does
+not need an outer mutable handoff or a custom `start` override. A zero-argument
+factory remains valid when it needs only ordering, and an already-running handle
+can still be passed directly. → ADR 0121.
+
 The value is published when `start` resolves and stays readable for the rest of
 the application's life — from `activate` and from the shutdown phases too, where
 a dependant may still need the handle it was given.
@@ -5071,7 +5193,10 @@ already-listening server and it adopts that one instead.
 const http = managedServerResource({
   id: 'http',
   dependsOn: [database],
-  server: () => createServer({ port: env.PORT, services }),
+  server: (context) => {
+    const db = context.use(database)
+    return createServer({ port: env.PORT, services: createServices(db) })
+  },
 })
 
 const app = createApplication({ id: 'service', resources: [database, http] })
@@ -5082,6 +5207,11 @@ The server resource publishes its `ManagedServerHandle`, so anything that needs
 the running server — a Socket.IO attachment, a URL to log, a probe — reads it
 with `context.use(http)` rather than through a module-local.
 
+The factory itself receives `ManagedResourceContext` too. It can read only the
+dependencies declared on the server resource and shares the graph's startup
+signal. A dependency failure prevents the factory from binding; a factory
+rejection is rolled back without invoking the factory a second time.
+
 Do not spread this resource over your own `start` to control creation order:
 that shape exists only as a workaround for the version whose `start` was empty,
 and `dependsOn` now expresses the order directly. The executable recipe binds a
@@ -5995,6 +6125,36 @@ page metadata and `pageParams`; an infinite create changes only the selected
 edge page (`createAt: 'start' | 'end'`). Creates are deduplicated across every
 cached page. `updateMissing` makes an absent update explicitly skip or insert.
 
+Filtered query families can additionally declare membership per exact key and
+evidence-aware total reconciliation:
+
+```ts
+list: {
+  key: ['tickets'],
+  shape: 'infinite-paginated',
+  createAt: 'start',
+  updateMissing: 'skip',
+  membership: {
+    evaluate: (event, queryKey) => membershipFor(event, queryKey),
+    unknown: 'invalidate',
+  },
+  total: {
+    mode: 'reconcile',
+    unknown: 'invalidate',
+    delta: ({ event, present, membership }) => provenDelta(event, present, membership),
+  },
+}
+```
+
+Membership is `include | exclude | unknown`. An excluded update removes an
+existing row; an included one follows `updateMissing`. Unknown evidence never
+guesses and either preserves or invalidates the exact query. The conservative
+total policy increments only a non-duplicate create and decrements only a
+delete/update whose membership is observed; unseen IDs are `unknown`. Supply
+`delta` only when the event itself proves a stronger transition. Every page's
+numeric `total` changes together while cursor metadata and `pageParams` remain
+unchanged.
+
 The event entity may be richer than a list row. Keep the full value in detail
 cache, project it for lists, and provide the same comparator the backend uses:
 
@@ -6032,9 +6192,9 @@ deleted payload without guessing. The same resolved detail key drives the
 `isFresh` echo guard. Shape checks also leave neighbouring detail caches alone
 when a list key is intentionally used as a partial query-key prefix.
 
-The helper deliberately does **not** flatten pages, update totals, derive a
-sort order or replace arbitrary `setQueryData` logic. Those are application
-policies; this helper only applies declared CRUD semantics.
+The helper deliberately does **not** flatten pages, infer filter semantics,
+derive a sort order or replace arbitrary `setQueryData` logic. Those remain
+declared application policies; Stitchkit applies their generic cache mechanics.
 
 ## Raw binary lane (Bun)
 
@@ -7643,6 +7803,11 @@ runtime or type-only package outside a case's budget fails with both the case id
 and package name, so an accidental eager import cannot hide behind another
 fixture's transitive dependency.
 
+That includes `stitchkit/tools/invoker`: a minimal packed consumer imports it
+without MCP/AI peers and executes validation, output projection and normalized
+errors on Bun and Node. The broader `stitchkit/tools` barrel deliberately keeps
+the adapter peer budget.
+
 Beside the matrix, one case is about the ARTIFACT rather than the inventory: a
 program that injects the Socket.IO peer loaders is bundled and started in a
 directory with no `node_modules`, under Node and under Bun with auto-install
@@ -7674,6 +7839,11 @@ const socket = await createSocketIOServer({
 })
 ```
 
+The packed Next/Webpack gate compiles the browser
+`peers.client: () => import('socket.io-client')` loader and rejects Webpack's
+"request is an expression" warning. Stitchkit's runtime fallback remains lazy;
+its emitted import carries a count-checked ignore directive.
+
 Omit `peers` and nothing changes: the peers stay lazy and are resolved from the
 machine. Both peers must be listed as dependencies of the package you bundle,
 because they now genuinely are.
@@ -10712,7 +10882,7 @@ The browser-and-server entrypoint. Re-exports everything from
 | `contractEndpointMatchers` | function | compile exact pathname matchers for selected HTTP contract operations and expected-401 policy |
 | `PathPrefixArgs` | _type_ | required string-valued keys exposed to a typed dynamic `pathPrefix` callback |
 | `createHttpClient` | function | the Ky-based HTTP transport; on Next.js SSR its first attempt stays request-memoizable while every retry is a distinct transport attempt — [guide](../guide/client.md#createhttpclient) |
-| `ApiError` | class | a non-2xx response, with `code` / `status` / `details` / `hint` and optional readonly `traceId` from `x-request-id` |
+| `ApiError` | class | a non-2xx or client failure, with `code` / `status` / `details` / `hint`, optional readonly `traceId` from `x-request-id`, and standard `cause` preserving an injected transport failure |
 | `HttpClient` | _type_ | the transport interface `createClient` builds on |
 | `ConfiguredHttpClient` | _type_ | a framework-created `HttpClient` carrying its readonly `baseUrl` for URL builders |
 | `HttpClientConfig` | _type_ | config for `createHttpClient`; retry `limit` counts retries after the initial attempt (default 2 = at most 3 GET attempts), with `statusCodes: []` by default; `fetch` installs an explicit transport and is mutually exclusive with the legacy Bun-only `unix` option — [details](../guide/client.md#createhttpclient) |
@@ -11070,8 +11240,9 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `StreamingSourceContext` | _type_ | what a streaming source is given, including the cancellation `signal` |
 | `StreamingFormat` | _type_ | `'ndjson' \| 'sse'` |
 | `createUnixClientTransport` | function | owned Fetch-compatible Unix-socket transport on Bun and Node; every redirect stays on the socket — [guide](../guide/client.md#unix-domain-sockets) |
-| `UnixClientTransportConfig` | _type_ | absolute socket path plus request/response/header/connection/redirect bounds |
+| `UnixClientTransportConfig` | _type_ | absolute socket path plus request/header/connection/redirect bounds and an explicit bounded-or-streaming response policy |
 | `UnixClientTransport` | _type_ | `{ fetch, closed, close() }`; `close()` settles owned active work |
+| `UnixResponseBodyMode` | _type_ | `bounded \| streaming`; bounded is the 16 MiB cumulative default, streaming keeps pull-driven buffering without a lifetime total |
 | `UnixClientTransportError` | class | stable transport failure with `code` and dispatch certainty in `delivery` |
 | `UnixClientTransportErrorCode` | _type_ | finite Unix transport failure-code union |
 | `UnixClientDeliveryState` | _type_ | `not-dispatched \| possibly-dispatched \| response-received`; input to application retry policy, never an implicit retry |
@@ -11119,7 +11290,7 @@ cutovers are covered by the executable
 | `ManagedResourceDependency` | _type_ | a dependency named by id or given as the resource itself — the second form is what `context.use(...)` can type |
 | `ManagedResourcePublished` | _type_ | the value type `context.use(resource)` returns, recovered from that resource's own `start` |
 | `ManagedResourcePublishesNoValue` | _type_ | what `context.use(...)` returns for a resource that publishes nothing — a branded refusal rather than `never`, so reading it does not silently compile |
-| `ManagedServerResourceConfig` | _type_ | the server or a thunk that makes one, stable ID, dependencies and policy for `managedServerResource` |
+| `ManagedServerResourceConfig` | _type_ | the server or a sync/async factory receiving `ManagedResourceContext`, plus stable ID, dependencies and shutdown policy for `managedServerResource` |
 | `ManagedServerResource` | _type_ | the resource `managedServerResource` returns, whose `start` publishes the `ManagedServerHandle` |
 | `ApplicationHealthHandlerOptions` / `ApplicationHealthHandlerOptionsSchema` | _type_ / schema | liveness/readiness selection and sanitized `Retry-After` policy |
 | `ApplicationOperationalHandlers` / `ApplicationOperationalHandlersOptions` / `ApplicationOperationalHandlersOptionsSchema` | _type_ / schema | conventional status/readiness/liveness route surface and shared retry policy |
@@ -11247,7 +11418,8 @@ Server-only optional application runtime. See the
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createAgentRuntime` | function | compose durable acceptance, stream loop, checkpoints, coordination, managed tools and winner-only terminal publication; reconciles same-owner terminal/interrupt/head CAS races before releasing the lane |
-| `defineAgentProtocol` | function | declare and validate context, input metadata and canonical message parts |
+| `defineAgentProtocol` | function | declare context, input metadata, canonical parts and optional pre-CAS terminal acceptance (`allow-empty`, `require-output` or callback) |
+| `hasAgentTerminalOutput` | function | generic `require-output` predicate for non-blank text, generated files, structured provider parts and explicit tool-only policy stops |
 | `AgentMessageSchema` / `AgentRunSchema` / `AgentSnapshotSchema` | schema | versioned canonical engine records |
 | `AgentRuntimeStore` | _type_ | aggregate CAS transaction boundary for message, run and compaction mutations |
 | `createAgentRuntimeStore` | function | build the aggregate store from one coherent transaction driver; framework owns every state transition |
@@ -11260,7 +11432,7 @@ Server-only optional application runtime. See the
 | `createMemoryAgentRuntimeStore` | function | process-local reference adapter, not production durability |
 | `projectAgentHistory` | function | asynchronously project canonical records and resolved multimodal files into provider-valid AI SDK messages |
 | `defineModelRegistry` | function | typed language-model descriptors, capabilities and provider construction |
-| `composeAgentPrompt` | function | ordered prompt contributions and provenance-aware context budget |
+| `composeAgentPrompt` | function | ordered prompt contributions and provenance-aware signed context budget; irreducible reservation deficits are `oversized`, not compactable history |
 | `structuredCompaction` | function | summarize a provider-valid snapshot range and replace it through CAS |
 | `createAgentSessionCoordinator` | function | strict process-local queue/interrupt/supersede lifecycle |
 | `AgentRuntimeStopPolicy` | _type_ | named custom AI SDK stop condition persisted and published on policy stop |
@@ -11289,7 +11461,8 @@ transport adapters validate the same records. Runtime composition types are `Age
 `AgentSessionCoordinator`, `AgentCompactionContext`, `AgentCompactionResult` and
 `StructuredCompactionConfig`.
 
-Canonical protocol exports are `AgentProtocol`, `AgentProtocolConfig`, `AgentRecordIdSchema`, `AgentRecordVersionSchema`,
+Canonical protocol exports are `AgentProtocol`, `AgentProtocolConfig`, `AgentTerminalAcceptance`,
+`AgentTerminalAcceptanceInput`, `hasAgentTerminalOutput`, `AgentRecordIdSchema`, `AgentRecordVersionSchema`,
 `AgentTimestampSchema`, `AgentJsonObjectSchema`, `AgentProviderEnvelopeSchema`,
 `AgentProviderEnvelope`, `AgentMessagePartSchema`, `AgentMessagePart`, `AgentTextPartSchema`,
 `AgentReasoningPartSchema`, `AgentFilePartSchema`, `AgentSourcePartSchema`,
@@ -11485,7 +11658,7 @@ payload.
 | `mountAgent` | function | a Vercel AI SDK `ToolSet` from a service — [guide](../guide/mcp-and-agents.md#ai-agents--mountagent) |
 | `defineRuntimeTool` | function | define one validated pathless operation for explicit MCP, Agent and/or CLI surfaces — [guide](../guide/mcp-and-agents.md#pathless-runtime-tools-and-multimodal-results) |
 | `createRuntimeToolFactory` | function | bind shared identity and Zod-validated per-call context for runtime tools — [guide](../guide/mcp-and-agents.md#pathless-runtime-tools-and-multimodal-results) |
-| `createToolInvoker` | function | compile an exposure-aware in-process dispatcher over the canonical tool runner — [guide](../guide/mcp-and-agents.md#in-process-calls--createtoolinvoker) |
+| `createToolInvoker` | function | compile an exposure-aware in-process dispatcher over the canonical tool runner; use peer-free `stitchkit/tools/invoker`, or the full `stitchkit/tools` adapter barrel — [guide](../guide/mcp-and-agents.md#in-process-calls--createtoolinvoker) |
 | `createCli` | function | a command-line program from contracts — [guide](../guide/cli.md) (also on `stitchkit/cli`) |
 | `defineCliCommand` | function | define one typed CLI-only command with optional post-validation `present` and successful `exitCode` policy — [guide](../guide/cli.md#native-binary-commands) (also on `stitchkit/cli`) |
 | `createToolkit` | function | context-typed tool mounts — [guide](../guide/cli.md#typed-context) |
@@ -11881,7 +12054,8 @@ runtime-agnostic pieces of `stitchkit/server` and the error helpers.
 | `NodeSocketLifecycle` | _type_ | Bun-free Socket.IO lifecycle accepted by `serveNode` |
 | `HandlerConfig` / `ServiceDef` / `RawRoute` / `RawRouteContext` | _type_ | runtime-neutral handler types; raw routes default their host server to `unknown` |
 | `SocketIORequestPolicy` / `SocketIOServerConfig` / `SocketIOPeerLoaders` / `SocketIOServerHandle` | _type_ | runtime-neutral handshake policy, config, optional-peer loaders and the Bun-free Node handle with `io`, `attach` and lifecycle |
-| `UnixClientTransportConfig` / `UnixClientTransport` | _type_ | Unix socket bounds and owned Fetch-compatible handle |
+| `UnixClientTransportConfig` / `UnixClientTransport` | _type_ | Unix socket bounds, explicit response-body mode and owned Fetch-compatible handle |
+| `UnixResponseBodyMode` | _type_ | finite cumulative `bounded` mode or explicit pull-driven `streaming` mode |
 | `UnixClientTransportError` / `UnixClientTransportErrorCode` / `UnixClientDeliveryState` | class / _type_ | stable failure plus dispatch certainty; no cross-transport fallback |
 | `AppError` + `appError` / `badRequest` / `unauthorized` / `forbidden` / `notFound` / `conflict` / `rateLimited` | — | error helpers (same as `/contract`) |
 
@@ -11930,6 +12104,8 @@ and `react-query-kit` peers.
 | `createCacheBridge` | function | sync socket events into the Query cache — [guide](../guide/realtime.md#cache-bridge) |
 | `createEntityCacheHandlers` | function | created/updated/deleted cache handlers for one entity — [guide](../guide/realtime.md#entity-cache-handlers) |
 | `EntityCacheConfig` | _type_ | config for `createEntityCacheHandlers` |
+| `EntityCacheMembership` / `EntityCacheMembershipPolicy` | _type_ | per-exact-query `include | exclude | unknown` filter decision and unknown invalidation policy |
+| `EntityCacheTotalPolicy` / `EntityCacheTotalDeltaInput` | _type_ | evidence-aware reconciliation of numeric totals on paginated cache shapes |
 | `EntityCacheHandlers` | _type_ | the `{ created, updated, deleted }` handlers it returns |
 | `EntityCacheEvent` | _type_ | discriminated created/updated/deleted input for dynamic cache keys |
 | `EntityCacheKey` | _type_ | static `QueryKey` or event-aware key factory |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.68.0",
+  "version": "0.68.2",
   "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",
@@ -56,6 +56,10 @@
       "types": "./dist/tools.d.ts",
       "import": "./dist/tools.js"
     },
+    "./tools/invoker": {
+      "types": "./dist/tool-invoker.d.ts",
+      "import": "./dist/tool-invoker.js"
+    },
     "./cli": {
       "types": "./dist/cli.d.ts",
       "import": "./dist/cli.js"
@@ -119,9 +123,9 @@
   "scripts": {
     "check": "bun x tsc --noEmit",
     "build:browser": "bun build src/index.ts src/react.ts src/contract/index.ts src/declaration.ts --outdir dist --target node --packages external --splitting --root src",
-    "build:server": "bun build src/server/index.ts src/node.ts src/tools.ts src/cli.ts src/remote.ts src/files.ts src/testing.ts src/observability/index.ts src/agent-runtime.ts src/agent-runtime-openrouter.ts src/application.ts src/application-grammy.ts src/application-opentelemetry.ts --outdir dist --target node --packages external --splitting --root src",
-    "build:js": "bun run build:browser && bun run build:server",
-    "build:types": "bun x tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "build:server": "bun build src/server/index.ts src/node.ts src/tools.ts src/tool-invoker.ts src/cli.ts src/remote.ts src/files.ts src/testing.ts src/observability/index.ts src/agent-runtime.ts src/agent-runtime-openrouter.ts src/application.ts src/application-grammy.ts src/application-opentelemetry.ts --outdir dist --target node --packages external --splitting --root src",
+    "build:js": "bun run build:browser && bun run build:server && bun scripts/preserve-webpack-ignore.mjs",
+    "build:types": "bun x tsc -p tsconfig.build.json --emitDeclarationOnly && bun scripts/rewrite-declaration-specifiers.mjs",
     "build": "rm -rf dist && bun run build:js && bun run build:types && bun scripts/check-browser-clean.mjs && bun scripts/check-env-live.mjs && bun scripts/check-public-types.mjs",
     "dev": "bun run build:js -- --watch",
     "prepack": "cp ../../README.md ./README.md && bun ../../scripts/gen-llms.ts && bun run build",

package/dist/{index-avjd67h6.js → index-cz32amcb.js}

@@ -1,10 +1,10 @@
-import {
-  objectShapeKeys
-} from "./index-6djpbnda.js";
 import {
   getRequestContext,
   runWithRequestContext
 } from "./index-69m2278y.js";
+import {
+  objectShapeKeys
+} from "./index-6djpbnda.js";
 import {
   formatZodError,
   isUnsafeKey,