stitchkit 0.101.3 → 0.102.0

package/CHANGELOG.md

@@ -15,6 +15,27 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.102.0] — 2026-09-30
+
+### ⚠️ Breaking changes
+
+- `stitchkit/tools`, `stitchkit/tools/contract`, `stitchkit/cli` — **`view_file`
+  rejects JSON arrays encoded inside a `paths` string during input validation**,
+  before file or network access, with a hint to pass an array or one path.
+  Previously the text was accepted as one filename and failed with a misleading
+  media-extension refusal. `paths: '["image.png"]'` → `paths: ['image.png']`.
+  An encoded array inside an array element is refused too. Managed surfaces
+  return `VALIDATION_ERROR`; raw MCP reports an input-validation error. → ADR 0218.
+
+**Who must act:** callers that serialize the `paths` array into a string, or
+branch on the former media-extension error for that input. Pass a real array
+(or a single path string) and handle the validation error.
+
+### Fixed
+
+- `stitchkit/tools` — a local non-media extension refusal identifies the
+  caller's path and the extension it saw, without reading the file.
+
 ## [0.101.3] — 2026-09-29
 
 ### Fixed

package/dist/entrypoints/tools/contract.js

@@ -6,7 +6,7 @@ import {
   ViewFileErrorSchema2,
   ViewFileOutputSchema2,
   ViewFileInputSchema2
-} from "../../index-5107q189.js";
+} from "../../index-zax7resm.js";
 import {
   coerceJsonArgs2
 } from "../../index-9pw0a51a.js";

package/dist/entrypoints/tools.js

