stitchkit 0.103.12 → 0.104.0

package/llms/telegram.txt

@@ -184,7 +184,8 @@ const report = await runTelegramBroadcast({
   `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.
+  so the run after the fix reaches them. An unknown transport outcome becomes
+  `uncertain` immediately and halts the run; resume never sends to that recipient again.
 - **Pacing** is `ratePerSecond`, 25 by default. `dryRun` counts and writes
   nothing. One runner per name: a second concurrent run is refused.
 
@@ -193,6 +194,66 @@ 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.
 
+### Injecting another transport's failure policy
+
+`classify(error)` returns the public `TelegramBroadcastFailure` union. It lets
+an application use its own client without adding that SDK to Stitchkit:
+
+```ts
+const report = await runTelegramBroadcast({
+  name: 'announcement',
+  directory: env.STATE_DIRECTORY,
+  recipients: () => audience.activeSubscribers(),
+  send: ({ recipient }) => client.sendMessage(recipient, message),
+  classify(error) {
+    if (isFloodWait(error))
+      return { kind: 'retry-after', retryAfterMs: error.seconds * 1000,
+        reason: 'provider-rate-limit' }
+    if (isRecipientGone(error))
+      return { kind: 'permanent', recipientUnreachable: true,
+        reason: 'recipient-gone' }
+    return { kind: 'ambiguous', reason: 'unknown-provider-outcome' }
+  },
+  maxRetryDelayMs: 60_000,
+  signal: stop.signal,
+})
+```
+
+The four variants are `retry-after` (exact `retryAfterMs`), `transient` (bounded
+backoff), `permanent` (optionally `recipientUnreachable` or `stopBroadcast`), and
+`ambiguous`. Retry variants certify that the failed attempt had no external
+effect. Lack of an HTTP status does not establish that fact: a server may have
+accepted the message before the connection failed. `ambiguous` durably records
+`uncertain`, then halts; resuming the name skips that recipient.
+
+`maxRetryDelayMs` defaults to 60 seconds. A provider wait above it halts with the
+recipient pending; it is never shortened to send early. `maxAttempts` is an
+integer from 1 to 100, `maxRetryDelayMs` is an integer from 0 to 2,147,483,647,
+and pacing/progress intervals must fit native timers. The optional
+`sleep(milliseconds, signal)` receives cancellation; the runner also stops waiting
+when the signal aborts if a custom sleeper ignores it. A send already in flight
+finishes and is recorded before stopping.
+
+Without `classify`, known Bot API 429, unreachable-recipient, malformed-message
+and server-error behavior remains. Unknown/no-status failures now halt as
+uncertain, rather than being automatically retried. Existing custom `send`
+implementations that relied on those retries must supply an explicit classifier
+for proven pre-effect failures. `report.halt` now carries
+`TelegramBroadcastFailure`; inspect `halt.kind` instead of the old send-failure
+`scope`/`retryable` fields.
+
+The runner uses the shared process-instance lock and checks its generation before
+sends and journal writes. The audience and initial journal directory entry are
+synced before sending. Lost ownership cannot write a stale delivered receipt or
+start another send; the persisted intent becomes uncertain on recovery. Old
+pid-only broadcast locks have unknown ownership and require recovery after their
+writers are verified stopped, rather than automatic age-based deletion.
+
+The installed
+[`telegram-broadcast-classifier.mjs`](../../packages/core/scripts/consumer-lane/fixtures/minimal/src/telegram-broadcast-classifier.mjs)
+fixture checks injected rate limits, ambiguity/no resend, wait budgets and abort
+on Bun and Node without a client SDK.
+
 ## Message markup
 
 `stitchkit/telegram/html` is Telegram's HTML parse mode as a tree, with no peer
@@ -393,8 +454,9 @@ injected grammY bot. → ADR 0143, ADR 0201 — [guide](../guide/telegram.md)
 | `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` / `TELEGRAM_SEND_FAILURE_REASONS` | _type_ / constant | `blocked-by-user` / `user-deactivated` / `chat-not-found` / `not-started` / `rate-limited` / `message-invalid` / `server-error` / `unknown`, and the same as a list; a `Record<TelegramSendFailureReason, …>` over them fails to compile when a reason is added |
-| `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 |
+| `runTelegramBroadcast` | function | a resumable broadcast by `name` under a state `directory`: audience and journal durably recorded, pacing at `ratePerSecond` (25), exact retry delays within the finite declared budget, injected classifier, uncertain send outcomes never replayed, `dryRun`, one fenced 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` |
+| `TelegramBroadcastFailureSchema` / `TelegramBroadcastFailure` | schema / _type_ | injected `classify` answers retry-after/transient/permanent/ambiguous; exact provider delay is bounded by `maxRetryDelayMs` without shortening, unknown outcome remains uncertain and is never replayed |
 | `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`, `sensitivePatterns` and `sensitiveValues` (a bot token is always masked), `dedupe`; a drop is `overflow` / `refused` / `attempts` / `closed` / `repeated` / `over-budget` with its classification |

package/llms/tools-connections.txt

@@ -23,6 +23,9 @@ and approval path.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `defineMcpClientConnection` | function | declare one external MCP server connection over Streamable HTTP with an optional SSE fallback |
+| `ConnectionOperationLimits` / `McpConnectionLimits` | _type_ | positive finite deadline/raw byte ceilings with independent discovery/call overrides; omitted fields inherit the shared bounds |
+| `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` |
 | `ConnectionAuthorizationRequiredError` | class | typed reauthorization signal raised on `401` with credentials resolved again on the next call |

package/llms/tools-mcp.txt

@@ -0,0 +1,29 @@
+# stitchkit/tools/mcp — 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: API reference: `stitchkit/tools/mcp`  (docs/api/reference.md)
+
+Also read:
+- see `llms/tools.txt` for the MCP & agents guide
+
+==============================================================================
+# API reference: `stitchkit/tools/mcp`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/tools/mcp`
+
+A server-only leaf over the same MCP owner as `stitchkit/tools`. Its runtime and strict
+NodeNext declarations require Zod and `@modelcontextprotocol/server`, with no AI SDK peer.
+HTTP/stdio factories, mounts, schema policy, catalog and resource helpers keep their canonical
+behavior and names. See [MCP guide](../guide/mcp-and-agents.md#mcp--createmcphandler).
+
+| Export | Kind | Purpose |
+|--------|------|---------|
+| `createMcpHandler` / `createMcpHttpRoute` / `buildMcpServer` / `mountMcp` | function | the shared authenticated HTTP handler, raw-route adapter, SDK server and contract mount |
+| `createStdioMcpServer` / `bindStdioProcessSignals` | function | the shared stdio server and bounded process cleanup |
+| `RuntimeMcpToolDefinitionWithOutput` | _type_ | schema-aware MCP-only construction with concrete handler output and presenter input |
+| `RuntimeMcpToolDefinition` | _type_ | heterogeneous MCP registration; the canonical runner validates input/output before invocation |
+| `RuntimeMcpToolPresenters` / `RuntimeMcpPresentation` | _type_ | official SDK content without framework-owned `structuredContent` or `isError`; one presenter owner shared with the full SDK surface |
+| `RuntimeToolDefinitionWithoutOutput` | _type_ | the shared neutral void definition |

package/llms/tools.2.txt

@@ -13,6 +13,65 @@ Parts of this slice:
 # Guide: MCP & agents  (docs/guide/mcp-and-agents.md)  (continued)
 ==============================================================================
 
+## Proxying a remote API — `implementRemote`
+
+`implement` binds a contract to local handlers. `implementRemote` binds it to a
+remote HTTP API instead — every handler forwards the call to a deployed server
+through the contract's typed client:
+
+```ts
+import { createHttpClient } from 'stitchkit'
+import { implementRemote } from 'stitchkit/remote'
+import { createStdioMcpServer } from 'stitchkit/tools/mcp'
+
+const http = createHttpClient({
+  baseUrl: 'https://api.example.com',
+  headers: () => ({ Authorization: `Bearer ${apiKey}` }),
+})
+
+const stdio = await createStdioMcpServer({
+  serverInfo: { name: 'my-app', version: '1.0.0' },
+  auth: null,
+  services: contracts.map((c) => implementRemote(c, http)),
+})
+
+// During graceful shutdown:
+await stdio.close()
+```
+
+This is how you ship a thin **local** MCP server for an API that already runs in
+the cloud: the local process owns only the transport and any filesystem-facing
+native tools, while every contract tool proxies to the remote API. One contract,
+no duplicated business logic.
+
+`implementRemote(contract, http, { transformArgs })` takes an optional
+`transformArgs` hook that rewrites a call's arguments before they are forwarded
+— e.g. to upload a local file referenced in the args and swap in its URL.
+
+The call's signal reaches the existing typed HTTP client's request options, for endpoints
+with or without arguments. An already cancelled call, including cancellation while an async
+argument transform runs, dispatches no request. Bind your process signal to `createCli` or
+`createCliInvoker`; `REQUEST_ABORTED` is a safe nonretryable failure with CLI exit130.
+Cooperative origins observe `ctx.signal` and release resources when their work ends. An
+origin or provider ignoring cancellation may continue after the local wait stops.
+
+An explicit `AppError.retryable` boolean also survives this remote hop. `false` on502 and
+`true` on409 remain the application's recommendation through HTTP, CLI, MCP and AI tools.
+Absent metadata keeps the previous defaults and does not alter HTTP transport retries.
+
+## Structured output
+
+When a contract endpoint or runtime tool declares `output`, its MCP tool
+registers that exact schema as `outputSchema` and returns the validated value as
+`structuredContent` alongside a JSON text block. Every JSON root type is kept
+unchanged: object, array, string, number, boolean and `null`. Stitchkit does not
+wrap non-object values in `{ result }`; protocol-era adaptation belongs to the
+official SDK.
+
+A tool without an output contract advertises no `outputSchema` and returns no
+invented structured value. Its successful MCP result has an empty `content`
+list.
+
 ## A different answer for tools — `withToolView`
 
 An admin page wants the full record; a model wants a card. Every byte of a

package/llms/tools.3.txt

@@ -278,6 +278,7 @@ Advanced building blocks — the shared machinery the mounts are built on.
 | `TransportSummary` | _type_ | `{ contractServices, runtimeTools, totals, sources }` from `summarizeTransports` |
 | `TransportCounts` | _type_ | per-transport counts (`{ HTTP, MCP, AGENT, CLI }`) |
 | `ToolSurfaceDefinition` | _type_ | shared object-shaped `{ services?, runtimeTools? }` introspection surface |
+| `ToolSurfaceProjection` | _type_ | one readonly services/runtime container shared by full and MCP-only surfaces; executable mounts specialize the runtime definition without pulling in another adapter's peers |
 | `ToolManifestConfig` | _type_ | mixed surface plus required model-facing `transport` and presentation options |
 | `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments |
 | `flattenToolJsonSchema` | function | project structurally identifiable discriminated unions into conservative object joins; scalar collisions retain provable types, object/array collisions retain structural alternatives, and field descriptions retain discriminator labels plus availability/requiredness hints; the projection never executes validation |

package/llms/tools.txt

@@ -147,13 +147,20 @@ get the view's defaults and projected answer, which is what `collectTools` and
 
 ## MCP — `createMcpHandler`
 
+An MCP-only server imports `stitchkit/tools/mcp` and installs
+`stitchkit`, `zod` and `@modelcontextprotocol/server`. The leaf's runtime and strict
+NodeNext declarations require no `ai`. It exports the existing HTTP/stdio server,
+schema policy, catalog and resource helpers; their implementation and security are shared
+with the full `stitchkit/tools` barrel. Use that full barrel when the application also
+needs its AI SDK features.
+
 `createMcpHandler` builds a complete stateless Streamable-HTTP MCP endpoint on
 the official TypeScript SDK v2 server package. It owns server creation,
 protocol-era negotiation and shutdown; application code does not import the SDK
 to mount a normal endpoint.
 
 ```ts
-import { createMcpHandler, createMcpHttpRoute } from 'stitchkit/tools'
+import { createMcpHandler, createMcpHttpRoute } from 'stitchkit/tools/mcp'
 import { createServer } from 'stitchkit/server'
 
 const mcp = createMcpHandler({
@@ -287,7 +294,7 @@ Every advertised tool and every tool result therefore carries the fingerprint of
 the catalog it came from:
 
 ```ts
-import { readMcpCatalogStamp } from 'stitchkit/tools';
+import { readMcpCatalogStamp } from 'stitchkit/tools/mcp';
 
 const listed = await client.listTools();
 let known = readMcpCatalogStamp(listed.tools[0]?._meta); // { digest, tools }
@@ -792,7 +799,7 @@ If you already run an `McpServer` from the SDK, `mountMcp` adds contract tools
 to it instead of owning the lifecycle:
 
 ```ts
-import { mountMcp } from 'stitchkit/tools'
+import { mountMcp } from 'stitchkit/tools/mcp'
 
 mountMcp(mcpServer, [usersService], { context: { source: 'mcp' } })
 ```
@@ -808,7 +815,7 @@ client (Claude Desktop, Claude Code, Cursor, Codex), on the user's machine, so
 it can reach the local filesystem.
 
 ```ts
-import { bindStdioProcessSignals, createStdioMcpServer } from 'stitchkit/tools'
+import { bindStdioProcessSignals, createStdioMcpServer } from 'stitchkit/tools/mcp'
 
 const stdio = await createStdioMcpServer({
   serverInfo: { name: 'my-app', version: '1.0.0' },
@@ -953,51 +960,3 @@ successes cannot reset a failing client's backoff.
 > Dynamic Client Registration is an explicit interoperability mode, not the
 > default. Enabling it changes public discovery and adds `/register`; keep it off
 > unless a client that cannot publish CIMD requires it.
-
-## Proxying a remote API — `implementRemote`
-
-`implement` binds a contract to local handlers. `implementRemote` binds it to a
-remote HTTP API instead — every handler forwards the call to a deployed server
-through the contract's typed client:
-
-```ts
-import { createHttpClient } from 'stitchkit'
-import { implementRemote } from 'stitchkit/remote'
-import { createStdioMcpServer } from 'stitchkit/tools'
-
-const http = createHttpClient({
-  baseUrl: 'https://api.example.com',
-  headers: () => ({ Authorization: `Bearer ${apiKey}` }),
-})
-
-const stdio = await createStdioMcpServer({
-  serverInfo: { name: 'my-app', version: '1.0.0' },
-  auth: null,
-  services: contracts.map((c) => implementRemote(c, http)),
-})
-
-// During graceful shutdown:
-await stdio.close()
-```
-
-This is how you ship a thin **local** MCP server for an API that already runs in
-the cloud: the local process owns only the transport and any filesystem-facing
-native tools, while every contract tool proxies to the remote API. One contract,
-no duplicated business logic.
-
-`implementRemote(contract, http, { transformArgs })` takes an optional
-`transformArgs` hook that rewrites a call's arguments before they are forwarded
-— e.g. to upload a local file referenced in the args and swap in its URL.
-
-## Structured output
-
-When a contract endpoint or runtime tool declares `output`, its MCP tool
-registers that exact schema as `outputSchema` and returns the validated value as
-`structuredContent` alongside a JSON text block. Every JSON root type is kept
-unchanged: object, array, string, number, boolean and `null`. Stitchkit does not
-wrap non-object values in `{ result }`; protocol-era adaptation belongs to the
-official SDK.
-
-A tool without an output contract advertises no `outputSchema` and returns no
-invented structured value. Its successful MCP result has an empty `content`
-list.