stitchkit 0.115.0 → 0.116.0

package/dist/internal/contained-files.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contained-files.d.ts","sourceRoot":"","sources":["../../src/internal/contained-files.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"contained-files.d.ts","sourceRoot":"","sources":["../../src/internal/contained-files.ts"],"names":[],"mappings":"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"}

package/dist/telegram/budget-transformer.d.ts

@@ -16,7 +16,7 @@
  * grammY is named in the declarations and never imported at run time.
  */
 import type { Transformer } from 'grammy';
-import type { TelegramOutboundBudget } from './outbound-budget.js';
+import type { TelegramOutboundBudget, TelegramOutboundCallOptions } from './outbound-budget.js';
 /**
  * A grammY client transformer that runs every Bot API call under `budget`.
  *
@@ -30,6 +30,9 @@ import type { TelegramOutboundBudget } from './outbound-budget.js';
  * `TelegramNotDispatchedError`: nothing was sent. A cancellation after the
  * request was handed on is the client's ordinary error and the outcome is
  * unknown, not a definite failure.
+ *
+ * `options.lane` applies to every call through this client: a campaign installs
+ * `{ lane: 'bulk' }` on its own `Api`, and replies stay ahead of it.
  */
-export declare function telegramBudgetTransformer(budget: TelegramOutboundBudget): Transformer;
+export declare function telegramBudgetTransformer(budget: TelegramOutboundBudget, options?: TelegramOutboundCallOptions): Transformer;
 //# sourceMappingURL=budget-transformer.d.ts.map

