stitchkit 0.70.6 → 0.71.0

package/dist/telegram.js

@@ -0,0 +1,224 @@
+import {
+  isRecord
+} from "./index-qyrqwr4c.js";
+
+// src/telegram/init-data.ts
+import { z } from "zod";
+var TelegramInitDataUserSchema = z.object({
+  id: z.int(),
+  is_bot: z.boolean().optional(),
+  first_name: z.string(),
+  last_name: z.string().optional(),
+  username: z.string().optional(),
+  language_code: z.string().optional(),
+  is_premium: z.boolean().optional(),
+  allows_write_to_pm: z.boolean().optional(),
+  photo_url: z.string().optional()
+}).transform((user) => ({
+  id: user.id,
+  firstName: user.first_name,
+  ...user.is_bot !== undefined && { isBot: user.is_bot },
+  ...user.last_name !== undefined && { lastName: user.last_name },
+  ...user.username !== undefined && { username: user.username },
+  ...user.language_code !== undefined && { languageCode: user.language_code },
+  ...user.is_premium !== undefined && { isPremium: user.is_premium },
+  ...user.allows_write_to_pm !== undefined && { allowsWriteToPm: user.allows_write_to_pm },
+  ...user.photo_url !== undefined && { photoUrl: user.photo_url }
+}));
+var encoder = new TextEncoder;
+async function hmacSha256(key, message) {
+  const imported = await crypto.subtle.importKey("raw", key, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  return crypto.subtle.sign("HMAC", imported, encoder.encode(message));
+}
+function toHex(buffer) {
+  return Array.from(new Uint8Array(buffer), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function digestsEqual(a, b) {
+  if (a.length !== b.length)
+    return false;
+  let difference = 0;
+  for (let index = 0;index < a.length; index += 1) {
+    difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
+  }
+  return difference === 0;
+}
+function optionalUser(raw, key) {
+  const encoded = raw[key];
+  if (encoded === undefined)
+    return;
+  return TelegramInitDataUserSchema.parse(JSON.parse(encoded));
+}
+async function verifyTelegramInitData(options) {
+  if (!options.botToken)
+    throw new TypeError("botToken is required to verify initData");
+  if (options.maxAgeSeconds !== undefined && (!Number.isFinite(options.maxAgeSeconds) || options.maxAgeSeconds < 0)) {
+    throw new TypeError("maxAgeSeconds must be a non-negative finite number");
+  }
+  const params = new URLSearchParams(options.initData);
+  const hash = params.get("hash");
+  if (!hash)
+    return { valid: false, reason: "missing-hash" };
+  const signed = {};
+  for (const [key, value] of params) {
+    if (key === "hash")
+      continue;
+    signed[key] = value;
+  }
+  const dataCheckString = Object.keys(signed).sort().map((key) => `${key}=${signed[key]}`).join(`
+`);
+  const secretKey = await hmacSha256(encoder.encode("WebAppData"), options.botToken);
+  const expected = toHex(await hmacSha256(secretKey, dataCheckString));
+  if (!digestsEqual(expected, hash.toLowerCase())) {
+    return { valid: false, reason: "signature-mismatch" };
+  }
+  const authDateSeconds = Number(signed.auth_date);
+  if (!Number.isSafeInteger(authDateSeconds) || authDateSeconds <= 0) {
+    return { valid: false, reason: "malformed" };
+  }
+  const nowMs = options.now?.() ?? Date.now();
+  const ageSeconds = Math.floor(nowMs / 1000) - authDateSeconds;
+  if (options.maxAgeSeconds !== undefined && ageSeconds > options.maxAgeSeconds) {
+    return { valid: false, reason: "expired", ageSeconds };
+  }
+  let user;
+  let receiver;
+  try {
+    user = optionalUser(signed, "user");
+    receiver = optionalUser(signed, "receiver");
+  } catch {
+    return { valid: false, reason: "malformed" };
+  }
+  return {
+    valid: true,
+    data: {
+      ...user !== undefined && { user },
+      ...receiver !== undefined && { receiver },
+      authDate: new Date(authDateSeconds * 1000),
+      ageSeconds,
+      ...signed.query_id !== undefined && { queryId: signed.query_id },
+      ...signed.start_param !== undefined && { startParam: signed.start_param },
+      ...signed.chat_type !== undefined && { chatType: signed.chat_type },
+      ...signed.chat_instance !== undefined && { chatInstance: signed.chat_instance },
+      raw: Object.freeze({ ...signed })
+    }
+  };
+}
+// src/telegram/send-failure.ts
+var BY_DESCRIPTION = [
+  [/bot was blocked by the user|bot was kicked/i, "blocked-by-user"],
+  [/user is deactivated|account is deactivated/i, "user-deactivated"],
+  [/can'?t initiate conversation|need to start a conversation/i, "not-started"],
+  [/chat not found|peer_id_invalid|user not found/i, "chat-not-found"],
+  [/too many requests|retry later|flood/i, "rate-limited"],
+  [
+    /message is too long|can'?t parse entities|message text is empty|wrong file identifier|button_url_invalid/i,
+    "message-invalid"
+  ]
+];
+var RETRYABLE = new Set([
+  "rate-limited",
+  "server-error"
+]);
+var UNREACHABLE = new Set([
+  "blocked-by-user",
+  "user-deactivated",
+  "chat-not-found",
+  "not-started"
+]);
+function numberAt(value, keys) {
+  if (!isRecord(value))
+    return;
+  for (const key of keys) {
+    const candidate = value[key];
+    if (typeof candidate === "number" && Number.isFinite(candidate))
+      return candidate;
+  }
+  return;
+}
+function statusOf(value, depth = 0) {
+  if (!isRecord(value) || depth > 4)
+    return;
+  const direct = numberAt(value, ["error_code", "statusCode", "status"]);
+  if (direct !== undefined && direct >= 400 && direct < 600)
+    return direct;
+  const nested = value.cause ?? value.response ?? value.error;
+  return nested === value ? undefined : statusOf(nested, depth + 1);
+}
+function retryAfterOf(value, depth = 0) {
+  if (!isRecord(value) || depth > 4)
+    return;
+  const direct = numberAt(value.parameters, ["retry_after"]);
+  if (direct !== undefined)
+    return direct;
+  const nested = value.cause ?? value.response ?? value.error;
+  return nested === value ? undefined : retryAfterOf(nested, depth + 1);
+}
+function descriptionOf(value, depth = 0) {
+  if (typeof value === "string")
+    return value;
+  if (value instanceof Error) {
+    const nested2 = isRecord(value) ? descriptionOf(value.cause, depth + 1) : "";
+    return `${value.message} ${nested2}`.trim();
+  }
+  if (!isRecord(value) || depth > 4)
+    return "";
+  const own = typeof value.description === "string" ? value.description : "";
+  const message = typeof value.message === "string" ? value.message : "";
+  const nested = descriptionOf(value.cause ?? value.response ?? value.error, depth + 1);
+  return [own, message, nested].filter(Boolean).join(" ");
+}
+function classifyTelegramSendFailure(error) {
+  const status = statusOf(error);
+  const retryAfterSeconds = retryAfterOf(error);
+  const description = descriptionOf(error);
+  if (retryAfterSeconds !== undefined) {
+    return {
+      reason: "rate-limited",
+      ...status !== undefined && { status },
+      retryAfterSeconds,
+      retryable: true,
+      recipientUnreachable: false,
+      evidence: "parameters"
+    };
+  }
+  for (const [pattern, reason] of BY_DESCRIPTION) {
+    if (pattern.test(description)) {
+      return {
+        reason,
+        ...status !== undefined && { status },
+        retryable: RETRYABLE.has(reason),
+        recipientUnreachable: UNREACHABLE.has(reason),
+        evidence: "description"
+      };
+    }
+  }
+  if (status === 429) {
+    return {
+      reason: "rate-limited",
+      status,
+      retryable: true,
+      recipientUnreachable: false,
+      evidence: "status"
+    };
+  }
+  if (status !== undefined && status >= 500) {
+    return {
+      reason: "server-error",
+      status,
+      retryable: true,
+      recipientUnreachable: false,
+      evidence: "status"
+    };
+  }
+  return {
+    reason: "unknown",
+    ...status !== undefined && { status },
+    retryable: false,
+    recipientUnreachable: false,
+    evidence: "none"
+  };
+}
+export {
+  verifyTelegramInitData,
+  classifyTelegramSendFailure
+};

package/dist/tool-invoker.js

@@ -1,9 +1,9 @@
 import {
   createToolInvoker
-} from "./index-ekkt4gy9.js";
-import"./index-ejv31h14.js";
-import"./index-qm87g51s.js";
-import"./index-w9m1wznn.js";
+} from "./index-jqtsc9mj.js";
+import"./index-7qy2ex0m.js";
+import"./index-s4c8wy8m.js";
+import"./index-nemjkxjp.js";
 import"./index-22by16v6.js";
 import"./index-cby4ar3v.js";
 import"./index-nt1mp8km.js";

package/dist/tools.js

@@ -4,7 +4,7 @@ import {
 import {
   buildToolManifest,
   mountAgent
-} from "./index-trrf7nch.js";
+} from "./index-ezmn6ac6.js";
 import"./index-3xnq72rz.js";
 import {
   signJwt,
@@ -20,7 +20,7 @@ import {
 } from "./index-vbf2p6me.js";
 import {
   createToolInvoker
-} from "./index-ekkt4gy9.js";
+} from "./index-jqtsc9mj.js";
 import {
   WaitTimeoutError,
   createCli,
@@ -29,10 +29,10 @@ import {
   fetchPinnedDocument,
   readCapped,
   runWaitOperation
-} from "./index-tnazr5tc.js";
+} from "./index-pz7ytdga.js";
 import {
   collectToolSurface
-} from "./index-hxtm2xr2.js";
+} from "./index-k2zczx1g.js";
 import {
   createRuntimeToolFactory,
   defineRuntimeTool
@@ -41,19 +41,19 @@ import {
   collectTools,
   createToolRunner,
   formatToolError
-} from "./index-ejv31h14.js";
+} from "./index-7qy2ex0m.js";
 import {
   ToolExecutionControlError,
   coerceJsonArgs,
   executeToolMethod,
   isToolExecutionControlError,
   toolResultFromError
-} from "./index-qm87g51s.js";
+} from "./index-s4c8wy8m.js";
 import {
   getRequestContext,
   getTraceId,
   runWithRequestContext
-} from "./index-w9m1wznn.js";
+} from "./index-nemjkxjp.js";
 import {
   ManagedFileError
 } from "./index-bfcpjw20.js";

