stitchkit 0.113.0 → 0.113.2

package/llms/cli.2.txt

@@ -149,9 +149,10 @@ One unconvertible schema does not take the connection down. The tool
 is skipped and **named** (`onSkippedTool`, or a stderr line by default), so a
 surface of two hundred tools is not lost to one.
 
-**A discovered schema is checked locally, except for its unions.** The arguments are
-coerced and parsed against the schema the server advertised, so a missing field or a
-wrong scalar is refused before anything is sent. A union in that schema is not judged
+**A discovered schema leaves unions and string formats to its server.** The arguments are
+coerced and parsed against the schema the server advertised. Reported structural failures
+(a missing field, wrong scalar type, unknown key or enum value) and bounds stay local.
+A union in that schema is not judged
 here: a server's presentation may join a discriminated union into one object whose
 shared field is an unlabelled `anyOf` (a stitchkit server with `flattenUnionInput`
 does), and judged against that, a wrong value could only be refused with every branch
@@ -159,6 +160,16 @@ listed. The value goes to the server, which holds the original schema, and its r
 names the one wrong field — `blocks.0.data.artifactId: expected string` rather than
 `No union branch matched — branch 1 … and 6 more branches`.
 
+String formats and patterns also lose the author's error messages in JSON Schema. A
+restored `date-time`, email, UUID or regex check would substitute Zod's generic wording.
+Those `invalid_format` refusals go to the remote instead: a bare `2026-10-12` reaches
+the original datetime schema, whose answer can explain that a full UTC timestamp such
+as `2026-10-12T00:00:00Z` is required. This also applies inside arrays, objects and
+record keys. A mixed refusal retains only its reported local reasons; a record-key
+wrapper stays local when it contains any of those reasons. A schema authored locally
+keeps its complete verdict, including custom errors and refinements. No second parse
+invents checks that the first parse did not reach. See [ADR 0272](../decisions/0272-a-restored-string-format-is-judged-by-its-server.md).
+
 MCP connection limits follow the operation phase. `initialize`, the initialized
 notification, `tools/list` and legacy endpoint discovery use `limits.discovery`;
 `tools/call` uses `limits.call`. A mounted call's handshake still uses discovery
