stitchkit 0.120.0 → 0.122.0

package/llms-full.txt

@@ -84,13 +84,13 @@ own, recorded as an ADR.
 | `stitchkit/xlsx` | browser **and** server | evolving | a workbook from rows and typed columns, with no dependency; text never runs as a formula |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 65 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 67 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, the managed-resource conformance kit and manual time for schedules and retries |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
 | `stitchkit/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
 | `stitchkit/react/keyboard/testing` | server (Bun or Node) | evolving | the keyboard layers and zones without a DOM — fakes for the window, elements and key events beside the two engines, to test the order of layers, `scope`/`inert` and the edges of a zone in milliseconds |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 25 of the 65 minors since 0.56.2, most recently 0.115.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 26 of the 67 minors since 0.56.2, most recently 0.121.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -102,7 +102,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 65 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 67 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
@@ -2698,6 +2698,54 @@ const internal = openApiRoute('/internal/openapi.json', fullDoc)   // behind aut
 const publicSpec = openApiRoute('/openapi.json', publicDoc)         // curated
 ```
 
+### Security schemes — `security`
+
+A generic client reads the spec to learn how to authenticate, and a scope name
+alone does not tell it which header to send. Pass `security` to describe that in
+standard OpenAPI terms: named schemes become `components.securitySchemes`, and
+every protected operation gets a `security` requirement. It is keyed by the
+scopes your contracts already declare, so there is no second list of which
+endpoint is protected:
+
+```ts
+const publicDoc = generateOpenApiDocument({
+  info: { title: 'Public API', version: '1.0.0' },
+  services: [account],
+  includeMethod: (m) => m.meta?.public === true,
+  security: {
+    schemes: {
+      apiKey: { type: 'http', scheme: 'bearer', description: 'An account API key' },
+    },
+    // Each protected scope → the schemes that satisfy it, any one of them.
+    scopes: { account: ['apiKey'] },
+  },
+})
+```
+
+A scheme is `{ type: 'http', scheme: 'bearer' | 'basic' }` or
+`{ type: 'apiKey', in: 'header' | 'query' | 'cookie', name }` (a session cookie
+is the `cookie` form). An operation is described by the scope the auth hook
+checks it under:
+
+| The operation's scope | In the document |
+|---|---|
+| `'public'` | no `security`, no 401/403 |
+| listed in `scopes` with schemes | `security: [{ apiKey: [] }, …]` and 401/403 |
+| listed with an empty list — a custom scope whose rule is `'public'` | no `security`, no 401/403 |
+| not listed | generation throws, naming the operation |
+| none of its own | read as `defaultScope` — pass the same value as `createAuthHook({ defaultScope })` |
+
+Generation refuses a protected scope it cannot describe instead of emitting the
+operation as open — a client would otherwise call it without a credential. Only
+the operations the document advertises need a mapping: a method `includeMethod`
+filters out is never checked. A scheme `scopes` names but `schemes` does not
+declare, and an entry for `'public'`, are refused the same way.
+
+The metadata describes your policy; it does not enforce it. The auth hook is
+still the only gate, and removing `security` changes the document, never a
+401 or 403. Credential values never belong here: describe where the key goes,
+not what it is.
+
 
 ==============================================================================
 # Guide: Typed client  (docs/guide/client.md)
@@ -4315,7 +4363,10 @@ render: async (ctx) => {
 
 `reportProgress` is present on every **tool** call — MCP, agent and CLI — so a
 handler never branches on transport, and it does nothing wherever nobody is
-listening. It is absent on the HTTP transport, which has no channel for it, so a
+listening. Under the agent runtime somebody is: each report becomes a transient
+`tool-progress` event of the run, so the person watching the agent sees the
+stage while the model still reads only the tool's result (see
+[Agent runtime → events](./agent-runtime.md)). It is absent on the HTTP transport, which has no channel for it, so a
 handler that also serves HTTP writes `ctx.reportProgress?.(…)`. It never throws and never
 rejects: a message about work must not be able to kill the work it describes, so
 a refused notification leaves the host exactly where a host that never asked for
@@ -5800,14 +5851,26 @@ outermost first, stopping at the first refusal; discovery rooted at `.` also ask
 Thus denying `credentials` denies everything
 under it. The comparison is segment-wise, so it does not deny `credentials-backup`, and a path of
 depth N costs N questions for direct access. Directory decisions happen before descent; file decisions and
-`search_files.include` happen before opening content. Requested paths use `/`: a backslash is
+`search_files.include` happen before opening content. Incompatible glob directory prefixes are
+pruned before policy or directory opens. Requested paths use `/`: a backslash is
 refused rather than normalised, because the workspace walk reads it as a separator and every
 authorization callback would otherwise be asked about a different decomposition than the one opened. File paths are relative, bounded and contained after
 descriptor-relative resolution: each ancestor is opened without following symlinks. Reads and edits
 stay pinned through authorization; `write_file` plans before it and opens the parent after, because
 the parent it creates does not exist yet. Reads revalidate the pinned file identity;
 writes and patches revalidate the pinned parent identity; search and resource discovery descend
