stitchkit 0.95.2 → 0.96.0

package/llms/observability.txt

@@ -5,6 +5,9 @@
 
 Contains: Guide: Observability  (docs/guide/observability.md) · API reference: `stitchkit/observability`  (docs/api/reference.md)
 
+Also read:
+- see `llms/telegram.txt` for the Telegram bots guide
+
 ==============================================================================
 # Guide: Observability  (docs/guide/observability.md)
 ==============================================================================
@@ -831,6 +834,8 @@ audit event. See the [Observability guide](../guide/observability.md).
 | `DimensionCollision` / `SetRequestDimensionsOptions` | _type_ | explicit overwrite, preserve or error policy for dimension keys |
 | `createBoundedLogger` | function | decorate a `StitchLogger` with request context, shared sanitisation, redaction and total bounds |
 | `DEFAULT_REDACT_PATHS` | constant | baseline credential/token paths added to the sanitizer's sensitive-key policy |
+| `createJsonLogger` | function | the process journal: one JSON line per call in pino's shape (numeric `level`, epoch `time`, `msg`) on standard output, through `createBoundedLogger` — an `Error` in any field keeps name, message, stack and cause; secrets masked; `level` threshold, static `fields`, injectable `write` |
+| `JsonLoggerOptions` / `JsonLogLevel` / `JSON_LOG_LEVELS` | _type_ / constant | the bounded-logger options plus `level`, `fields`, `write`, `now`; pino's numbers `debug` 20 … `error` 50, which a line reader matches on |
 | `BoundedLoggerBounds` / `BoundedLoggerOptions` | _type_ | per-value and total record ceilings (`stringLengthByKey` raises the string bound for named keys such as `stack`) plus sink/redaction configuration |
 | `RequestEvent` | _type_ | the normalised audit event handed to the sink; opt-in HTTP cancellation rows carry `outcome: 'cancelled'` |
 | `runUnitOfWork` / `RunUnitOfWorkOptions` | function / _type_ | run work that did not arrive over a transport — an agent loop, a scheduled broadcast — inside one context, with the same completion record a request gets |

package/llms/server.4.txt

@@ -386,6 +386,9 @@ and our payload is wrong, which is the case a list of substrings quietly counts
 against the user. An unrecognised refusal leaves the recipient reachable: losing
 a working subscriber forever costs more than one wasted send.
 