package/llms-full.txt

@@ -55,11 +55,12 @@ 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/observability` | server | stable | 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 store and managed-resource conformance kits |
 | `stitchkit/declaration` | build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser | stable | `createCursorQuery`, `createCacheBridge` |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 10 of the 15 minors since 0.56.2, most recently 0.69.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 10 of the 16 minors since 0.56.2, most recently 0.69.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
 | `stitchkit/agent-runtime/coding-tools` | server (Bun or Node) | evolving | bounded host-authorized direct file and shell tools; a root boundary, not an OS sandbox |
 | `stitchkit/agent-runtime/openrouter` | server | evolving | isolated OpenRouter language-model adapter |
@@ -67,7 +68,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` | server | evolving<br>_redefined in 3 of the 15 minors since 0.56.2, most recently 0.67.0_ | managed resource graph, readiness, admission, schedules and bounded shutdown |
+| `stitchkit/application` | server | evolving<br>_redefined in 3 of the 16 minors since 0.56.2, most recently 0.67.0_ | managed resource graph, readiness, admission, schedules and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 
@@ -180,6 +181,7 @@ map — feature → packages:
 | **Socket.IO server on Node** | `socket.io` |
 | Socket.IO client | `socket.io-client` (runtime peer; unrelated root declarations remain peer-free) |
 | grammY lifecycle adapters (`stitchkit/application/grammy`) | `grammy` |