-only through opened directories. A path that changed during authorization refuses with `CONFLICT`.
+only through opened directories. Every filesystem tool selects its root capability before operation or path authorization and retains
+that identity if a callback replaces the root path or configured alias. On Linux the ordinary
+command launcher spawns the command with the pinned directory's `/proc` descriptor link as its cwd;
+on macOS it inherits the pinned cwd through an isolated guard — one short-lived guard process per
+command, tens of milliseconds, outside `shellTimeoutMs`, which counts from the command's start. The
+application process never changes cwd. Where
+contained descriptors are unavailable (Windows), `run_command` accepts a cwd whose realpath is
+that same name under the root — a symlink segment refuses there too — and checks the directory's
+identity again immediately before launch, after every host decision.
+A custom sandbox launcher owns atomic cwd capture at its pathname handoff; the SDK refuses a
+changed identity after policy/prepare and immediately before that handoff. A path that changed
+during direct-access authorization refuses with `CONFLICT`.
 A path spelled differently from the name stored on disk refuses before any policy reads it, so on a
 case-insensitive volume a rule on `credentials` cannot be passed by asking for `CREDENTIALS`.
 NUL bytes are refused before either host policy sees a path.
@@ -5861,11 +5924,51 @@ crosses a process boundary and is rebuilt from the wire.
 excluded directory is not "no files", and a model told only "nothing found" concludes the wrong
 thing. `search_files` takes `regex`, `context` lines and an anchored `include` pattern matched
 against the whole workspace-relative path. `*` does not cross `/`, so files in subdirectories need
-`**/`; `scannedFiles` counts files admitted by both that filter and host authorization. A `hint`
-explains the zero only when the filter produced it, rejecting every file the scan reached; an empty
-tree and a host refusal return the same empty result without blaming the pattern. Regex is bounded by
-refusing backreferences and lookaround and capping line length rather than by a timeout, because a
-JavaScript `RegExp` cannot be interrupted once it starts backtracking. With an optional `AgentCodingArtifactStore`, shell output beyond the inline
+`**/`; `scannedFiles` counts files admitted by both that filter and host authorization that reached
+comparison. One finite glob automaton matches files and prunes incompatible directory prefixes;
+`glob` also confines its walk to the requested path. A `hint` can explain include filtering or
+pruning, without counting files below unopened directories.
+
+Search processes one file at a time. List, glob and search share directory, entry, serialized-output,
+timeout and cancellation budgets, including canonical spelling checks before path authorization.
+`list_directory` caps raw enumeration at the smaller of `maxListEntries` and `maxSearchEntries`;
+its coverage scope lists symlinks while glob/search skip them. Glob patterns are limited to 4,096
+UTF-16 units. A scoped glob measures depth from its requested base directory. In addition to `maxSearchFiles` (10,000), `maxSearchDepth`
+(32), `maxSearchResults` (100) and `maxReadBytes` (262,144), hosts can configure
+`maxSearchDirectories` (1,000 directory-open attempts, root included), `maxSearchEntries`
+(20,000 entries observed by bounded readers), `maxSearchBytes` (16,777,216 aggregate content
+bytes, including rejected UTF-8), `maxSearchOutputBytes` (65,536 bytes for the entire serialized
+UTF-8 JSON, minimum 1,024) and `searchTimeoutMs` (5,000). An input whose minimum coverage
+envelope cannot fit the output ceiling refuses before filesystem access. Directory readers cap
+enumeration before materialization and sorting; reaching an entry or result ceiling is
+conservatively partial, without reading a lookahead entry or match.
+
+`list_directory`, `glob` and `search_files` return `coverage.complete` and `coverage.reasons`
+to distinguish full empty results from partial work. Glob `resultTruncated` conservatively marks
+the result ceiling even when no extra match was read.
+Coverage names the include/exclusion/symlink scope, directory and entry counters, actual content
+bytes and elapsed milliseconds. Limits, cancellation, denial, unreadable files and oversized
+lines are explicit reasons. `errors` names only a workspace-relative path, operation and safe code;
+`errorsTruncated` and `deniedTruncated` report shortened diagnostics. Excluded directories and
+symlinks are outside the declared search scope. The caller's signal and deadline reach host
+authorization, file reads and traversal; CPU checkpoints and asynchronous races stop further work.
+Late opened handles are closed, while already-running kernel calls may finish later. Directory
+enumeration and glob matching have internal checkpoints; cancellation stops their producer loops.
+Host policy and visitor exceptions propagate to error hooks with their original cause, rather
+than becoming filesystem diagnostics. Diagnostic byte admission is linear and checks the deadline
+even for an empty result.
+
+Regex searches use JavaScript `RegExp` syntax without flags — groups, alternation, classes,
+anchors, `\b`, quantifiers and `(?ims-ims:…)` modifiers — with bounded cost per line. A line
+whose backtracking work (paths × longest path × line length × (number of groups + 1), every
+repetition capped at the line length beyond the iterations it requires) stays within 2^24 steps runs on the native engine, so ordinary `.*` searches over code
+lines keep native speed and the deadline is observed between lines; any other line runs on a
+cached linear automaton, so `(a+)+$` on a long line costs the same as `a+` and the deadline is
+observed inside the line. Backreferences and
+lookaround refuse before I/O; lines over 8,192 UTF-8 bytes are skipped with incomplete coverage.
+Literal queries allow up to 8,192 UTF-16 units and include patterns up to 4,096.
+
+With an optional `AgentCodingArtifactStore`, shell output beyond the inline
 preview continues into an opaque bounded artifact and `read_output` reads slices without
 exposing a host path. Without a store, the previous finite output-limit behavior is unchanged.
 