@@ -69,7 +69,7 @@ import {
   ViewFileErrorSchema2,
   ViewFileOutputSchema2,
   ViewFileInputSchema2
-} from "../index-5107q189.js";
+} from "../index-zax7resm.js";
 import {
   fetchGuarded,
   fetchPinnedDocument,
@@ -2632,7 +2632,8 @@ var EXT_MIME = {
   ".mov": "video/quicktime"
 };
 async function fetchSource(pathOrUrl, options, maxBytes) {
-  const extMime = EXT_MIME[extname2(pathOrUrl).toLowerCase()];
+  const extension = extname2(pathOrUrl);
+  const extMime = EXT_MIME[extension.toLowerCase()];
   if (pathOrUrl.startsWith("http://") || pathOrUrl.startsWith("https://")) {
     const url = new URL(pathOrUrl);
     const res = await fetchGuarded(url, options.allowPrivateHosts ?? false, {
@@ -2660,7 +2661,7 @@ async function fetchSource(pathOrUrl, options, maxBytes) {
   }
   options.signal?.throwIfAborted();
   if (!extMime) {
-    throw new AppError2("FILE_INSPECTION_REJECTED", "refusing to read a non-media file", 422);
+    throw new AppError2("FILE_INSPECTION_REJECTED", `refusing to read ${JSON.stringify(pathOrUrl)} — ${JSON.stringify(extension)} is not a media extension`, 422);
   }
   try {
     const source = await options.files.read(pathOrUrl, {

package/dist/{index-5107q189.js → index-zax7resm.js}

@@ -45,7 +45,19 @@ var ViewFileOutputSchema2 = z2.object({
   content: z2.array(McpMediaContentSchema2),
   errors: z2.array(ViewFileErrorSchema2)
 });
+function isTextList(value) {
+  if (!value.trimStart().startsWith("["))
+    return false;
+  try {
+    return Array.isArray(JSON.parse(value));
+  } catch {
+    return false;
+  }
+}
+var MediaPathSchema = z2.string().refine((value) => !isTextList(value), {
+  message: "paths is a list written as text — pass an array of paths or one path"
+});
 var ViewFileInputSchema2 = z2.object({
-  paths: z2.union([z2.string(), z2.array(z2.string()).max(MAX_VIEW_FILES)]).describe("Media URL(s) or file path(s) to view")
+  paths: z2.union([MediaPathSchema, z2.array(MediaPathSchema).max(MAX_VIEW_FILES)]).describe("One media URL or file path, or an array of them. Pass the array itself, not JSON written as text.")
 });
 export { AsyncOperationCancelResultSchema2, createAsyncOperationSnapshotSchema2, McpAnnotationsSchema2, McpMediaContentSchema2, ViewFileErrorSchema2, ViewFileOutputSchema2, ViewFileInputSchema2 };

package/dist/tools/transfer/view-file-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"view-file-contract.d.ts","sourceRoot":"","sources":["../../../src/tools/transfer/view-file-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,qFAAqF;AACrF,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;iBAG/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,6EAA6E;AAC7E,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;2BAchC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,mBAAmB;;;iBAG9B,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAG/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,mBAAmB;;iBAI9B,CAAC"}
+{"version":3,"file":"view-file-contract.d.ts","sourceRoot":"","sources":["../../../src/tools/transfer/view-file-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,qFAAqF;AACrF,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;iBAG/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,6EAA6E;AAC7E,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;2BAchC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,mBAAmB;;;iBAG9B,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAG/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAgBlE,eAAO,MAAM,mBAAmB;;iBAM9B,CAAC"}

package/dist/tools/transfer/view-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"view-file.d.ts","sourceRoot":"","sources":["../../../src/tools/transfer/view-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,EAAE,mBAAmB,EAAwB,MAAM,sBAAsB,CAAC;AAEjF,OAAO,EACL,KAAK,cAAc,EACnB,oBAAoB,EACpB,KAAK,eAAe,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,KAAK,cAAc,EACnB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,KAAK,mBAAmB,EAAoB,MAAM,sBAAsB,CAAC;AAwBlF,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,KAAK,CAAC,EAAE,mBAAmB,CAAC;IAC5B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAoKD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,eAAe,EAAE,CAAC,CAE5B;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC,OAAO,CAAC,EACpD,OAAO,GAAE,eAAoB,EAC7B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC,CAuBzB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,GAAE,eAAoB,GAAG,IAAI,CAgBpF"}
+{"version":3,"file":"view-file.d.ts","sourceRoot":"","sources":["../../../src/tools/transfer/view-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,EAAE,mBAAmB,EAAwB,MAAM,sBAAsB,CAAC;AAEjF,OAAO,EACL,KAAK,cAAc,EACnB,oBAAoB,EACpB,KAAK,eAAe,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,KAAK,cAAc,EACnB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,KAAK,mBAAmB,EAAoB,MAAM,sBAAsB,CAAC;AAwBlF,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,KAAK,CAAC,EAAE,mBAAmB,CAAC;IAC5B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAyKD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,eAAe,EAAE,CAAC,CAE5B;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC,OAAO,CAAC,EACpD,OAAO,GAAE,eAAoB,EAC7B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC,CAuBzB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,GAAE,eAAoB,GAAG,IAAI,CAgBpF"}

package/llms/stitchkit.txt

@@ -79,12 +79,12 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `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 46 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 47 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, plus the managed-resource conformance kit |
 | `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/agent-runtime` | server | evolving<br>_redefined in 22 of the 46 minors since 0.56.2, most recently 0.97.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 22 of the 47 minors since 0.56.2, most recently 0.97.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 |
@@ -94,7 +94,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 10 of the 46 minors since 0.56.2, most recently 0.100.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 10 of the 47 minors since 0.56.2, most recently 0.100.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 |

package/llms/tools.2.txt

@@ -365,6 +365,15 @@ multimodal content beside structured per-item `errors`, and charges every item
 to one total 20 MB batch budget. Its MCP and Agent presenters are built in;
 remote fetch cancellation follows the active call signal.
 
+`paths` is one path/URL string or an actual array of strings (at most 20).
+Pass `{ paths: ['image.png'] }`, not `{ paths: '["image.png"]' }`: a JSON
+array written as text fails input validation before any file or network access,
+with the hint `paths is a list written as text — pass an array of paths or one
+path`. The same rule applies to array items and the raw `mountViewFile` input.
+Ordinary file names containing brackets, such as `[preview].png`, remain valid.
+A local file with an unsupported extension is refused before reading; its
+per-item error identifies the caller's path and the extension it saw.
+
 The older `mountWait`, `mountDownload`, `mountUpload` and `mountViewFile`
 functions remain
 intentional raw MCP adapters with their text-envelope behavior. Use them under

package/llms/tools.3.txt

@@ -113,7 +113,7 @@ payload.
 | `ToolCallContext` | _type_ | the context every tool hook receives — `{ source, mcp? }` plus whatever the mount's `context` added |
 | `ViewFileOptions` | _type_ | shared URL/managed-file-boundary policy for `defineViewFileTool`, `mountViewFile` and `resolveMedia` |
 | `ViewFileOutput` | _type_ | neutral managed batch result with multimodal `content` and per-item `errors` |
-| `ViewFileInputSchema` | constant | fixed one-or-many media path/URL input schema |
+| `ViewFileInputSchema` | constant | one media path/URL or an array of at most 20; rejects a JSON array written as text, including in array items, before IO |
 | `ViewFileOutputSchema` | constant | Zod schema for the neutral managed view-file batch result |
 | `ViewFileErrorSchema` | constant | Zod schema for one structured per-item view failure |
 | `McpAnnotations` | _type_ | MCP annotations on a media result |

package/llms/{upgrading-0.61.0-0.73.0.txt → upgrading-0.61.0-0.74.0.txt}

@@ -1,14 +1,75 @@
-# Upgrading 0.61.0 → 0.73.0 — stitchkit docs slice
+# Upgrading 0.61.0 → 0.74.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.61.0 → 0.73.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.61.0 → 0.74.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.61.0 → 0.73.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.61.0 → 0.74.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.74.0
+
+One change, and it only reaches you if you catch a refusal the **client** raised — one it made while
+planning the request, before anything was sent. A server refusal is unchanged.
+
+### If you match on the text of a client-side refusal
+
+A missing path param, a missing scoped prefix key, a non-flat field in a `GET` input, a missing or
+invalid multipart file: each used to arrive as a plain `Error` carrying only a sentence. They now
+arrive as an `ApiError` in the same shape a server validation failure uses.
+
+```ts
+// before
+catch (e) {
+  if (/Missing path param/.test(e.message)) …
+}
+
+// after
+catch (e) {
+  if (e.code === 'VALIDATION_ERROR' && e.status === 0) …   // refused here, nothing was sent
+}
+// e.details.issues[0].path === 'id'
+```
+
+`status` is what separates the two worlds, and it is not new — `0` has always meant *this never
+reached the server*, as `REQUEST_ABORTED` and `REQUEST_TIMEOUT` already used it:
+
+| | `code` | `status` |
+|---|---|---|
+| the client refused your arguments | `VALIDATION_ERROR` | `0` |
+| the server refused your arguments | `VALIDATION_ERROR` | `400` |
+
+`details.issues` is the same `{ path, code, message }` array on both, so one rendering serves both —
+and `zodIssues` / `ZodIssueSummary` are now importable from `stitchkit` itself, not only from
+`stitchkit/server`.
+
+### If you are on `createHttpClient` and your call site relied on a synchronous throw
+
+This is the sharp one, because it is invisible in a diff. Those refusals used to be thrown
+**synchronously** on the Ky-backed client — before the call returned a promise — so
+`api.upload({}).catch(handler)` never reached the handler, while the same mistake on the bare-fetch
+client rejected normally. They now reject on both.
+
+```ts
+// before, on createHttpClient only
+try {
+  api.upload({})            // threw here
+} catch (e) { … }
+
+// after, on both transports
+await api.upload({}).catch(handler)
+```
+
+A `try/catch` around an `await`ed call keeps working. A `try/catch` around an un-awaited call no
+longer catches anything — which was already true on the other transport.
+
+Not a migration, but worth knowing: a missing multipart file used to be reported as
+`UNKNOWN_ERROR`, the code that means *this client cannot tell you what happened*, on the one refusal
+where it is certain nothing was sent. → ADR 0148 carries the reasoning, including why argument
+validation stays on the server.
+
 ## Released migration: 0.73.0
 
 Two breaking changes. Nothing you send to a server changed, and only one of these

package/llms/{upgrading-0.74.0-0.101.0.txt → upgrading-0.75.0-0.102.0.txt}

@@ -1,14 +1,38 @@
-# Upgrading 0.74.0 → 0.101.0 — stitchkit docs slice
+# Upgrading 0.75.0 → 0.102.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.74.0 → 0.101.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.75.0 → 0.102.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.74.0 → 0.101.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.75.0 → 0.102.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.102.0
+
+### `view_file` receives an array, not an array encoded as text
+
+**Who must act:** callers sending `paths` as a JSON-encoded array string, or
+matching the former media-extension refusal for that input. Managed MCP,
+Agent and CLI surfaces now reject it as `VALIDATION_ERROR` before IO; raw MCP
+reports an input-validation error. Correct single paths and arrays need no change.
+
+```ts
+// Before
+{ paths: '["image.png"]' }
+// After
+{ paths: ['image.png'] }
+// One file may also be a string
+{ paths: 'image.png' }
+```
+
+The same rule applies to an array element containing another encoded array.
+Do not change generic string-union coercion: path strings remain strings.
+A legitimate filename such as `[preview].PNG` is still accepted. Local
+unsupported-extension errors now include the caller's path and extension;
+match the error code rather than the former generic message.
+
 ## Released migration: 0.101.0
 
 ### `TelegramInitDataUser` is `TelegramUser`
@@ -1062,64 +1086,3 @@ schema.
 `stitchkit/live`, the watch hub, the keyspace and the trust fence are all
 additive. Adopt them when you want them; the guide is
 [Live data](./live.md).
-
-## Released migration: 0.74.0
-
-One change, and it only reaches you if you catch a refusal the **client** raised — one it made while
-planning the request, before anything was sent. A server refusal is unchanged.
-
-### If you match on the text of a client-side refusal
-
-A missing path param, a missing scoped prefix key, a non-flat field in a `GET` input, a missing or
-invalid multipart file: each used to arrive as a plain `Error` carrying only a sentence. They now
-arrive as an `ApiError` in the same shape a server validation failure uses.
-
-```ts
-// before
-catch (e) {
-  if (/Missing path param/.test(e.message)) …
-}
-
-// after
-catch (e) {
-  if (e.code === 'VALIDATION_ERROR' && e.status === 0) …   // refused here, nothing was sent
-}
-// e.details.issues[0].path === 'id'
-```
-
-`status` is what separates the two worlds, and it is not new — `0` has always meant *this never
-reached the server*, as `REQUEST_ABORTED` and `REQUEST_TIMEOUT` already used it:
-
-| | `code` | `status` |
-|---|---|---|
-| the client refused your arguments | `VALIDATION_ERROR` | `0` |
-| the server refused your arguments | `VALIDATION_ERROR` | `400` |
-
-`details.issues` is the same `{ path, code, message }` array on both, so one rendering serves both —
-and `zodIssues` / `ZodIssueSummary` are now importable from `stitchkit` itself, not only from
-`stitchkit/server`.
-
-### If you are on `createHttpClient` and your call site relied on a synchronous throw
-
-This is the sharp one, because it is invisible in a diff. Those refusals used to be thrown
-**synchronously** on the Ky-backed client — before the call returned a promise — so
-`api.upload({}).catch(handler)` never reached the handler, while the same mistake on the bare-fetch
-client rejected normally. They now reject on both.
-
-```ts
-// before, on createHttpClient only
-try {
-  api.upload({})            // threw here
-} catch (e) { … }
-
-// after, on both transports
-await api.upload({}).catch(handler)
-```
-
-A `try/catch` around an `await`ed call keeps working. A `try/catch` around an un-awaited call no
-longer catches anything — which was already true on the other transport.
-
-Not a migration, but worth knowing: a missing multipart file used to be reported as
-`UNKNOWN_ERROR`, the code that means *this client cannot tell you what happened*, on the one refusal
-where it is certain nothing was sent. → ADR 0148 carries the reasoning, including why argument
-validation stays on the server.

package/llms/upgrading.txt

@@ -11,8 +11,8 @@ Contains: Guide: Upgrading, general  (docs/guide/upgrading.md)
 
 Load this slice, then every range slice between your installed version and the target:
 
-- 0.74.0 → 0.101.0: `llms/upgrading-0.74.0-0.101.0.txt`
-- 0.61.0 → 0.73.0: `llms/upgrading-0.61.0-0.73.0.txt`
+- 0.75.0 → 0.102.0: `llms/upgrading-0.75.0-0.102.0.txt`
+- 0.61.0 → 0.74.0: `llms/upgrading-0.61.0-0.74.0.txt`
 - 0.44.0 → 0.60.0: `llms/upgrading-0.44.0-0.60.0.txt`
 - 0.37.0 → 0.37.0: `llms/upgrading-0.37.0.txt`
 

package/llms-full.txt

@@ -70,12 +70,12 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `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 46 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 47 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, plus the managed-resource conformance kit |
 | `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/agent-runtime` | server | evolving<br>_redefined in 22 of the 46 minors since 0.56.2, most recently 0.97.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 22 of the 47 minors since 0.56.2, most recently 0.97.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 |
@@ -85,7 +85,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 10 of the 46 minors since 0.56.2, most recently 0.100.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 10 of the 47 minors since 0.56.2, most recently 0.100.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 |
@@ -4777,6 +4777,15 @@ multimodal content beside structured per-item `errors`, and charges every item
 to one total 20 MB batch budget. Its MCP and Agent presenters are built in;
 remote fetch cancellation follows the active call signal.
 
+`paths` is one path/URL string or an actual array of strings (at most 20).
+Pass `{ paths: ['image.png'] }`, not `{ paths: '["image.png"]' }`: a JSON
+array written as text fails input validation before any file or network access,
+with the hint `paths is a list written as text — pass an array of paths or one
+path`. The same rule applies to array items and the raw `mountViewFile` input.
+Ordinary file names containing brackets, such as `[preview].png`, remain valid.
+A local file with an unsupported extension is refused before reading; its
+per-item error identifies the caller's path and the extension it saw.
+
 The older `mountWait`, `mountDownload`, `mountUpload` and `mountViewFile`
 functions remain
 intentional raw MCP adapters with their text-envelope behavior. Use them under
@@ -14229,6 +14238,31 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## Released migration: 0.102.0
+
+### `view_file` receives an array, not an array encoded as text
+
+**Who must act:** callers sending `paths` as a JSON-encoded array string, or
+matching the former media-extension refusal for that input. Managed MCP,
+Agent and CLI surfaces now reject it as `VALIDATION_ERROR` before IO; raw MCP
+reports an input-validation error. Correct single paths and arrays need no change.
+
+```ts
+// Before
+{ paths: '["image.png"]' }
+// After
+{ paths: ['image.png'] }
+// One file may also be a string
+{ paths: 'image.png' }
+```
+
+The same rule applies to an array element containing another encoded array.
+Do not change generic string-union coercion: path strings remain strings.
+A legitimate filename such as `[preview].PNG` is still accepted. Local
+unsupported-extension errors now include the caller's path and extension;
+match the error code rather than the former generic message.
+
+
 ## Released migration: 0.101.0
 
 ### `TelegramInitDataUser` is `TelegramUser`
@@ -19769,7 +19803,7 @@ payload.
 | `ToolCallContext` | _type_ | the context every tool hook receives — `{ source, mcp? }` plus whatever the mount's `context` added |
 | `ViewFileOptions` | _type_ | shared URL/managed-file-boundary policy for `defineViewFileTool`, `mountViewFile` and `resolveMedia` |
 | `ViewFileOutput` | _type_ | neutral managed batch result with multimodal `content` and per-item `errors` |
-| `ViewFileInputSchema` | constant | fixed one-or-many media path/URL input schema |
+| `ViewFileInputSchema` | constant | one media path/URL or an array of at most 20; rejects a JSON array written as text, including in array items, before IO |
 | `ViewFileOutputSchema` | constant | Zod schema for the neutral managed view-file batch result |
 | `ViewFileErrorSchema` | constant | Zod schema for one structured per-item view failure |
 | `McpAnnotations` | _type_ | MCP annotations on a media result |

package/llms.txt

@@ -13,7 +13,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/live**: [llms/live.txt](llms/live.txt) 21.6 KB
 - **stitchkit/react**: [llms/react.txt](llms/react.txt) 9.0 KB
 - **stitchkit/react/keyboard**: [llms/react-keyboard.txt](llms/react-keyboard.txt) 9.4 KB
-- **stitchkit/tools**: [llms/tools.txt](llms/tools.txt) 45.0 KB → [llms/tools.2.txt](llms/tools.2.txt) 26.3 KB → [llms/tools.3.txt](llms/tools.3.txt) 25.4 KB
+- **stitchkit/tools**: [llms/tools.txt](llms/tools.txt) 45.0 KB → [llms/tools.2.txt](llms/tools.2.txt) 26.9 KB → [llms/tools.3.txt](llms/tools.3.txt) 25.4 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.1 KB
@@ -55,8 +55,8 @@ 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) 10.3 KB
-- **Upgrading 0.74.0 → 0.101.0**: [llms/upgrading-0.74.0-0.101.0.txt](llms/upgrading-0.74.0-0.101.0.txt) 46.3 KB
-- **Upgrading 0.61.0 → 0.73.0**: [llms/upgrading-0.61.0-0.73.0.txt](llms/upgrading-0.61.0-0.73.0.txt) 41.2 KB
+- **Upgrading 0.75.0 → 0.102.0**: [llms/upgrading-0.75.0-0.102.0.txt](llms/upgrading-0.75.0-0.102.0.txt) 44.8 KB
+- **Upgrading 0.61.0 → 0.74.0**: [llms/upgrading-0.61.0-0.74.0.txt](llms/upgrading-0.61.0-0.74.0.txt) 43.5 KB
 - **Upgrading 0.44.0 → 0.60.0**: [llms/upgrading-0.44.0-0.60.0.txt](llms/upgrading-0.44.0-0.60.0.txt) 43.9 KB
 - **Upgrading 0.37.0 → 0.37.0**: [llms/upgrading-0.37.0.txt](llms/upgrading-0.37.0.txt) 6.2 KB
 

package/package.json

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