+| Telegram platform primitives (`stitchkit/telegram`) | — (peer-free) |
 | OpenTelemetry gauges (`stitchkit/application/opentelemetry`) | `@opentelemetry/api` |
 
 ```bash
@@ -4101,7 +4103,8 @@ responses and results with a different call or tool name are invalid; dropping a
 approval input fails the run with a private diagnostic rather than starting a fresh model turn.
 
 `stitchkit/agent-runtime/coding-tools` returns ordinary direct runtime tools named `read_file`,
-`write_file`, `search_files`, `apply_patch`, `run_command` and optional `read_output`. Every call passes a
+`write_file`, `edit_file`, `list_directory`, `glob`, `search_files`, `run_command` and optional
+`read_output`. Every call passes a
 required host authorization callback. File paths are relative, bounded and contained after
 descriptor-relative resolution: each ancestor is opened without following symlinks and remains
 pinned through authorization and the filesystem effect. Reads revalidate the pinned file identity;
@@ -4117,10 +4120,32 @@ Arguments, output and time are bounded, while cancellation terminates the child.
 root and cwd are path boundaries, not a security sandbox: isolate the process when an executable
 must not access the rest of the machine.
 
-`apply_patch` binds the exact source to `baseSha256`, supports dry-run, authorizes the exact
-replacement count, result digest and byte size, then rechecks the base under a per-target lock
-before same-directory atomic replacement. It deliberately does not claim
-multi-file atomicity. With an optional `AgentCodingArtifactStore`, shell output beyond the inline
+`edit_file` replaces one exact snippet. `oldText` is itself the freshness guard for the region it
+changes, so the digest is the optional `expectedSha256` and an edit is one call; pass the digest
+`read_file` returned when you want the whole-file guarantee, and read the `sha256` it returns to
+chain the next edit without re-reading. The read, the occurrence count and the construction of the
+new content all happen inside one per-target lock, so two concurrent edits of different snippets in
+one file cannot each build a file from the same base and have the second erase the first — the lock
+is process-local, which covers many agents in one process and not two processes over one workspace.
+It authorizes the exact replacement count, result digest and byte size, and deliberately does not
+claim multi-file atomicity.
+
+`write_file` creates missing parent directories inside the root and names them in
+`createdDirectories`; the walk that finds them runs before authorization and reports them in the
+authorization payload, so no directory is created before a host approves it.
+
+**Every ordinary outcome is a refusal a model can act on** — a missing file is `NOT_FOUND`, an
+existing file without `overwrite` is `CONFLICT`, an ambiguous snippet is `CONFLICT` carrying its
+occurrence count, a path outside the root is `FORBIDDEN` — each with a `hint` naming the next move.
+Host-level causes stay scrubbed to `INTERNAL_SERVER_ERROR` and name nothing outside the workspace.
+→ ADR 0139
+
+`list_directory` marks excluded directories rather than hiding them, and `glob` reports
+`skippedDirectories` beside its matches: an empty result from a tree whose files all live under an
+excluded directory is not "no files", and a model told only "nothing found" concludes the wrong
+thing. `search_files` takes `regex`, `context` lines and an `include` pattern; regex is bounded by
+refusing backreferences and lookaround and capping line length rather than by a timeout, because a
+JavaScript `RegExp` cannot be interrupted once it starts backtracking. With an optional `AgentCodingArtifactStore`, shell output beyond the inline
 preview continues into an opaque bounded artifact and `read_output` reads slices without
 exposing a host path. Without a store, the previous finite output-limit behavior is unchanged.
 
@@ -4807,6 +4832,40 @@ replace a leading summary on the next compaction.
 Set `maxAttempts` to allow bounded conflict recovery. Every retry reloads the snapshot, reselects the
 eligible range and recomputes the summary; the stale summary is never retried.
 
+### Compacting without the store
+
+The *selection* inside compaction needs no store, no version and no runtime, so
+it is published on its own as `selectCompactableHistory` — for an application
+that drives the model itself and keeps its own history (→ ADR 0142):
+
+```ts
+import { selectCompactableHistory } from 'stitchkit/agent-runtime'
+
+const { leadingSummary, compactable, retained } = selectCompactableHistory({
+  messages,
+  keepRecentTurns: 3,
+})
+if (compactable.length > 0) {
+  const summary = await summarize(compactable, leadingSummary)
+  messages = [summary, ...retained]     // replace the old summary, never stack one
+}
+```
+
+`compactable` is the oldest **whole complete** turns and `retained` is
+everything the model must still hear; together they are the input, in order. A
+turn holding a tool call whose result never arrived is never eligible, and
+neither is anything after it: half a turn hands the provider a call with no
+result, which most of them refuse outright.
+
+`structuredCompaction` calls this same function, so the published selection and
+the runtime's cannot drift into two behaviours. What it adds is the part that
+does need the store — writing the result back under a version check.
+
+Deciding *when* to compact is yours: `AgentRuntimeRunContext.contextUsage`
+carries the last step's prompt size beside the model's window, and dividing them
+is one line where the threshold is decided. The core does not own that ratio, on
+purpose — see ADR 0142 for what it publishes and what it declines to.
+
 ## Observability
 
 `createAgentObservability` emits a separate operator-only `AgentRunEvent`. It
@@ -7445,6 +7504,68 @@ const payload = await verifyJwt(token, env.JWT_SECRET)
 `extractToken(req, cookieName?)` reads a bearer token from the `Authorization`
 header, or from the named cookie.
 
+## Telegram Mini Apps
+
+A Mini App hands its backend an `initData` query string that Telegram signed
+with a key derived from the bot token. `verifyTelegramInitData` checks that
+signature and reports what the string says — and refuses with a **reason**,
+because an application answers a stale string differently from a forged one.
+
+```ts
+import { verifyTelegramInitData } from 'stitchkit/telegram'
+import { unauthorized } from 'stitchkit/contract'
+import { env } from './env'
+
+const result = await verifyTelegramInitData({
+  initData,
+  botToken: env.BOT_TOKEN,
+  maxAgeSeconds: 3600,          // a signed string is otherwise valid forever
+})
+if (!result.valid) {
+  // 'missing-hash' | 'signature-mismatch' | 'malformed' | 'expired'
+  throw unauthorized(result.reason === 'expired' ? 'Reopen the app' : 'Invalid session')
+}
+const telegramId = result.data.user?.id
+```
+
+Three things it does that a hand-written check usually does not:
+
+- the **signature is checked first**, before `auth_date` or anything else is
+  read — an expiry inside an unverified payload is a number the sender chose;
+- digests are compared **without an early exit**, so the time a rejection takes
+  is not a measurement of how much of the digest was right;
+- `raw` keeps every signed pair, so a field Telegram adds after this release
+  does not need a release to reach.
+
+`maxAgeSeconds` is optional and there is no default: only the application knows
+how long its own session is worth. Omitting it means the string never expires,
+which is a decision rather than an oversight.
+
+The module is server-only and pulls in no bot library — the token never belongs
+in a browser bundle. `stitchkit/application/grammy` remains the lifecycle
+adapter for an injected grammY bot. Its companion,
+`classifyTelegramSendFailure`, names why a send was refused and separates *retry
+this send* from *stop addressing this recipient*:
+
+```ts
+import { classifyTelegramSendFailure } from 'stitchkit/telegram'
+
+try {
+  await bot.api.sendMessage(chatId, text)
+} catch (error) {
+  const failure = classifyTelegramSendFailure(error)
+  if (failure.recipientUnreachable) await markUnreachable(chatId, failure.reason)
+  else if (failure.retryable) await requeue(chatId, failure.retryAfterSeconds)
+}
+```
+
+The two flags are separate because one answer cannot serve both. A rate limit is
+retryable and implicates nobody; a blocked user is unreachable and no retry
+helps; a message Telegram could not parse is *neither* — the recipient is fine
+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.
+
 ## Cookies
 
 ```ts