+The rest of what a bot is assembled from — its resources, journal, operator
+channel, broadcasts and local Bot API files — is in [Telegram bots](telegram.md).
+
 ## Cookies
 
 ```ts

package/llms/stitchkit.txt

@@ -69,7 +69,7 @@ own, recorded as an ADR.
 | `stitchkit/cli` | server | stable | `createCli` — the CLI transport, light (no MCP SDK / `ai`) |
 | `stitchkit/remote` | browser **and** server | stable | peer-free `implementRemote` for thin HTTP proxy processes |
 | `stitchkit/files` | server (Bun or Node) | stable | peer-free managed local-file boundary |
-| `stitchkit/telegram` | server (Bun or Node) | evolving | peer-free Telegram platform primitives — Mini App `initData` verification and Bot API send-failure classification |
+| `stitchkit/telegram` | server (Bun or Node) | evolving | peer-free Telegram platform primitives — Mini App `initData` verification, send-failure classification, resumable broadcasts, the operator channel and local Bot API files |
 | `stitchkit/tracking` | browser **and** server | evolving | visitor-tracking mechanics — `createTrackingClient`, the tab-shared outbox, the page-leave beacon, attribution, the contract factory; no event vocabulary, no React |
 | `stitchkit/tracking/server` | server (Bun or Node) | evolving | the decisions a tracking backend makes — dispositions, visit lease over an application-owned store, active intervals, presence; no database |
 | `stitchkit/release` | browser **and** server | evolving | a page follows the release it was built for — `createReleaseMarker` on the server, `createReleaseWatcher` in the browser, the `X-Build-Id` header and a socket event between them |
@@ -77,11 +77,11 @@ 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 40 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 41 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/agent-runtime` | server | evolving<br>_redefined in 21 of the 40 minors since 0.56.2, most recently 0.94.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 21 of the 41 minors since 0.56.2, most recently 0.94.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 |
@@ -91,8 +91,8 @@ 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 8 of the 40 minors since 0.56.2, most recently 0.95.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
-| `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 9 of the 41 minors since 0.56.2, most recently 0.96.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 |
 | `stitchkit/application/diagnostic-journal` | server | evolving | the local diagnostic journal — the one part of the kernel that spawns, locks and writes files |

package/llms/telegram.txt

@@ -3,7 +3,152 @@
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: API reference: `stitchkit/telegram`  (docs/api/reference.md)
+Contains: Guide: Telegram bots  (docs/guide/telegram.md) · API reference: `stitchkit/telegram`  (docs/api/reference.md)
+
+==============================================================================
+# Guide: Telegram bots  (docs/guide/telegram.md)
+==============================================================================
+
+# Telegram bots
+
+`stitchkit/telegram` holds what the Bot API itself asks of every bot, with no
+bot library; `stitchkit/application/grammy` makes a grammY bot a set of
+application resources. Together they are what a bot is assembled from, so that
+a bot's own code is its product and nothing else. A generated bot to start from:
+`bun create stitchkit my-bot --template telegram-bot`. Why it is shaped this
+way: [ADR 0201](../decisions/0201-a-telegram-bot-is-assembled-from-primitives.md).
+
+| Job | Where |
+|---|---|
+| the bot as resources: command menu, then long polling with updates admitted by batch | `grammyBotResources` — [application kernel](application-kernel.md#optional-grammy-adapter) |
+| the process journal | `createJsonLogger` from `stitchkit/observability` |
+| the operator's chat: product events, apart from the journal | `createTelegramOperatorChannel` |
+| a broadcast that survives crashes, deploys and Ctrl-C | `runTelegramBroadcast` |
+| a file the local Bot API server wrote to disk | `createTelegramLocalFiles` |
+| why a send was refused | `classifyTelegramSendFailure` — [auth and errors](auth-and-errors.md#telegram-mini-apps) |
+| Mini App `initData` | `verifyTelegramInitData` — [auth and errors](auth-and-errors.md#telegram-mini-apps) |
+| one Bot API call without a bot library | `callTelegramBotApi` |
+
+## The journal
+
+A bot's journal is `createJsonLogger`: one JSON object per line on standard
+output, in pino's shape — numeric `level` (`debug` 20, `info` 30, `warn` 40,
+`error` 50), `time` in epoch milliseconds, `msg` — so `pino-pretty` reads it on
+a terminal and a supervisor matching `"level":50` sees errors. Unlike pino, an
+`Error` under *any* key is written with its name, message, stack and cause; an
+error logged as `{ error }` does not become `"error":{}`.
+
+```ts
+import { createJsonLogger } from 'stitchkit/observability'
+import { TELEGRAM_BOT_TOKEN_PATTERN } from 'stitchkit/telegram'
+
+export const logger = createJsonLogger({
+  level: env.LOG_LEVEL,
+  fields: { service: 'my-bot' },
+  sensitiveUrlPatterns: [TELEGRAM_BOT_TOKEN_PATTERN],
+})
+
+logger.error('Application startup failed', { error })
+```
+
+The error line contract, for whatever recognises a failure from the journal: a
+line whose `level` is `50` or more is an error. There is no separate `fatal`;
+an unrecoverable end is an `error` line followed by a non-zero exit.
+
+## The operator channel
+
+The chat where people read about new users, payments and failures is not the
+journal. The journal must not lose a line to a slow network; the chat must not
+slow the bot down. `post` returns at once and never throws; sends are paced
+below Telegram's per-chat limit (one every 3 s by default), 429s wait the time
+Telegram named, and when the chat cannot keep up the oldest message is dropped
+and reported.
+
+```ts
+import { createTelegramOperatorChannel, telegramOperatorSender } from 'stitchkit/telegram'
+
+const operators = createTelegramOperatorChannel<'users' | 'payments' | 'errors'>({
+  chatId: env.OPERATOR_CHAT_ID,
+  topics: { users: 2, payments: 3, errors: 4 },   // forum message_thread_id
+  send: telegramOperatorSender({ token: env.BOT_TOKEN }),
+  onDropped: (drop) => logger.warn('Operator message dropped', { ...drop }),
+})
+
+operators.post(`New user ${user.id}`, 'users')
+```
+
+What to post stays the bot's. On the way down, drain it within the grace period
+and close it: `drain: (context) => operators.drain(context.signal)`,
+`close: () => operators.close()` in a resource.
+
+## Broadcasts
+
+A broadcast is a job with an end, so it is a function, not a resource:
+
+```ts
+import { runTelegramBroadcast, telegramBroadcastSender } from 'stitchkit/telegram'
+
+const report = await runTelegramBroadcast({
+  name: '2026-04-28-price-lock',
+  directory: env.STATE_DIRECTORY,            // a state root, never the release tree
+  recipients: () => audience.activeSubscribers(),
+  send: telegramBroadcastSender({
+    token: env.BOT_TOKEN,
+    message: { copyFrom: { chatId: env.DRAFTS_CHAT_ID, messageId: 42 } },
+  }),
+  signal: stop.signal,
+  onProgress: (progress) => logger.info('Broadcast', { ...progress }),
+})
+```
+
+- **Resumable by name.** The audience is written once on the first run; running
+  the same name again continues with that list. Progress is an append-only
+  journal beside it, one line before and one after each send.
+- **Nobody twice.** A send that was in flight when the process died is recorded
+  `uncertain` and not repeated. A signal stops between sends, after the one in
+  flight is recorded.
+- **Refusals by meaning.** A blocked, deactivated or never-started recipient is
+  `unreachable` and never addressed again. A 429 waits Telegram's
+  `retry_after` and sends the same recipient again; a server error is retried
+  with backoff up to `maxAttempts`, then `failed`. A message Telegram cannot
+  parse is not the recipient's fault: the run **halts** with them still pending,
+  so the run after the fix reaches them. So does Telegram being unreachable.
+- **Pacing** is `ratePerSecond`, 25 by default. `dryRun` counts and writes
+  nothing. One runner per name: a second concurrent run is refused.
+
+The same call works from a script (the process's signal) and inside a live
+application (the application's signal, with admission held by the caller).
+The recipient state contains Telegram ids: keep it in the state directory, out
+of git.
+
+## Files from a local Bot API server
+
+A local `telegram-bot-api` keeps downloaded files under `<dir>/<bot token>/`,
+and a bot sharing that directory reads them from disk and deletes them when
+done. `file_path` comes from a server over the network, so it is resolved only
+inside the bot's directory — `../`, an absolute path elsewhere and a link
+pointing out are refused, judged on real paths.
+
+```ts
+import { createTelegramLocalFiles } from 'stitchkit/telegram'
+
+const files = createTelegramLocalFiles({ root: env.BOT_API_FILES_ROOT, token: env.BOT_TOKEN })
+
+const { file_path } = await ctx.getFile()
+const path = await files.resolve(file_path)   // throws TelegramLocalFileError
+// … process it …
+await files.remove(file_path)
+```
+
+The recommended variable for the root is **`BOT_API_FILES_ROOT`** — the
+server's `--dir`, absolute, as the bot's process sees it. A relative `file_path`
+(a server without `--local`) and an absolute one inside the bot's directory (a
+server with `--local`) both resolve. A refusal carries a reason
+(`root-not-absolute`, `bot-directory-unavailable`, `outside-bot-directory`,
+`missing`, `not-a-file`) and never the path or the token. `files.check()`
+answers whether the directory is there to read and delete from; a resource that
+throws on `{ ready: false }` in `start` keeps the bot from answering before it
+can read its media.
 
 ==============================================================================
 # API reference: `stitchkit/telegram`  (docs/api/reference.md)
@@ -11,9 +156,10 @@ Contains: API reference: `stitchkit/telegram`  (docs/api/reference.md)
 
 ## `stitchkit/telegram`
 
-Peer-free server-only Telegram platform primitives. Importing this resolves no
+Peer-free server-only Telegram platform primitives — the Bot API's own
+protocols and the jobs every bot rewrote around them. Importing this resolves no
 bot library; `stitchkit/application/grammy` remains the lifecycle adapter for an
-injected grammY bot. → ADR 0143
+injected grammY bot. → ADR 0143, ADR 0201 — [guide](../guide/telegram.md)
 
 | Export | Kind | Summary |
 |--------|------|---------|
@@ -26,5 +172,15 @@ injected grammY bot. → ADR 0143
 | `classifyTelegramSendFailure` | function | name a refused Bot API send and separate "retry this send" from "stop addressing this recipient" |
 | `TelegramSendFailure` | _type_ | reason, `status`, Telegram-stated `retryAfterSeconds`, `retryable`, `recipientUnreachable` and which evidence produced the answer |
 | `TelegramSendFailureReason` | _type_ | `blocked-by-user` / `user-deactivated` / `chat-not-found` / `not-started` / `rate-limited` / `message-invalid` / `server-error` / `unknown` |
+| `runTelegramBroadcast` | function | a resumable broadcast by `name` under a state `directory`: audience written once, an append-only journal, pacing at `ratePerSecond` (25), 429 waits `retry_after`, unreachable recipients never addressed again, a `message-invalid` or unreachable Telegram halts without charging the recipient, a send in flight at a crash is `uncertain` and not repeated, `dryRun`, one runner per name |
+| `TelegramBroadcastConfig` / `TelegramBroadcastSend` / `TelegramBroadcastReport` / `TelegramBroadcastRunOutcome` / `TelegramBroadcastOutcome` / `TelegramBroadcastRecipient` | _type_ | `name`, `directory`, `recipients()`, `send({ recipient, attempt })`, `maxAttempts`, `signal`, `onProgress`; counts `delivered` / `unreachable` / `failed` / `uncertain` / `pending` and `finished` / `stopped` / `halted` / `dry-run` |
+| `telegramBroadcastSender` / `TelegramBroadcastSenderConfig` / `TelegramBroadcastMessage` | function / _type_ | the standard `send`: `sendMessage` with a text or `copyMessage` of a prepared message, through the Bot API |
+| `createTelegramOperatorChannel` | function | the operator chat, apart from the journal: `post(text, topic?)` returns at once and never throws; paced sends into forum topics, 429 honoured, oldest dropped on overflow, `drain(signal)` and `close()` for the way down |
+| `TelegramOperatorChannelConfig` / `TelegramOperatorChannel` / `TelegramOperatorMessage` / `TelegramOperatorDrop` / `TelegramChatId` | _type_ | `chatId`, `topics`, `send`, `maxQueued`, `minIntervalMs`, `maxAttempts`, `onDropped`; a drop is `overflow` / `refused` / `attempts` / `closed` with its classification |
+| `telegramOperatorSender` / `TelegramOperatorSenderConfig` | function / _type_ | the standard `send`: `sendMessage` into the chat and topic, plain text unless `parseMode` |
+| `createTelegramLocalFiles` | function | files the local Bot API server wrote under `<root>/<token>/`: `resolve(file_path)` and `remove(file_path)` only inside the bot's directory, judged on real paths so a link is judged by where it leads; `check()` for readiness. Recommended root variable: `BOT_API_FILES_ROOT` |
+| `TelegramLocalFilesConfig` / `TelegramLocalFiles` / `TelegramLocalFilesCheck` / `TelegramLocalFileError` / `TelegramLocalFileRefusal` | _type_ / class | `root`, `token`; refusals `root-not-absolute` / `bot-directory-unavailable` / `outside-bot-directory` / `missing` / `not-a-file`, never carrying the path or the token |
+| `callTelegramBotApi` / `TelegramBotApiCall` / `TelegramBotApiError` | function / _type_ / class | one Bot API method over `fetch`; a refusal keeps `error_code`, `description` and `parameters` for the classifier, and no error names the URL |
+| `TELEGRAM_BOT_TOKEN_PATTERN` | constant | the shape of a bot token, for a logger's `sensitiveUrlPatterns` |
 
 ---

package/llms/{upgrading-0.37.0-0.53.0.txt → upgrading-0.37.0-0.56.0.txt}

@@ -1,14 +1,141 @@
-# Upgrading 0.37.0 → 0.53.0 — stitchkit docs slice
+# Upgrading 0.37.0 → 0.56.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.37.0 → 0.53.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.37.0 → 0.56.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.37.0 → 0.53.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.37.0 → 0.56.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.56.0
+
+### Surface manifests are version 2
+
+`operation.tools` could not describe a role-selected MCP surface, a different
+Agent or CLI selection, or an advertised `extend` schema, so projections moved
+out of the canonical operation:
+
+```ts
+// before
+manifest.operations[0].tools.MCP
+// after
+manifest.toolSurfaces.find((s) => s.transport === 'MCP' && s.surface === null)?.tools
+
+// before
+buildSurfaceManifest({ mcpSurfaces: { admin: { services, extend } } })
+// after
+buildSurfaceManifest({ mcpSurfaces: { admin: { services } }, mcpPreparation: { extend } })
+```
+
+A committed snapshot is regenerated once, deliberately: `manifestVersion` is
+`2`, and `ConformanceTransport` gained `REALTIME`, so any exhaustive
+`Record<ConformanceTransport, …>` must handle it.
+
+### `FILE_*` codes joined the error registry
+
+`StitchErrorCode` gained `FILE_INVALID_PATH`, `FILE_OUTSIDE_ROOT`,
+`FILE_NOT_FOUND`, `FILE_NOT_REGULAR`, `FILE_INSPECTION_REJECTED`,
+`FILE_TOO_LARGE` and `FILE_EXISTS`. Only exhaustive maps break:
+
+```ts
+// before — compiled while the registry had no file codes
+const copy: Record<StitchErrorCode, string> = { …, RATE_LIMITED: '…' }
+// after — add the seven managed-file codes (or use Partial<Record<…>>)
+```
+
+Unexpected IO stays scrubbed as `INTERNAL_SERVER_ERROR`: the new codes are the
+caller-safe ones only.
+
+### `ScopedAuthHook` is nominal
+
+A hand-written function shaped like an auth hook is no longer assignable —
+identity now comes from the factory, so scope ownership and the inferred
+context cannot drift apart:
+
+```ts
+// before — a structural stand-in
+const auth: ScopedAuthHook<Scopes> = async (ctx, endpoint) => { … }
+// after — create it, then compose domains
+const auth = createAuthHook({ resolve, rules })
+const composed = composeAuthHooks({ hooks: [auth, billingAuth], defaultScope: 'public' })
+```
+
+### Managed-file inspectors also run on reads
+
+An inspector is no longer write-only, and it has a finite default deadline
+(15 s). Make it read-aware and idempotent — a read carries no
+`declaredMediaType`:
+
+```ts
+// before
+inspect: ({ declaredMediaType }) => inspectDeclaredType(declaredMediaType!)
+// after
+inspect: ({ prefix, declaredMediaType, signal }) =>
+  inspectBytes(prefix, { declaredMediaType, signal })
+```
+
+Set `inspectionTimeoutMs` explicitly when 15 seconds is the wrong budget.
+
+### Direct async-operation binding needs a wire-stable ID
+
+A direct binding reuses the start output as the follow-up wire input, so the ID
+schema must parse to itself (`z.input` equals `z.output`, no transform,
+coercion, default or overwrite). Anything else is parsed twice:
+
+```ts
+// before — a transform silently ran on start and again on every follow-up
+defineAsyncOperationContract({ binding: 'direct', id: z.string().transform(Number) })
+// after — keep the wire shape, adapt explicitly
+defineAsyncOperationContract({
+  binding: 'adapted',
+  id,
+  adapters: { idFromStart, inputFor },
+})
+```
+
+## Released migration: 0.55.0
+
+### Peer-free `implementRemote`
+
+`implementRemote` now has one canonical, optional-peer-free owner. This keeps
+MCP SDK and AI SDK modules out of CLI bundles that only proxy HTTP calls:
+
+```ts
+// before
+import { implementRemote } from 'stitchkit/tools'
+// after
+import { implementRemote } from 'stitchkit/remote'
+```
+
+### Managed file boundary and strict auth returns
+
+Create one boundary during application bootstrap and pass the capability, never
+a per-call directory or host path:
+
+```ts
+import { createManagedFileBoundary } from 'stitchkit/files'
+
+const files = await createManagedFileBoundary({ root: '/srv/app-files' })
+
+// before
+defineDownloadTool({ defaultDir: '/srv/app-files', resolveUrl, ...common })
+defineUploadTool({ upload: (path) => provider.uploadFile(path), ...common })
+defineViewFileTool({ baseDir: '/srv/app-files', ...common })
+
+// after
+defineDownloadTool({ files, resolveUrl, ...common })
+defineUploadTool({ files, upload: ({ bytes }) => provider.upload(bytes), ...common })
+defineViewFileTool({ files, ...common })
+```
+
+Downloaded `path` is now relative to the boundary and MIME metadata is named
+`mediaType`. Update raw `mountDownload`/`mountUpload`/`mountViewFile` configs the
+same way. Auth predicates must explicitly return `true`, `false`, or a plain
+object of context fields; replace accidental `undefined` fallthroughs with the
+intended boolean.
+
 ## Released migration: 0.53.0
 
 ### Realtime `emit` returns `boolean` instead of `void`

package/llms/{upgrading-0.55.0-0.68.0.txt → upgrading-0.57.0-0.69.0.txt}

@@ -1,14 +1,55 @@
-# Upgrading 0.55.0 → 0.68.0 — stitchkit docs slice
+# Upgrading 0.57.0 → 0.69.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.55.0 → 0.68.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.57.0 → 0.69.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.55.0 → 0.68.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.57.0 → 0.69.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.69.0
+
+### Direct coding-tool operation names
+
+`createAgentCodingTools` no longer prefixes durable operation identity with `coding_`, and the
+unguarded exact-string edit tool is gone. Update approval maps, presenters and tests together:
+
+```ts
+// before
+{ coding_read_file: 'approved', coding_search: 'approved', coding_patch_file: 'user-approval' }
+
+// after
+{ read_file: 'approved', search_files: 'approved', apply_patch: 'user-approval' }
+```
+
+The full mapping is `coding_read_file → read_file`, `coding_write_file → write_file`,
+`coding_search → search_files`, `coding_patch_file → apply_patch`, `coding_shell → run_command`,
+`coding_read_artifact → read_output` and `harness_read_resource → read_resource`. Replace
+`coding_edit_file` with `read_file` followed by guarded `apply_patch`; `read_file` now returns the
+required SHA-256. If the host declares no executable aliases, expect `run_command` to be absent.
+
+### Durable Agent approval message variants
+
+If a renderer, store adapter or export pipeline exhaustively switches over
+`AgentMessage.role`, add the `tool` branch. If it switches over
+`AgentMessagePart.type`, add `tool-approval-request` and `tool-approval-response`.
+They are durable provider-continuation evidence: preserve them in storage and provider history;
+a UI may render them as approval state or intentionally omit their visual row.
+
+```ts
+// before
+const unreachable: never = message.role
+
+// after
+if (message.role === 'tool') renderToolContinuation(message.parts)
+else renderExistingRole(message)
+```
+
+No data migration is needed. The schema still accepts all earlier records, and applications that
+do not exhaustively branch over these unions compile unchanged.
+
 ## Released migration: 0.68.0
 
 ### Make Unix transport selection explicit outside Bun
@@ -1073,130 +1114,3 @@ The consequence for an exhaustive switch written without a `default` branch is a
 compile error, which is the point. The consequence for a switch that *has* a
 `default` is worse and silent: post-commit admissions fall into it and are
 projected as an unknown event. Grep for publisher switches before upgrading.
-
-## Released migration: 0.56.0
-
-### Surface manifests are version 2
-
-`operation.tools` could not describe a role-selected MCP surface, a different
-Agent or CLI selection, or an advertised `extend` schema, so projections moved
-out of the canonical operation:
-
-```ts
-// before
-manifest.operations[0].tools.MCP
-// after
-manifest.toolSurfaces.find((s) => s.transport === 'MCP' && s.surface === null)?.tools
-
-// before
-buildSurfaceManifest({ mcpSurfaces: { admin: { services, extend } } })
-// after
-buildSurfaceManifest({ mcpSurfaces: { admin: { services } }, mcpPreparation: { extend } })
-```
-
-A committed snapshot is regenerated once, deliberately: `manifestVersion` is
-`2`, and `ConformanceTransport` gained `REALTIME`, so any exhaustive
-`Record<ConformanceTransport, …>` must handle it.
-
-### `FILE_*` codes joined the error registry
-
-`StitchErrorCode` gained `FILE_INVALID_PATH`, `FILE_OUTSIDE_ROOT`,
-`FILE_NOT_FOUND`, `FILE_NOT_REGULAR`, `FILE_INSPECTION_REJECTED`,
-`FILE_TOO_LARGE` and `FILE_EXISTS`. Only exhaustive maps break:
-
-```ts
-// before — compiled while the registry had no file codes
-const copy: Record<StitchErrorCode, string> = { …, RATE_LIMITED: '…' }
-// after — add the seven managed-file codes (or use Partial<Record<…>>)
-```
-
-Unexpected IO stays scrubbed as `INTERNAL_SERVER_ERROR`: the new codes are the
-caller-safe ones only.
-
-### `ScopedAuthHook` is nominal
-
-A hand-written function shaped like an auth hook is no longer assignable —
-identity now comes from the factory, so scope ownership and the inferred
-context cannot drift apart:
-
-```ts
-// before — a structural stand-in
-const auth: ScopedAuthHook<Scopes> = async (ctx, endpoint) => { … }
-// after — create it, then compose domains
-const auth = createAuthHook({ resolve, rules })
-const composed = composeAuthHooks({ hooks: [auth, billingAuth], defaultScope: 'public' })
-```
-
-### Managed-file inspectors also run on reads
-
-An inspector is no longer write-only, and it has a finite default deadline
-(15 s). Make it read-aware and idempotent — a read carries no
-`declaredMediaType`:
-
-```ts
-// before
-inspect: ({ declaredMediaType }) => inspectDeclaredType(declaredMediaType!)
-// after
-inspect: ({ prefix, declaredMediaType, signal }) =>
-  inspectBytes(prefix, { declaredMediaType, signal })
-```
-
-Set `inspectionTimeoutMs` explicitly when 15 seconds is the wrong budget.
-
-### Direct async-operation binding needs a wire-stable ID
-
-A direct binding reuses the start output as the follow-up wire input, so the ID
-schema must parse to itself (`z.input` equals `z.output`, no transform,
-coercion, default or overwrite). Anything else is parsed twice:
-
-```ts
-// before — a transform silently ran on start and again on every follow-up
-defineAsyncOperationContract({ binding: 'direct', id: z.string().transform(Number) })
-// after — keep the wire shape, adapt explicitly
-defineAsyncOperationContract({
-  binding: 'adapted',
-  id,
-  adapters: { idFromStart, inputFor },
-})
-```
-
-## Released migration: 0.55.0
-
-### Peer-free `implementRemote`
-
-`implementRemote` now has one canonical, optional-peer-free owner. This keeps
-MCP SDK and AI SDK modules out of CLI bundles that only proxy HTTP calls:
-
-```ts
-// before
-import { implementRemote } from 'stitchkit/tools'
-// after
-import { implementRemote } from 'stitchkit/remote'
-```
-
-### Managed file boundary and strict auth returns
-
-Create one boundary during application bootstrap and pass the capability, never
-a per-call directory or host path:
-
-```ts
-import { createManagedFileBoundary } from 'stitchkit/files'
-
-const files = await createManagedFileBoundary({ root: '/srv/app-files' })
-
-// before
-defineDownloadTool({ defaultDir: '/srv/app-files', resolveUrl, ...common })
-defineUploadTool({ upload: (path) => provider.uploadFile(path), ...common })
-defineViewFileTool({ baseDir: '/srv/app-files', ...common })
-
-// after
-defineDownloadTool({ files, resolveUrl, ...common })
-defineUploadTool({ files, upload: ({ bytes }) => provider.upload(bytes), ...common })
-defineViewFileTool({ files, ...common })
-```
-
-Downloaded `path` is now relative to the boundary and MIME metadata is named
-`mediaType`. Update raw `mountDownload`/`mountUpload`/`mountViewFile` configs the
-same way. Auth predicates must explicitly return `true`, `false`, or a plain
-object of context fields; replace accidental `undefined` fallthroughs with the
-intended boolean.