@@ -6733,6 +6836,19 @@ or it keeps the failed attempt's partial text on screen.
   start and output on completion. A mounted typed failure carries the same safe
   `{ error, retryable, details?, _hint? }` envelope as the durable result; an unknown
   internal cause remains generic and stays in local observability only;
+- `tool-progress` is transient: what a running tool handler reported through
+  `ctx.reportProgress` — `message`, `progress` and `total`, the fields an MCP host
+  receives — with the call's `callId` and `toolName`. It never enters the
+  model's input or the durable history. A message longer than
+  `AGENT_TOOL_PROGRESS_MESSAGE_MAX` (280) is cut, reports of one call closer
+  than 250 ms apart are dropped, and a report after the call's terminal
+  `tool-status` or after its attempt was abandoned is dropped; the terminal
+  status carries the final word. `reduceAgentControlEvent` keeps the last
+  report of each running call in `transientByRun[runId].tools[callId]` and
+  removes it on that call's `completed`, `failed` or `interrupted`. The runtime
+  hands its reporter to a call through the SDK tool context, beside its step
+  ledger; a tool that declares its own `contextSchema` keeps that contract and
+  reports nowhere;
 - `terminal` follows the winning terminal CAS.
 
 `loop.checkpointEveryEvents` batches ordinary stream parts (default `20`) and
@@ -8913,7 +9029,9 @@ concurrently or cancel the stream you ignore. Cancelling a stream drops its late
 command fails or is stopped, both streams error and the bytes still queued are dropped.
 
 A command needs a caller `signal` or a finite `timeoutMs` (1 to 2147483647 ms, the native timer
-range; a larger value is refused, never turned into 1 ms). Streaming runs for the caller's lifetime,
+range; a larger value is refused, never turned into 1 ms). `timeoutMs` counts from the moment the
+command started. A guarded command (`ownerLoss: 'terminate'`) first starts its guard; that start is
+bounded by `timeoutMs` or 5 seconds, whichever is longer, and does not use the command's budget. Streaming runs for the caller's lifetime,
 with no hidden 60-second timeout or 1 MiB output limit. `capture` defaults to false; `true` requires
 `maxOutputBytes` for the combined stdout and stderr. The limit counts source bytes; the API returns
 `Uint8Array` and does not decode invalid UTF-8. The result holds the observed `exitCode: number | null`
@@ -10713,15 +10831,27 @@ Rules worth knowing before you rely on them:
 A failed call still reports its own error and exit code. An aggregate over an
 error is not an answer to the question that was asked.
 
-If the command succeeds but its requested view cannot be built, the CLI writes
-the complete original result to stdout, using the normal JSON format (`--json`
-still selects compact output). It writes a separate structured
-`CLI_PRESENTATION_FAILED` diagnostic to stderr and exits with `8`, configurable
-through `exitCodes`. Its `details.operationSucceeded: true` and `retryable: false`
-distinguish a presentation refusal from a failed operation; `details.cause`
-preserves the safe reason. Recover the answer from stdout instead of repeating
-the mutation. Domain retry hints are not appended to this diagnostic. CLI
-argument errors detected before execution still exit with `2`
+If the command succeeds but its requested view cannot be built, the CLI writes a
+structured `CLI_PRESENTATION_FAILED` diagnostic to stderr and exits with `8`,
+configurable through `exitCodes`. Its `details.operationSucceeded: true` and
+`retryable: false` distinguish a presentation refusal from a failed operation;
+`details.cause` preserves the safe reason, such as the misspelled field and the
+fields that are there. Domain retry hints are not appended to this diagnostic.
+
+What reaches stdout depends on whether the command can be called again for its answer,
+and `details.resultOnStdout` states which case occurred:
+
+| Command | stdout | Recover the answer by |
+|---|---|---|
+| has an effect | the complete original result in the normal JSON format (`--json` still selects compact output) | reading stdout — never by repeating the mutation |
+| only reads | nothing | repeating the command with a corrected view |
+
+A managed command only reads when its tool declares `annotations.readOnlyHint: true`,
+or declares no `readOnlyHint` and its method is `GET`. `readOnlyHint: false` on a `GET`
+endpoint keeps the result on stdout. A native `defineCliCommand` declares neither fact,
+so a failed `present` always keeps the validated result on stdout.
+
+CLI argument errors detected before execution still exit with `2`
 and have no successful result to preserve.
 
 ## Named profiles