package/dist/telegram/budget-transformer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"budget-transformer.d.ts","sourceRoot":"","sources":["../../src/telegram/budget-transformer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAE1C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AA4BhE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,sBAAsB,GAAG,WAAW,CAsBrF"}
+{"version":3,"file":"budget-transformer.d.ts","sourceRoot":"","sources":["../../src/telegram/budget-transformer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAE1C,OAAO,KAAK,EAAE,sBAAsB,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AA4B7F;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,sBAAsB,EAC9B,OAAO,CAAC,EAAE,2BAA2B,GACpC,WAAW,CA4Bb"}

package/dist/telegram/outbound-budget.d.ts

@@ -13,9 +13,15 @@
  * `forwardMessages` cost their message ids, and the follow-up call to action
  * after an album is one more message.
  *
- * **It paces; it does not retry.** A 429 pauses every sender of the token for
- * the wait Telegram stated (or a declared fallback when it stated none). A
- * network failure or a 5xx is returned to the caller unchanged: repeating a
+ * Two lanes share that one rate. An `interactive` call is granted before any
+ * `bulk` call that is waiting, so a person's reply never queues behind a
+ * campaign; a campaign runs at whatever rate replies leave it.
+ *
+ * **It paces; it does not retry.** A 429 on a method that spends the budget
+ * pauses every sender of the token for the wait Telegram stated (or a declared
+ * fallback when it stated none). A 429 on an edit or a read concerns that call
+ * and pauses nothing. A network failure or a 5xx is returned to the caller
+ * unchanged: repeating a
  * send whose external outcome is unknown is the caller's decision, and a
  * primitive that retried it would turn one unknown message into two.
  *
@@ -25,6 +31,8 @@
  * saved burst at start and again after a 429 pause, which is exactly the
  * stampede a shared budget exists to prevent.
  */
+/** Whose turn comes first. `interactive` answers a person; `bulk` is a campaign. */
+export type TelegramOutboundLane = 'interactive' | 'bulk';
 export interface TelegramOutboundBudgetConfig {
     /** The bot token whose sends share this budget. It is never returned or logged. */
     readonly token: string;
@@ -52,31 +60,38 @@ export interface TelegramOutboundBudgetStats {
     readonly granted: number;
     /** Weighted messages admitted: an album of three counts as three. */
     readonly messages: number;
-    /** Calls waiting for their turn. */
+    /** Calls waiting for their turn, in both lanes. */
     readonly queued: number;
+    /** How many of them are in the `bulk` lane. */
+    readonly queuedBulk: number;
     readonly messagesPerSecond: number;
     /** How much of the current 429 pause is still ahead, in milliseconds. */
     readonly pausedForMs: number;
 }
+export interface TelegramOutboundCallOptions {
+    /** Default `interactive`. */
+    readonly lane?: TelegramOutboundLane;
+}
 /**
  * A token's outbound budget. `run` is the narrow adapter a client transformer
  * calls around its own send; it gates, pauses on 429 and never retries.
  */
 export interface TelegramOutboundBudget {
     /**
-     * Run one Bot API call under the budget. A non-send method passes through
-     * without spending a message. A 429 pauses every sender of the token, whether
-     * `send` throws it or resolves with the Bot API's `{ ok: false, … }` body, as
-     * a client transformer's `send` does. The error is rethrown, or the response
-     * returned, unchanged and the call is not repeated.
+     * Run one Bot API call under the budget, in the `interactive` lane by default.
+     * A non-send method passes through without spending a message. A 429 on a send
+     * pauses every sender of the token, whether `send` throws it or resolves with
+     * the Bot API's `{ ok: false, … }` body, as a client transformer's `send` does;
+     * a 429 on a non-send method pauses nothing. The error is rethrown, or the
+     * response returned, unchanged and the call is not repeated.
      */
-    run<T>(method: string, payload: unknown, signal: AbortSignal | undefined, send: () => Promise<T>): Promise<T>;
+    run<T>(method: string, payload: unknown, signal: AbortSignal | undefined, send: () => Promise<T>, options?: TelegramOutboundCallOptions): Promise<T>;
     /**
      * Wait until `cost` messages fit. The wait rejects with `signal.reason`
      * without spending a token; a granted call owns its slots even if its later
      * send is aborted, which the caller must not repeat as a definite failure.
      */
-    acquire(cost: number, signal?: AbortSignal): Promise<void>;
+    acquire(cost: number, signal?: AbortSignal, options?: TelegramOutboundCallOptions): Promise<void>;
     /** Pause every sender of this token for at least `milliseconds`. Never shortens an existing pause. */
     pause(milliseconds: number): void;
     /** Pause the token after a rate-limited refusal; another failure does nothing. */

package/dist/telegram/outbound-budget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"outbound-budget.d.ts","sourceRoot":"","sources":["../../src/telegram/outbound-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAwEH,MAAM,WAAW,4BAA4B;IAC3C,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChF;AAED,kEAAkE;AAClE,MAAM,WAAW,2BAA2B;IAC1C,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,yEAAyE;IACzE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,EACH,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,CAAC,CAAC,CAAC;IACd;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,sGAAsG;IACtG,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,kFAAkF;IAClF,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC;;;OAGG;IACH,gBAAgB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,sDAAsD;IACtD,KAAK,IAAI,2BAA2B,CAAC;CACtC;AAyMD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,4BAA4B,GACnC,sBAAsB,CAsCxB"}
+{"version":3,"file":"outbound-budget.d.ts","sourceRoot":"","sources":["../../src/telegram/outbound-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAwEH,oFAAoF;AACpF,MAAM,MAAM,oBAAoB,GAAG,aAAa,GAAG,MAAM,CAAC;AAE1D,MAAM,WAAW,4BAA4B;IAC3C,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChF;AAED,kEAAkE;AAClE,MAAM,WAAW,2BAA2B;IAC1C,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,yEAAyE;IACzE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,2BAA2B;IAC1C,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,oBAAoB,CAAC;CACtC;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,GAAG,CAAC,CAAC,EACH,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,CAAC,CAAC,CAAC;IACd;;;;OAIG;IACH,OAAO,CACL,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,sGAAsG;IACtG,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,kFAAkF;IAClF,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC;;;OAGG;IACH,gBAAgB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,sDAAsD;IACtD,KAAK,IAAI,2BAA2B,CAAC;CACtC;AA6ND;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,4BAA4B,GACnC,sBAAsB,CAsCxB"}

package/dist/tools/cli/view.d.ts

@@ -1,12 +1,18 @@
 import type { CliResultView } from './args-view.js';
-/** What a view produces: a JSON value, or the one human-facing shape. */
+/**
+ * What a view produces: a JSON value, or the one human-facing shape. `order` is the order of
+ * a grouped object's keys, which an object cannot hold once a key looks like an integer.
+ */
 export type CliViewOutput = {
     kind: 'json';
     data: unknown;
+    order?: readonly string[];
 } | {
     kind: 'text';
     text: string;
 };
+/** One grouped view in its own order, spaced as the CLI spaces any JSON it prints. */
+export declare function stringifyGroups(data: unknown, order: readonly string[], compact: boolean): string;
 /** Compute the requested view, or refuse it with a message naming the field. */
 export declare function renderCliView(data: unknown, view: CliResultView): CliViewOutput;
 //# sourceMappingURL=view.d.ts.map

package/dist/tools/cli/view.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/view.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,yEAAyE;AACzE,MAAM,MAAM,aAAa,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AA4M7F,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,GAAG,aAAa,CAgC/E"}
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/view.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD;;;GAGG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAuGnC,sFAAsF;AACtF,wBAAgB,eAAe,CAC7B,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,EAAE,OAAO,GACf,MAAM,CAMR;AA6GD,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,GAAG,aAAa,CAgC/E"}

package/llms/agent-runtime.txt

@@ -314,8 +314,8 @@ stay pinned through authorization; `write_file` plans before it and opens the pa
 the parent it creates does not exist yet. Reads revalidate the pinned file identity;
 writes and patches revalidate the pinned parent identity; search and resource discovery descend
 only through opened directories. A path that changed during authorization refuses with `CONFLICT`.
-Policies compare path strings, so on a case-insensitive filesystem such as default macOS volumes a
-rule on `credentials` does not match `CREDENTIALS`; such a host must normalize in its own policy.
+A path spelled differently from the name stored on disk refuses before any policy reads it, so on a
+case-insensitive volume a rule on `credentials` cannot be passed by asking for `CREDENTIALS`.
 NUL bytes are refused before either host policy sees a path.
 Reads and edits open file candidates without blocking on special files, then require a regular
 file. A writerless FIFO therefore refuses instead of occupying a filesystem worker. `write_file`

package/llms/cli.txt

@@ -670,7 +670,9 @@ myapp item_list --sort messages --top 5 --json                # the same five, a
 myapp item_list --sort name --ascending                       # ordered the other way
 ```
 
-Groups come back largest first for the same reason. A record that carries no
+Groups come back largest first for the same reason, in the printed bytes even when a key looks
+like a number; a reader that parses them into a JavaScript object reorders such keys itself.
+A string equal to `null` or `(absent)` is quoted, so it stays apart from the missing value. A record that carries no
 value for the sort field sorts **last in both directions**: it is not the
 smallest, it is not on the scale at all, and letting it lead an ascending list
 would answer a question nobody asked.

package/llms/stitchkit.txt

@@ -86,13 +86,13 @@ 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 60 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 61 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, the managed-resource conformance kit and manual time for schedules and retries |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
 | `stitchkit/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
 | `stitchkit/react/keyboard/testing` | server (Bun or Node) | evolving | the keyboard layers and zones without a DOM — fakes for the window, elements and key events beside the two engines, to test the order of layers, `scope`/`inert` and the edges of a zone in milliseconds |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 25 of the 60 minors since 0.56.2, most recently 0.115.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 25 of the 61 minors since 0.56.2, most recently 0.115.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 |
@@ -104,7 +104,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 60 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 61 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |

package/llms/telegram.txt

@@ -122,6 +122,13 @@ cast, and a send cancelled in the queue then waits for its slot and fails as
   a follow-up call to action after an album costs one more. Reads and edits
   (`getMe`, `getFile`, `editMessage*`, `deleteMessage`, `sendChatAction`) do not
   spend the budget.
+- **Two lanes share one rate.** A call is `interactive` by default; a campaign passes
+  `{ lane: 'bulk' }` to `run` or `acquire`, or installs
+  `telegramBudgetTransformer(budget, { lane: 'bulk' })` on its own `Api`. A waiting
+  interactive call is granted first, so a reply never queues behind recipients;
+  the wait it can still see is the interval of the grant before it, up to one
+  album. Bulk runs at whatever rate replies leave, and the sum never exceeds
+  `messagesPerSecond`.
 - **The first send after idle is immediate; the rest are spaced.** This is a
   strict budget, not a bucket that saves a burst: at 24/s the next send is due
   one interval later. A 429 pauses the whole token; when it resumes, one send
@@ -133,8 +140,8 @@ cast, and a send cancelled in the queue then waits for its slot and fails as
   The refusal may be thrown or returned: a client transformer sits below the
   place where grammY turns Telegram's `{ ok: false, error_code: 429, … }` body into
   a `GrammyError`, so `run` reads that body too and hands it back unchanged.
-  A 429 from an edit or a read is still a fact about the token and pauses later
-  sends too. A network failure is rethrown unchanged and stays `unknown`; a 5xx
+  A 429 from an edit or a read concerns that call and pauses nothing; `budget.pauseAfter`
+  remains for a caller who decides otherwise. A network failure is rethrown unchanged and stays `unknown`; a 5xx
   is rethrown unchanged and stays `server-error`. Neither is retried by the
   budget or pauses the token — repeating a send whose outcome is unknown is a
   decision, not a primitive's silent guess.
@@ -608,7 +615,7 @@ injected grammY bot. → ADR 0143, ADR 0201, ADR 0274 — [guide](../guide/teleg
 | `TelegramFetch` / `TelegramBotTransportOpen` / `TelegramBotTransportResolve` / `TelegramBotTransportSocket` | _types_ | the `(url, init) => Promise<Response>` the senders take; the transport's socket factory, resolver and the structural socket it needs (a Node `net.Socket` or `tls.TLSSocket` fits) |
 | `TelegramNotDispatchedError` / `TelegramNotDispatchedStage` | class / _type_ | a request that provably never left (`lookup`, `connect` or `request`), so repeating it cannot duplicate a message |
 | `TelegramSendFailureReason` / `TELEGRAM_SEND_FAILURE_REASONS` | _type_ / constant | `blocked-by-user` / `user-deactivated` / `chat-not-found` / `not-started` / `bot-to-bot-disabled` / `rate-limited` / `message-invalid` / `server-error` / `not-dispatched` / `unknown`, and the same as a list; a `Record<TelegramSendFailureReason, …>` over them fails to compile when a reason is added |
-| `telegramOutboundBudget` / `TelegramOutboundBudget` / `TelegramOutboundBudgetConfig` / `TelegramOutboundBudgetStats` | function / _type_ | one token-wide outbound budget: one object per token in the process, strict 24 messages/s by default, weighted albums and multi-message copies, `run(method, payload, signal, send)` as the transformer adapter (a 429 pauses the token whether `send` throws it or resolves with the Bot API's `{ ok: false, … }` body), `pause`/`pauseAfter` for 429, `waitUntilResumed` for non-send retries and `stats`; it paces and never retries, and no public value carries the token |
+| `telegramOutboundBudget` / `TelegramOutboundBudget` / `TelegramOutboundBudgetConfig` / `TelegramOutboundBudgetStats` / `TelegramOutboundCallOptions` / `TelegramOutboundLane` | function / _type_ | one token-wide outbound budget: one object per token in the process, strict 24 messages/s by default, weighted albums and multi-message copies, an `interactive` lane granted before `bulk`, `run(method, payload, signal, send, { lane })` as the transformer adapter (a 429 on a send pauses the token whether `send` throws it or resolves with the Bot API's `{ ok: false, … }` body), `pause`/`pauseAfter` for 429, `waitUntilResumed` for non-send retries and `stats`; it paces and never retries, and no public value carries the token |
 | `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 |

package/llms/{upgrading-0.104.0-0.115.0.txt → upgrading-0.105.0-0.116.0.txt}

@@ -1,14 +1,37 @@
-# Upgrading 0.104.0 → 0.115.0 — stitchkit docs slice
+# Upgrading 0.105.0 → 0.116.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.104.0 → 0.115.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.105.0 → 0.116.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.104.0 → 0.115.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.105.0 → 0.116.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.116.0
+
+### send-only-telegram-pause
+
+**Who must act:** code that relied on a 429 from `editMessage*`, `deleteMessage` or a read to stop a
+token's sends. Code that only sends needs no change.
+
+`run` pauses the token only on a method that spends the budget
+([ADR 0277](../decisions/0277-a-telegram-budget-serves-replies-first.md)). Where an edit must still stop
+the sends, say so:
+
+```ts
+// before
+await budget.run('editMessageText', payload, signal, send)
+// after
+await budget.run('editMessageText', payload, signal, send).catch((error) => {
+  budget.pauseAfter(error)
+  throw error
+})
+```
+
+Search pattern: `budget.run` next to edit and read methods.
+
 ## Released migration: 0.115.0
 
 ### contained-cli-downloads
@@ -794,124 +817,3 @@ in the second position is a type error.
 
 4. Both classes accept the standard `cause`, which `error.cause` returns; omit the option to
    leave the property absent.
-
-## Released migration: 0.104.0
-
-JS bundles carrying Darwin native capabilities also need the
-[delivery migration first affected in 0.103.13](#released-migration-010313).
-Consumers upgrading from 0.103.12 or earlier must apply it even if their TypeScript API is unchanged.
-
-### CLI runtime-tool construction
-
-**Who must act:** callers writing a schema-dependent handler or MCP/AI `present` directly
-inside an annotated `CliConfig.runtimeTools` or `CliInvokerConfig.runtimeTools` object.
-Native `commands` and values returned by `defineRuntimeTool` / `createRuntimeToolFactory`
-remain valid. Execution, auth, validation and the invocation result envelope keep their behavior.
-
-Construct a CLI-only managed definition with the neutral schema-aware type before registration:
-
-```ts
-import type { CliInvokerConfig, RuntimeToolExecutionWithOutput } from 'stitchkit/cli'
-import { z } from 'zod'
-
-const input = z.object({ text: z.string() })
-const output = z.object({ size: z.number() })
-// Before: handler receives the heterogeneous registry context.
-const config: CliInvokerConfig = {
-  name: 'app',
-  runtimeTools: [{
-    name: 'measure', description: 'Measure text',
-    identity: { serviceName: 'text', action: 'measure', method: 'POST' },
-    transports: ['CLI'], input, output,
-    handler: ({ input }) => ({ size: String(input.text).length }),
-  }],
-}
-// After: handler input and output derive from the construction schemas.
-const measure = {
-  name: 'measure', description: 'Measure text',
-  identity: { serviceName: 'text', action: 'measure', method: 'POST' },
-  transports: ['CLI'], input, output,
-  handler: ({ input }) => ({ size: input.text.length }),
-} satisfies RuntimeToolExecutionWithOutput<typeof input, typeof output>
-const nextConfig: CliInvokerConfig = { name: 'app', runtimeTools: [measure] }
-```
-
-For a shared MCP/AI tool, construct the definition with `defineRuntimeTool` from
-`stitchkit/tools`, including its typed SDK `present` callbacks, then pass the returned value
-to `runtimeTools`. Install the corresponding SDK peers for that integration. A CLI-only
-consumer needs `stitchkit`, `zod` and its ordinary Node type tooling.
-
-`RuntimeToolExecution` names the heterogeneous registration contract. Call a registered
-operation through `createCli` or `createCliInvoker`; its erased handler input is `never`
-because the managed runner owns schema validation before execution. For a managed void
-definition, use `RuntimeToolDefinitionWithoutOutput<typeof input>`.
-
-### MCP construction, state stores and delivery
-
-**Who must act:** schema-dependent runtime tool literals written directly inside MCP mount
-configuration, MCP presenters returning malformed content or metadata, custom `StateStore`
-implementations, file-store consumers using retired lock
-options, broadcast consumers reading `halt` or retrying unknown send outcomes, and consumers
-that validate HTTP error envelopes with a closed schema. Applications collecting raw tool
-causes from `console.error` must configure an internal tool hook sink.
-
-MCP-only code can import the existing server factories from `stitchkit/tools/mcp` and
-construct its schema-aware tool before heterogeneous registration:
-
-```ts
-import { buildMcpServer, type RuntimeMcpToolDefinitionWithOutput } from 'stitchkit/tools/mcp'
-import { z } from 'zod'
-const input = z.object({ value: z.number() })
-const output = z.object({ doubled: z.number() })
-// Before: runtimeTools: [{ input, output, handler, present }]
-const double = {
-  name: 'double', description: 'Double a number',
-  identity: { serviceName: 'numbers', action: 'double', method: 'POST' },
-  input, output,
-  handler: ({ input }) => ({ doubled: input.value * 2 }),
-  present: { mcp: ({ doubled }) => ({ content: [{ type: 'text', text: String(doubled) }] }) },
-} satisfies RuntimeMcpToolDefinitionWithOutput<typeof input, typeof output>
-const server = buildMcpServer({ serverInfo: { name: 'numbers', version: '1' }, services: [], runtimeTools: [double] })
-```
-
-Full MCP/AI integrations keep `defineRuntimeTool` from `stitchkit/tools`; those typed values
-remain accepted by the MCP leaf and CLI. The leaf requires the MCP SDK and Zod, with no AI peer.
-
-`RuntimeMcpPresentation` preserves the official SDK's required `content` and typed `_meta`
-fields. A presenter returning `{}` must return `{ content: [] }`; text blocks require string
-text, and metadata must be an object. `structuredContent` and `isError` remain framework-owned.
-This restores SDK checks that an indexed mapped type previously erased.
-
-Unexpected tool causes remain in `hooks.onToolError` and the `error` field of
-`hooks.afterToolCall`. Protocol stderr carries safe errors. MCP resolver failures use those
-same observers without executing the handler or its lifecycle again. HTTP's default
-unexpected-error logging retains its behavior.
-
-A custom state adapter's `update` must invoke `transition(current, context)` while it still
-owns the serialized transaction. `context.assertHeld()` checks the actual transaction or lock
-generation and refuses after completion, rollback or ownership loss. A no-op guard cannot
-satisfy this contract. Existing transition callbacks may keep one parameter. For the owning
-file adapter, replace `{ staleLockMs, retryMs, lockTimeoutMs }` with `{ lockTimeoutMs }`:
-the remaining budget controls acquisition waiting, never expiry of a live transaction.
-Unknown legacy PID locks and historical temporary files are preserved; recover them only
-after independently proving their owner is gone.
-
-Broadcast consumers change `report.halt.reason` checks to the closed `halt.kind` union:
-`retry-after`, `transient`, `permanent` or `ambiguous`. A custom MTProto adapter can classify
-an acknowledged flood refusal as `{ kind: 'retry-after', retryAfterMs: wait }`; the exact
-provider wait is respected. A wait over `maxRetryDelayMs` halts with the recipient pending.
-Unknown write outcome becomes `uncertain`; restarting the same broadcast does not send it
-again. A retry classification must certify that the attempt did not apply the external effect.
-
-HTTP errors gain optional boolean `error.retryable`; framed contract streams use the same
-field. Update closed consumer schemas before producers declaring it. `false` on 502 and
-`true` on 409 remain explicit recommendations through the remote tool path. An absent field
-retains prior status-derived defaults; the field does not change the HTTP client's retry policy.
-The existing seventh `ApiError` constructor argument remains `ErrorOptions`; retryability is
-the new eighth argument.
-
-Caller cancellation now reaches `implementRemote`'s existing HTTP call. Applications bind
-signals to `createCli` / `createCliInvoker` and cooperative handlers observe `ctx.signal`.
-`REQUEST_ABORTED` is nonretryable and exits 130. A disconnected caller does not prove that
-an origin ignoring cancellation or an external provider stopped; keep resource leases until
-that work actually completes.

package/llms/{upgrading-0.44.0-0.61.0.txt → upgrading-0.44.0-0.62.0.txt}

@@ -1,14 +1,131 @@
-# Upgrading 0.44.0 → 0.61.0 — stitchkit docs slice
+# Upgrading 0.44.0 → 0.62.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.44.0 → 0.61.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.44.0 → 0.62.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.44.0 → 0.61.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.44.0 → 0.62.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.62.0
+
+Two groups of behaviour changes. Nothing moves an export — the surface is
+strictly additive — and every item changes what a running system reports or
+sends, which is what this heading is for. One of them changes a number you may
+already be billing against.
+
+### A run reports what it spent
+
+Three changes to what the runtime says about cost and tokens. Nothing moves an
+export; all three change numbers a running system reports, and one of them
+changes a number you may already be billing against.
+
+#### Multi-step cost was under-reported and is now summed
+
+No code change is needed to get the fix — but check any predicate that reads
+`provenance`:
+
+```ts
+// before — accepted a number that was one step's cost, not the run's
+if (usage.cost?.provenance === 'provider-reported') bill(usage.cost.value)
+
+// after — a sum stitchkit performed says so
+if (usage.cost && usage.cost.provenance !== 'unavailable') bill(usage.cost.value)
+```
+
+`'computed'` means stitchkit added up provider-reported parts. It is not a guess
+— `'estimated'` is the word for that — but it is deliberately not
+`'provider-reported'`, because that label is what a caller filters on when it
+wants a figure it can bill against unchanged, and a sum is not one.
+
+Token totals moved with it. The AI SDK's `totalUsage` is a sum *it* performed
+over per-step provider figures — not a run total any provider handed over — so
+labelling it `provider-reported` was the same overstatement. **A run total on a
+terminal event is always `computed`.** If you want a figure with the provider's
+own word on it, read `step-finished`: each step carries what that call reported.
+
+#### `usage` is always present on a terminal event
+
+```ts
+// before — absent when the run ended before the provider's `finish`
+const spent = event.usage?.cost?.value ?? 0        // silently 0 for a real spend
+
+// after — present, and it says what it does not know
+event.usage?.cost?.provenance === 'unavailable'    // we spent, and cannot say how much
+```
+
+Keep the optional chaining: one `AgentRunEvent` shape covers `run-started`,
+`step-finished` and `run-terminal`, so `usage` stays optional on the type. The
+guarantee is about terminal events, and a schema shared with `run-started`
+cannot express it.
+
+**Do not read `unavailable` as zero.** A run aborted mid-stream has spent real
+money that nobody has counted; a run that never reached the provider has not.
+Both used to look the same and now do not.
+
+#### A losing executor reports its own spend
+
+An execution that loses the terminal compare-and-swap now emits an operator
+`run-terminal` event, because it ran and it spent. If a sink treated those events
+as "runs this process committed", that is no longer true — `AgentRuntimeResult.metrics`
+is still `undefined` for a losing executor and remains the way to tell.
+
+The *delivery* `terminal` event is unchanged and still fires only for the winner,
+so nothing delivers a turn twice.
+
+### An interrupted answer stops passing as a finished one
+
+Two behaviour changes, one shared cause: a run ended by a newer input used to
+leave its half-written answer in the conversation with no sign that it was cut
+off, and the next request to the provider carried it as an ordinary assistant
+turn.
+
+#### The projection marks an interrupted turn
+
+Nothing to change to adopt the fix — the default is the fixed behaviour. What to
+check is whether the marker is the *right* form for your surface, and the
+question that decides it is not "was the run interrupted" but **"did anyone see
+what it produced"**.
+
+```ts
+// after — pick the form; the default is 'assistant-marked'
+createAgentRuntime({ history: { interruptedAssistant: 'system-note' } })
+```
+
+- **The user pressed stop and the text was on their screen** — keep
+  `'assistant-marked'`. The assistant turn is the truthful record of what the
+  human read, and the model should stay consistent with it.
+- **The partial never reached anyone** — a surface that sends nothing until the
+  run is done — prefer `'system-note'`. An assistant turn in provider history is
+  a commitment the model stays consistent with; a system line is context.
+
+If you pass `history.project` you own the projection outright and none of this
+applies — but the same question does.
+
+#### A run ended by a newer input can now say so
+
+```ts
+// before
+runs: { inputPolicy: 'interrupt' }   // ends the run, keeps its partial answer
+
+// after — for a surface where a follow-up message invalidates the answer
+// in flight rather than merely stopping it
+runs: { inputPolicy: 'supersede' }   // ends the run, discards its partial answer
+```
+
+`inputPolicy` also accepts `(input) => policy`, which is how one application
+gives two conversation surfaces different rules without the runtime learning
+which is which.
+
+A superseded run terminates with `terminalReason: 'superseded'`, state
+`'superseded'` and an assistant message of status `'superseded'`. **If you switch
+exhaustively on any of those enums, add the arm** — that is the part of this
+release that can break a build rather than a behaviour. The record itself is
+kept: it is excluded from the projection, not deleted, so an operator can still
+see what was thrown away.
+
 ## Released migration: 0.61.0
 
 Three behaviour changes between versions. None moves an export — the surface is