@@ -9172,6 +9293,94 @@ additive** — adopting it changes nothing in your code. (See
 So upgrading is: read the `### ⚠️ Breaking changes` of every version *above* your
 current one *up to* your target, and apply each snippet.
 
+## Released migration: 0.71.0
+
+The Agent coding tools. Two of the three changes are visible to the compiler;
+the third is the one to read carefully, because nothing will point at it.
+
+### If you implement `authorize`
+
+The operation union gained `edit`, `list` and `glob` and lost `patch`. An
+exhaustive matcher stops compiling and the compiler shows you every arm. **A
+matcher with a default branch does not**, and that is the dangerous case:
+
+```ts
+// before — and after this upgrade, silently wrong in both directions
+if (request.operation === 'patch') return reviewPatch(request)
+return true            // now also authorizes edit, list and glob
+// …or: return false   // now also kills edit_file
+```
+
+```ts
+// after
+switch (request.operation) {
+  case 'edit':   return reviewEdit(request)   // the old `patch` payload, unchanged
+  case 'list':
+  case 'glob':   return true                  // or your own policy
+  // …existing read / write / search / shell / artifact-read arms
+}
+```
+
+`write` gained `createsDirectories` — the workspace-relative directories the
+call would create, outermost first, reported **before** anything is created. A
+host that wants to refuse implicit directory creation now can.
+
+### If you call `apply_patch`
+
+It is `edit_file`, and it is one call:
+
+```ts
+// before
+const read = await readFile({ path })
+await applyPatch({ path, baseSha256: read.sha256, oldText, newText, dryRun: true })
+await applyPatch({ path, baseSha256: read.sha256, oldText, newText, dryRun: false })
+
+// after
+await editFile({ path, oldText, newText })
+```
+
+`expectedSha256` is optional and still refuses a stale base with `CONFLICT` when
+you pass it; `edit_file` returns the resulting `sha256`, so a chain of edits
+never needs to re-read. If you key an approval policy or a UI label on the string
+`apply_patch`, update the key — nothing will fail loudly.
+
+### If you match on `INTERNAL_SERVER_ERROR` from a coding tool
+
+Ordinary outcomes no longer arrive that way. A missing file is `NOT_FOUND`, an
+existing file without `overwrite` is `CONFLICT`, an ambiguous snippet is
+`CONFLICT` with the occurrence count, a path outside the root is `FORBIDDEN`.
+Code that treated any coding-tool failure as an internal fault will now see
+codes it did not before; code that showed the model an empty error now has a
+sentence and a `hint` to show it. Host-level causes are unchanged and still
+scrubbed.
+
+### If you write files into new directories
+
+Nothing to change: `write_file` creates missing parents inside the root. Read
+`createdDirectories` in the result if you want to notice a typo — a path that
+was a failure before is now a successful write into a new tree.
+
+### If you want a step to know its context budget
+
+Opt in by reading it; nothing is injected for you:
+
+```ts
+loop: {
+  prepareStep: ({ contextUsage }) => {
+    const used = contextUsage?.usedTokens
+    if (used?.provenance === 'unavailable') return {}      // no step has landed yet
+    const fraction = (used?.value ?? 0) / (contextUsage?.contextWindow ?? 1)
+    // …render it wherever you put it
+    return {}
+  },
+}
+```
+
+Put it at the **tail** of the conversation rather than in the system
+instructions unless you have a reason: changing the system prompt on every step
+invalidates the provider's prefix cache for the whole conversation, and on a long
+run that is a multiple of the input cost.
+
 ## Released migration: 0.70.0
 
 ### Descriptor-backed Agent filesystem containment
@@ -12143,6 +12352,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `generateTraceId` | function | a fresh trace id |
 | `resolveTraceId` | function | the default per-request trace-id resolver |
 | `extractIp` | function | the caller IP from a request |
+| `isPublicIp` | function | whether an address belongs to the public internet; anything unparseable is not |
 | `resolveSocketIp` | function | the caller IP for a Socket.IO handshake (proxy-aware) |
 | `getClientInfo` | function | caller IP + user-agent |
 | `EventBus` | _type_ | the `createEventBus` handle |
@@ -12397,6 +12607,8 @@ Server-only optional application runtime. See the
 | `AgentConversationMessagePageSchema` / `AgentConversationMessagePage` | schema / _type_ | cursor-paged durable message history |
 | `composeAgentPrompt` | function | ordered prompt contributions and provenance-aware signed context budget; irreducible reservation deficits are `oversized`, not compactable history |
 | `structuredCompaction` | function | summarize a provider-valid snapshot range and replace it through CAS |
+| `selectCompactableHistory` | function | which oldest whole complete turns may be summarised away — the half of compaction that needs no store (→ ADR 0142) |
+| `SelectCompactableHistoryOptions` / `CompactableHistory` | _type_ | message list, retained-turn count and evidence policy in; `leadingSummary`, `compactable` and `retained` out |
 | `createAgentSessionCoordinator` | function | strict process-local queue/interrupt/supersede lifecycle |
 | `AgentRuntimeStopPolicy` | _type_ | named custom AI SDK stop condition persisted and published on policy stop |
 | `AgentRuntimePrepareStep` | _type_ | per-run controlled step callback with typed domain context and managed run signal/fence |
@@ -12425,6 +12637,29 @@ transport adapters validate the same records. Runtime composition types are `Age
 `AgentSessionCoordinator`, `AgentCompactionContext`, `AgentCompactionResult` and
 `StructuredCompactionConfig`.
 
+A provider refusal is classified rather than phrased. `classifyProviderFailure` returns an
+`AgentProviderFailure` — an `AgentProviderFailureReason` (`insufficient-credits`, `rate-limited`,
+`model-unavailable`, `context-overflow`, `timeout`, `cancelled`, `unknown`), the provider's `status`
+when it supplied one, whether the same request is `retryable` unchanged, and the `evidence` the
+answer rests on: `status` is the provider stating its own answer, `message` is us reading its prose,
+and `none` is an honest refusal to guess. The sentence a user reads stays with the application —
+its tone and its decision about what to admit are not the core's to make. `isToolResultFailure`
+recognises a failure carried inside a *successful* tool result, in both the bare and the
+`{ value: … }` envelope. Both are plain functions and need no runtime. → ADR 0141
+
+`normalizeOpenRouterUsage` is the same normalisation `openRouterProvider`
+applies, exported so an application calling the SDK directly gets provenance-correct numbers
+without adopting the runtime.
+
+`AgentContextUsage` reaches every step through `AgentRuntimeRunContext.contextUsage`: how full the
+model's context is, as `usedTokens` (an `AgentUsageValue`, so it carries the provenance that says
+where the number came from) beside the model's declared `contextWindow`. It is the **last completed
+step's prompt size**, not the run's cumulative input tokens — cumulative counts every step's prompt
+again and is a multiple of the real fill. Before the first step lands there is no provider-reported
+number and the provenance is `unavailable`, which is a different fact from zero. No fraction is
+exposed: dividing is one line where it is rendered, and the output reserve belongs to the
+consumer's prompt budget rather than to this layer.
+
 Canonical protocol exports are `AgentProtocol`, `AgentProtocolConfig`, `AgentTerminalAcceptance`,
 `AgentTerminalAcceptanceInput`, `hasAgentTerminalOutput`, `AgentRecordIdSchema`, `AgentRecordVersionSchema`,
 `AgentTimestampSchema`, `AgentJsonObjectSchema`, `AgentProviderEnvelopeSchema`,
@@ -12566,12 +12801,14 @@ explicit policy; use the Bun or Node SQLite leaf for durable reopen.
 ## `stitchkit/agent-runtime/coding-tools`
 
 Server-only evolving, peer-free direct runtime tools. `createAgentCodingTools(config)` returns
-`read_file`, `write_file`, `search_files`, `apply_patch`, optional `run_command` and, when an
+`read_file`, `write_file`, `edit_file`, `list_directory`, `glob`, `search_files`, optional
+`run_command` and, when an
 artifact store is supplied, `read_output`.
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `createAgentCodingTools` | function | construct direct host-authorized bounded file, search, guarded patch, shell and artifact runtime-tool definitions; filesystem operations use Linux `/proc/self/fd` or the packaged macOS Node-API backend and otherwise fail closed |
+| `createAgentCodingTools` | function | construct direct host-authorized bounded file, listing, glob, search, exact-snippet edit, shell and artifact runtime-tool definitions; every ordinary refusal is a typed code with an instructive `hint`, and filesystem operations use Linux `/proc/self/fd` or the packaged macOS Node-API backend and otherwise fail closed |
+| `AGENT_CODING_TOOL_NAMES` | const | the mounted tool names — `read_file`, `write_file`, `edit_file`, `list_directory`, `glob`, `search_files`, `run_command`, `read_output` |
 | `AgentCodingToolDefinition` | _type_ | peer-free structural direct-tool shape accepted by the canonical runtime-tool surface |
 | `AgentCodingToolConfig` | _type_ | absolute root, required authorization callback, finite executable alias map, exact child environment and optional limits |
 | `AgentCodingToolAuthorizationSchema` / `AgentCodingToolAuthorization` | schema / _type_ | discriminated read/write/search/patch/shell/artifact decision presented to host policy before effect |
@@ -13094,6 +13331,26 @@ available from `stitchkit/contract`.
 
 ---
 
+## `stitchkit/telegram`
+
+Peer-free server-only Telegram platform primitives. Importing this resolves no
+bot library; `stitchkit/application/grammy` remains the lifecycle adapter for an
+injected grammY bot. → ADR 0143
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `verifyTelegramInitData` | function | verify a Mini App `initData` signature against the bot token in constant time, before reading anything out of it |
+| `VerifyTelegramInitDataOptions` | _type_ | raw `initData`, bot token, optional `maxAgeSeconds` bound and injected clock |
+| `TelegramInitDataVerification` | _type_ | `{ valid: true, data }` or a refusal carrying its reason |
+| `TelegramInitData` | _type_ | verified `user`/`receiver`, `authDate`, `ageSeconds`, `queryId`, `startParam`, `chatType`, `chatInstance` and every signed pair in `raw` |
+| `TelegramInitDataUser` | _type_ | camelCase user record inferred from Telegram's signed `user` payload |
+| `TelegramInitDataRefusal` | _type_ | `missing-hash` / `signature-mismatch` / `malformed` / `expired` — an expired string is not a forged one |
+| `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` |
+
+---
+
 ## `stitchkit/declaration`
 
 Zod-only, dependency-free. The **project declaration**: the single