@@ -17149,6 +17279,84 @@ charts, no merged cells and no streaming: an application that needs them takes a
 
 # Upgrading stitchkit
 
+## Released migration: 0.122.0
+
+### read-view-refusal
+
+**Who must act:** scripts and agents that read stdout after a managed CLI command exits with
+`CLI_PRESENTATION_FAILED` (`8` by default) when that command is a `GET` endpoint or a tool
+declaring `annotations.readOnlyHint: true`. Commands with an effect and native
+`defineCliCommand` presenters change nothing.
+
+A read no longer prints its complete result when the requested view is refused; stdout is
+empty and the diagnostic carries `details.resultOnStdout: false`.
+
+```sh
+# before: the full list arrived on stdout beside the diagnostic
+app user_list --table id,nosuchcolumn > users.json   # exit 8, users.json holds every record
+
+# after: repeat the read with a field the diagnostic names
+app user_list --table id,nosuchcolumn                # exit 8, stdout empty
+app user_list --table id,name
+```
+
+A `GET` endpoint whose call has an effect that must not be repeated declares it, and keeps
+its result on stdout:
+
+```ts
+tool: { name: 'token_rotate', annotations: { readOnlyHint: false } }
+```
+
+## Released migration: 0.121.0
+
+### bounded-coding-search
+
+**Who must act:** hosts that construct a complete `AgentCodingToolLimits` value, inspect exact
+`list_directory`, `glob` or `search_files` output objects, rely on symlink cwd aliases, call `glob` on a path that may not exist, or send regex named backreferences or counted repetition above 1,000.
+
+Partial `limits` still fill finite defaults. Complete values add:
+
+```ts
+maxSearchDirectories: 1_000,
+maxSearchEntries: 20_000,
+maxSearchBytes: 16_777_216,
+maxSearchOutputBytes: 65_536,
+searchTimeoutMs: 5_000,
+```
+
+Read `coverage.complete` on list, glob and search before interpreting an empty result.
+List raw enumeration is also capped by `maxListEntries`; glob patterns have a 4,096-unit ceiling.
+The ordinary command cwd is a pinned directory, so descendant symlink cwd aliases are refused;
+use the real relative directory name. Custom sandbox launchers own atomic cwd capture.
+`coverage.reasons` names stopped
+budgets, cancellation, denial, unreadable files and lines beyond the searchable byte ceiling.
+`coverage.scope` names the workspace-relative include, exclusion policy and symlink policy;
+directory/entry/read-byte counters report work reached by the bounded reader. Denied and error
+lists can themselves be truncated. The entire UTF-8 JSON result fits `maxSearchOutputBytes`
+(minimum 1,024); an input whose minimum envelope cannot fit refuses before I/O.
+
+Regex queries keep JavaScript syntax, `(?ims-ims:…)` modifiers and Annex B forms, and their
+cost is bounded per line: a line whose backtracking work, repetition capped at the line's length,
+stays within 2^24 steps runs natively, any other line in linear time. Named backreferences,
+counted repetition above 1,000 and patterns needing the automaton with more than 16,384 automaton states, 65,536
+construction steps (nested repetition of an empty group such as `(?:(?:){1000}){1000}`) or
+4,194,304 overlapping character-set memberships now return `BAD_REQUEST`
+before authorization or file access, as
+numbered backreferences and lookaround already did. Spell the repeated text out, for example
+replace `{ query: '(?<w>ab)\\k<w>', regex: true }` with `{ query: '(ab)ab', regex: true }`.
+
+`glob` with a `path` that is missing, a file or a symlink now refuses (`NOT_FOUND` or
+`BAD_REQUEST`, with a hint) instead of returning no paths; treat that refusal as "nothing
+there". `run_command` refuses such a `cwd` the same way.
+
+Glob matching preserves `**`, `*`, `?` and literal punctuation, including embedded `**`.
+A pattern that prunes directories may produce an explanatory `hint` without counting unseen
+files. `glob` confines traversal to its requested path and viable pattern prefixes.
+
+Traversal checks cancellation and deadlines at CPU checkpoints and races asynchronous waits.
+Late opened handles are closed; in-flight operating-system calls are not claimed to be interrupted.
+Reaching an entry or result ceiling conservatively reports partial coverage without a lookahead.
+
 ## Released migration: 0.120.0
 
 ### tools-barrel-subpaths
@@ -22625,7 +22833,7 @@ from the root `stitchkit`.
 | `McpProgressUpdate` | _type_ | one mid-call progress update — `message`, and `progress`/`total` when the operation knows a scale |
 | `McpReportProgress` | _type_ | `ctx.reportProgress` — sends one update to the host that asked for progress; a no-op when none did, and never throws |
 | `McpRoundOutcome` | _type_ | managed multi-round attempt outcome |
-| `EndpointHandlerContext` | _type_ | one endpoint handler's fully inferred params, input, files and runtime context |
+| `HandlerContext` | _type_ | contract handler's fully inferred params, input, files and runtime context |
 | `EndpointFn` | _type_ | the call signature of one client method |
 | `TypedClient` | _type_ | the full typed client for a contract |
 | `TypedHttpClient` | _type_ | the typed client, HTTP endpoints only (`= ScopedHttpClient<C, unknown>`) |