@@ -279,7 +290,7 @@ SDK nor the `ai` peer.
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `createCli` | function | build and run a CLI from contracts — [guide](../guide/cli.md) |
+| `createCli` | function | build and run a CLI from contracts; a runtime catalogue field conflicting with reserved/global argv options disables only that entry, retained in help with its reason; invocation returns `CLI_COMMAND_UNAVAILABLE` before side effects — [guide](../guide/cli.md#when-one-runtime-command-cannot-be-represented-in-argv) |
 | `defineCliCommand` | function | define one Zod-typed CLI-only executable command with optional validated-result presentation/exit policy |
 | `parseCliArgs` | function | argv → typed tool args against a schema; inline `--field:=JSON` assigns a whole JSON value, including null, while ordinary string flags remain lexical; named array options together with bare positionals require an explicit `positionals` policy (advanced) |
 | `routeCliArgv` | function | select the command out of argv without duplicating the global-option grammar (advanced) |

package/llms/cli.txt

@@ -490,13 +490,42 @@ command name — validated against the declared schema, and kept out of every
 operation's arguments: `handoff_read` above receives `{ handoffId: 'u' }` and
 nothing else. The values reach `resolveAuth(globals)`, `context(auth, globals)`
 and a native command's `globals`. An invalid value is an argument error naming
-the flag; a name that collides with a framework option, or with a field of any
-command, is refused at startup rather than shadowing it silently. Past a bare
+the flag. An application global that collides with a framework option is refused
+at startup. Field collisions in authored commands are configuration errors;
+runtime catalogue entries are isolated as described below. Past a bare
 `--` every token is a literal, so a positional value that reads like a global
 survives intact.
 
 Both help levels list them under `Application options:`.
 
+## When one runtime command cannot be represented in argv
+
+A `runtimeTools` catalogue can change independently of the CLI application. An
+entry whose input declares a framework option such as `json`, or a field shadowed
+by an application global such as `caller`, cannot receive that field through argv.
+Only that entry becomes unavailable. Other commands still run, and top-level,
+filtered and command-specific help retain the entry and its full reason:
+
+```text
+  inspect  Inspect an operation [unavailable]
+    Unavailable: [stitchkit] CLI command "inspect" declares field(s) shadowed by application global options: caller
+```
+
+Calling it returns `CLI_COMMAND_UNAVAILABLE`, `retryable: false`, and the same
+reason in `details.message` on stderr; the default exit code is 1. `--json`
+compacts the error as usual; `exitCodes` and `errorHint` apply. The refusal precedes
+command argument parsing, stdin, context, hooks and the handler; `--dry-run` cannot
+turn it into success. A known unavailable `--wait` target returns the same refusal;
+an unknown target keeps `NOT_FOUND`.
+
+This isolates only reserved/global **field** conflicts in `runtimeTools`.
+Native commands and contract-defined `services` still fail at startup for those
+conflicts. Duplicate or reserved command names and invalid local aliases,
+positionals or passthrough policies remain configuration errors for every entry.
+`createCliInvoker` receives globals and command input separately and has no argv
+projection, so its own `caller` or `json` input stays callable without renaming.
+See [ADR 0273](../decisions/0273-a-runtime-cli-field-conflict-is-one-commands-unavailability.md).
+
 ## When the managed surface cannot resolve
 
 A CLI whose commands come from a running server declares them with a factory,

package/llms/server.4.txt

@@ -553,7 +553,7 @@ core never models them (ADR 0002). But stitchkit itself emits a set of its own:
 `FILE_INSPECTION_REJECTED`, `FILE_TOO_LARGE`, `FILE_EXISTS`,
 `REALTIME_CONTRACT_VIOLATION`, `APPLICATION_NOT_ACCEPTING`, `NOT_IMPLEMENTED`,
 `WAIT_TIMEOUT`,
-`WAIT_FAILED`, `DOWNLOAD_NOT_FOUND`, `VIEW_HTTP_ERROR`,
+`WAIT_FAILED`, `CLI_COMMAND_UNAVAILABLE`, `DOWNLOAD_NOT_FOUND`, `VIEW_HTTP_ERROR`,
 `CONNECTION_TIMEOUT`, `CONNECTION_RESPONSE_TOO_LARGE`,
 `CONNECTION_REQUEST_FAILED`, `UPSTREAM_TOOL_ERROR`,
 `OPERATION_NOT_SUCCEEDED`, `STREAM_ITEM_INVALID`, `STREAM_FRAME_TOO_LARGE`,

package/llms/tools-connections.txt

@@ -27,7 +27,7 @@ and approval path.
 | `ConnectionPhase` / `ConnectionOperation` / `ConnectionFailureContext` | _type_ | closed operation/phase vocabulary and measured read context for existing typed connection errors |
 | `ConnectionTimeoutError` / `ConnectionResponseTooLargeError` | class | bounded operation refusal, with phase, operation and finite observed bytes; safe tool projection retains the raw cause locally |
 | `defineOpenApiConnection` | function | declare one OpenAPI document (object, JSON text or JSON URL) as a tool surface |
-| `mountConnections` | function | discover every connection and return readonly `RuntimeToolDefinition`s for `mountAgent`; a call's arguments are parsed against the discovered schema before sending, except its unions, which the server judges (ADR 0266) |
+| `mountConnections` | function | discover every connection and return readonly `RuntimeToolDefinition`s for `mountAgent`; reported structural failures and bounds stay local, while unions and string-format/pattern refusals (including inside record keys) are judged by the server that owns the original schema (ADR 0266, ADR 0272) |
 | `ConnectionAuthorizationRequiredError` | class | typed reauthorization signal raised on `401` with credentials resolved again on the next call |
 | `ConnectionBudgetExceededError` | class | the mount would expose more foreign tools than its declared budget |
 | `ConnectionRequestError` | class | any non-`2xx` connection response other than the reauthorization signal |

package/llms-full.txt

@@ -10289,13 +10289,42 @@ command name — validated against the declared schema, and kept out of every
 operation's arguments: `handoff_read` above receives `{ handoffId: 'u' }` and
 nothing else. The values reach `resolveAuth(globals)`, `context(auth, globals)`
 and a native command's `globals`. An invalid value is an argument error naming
-the flag; a name that collides with a framework option, or with a field of any
-command, is refused at startup rather than shadowing it silently. Past a bare
+the flag. An application global that collides with a framework option is refused
+at startup. Field collisions in authored commands are configuration errors;
+runtime catalogue entries are isolated as described below. Past a bare
 `--` every token is a literal, so a positional value that reads like a global
 survives intact.
 
 Both help levels list them under `Application options:`.
 
+## When one runtime command cannot be represented in argv
+
+A `runtimeTools` catalogue can change independently of the CLI application. An
+entry whose input declares a framework option such as `json`, or a field shadowed
+by an application global such as `caller`, cannot receive that field through argv.
+Only that entry becomes unavailable. Other commands still run, and top-level,
+filtered and command-specific help retain the entry and its full reason:
+
+```text
+  inspect  Inspect an operation [unavailable]
+    Unavailable: [stitchkit] CLI command "inspect" declares field(s) shadowed by application global options: caller
+```
+
+Calling it returns `CLI_COMMAND_UNAVAILABLE`, `retryable: false`, and the same
+reason in `details.message` on stderr; the default exit code is 1. `--json`
+compacts the error as usual; `exitCodes` and `errorHint` apply. The refusal precedes
+command argument parsing, stdin, context, hooks and the handler; `--dry-run` cannot
+turn it into success. A known unavailable `--wait` target returns the same refusal;
+an unknown target keeps `NOT_FOUND`.
+
+This isolates only reserved/global **field** conflicts in `runtimeTools`.
+Native commands and contract-defined `services` still fail at startup for those
+conflicts. Duplicate or reserved command names and invalid local aliases,
+positionals or passthrough policies remain configuration errors for every entry.
+`createCliInvoker` receives globals and command input separately and has no argv
+projection, so its own `caller` or `json` input stays callable without renaming.
+See [ADR 0273](../decisions/0273-a-runtime-cli-field-conflict-is-one-commands-unavailability.md).
+
 ## When the managed surface cannot resolve
 
 A CLI whose commands come from a running server declares them with a factory,
@@ -10900,9 +10929,10 @@ One unconvertible schema does not take the connection down. The tool
 is skipped and **named** (`onSkippedTool`, or a stderr line by default), so a
 surface of two hundred tools is not lost to one.
 
-**A discovered schema is checked locally, except for its unions.** The arguments are
-coerced and parsed against the schema the server advertised, so a missing field or a
-wrong scalar is refused before anything is sent. A union in that schema is not judged
+**A discovered schema leaves unions and string formats to its server.** The arguments are
+coerced and parsed against the schema the server advertised. Reported structural failures
+(a missing field, wrong scalar type, unknown key or enum value) and bounds stay local.
+A union in that schema is not judged
 here: a server's presentation may join a discriminated union into one object whose
 shared field is an unlabelled `anyOf` (a stitchkit server with `flattenUnionInput`
 does), and judged against that, a wrong value could only be refused with every branch
@@ -10910,6 +10940,16 @@ listed. The value goes to the server, which holds the original schema, and its r
 names the one wrong field — `blocks.0.data.artifactId: expected string` rather than
 `No union branch matched — branch 1 … and 6 more branches`.
 
+String formats and patterns also lose the author's error messages in JSON Schema. A
+restored `date-time`, email, UUID or regex check would substitute Zod's generic wording.
+Those `invalid_format` refusals go to the remote instead: a bare `2026-10-12` reaches
+the original datetime schema, whose answer can explain that a full UTC timestamp such
+as `2026-10-12T00:00:00Z` is required. This also applies inside arrays, objects and
+record keys. A mixed refusal retains only its reported local reasons; a record-key
+wrapper stays local when it contains any of those reasons. A schema authored locally
+keeps its complete verdict, including custom errors and refinements. No second parse
+invents checks that the first parse did not reach. See [ADR 0272](../decisions/0272-a-restored-string-format-is-judged-by-its-server.md).
+
 MCP connection limits follow the operation phase. `initialize`, the initialized
 notification, `tools/list` and legacy endpoint discovery use `limits.discovery`;
 `tools/call` uses `limits.call`. A mounted call's handshake still uses discovery
@@ -13057,7 +13097,7 @@ core never models them (ADR 0002). But stitchkit itself emits a set of its own:
 `FILE_INSPECTION_REJECTED`, `FILE_TOO_LARGE`, `FILE_EXISTS`,
 `REALTIME_CONTRACT_VIOLATION`, `APPLICATION_NOT_ACCEPTING`, `NOT_IMPLEMENTED`,
 `WAIT_TIMEOUT`,
-`WAIT_FAILED`, `DOWNLOAD_NOT_FOUND`, `VIEW_HTTP_ERROR`,
+`WAIT_FAILED`, `CLI_COMMAND_UNAVAILABLE`, `DOWNLOAD_NOT_FOUND`, `VIEW_HTTP_ERROR`,
 `CONNECTION_TIMEOUT`, `CONNECTION_RESPONSE_TOO_LARGE`,
 `CONNECTION_REQUEST_FAILED`, `UPSTREAM_TOOL_ERROR`,
 `OPERATION_NOT_SUCCEEDED`, `STREAM_ITEM_INVALID`, `STREAM_FRAME_TOO_LARGE`,
@@ -23103,7 +23143,7 @@ and approval path.
 | `ConnectionPhase` / `ConnectionOperation` / `ConnectionFailureContext` | _type_ | closed operation/phase vocabulary and measured read context for existing typed connection errors |
 | `ConnectionTimeoutError` / `ConnectionResponseTooLargeError` | class | bounded operation refusal, with phase, operation and finite observed bytes; safe tool projection retains the raw cause locally |
 | `defineOpenApiConnection` | function | declare one OpenAPI document (object, JSON text or JSON URL) as a tool surface |
-| `mountConnections` | function | discover every connection and return readonly `RuntimeToolDefinition`s for `mountAgent`; a call's arguments are parsed against the discovered schema before sending, except its unions, which the server judges (ADR 0266) |
+| `mountConnections` | function | discover every connection and return readonly `RuntimeToolDefinition`s for `mountAgent`; reported structural failures and bounds stay local, while unions and string-format/pattern refusals (including inside record keys) are judged by the server that owns the original schema (ADR 0266, ADR 0272) |
 | `ConnectionAuthorizationRequiredError` | class | typed reauthorization signal raised on `401` with credentials resolved again on the next call |
 | `ConnectionBudgetExceededError` | class | the mount would expose more foreign tools than its declared budget |
 | `ConnectionRequestError` | class | any non-`2xx` connection response other than the reauthorization signal |
@@ -23582,7 +23622,7 @@ SDK nor the `ai` peer.
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `createCli` | function | build and run a CLI from contracts — [guide](../guide/cli.md) |
+| `createCli` | function | build and run a CLI from contracts; a runtime catalogue field conflicting with reserved/global argv options disables only that entry, retained in help with its reason; invocation returns `CLI_COMMAND_UNAVAILABLE` before side effects — [guide](../guide/cli.md#when-one-runtime-command-cannot-be-represented-in-argv) |
 | `defineCliCommand` | function | define one Zod-typed CLI-only executable command with optional validated-result presentation/exit policy |
 | `parseCliArgs` | function | argv → typed tool args against a schema; inline `--field:=JSON` assigns a whole JSON value, including null, while ordinary string flags remain lexical; named array options together with bare positionals require an explicit `positionals` policy (advanced) |
 | `routeCliArgv` | function | select the command out of argv without duplicating the global-option grammar (advanced) |

package/llms.txt

@@ -17,8 +17,8 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/tools/mcp**: [llms/tools-mcp.txt](llms/tools-mcp.txt) 1.8 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.8 KB
-- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 45.3 KB → [llms/cli.2.txt](llms/cli.2.txt) 21.4 KB
+- **stitchkit/tools/connections**: [llms/tools-connections.txt](llms/tools-connections.txt) 3.9 KB
+- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 47.0 KB → [llms/cli.2.txt](llms/cli.2.txt) 22.5 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) 31.9 KB

package/package.json

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