@@ -22780,6 +22988,8 @@ schedules, transports and file generation remain application-owned.
 
 ## `stitchkit/server`
 
+`EndpointHandlerContext` is the server endpoint handler’s inferred params, input, files and runtime context.
+
 Server-only. Builds and runs the HTTP server, and carries the server primitives.
 Also re-exports the error helpers from `stitchkit/contract`.
 
@@ -22995,6 +23205,8 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `OpenApiConfig` | _type_ | config for `generateOpenApiDocument` (incl. `includeMethod` — curate a public subset) — [guide](../guide/server.md#curating-the-spec--includemethod) |
 | `OpenApiDocument` | _type_ | the generated document |
 | `OpenApiInfo` | _type_ | the spec `info` block |
+| `OpenApiSecurity` | _type_ | `OpenApiConfig.security` — named schemes and the schemes each protected scope accepts — [guide](../guide/server.md#security-schemes--security) |
+| `OpenApiSecurityScheme` | _type_ | one way a caller presents its credential: HTTP bearer or basic, or an API key in a header, query or cookie |
 | `OpenApiServer` | _type_ | a spec `servers` entry |
 
 ---
@@ -23016,6 +23228,8 @@ lane never reaches the hooks on either runtime.
 
 ## `stitchkit/application`
 
+Construct a directory inbox with `createDirectoryInbox` from `stitchkit/application/directory-inbox`.
+
 `StartFact` also carries `previousDrainUpperBoundMs`: the time from a predecessor's recorded admission stop to this start when its exit is `interrupted`, otherwise `null`. This is an upper bound, and does not identify a kill signal or supervisor deadline.
 
 
@@ -23041,7 +23255,7 @@ cutovers are covered by the executable
 | `NotificationOutboxItem` / `NotificationOutboxReceipt` / `NotificationOutboxState` / `NotificationSend` / `NotificationFailureClassification` / `DroppedNotification` / `EnqueueNotification` | _type_ | versioned queue records, stable send identity and delivery decisions |
 | `notificationOutboxStateSchema` | function | strict persisted-state schema over an application payload schema |
 | `notificationOutboxResource` / `NotificationOutboxResource` / `NotificationOutboxResourceConfig` | function / _type_ | thin managed-resource scheduler over an outbox handle |
-| `createDirectoryInbox` (from `stitchkit/application/directory-inbox`) / `DirectoryInbox` / `DirectoryInboxConfig` / `DirectoryInboxDelivery` / `DirectoryInboxResource` | function / _type_ | one managed directory inbox for files or durable `accept({ source, key, entry })` (`entry` is the schema's input, stored as given); a hard-linked file is set aside as `invalid`; first payload wins, bounded capacity/bytes/receipts and renewable fenced leases; delivery begins after readiness and effects remain at least once |
+| `DirectoryInbox` / `DirectoryInboxConfig` / `DirectoryInboxDelivery` / `DirectoryInboxResource` | _type_ | one managed directory inbox for files or durable `accept({ source, key, entry })` (`entry` is the schema's input, stored as given); a hard-linked file is set aside as `invalid`; first payload wins, bounded capacity/bytes/receipts and renewable fenced leases; delivery begins after readiness and effects remain at least once |
 | `DirectoryInboxIdentitySchema` / `DirectoryInboxIdentity` / `DirectoryInboxAccept` / `DirectoryInboxAcceptResultSchema` / `DirectoryInboxAcceptResult` | schema / _type_ | validated source/key, typed entry and durable accepted/duplicate result with filename; duplicates do not replace the first payload |
 | `StateStoreUpdateContext` | _type_ | real active protected transaction: `assertHeld()` refuses after ownership loss or completion; custom adapters supply this context to their transition |
 | `DirectoryInboxStateSchema` / `DirectoryInboxState` / `DirectoryInboxRejection` / `DirectoryInboxRejectionReasonSchema` / `DirectoryInboxRejectionReason` | schema / _type_ | the inbox's claims, receipts and rejections (`invalid`, `too-large`, `attempt-limit`) |
@@ -23124,9 +23338,10 @@ cutovers are covered by the executable
 
 ### Bounded diagnostic journal
 
+Construct the writer with `createDiagnosticJournal` from `stitchkit/application/diagnostic-journal`.
+
 | Export | Kind | Summary |
 |--------|------|---------|
-| `createDiagnosticJournal` | function | create one schema-owned FIFO JSONL writer with bounded retained memory, exclusive local path ownership and finite rotation |
 | `DiagnosticJournalConfig` / `DiagnosticJournal` | _type_ | owner schema/path/limits/failure observer, `startupScan` (`tails` by default, or `full`), `onStartupRefusal` (`quarantine` by default, or `fail`) and the synchronous `submit`, bounded-wait `flush`/`close`, status handle |
 | `DiagnosticJournalLimitsSchema` / `DiagnosticJournalLimits` | schema / _type_ | positive event, pending-item, pending-byte, file-byte and retained-file limits |
 | `DiagnosticJournalLockPolicySchema` / `DiagnosticJournalLockPolicy` | schema / _type_ | `refuse` (default) or `reclaim-stale`, which reclaims only a lock whose recorded owner is provably gone |
@@ -23625,7 +23840,9 @@ Delivery exports are `AgentAdmissionEventSchema`, `AgentAttemptResetEventSchema`
 `AgentRunStateEventSchema`, `AgentRunOperationEventSchema`, `AgentTerminalEventSchema`,
 `AgentTransientDeltaEventSchema`,
 `AgentReasoningStartEventSchema`, `AgentReasoningDeltaEventSchema`,
-`AgentReasoningEndEventSchema`, `AgentToolStatusEventSchema`, `AgentRuntimeEvent`,
+`AgentReasoningEndEventSchema`, `AgentToolStatusEventSchema`, `AgentToolProgressEventSchema` (what a
+running tool reported through `ctx.reportProgress`, transient and never part of the model's input),
+`AgentRuntimeEvent`,
 `AgentRuntimeEventCursor`, `AgentRuntimeEventCursorSchema`, `AgentRuntimeCursorAdvance`,
 `advanceAgentRuntimeEventCursor`, `agentDurableEventId`, `AgentRuntimeEventSink`,
 `AgentRuntimeEventSinkConfig` and `createAgentRuntimeEventSink`. Cursor gaps require a canonical
@@ -23732,28 +23949,28 @@ artifact store is supplied, `read_output`.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createAgentCodingTools` | function | construct direct host-authorized bounded file, listing, glob, search, exact-snippet edit, shell and artifact runtime-tool definitions; `edit_file` inserts `newText` literally in both single and `replaceAll` modes; every ordinary refusal is a typed code with an instructive `hint`, and filesystem operations use Linux `/proc/self/fd` or the packaged macOS Node-API backend and otherwise fail closed |
-| `AGENT_CODING_TOOL_NAMES` | const | the mounted tool names — `read_file`, `write_file`, `edit_file`, `list_directory`, `glob`, `search_files`, `run_command`, `read_output` |
 | `AgentCodingToolDefinition` | _type_ | peer-free structural direct-tool shape accepted by the canonical runtime-tool surface |
 | `AgentCodingToolConfig` | _type_ | absolute root, required operation authorization, optional async/sync `authorizePath({ path })` shared by direct file effects and discovery, finite executable alias map, exact child environment and optional limits |
 | `AgentCodingToolAuthorizationSchema` / `AgentCodingToolAuthorization` | schema / _type_ | discriminated read/write/search/patch/shell/artifact decision presented to host policy before effect |
 | `AgentCodingToolPathAuthorizationSchema` / `AgentCodingToolPathAuthorization` | schema / _type_ | strict workspace-relative path presented to the shared path policy before disclosure, opening or mutation |
-| `AgentCodingToolLimitsSchema` / `AgentCodingToolLimits` | schema / _type_ | explicit path/read/write/argument-count/argument-byte/output/artifact/timeout/termination-grace ceilings |
+| `AgentCodingToolLimitsSchema` / `AgentCodingToolLimits` | schema / _type_ | explicit path/read/write/argument-count/argument-byte/output/artifact/timeout/termination-grace ceilings; shared discovery directory/entry/serialized-output/deadline ceilings, aggregate search-read ceiling and measured coverage |
 | `AgentCodingArtifactStore` | _type_ | host-owned opaque artifact write and bounded read boundary |
-| `FileReadInputSchema` / `FileReadOutputSchema` | schema | bounded strict-UTF-8 byte slice; offsets must align with UTF-8 code-point boundaries |
-| `FileWriteInputSchema` / `FileWriteOutputSchema` | schema | create-only by default or explicit atomic replacement; symlink targets fail closed |
-| `createShellInputSchema` / `ShellOutputSchema` | schema | enumerated executable alias plus arguments and concrete relative cwd; explicit exited/timeout/output-limit/cancelled outcome |
 
-File/search operations pin directory descriptors across authorization and the actual effect;
+File/search operations select a root descriptor before both policy callback kinds and pin directory descriptors across authorization and the actual effect;
 resource discovery uses the same ancestor-safe traversal. This closes parent rename/symlink races
-without claiming an executable sandbox. The default ceilings are 4,096 path bytes, 256 KiB read/write/output, 128 shell arguments, 64 KiB
+without claiming an executable sandbox. The ordinary command launcher passes a pinned cwd to its
+isolated guard (inherited fd 4); a custom sandbox launcher owns atomic capture of its pathname cwd. List/glob/search report coverage; canonical spelling work consumes the same budget. List raw entries
+are capped by maxListEntries and maxSearchEntries, and glob patterns by 4,096 UTF-16 units.
+The default ceilings are 4,096 path bytes, 256 KiB read/write/output, 128 shell arguments, 64 KiB
 of aggregate argument text, 4 MiB per artifact and 30 seconds. The root is a path-resolution
 boundary, not an OS sandbox; executable behavior, process
 isolation, credentials and external-effect idempotency remain host responsibilities.
 
 When `authorizePath` denies a path, direct read/write/edit returns `FORBIDDEN`, while
 `list_directory`, `glob` and `search_files` omit it. Denial is recursive: direct access and
-discovery base paths are checked against `.` and every ancestor, outermost first and segment-wise,
-so denying `credentials` denies `credentials/token.txt` but not `credentials-backup`. Directory
+discovery base paths check every named ancestor, outermost first and segment-wise; `.` is
+checked only when the requested base itself is `.`, so subtree allowlists remain usable. Thus
+denying `credentials` denies `credentials/token.txt` but not `credentials-backup`. Directory
 admission happens before descent and file admission before opening; `search_files.include` is also
 applied before content is read. Requested paths must use `/` — a backslash is refused, because the
 containment walk reads it as a separator while a callback would read it as one name.
@@ -23779,7 +23996,10 @@ including `AgentAttemptResetEventSchema` for `attempt-reset`),
 `AgentControlErrorCodeSchema` / `AgentControlErrorCode` (the one vocabulary of every control
 error code: `FORBIDDEN`, `CONNECTION_CLOSED`, `REQUEST_CAPACITY`, `ATTACHMENT_CAPACITY`,
 `LEASE_CONFLICT`, `EVENT_OVERFLOW` and the rest), `AgentMultiSessionCursorSchema` /
-`AgentMultiSessionCursor`, `AgentConversationView`, `AgentControlView`,
+`AgentMultiSessionCursor`, `AgentConversationView`, `AgentControlView`, `AgentRunTransient` (a
+run's streamed text, reasoning and running tool calls before its next checkpoint),
+`AgentToolActivity` (one running call with its last reported progress),
+`AGENT_TOOL_PROGRESS_MESSAGE_MAX` (the longest progress message a run publishes),
 `advanceAgentMultiSessionCursor`, `createAgentControlView`, `reduceAgentControlSnapshot`,
 `reduceAgentControlEvent` and
 `agentDurableEventId`. It imports no model provider, executor, store, event sink

package/llms.txt

@@ -14,25 +14,25 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/react**: [llms/react.txt](llms/react.txt) 8.7 KB
 - **stitchkit/react/keyboard**: [llms/react-keyboard.txt](llms/react-keyboard.txt) 22.7 KB
 - **stitchkit/react/keyboard/testing**: [llms/react-keyboard-testing.txt](llms/react-keyboard-testing.txt) 1.9 KB
-- **stitchkit/tools**: [llms/tools.txt](llms/tools.txt) 46.7 KB → [llms/tools.2.txt](llms/tools.2.txt) 30.5 KB → [llms/tools.3.txt](llms/tools.3.txt) 21.0 KB
+- **stitchkit/tools**: [llms/tools.txt](llms/tools.txt) 47.0 KB → [llms/tools.2.txt](llms/tools.2.txt) 30.5 KB → [llms/tools.3.txt](llms/tools.3.txt) 21.0 KB
 - **stitchkit/tools/mcp**: [llms/tools-mcp.txt](llms/tools-mcp.txt) 6.6 KB
 - **stitchkit/tools/agent**: [llms/tools-agent.txt](llms/tools-agent.txt) 1.1 KB
 - **stitchkit/tools/toolkit**: [llms/tools-toolkit.txt](llms/tools-toolkit.txt) 0.9 KB
 - **stitchkit/tools/contract**: [llms/tools-contract.txt](llms/tools-contract.txt) 0.2 KB
 - **stitchkit/tools/invoker**: [llms/tools-invoker.txt](llms/tools-invoker.txt) 0.2 KB
 - **stitchkit/tools/connections**: [llms/tools-connections.txt](llms/tools-connections.txt) 3.9 KB
-- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 36.6 KB → [llms/cli.2.txt](llms/cli.2.txt) 36.4 KB
+- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 37.2 KB → [llms/cli.2.txt](llms/cli.2.txt) 36.4 KB
 - **stitchkit/cli/publish**: [llms/cli-publish.txt](llms/cli-publish.txt) 1.5 KB
 - **stitchkit/remote**: [llms/remote.txt](llms/remote.txt) 1.0 KB
 - **stitchkit/contract**: [llms/contract.txt](llms/contract.txt) 33.8 KB
 - **stitchkit/primitives**: [llms/primitives.txt](llms/primitives.txt) 13.2 KB
-- **stitchkit/server**: [llms/server.txt](llms/server.txt) 44.2 KB → [llms/server.2.txt](llms/server.2.txt) 20.9 KB → [llms/server.3.txt](llms/server.3.txt) 47.0 KB → [llms/server.4.txt](llms/server.4.txt) 38.6 KB → [llms/server.5.txt](llms/server.5.txt) 23.1 KB
+- **stitchkit/server**: [llms/server.txt](llms/server.txt) 44.2 KB → [llms/server.2.txt](llms/server.2.txt) 23.1 KB → [llms/server.3.txt](llms/server.3.txt) 47.0 KB → [llms/server.4.txt](llms/server.4.txt) 38.6 KB → [llms/server.5.txt](llms/server.5.txt) 23.5 KB
 - **stitchkit/observability**: [llms/observability.txt](llms/observability.txt) 46.9 KB
-- **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 44.3 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 46.8 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 39.7 KB → [llms/agent-runtime.4.txt](llms/agent-runtime.4.txt) 11.7 KB
+- **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 47.6 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 43.3 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 45.1 KB → [llms/agent-runtime.4.txt](llms/agent-runtime.4.txt) 11.7 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
-- **stitchkit/agent-runtime/browser**: [llms/agent-runtime-browser.txt](llms/agent-runtime-browser.txt) 3.8 KB
+- **stitchkit/agent-runtime/browser**: [llms/agent-runtime-browser.txt](llms/agent-runtime-browser.txt) 4.0 KB
 - **stitchkit/agent-runtime/openrouter**: [llms/agent-runtime-openrouter.txt](llms/agent-runtime-openrouter.txt) 1.1 KB
 - **stitchkit/agent-runtime/sqlite/bun**: [llms/agent-runtime-sqlite-bun.txt](llms/agent-runtime-sqlite-bun.txt) 1.8 KB
 - **stitchkit/agent-runtime/sqlite/node**: [llms/agent-runtime-sqlite-node.txt](llms/agent-runtime-sqlite-node.txt) 1.7 KB
@@ -64,7 +64,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/node**: [llms/node.txt](llms/node.txt) 3.1 KB
 - **stitchkit/agent-runtime/react**: [llms/agent-runtime-react.txt](llms/agent-runtime-react.txt) 1.0 KB
 - **stitchkit/agent-runtime/realtime**: [llms/agent-runtime-realtime.txt](llms/agent-runtime-realtime.txt) 2.6 KB
-- **stitchkit/process**: [llms/process.txt](llms/process.txt) 44.5 KB → [llms/process.2.txt](llms/process.2.txt) 4.3 KB
+- **stitchkit/process**: [llms/process.txt](llms/process.txt) 44.7 KB → [llms/process.2.txt](llms/process.2.txt) 4.3 KB
 - **stitchkit/process/owner-loss**: [llms/process-owner-loss.txt](llms/process-owner-loss.txt) 0.9 KB
 - **stitchkit/files/packaging**: [llms/files-packaging.txt](llms/files-packaging.txt) 3.5 KB
 - **stitchkit/http**: [llms/http.txt](llms/http.txt) 0.9 KB
@@ -72,7 +72,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 
 ## Upgrading slices
 - **Upgrading — how to move across versions**: [llms/upgrading.txt](llms/upgrading.txt) 12.7 KB
-- **Upgrading 0.106.0 → 0.120.0**: [llms/upgrading-0.106.0-0.120.0.txt](llms/upgrading-0.106.0-0.120.0.txt) 30.5 KB
+- **Upgrading 0.106.0 → 0.122.0**: [llms/upgrading-0.106.0-0.122.0.txt](llms/upgrading-0.106.0-0.122.0.txt) 34.4 KB
 - **Upgrading 0.96.0 → 0.105.0**: [llms/upgrading-0.96.0-0.105.0.txt](llms/upgrading-0.96.0-0.105.0.txt) 45.8 KB
 - **Upgrading 0.69.0 → 0.95.0**: [llms/upgrading-0.69.0-0.95.0.txt](llms/upgrading-0.69.0-0.95.0.txt) 46.6 KB
 - **Upgrading 0.55.0 → 0.68.0**: [llms/upgrading-0.55.0-0.68.0.txt](llms/upgrading-0.55.0-0.68.0.txt) 47.0 KB

package/native-assets.json

@@ -4,13 +4,13 @@
   "assets": {
     "arm64": {
       "path": "native/darwin-arm64.node",
-      "size": 52912,
-      "sha256": "abd9f0dcebb9330cc7206d7b7c735e3af5f54436393f482adc8e73e3373bbdf1"
+      "size": 53152,
+      "sha256": "2dcbf34310db6cd32d2bc1f3ffad4a1924b84b9107f97d81f5616909dbf61507"
     },
     "x64": {
       "path": "native/darwin-x64.node",
-      "size": 23736,
-      "sha256": "aa0bc3084497eea9ac19bd060ee8456e7e8642c1b0035f0b224e9811ccfae133"
+      "size": 23984,
+      "sha256": "0c052fb61b4d744fba091ac40f4e3cac6bf1d5eac8ca884648661023e4e36a94"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.120.0",
+  "version": "0.122.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",
@@ -405,6 +405,7 @@
     "@modelcontextprotocol/server": "^2.4.0",
     "@openrouter/ai-sdk-provider": "^3.1.0",
     "@opentelemetry/api": "^1.10.0",
+    "@seriousme/openapi-schema-validator": "^2.11.0",
     "@socket.io/bun-engine": "^0.1.2",
     "@socket.io/component-emitter": "^3.1.2",
     "@tanstack/react-query": "5.105.3",