stitchkit 0.70.5 → 0.71.0

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.
 
@@ -4548,6 +4573,61 @@ boundary, validate with the exported schema, and write only the current
 version. Core deliberately does not guess an application's database migration
 or silently accept an unknown future version.
 
+### Purging a conversation
+
+```ts
+import { purgeAgentConversation } from 'stitchkit/agent-runtime';
+
+const result = await purgeAgentConversation(store, {
+  conversationId,
+  expectedVersion: snapshot.version, // optional stale-intent protection
+});
+```
+
+The optional `AgentRuntimeStore.purgeConversation` capability is implemented by the memory and
+initialized Bun/Node SQLite stores. The helper returns `unsupported` for stores without it; it
+never pretends deletion succeeded. Other outcomes are `purged`, `already_purged`,
+`active` (with `runIds`), or `conflict` (with `actualVersion`). Storage failures reject.
+
+Purge refuses queued, running and interrupt-requested runs. It does not interrupt, force-abandon
+or wait for a provider. Authorize the destructive request in the host, close its conversation
+ingress/attachments, then settle runs through normal interruption or explicitly justified recovery.
+Retry purge after they are terminal. An optional expected version must match the current snapshot;
+a version conflict requires a fresh deletion decision, not blind retry with a new version.
+
+Successful purge atomically removes messages (including compacted inactive rows), all runs and
+retained terminal assistants, admissions/idempotency receipts, conversation heads and their owned
+indexes. It retains only a permanent conversation-ID tombstone. Purging an unknown ID reserves it
+as well, so a submit paused before admission cannot create it later. Repeating the call returns
+`already_purged`, regardless of the original expected version. A lost response is safely retried
+with the same ID; **new chats require a new ID**.
+
+Every later runtime mutation rejects with `AgentConversationPurgedError`, including fresh and
+duplicate admissions, checkpoints, recovery and compaction. Existing controller leases grant no
+exception. Existing reads return empty snapshots, absent runs and empty message pages; purged
+conversations disappear from the SQLite catalog and recovery scans. Snapshots retain their
+existing empty `version: 0` shape; use the purge result, not an empty snapshot, as deletion evidence.
+
+SQLite commits the tombstone and all deletions in one `BEGIN IMMEDIATE` transaction. Failure before
+commit rolls everything back; reopen/recovery cannot restore committed deleted records. Same-thread
+connection contention rejects promptly without effects; retry after the competing operation settles.
+Initialization adds the tombstone table and write guards to schema v1 transactionally, without
+changing application tables or `user_version`. Guards also fence older writers. `initialize: false`
+on an original v1 database does not add purge capability; open an initialized writer first.
+
+Consumer-owned model selections, projections, attachment files, delivery/outbox records and event
+logs remain outside this boundary. Retain an authorized cleanup intent plus any needed opaque file
+references in consumer storage, purge first, then retry idempotent consumer cleanup. Invalidate local
+caches/subscriptions so an old delivered event cannot repopulate a UI. The library never traverses
+paths, revokes remote artifacts or claims a cross-store transaction. Nor does logical purge securely
+wipe database free pages, WAL or backups. Memory tombstones last only for that store instance.
+
+Custom normalized drivers may opt in through `AgentConversationPurgeDriver` on `driver.conversations`.
+Their transaction must serialize `isPurged`, head/active-run checks, `remove`, and **all** mutations
+for the same ID, including absent-ID admission. An optimistic head CAS alone is insufficient. `remove`
+must delete every owned payload/index and preserve the tombstone; errors must roll back the entire
+transaction. Drivers without this guarantee must leave the capability absent. See ADR 0138.
+
 ## Events and reconnect
 
 `publish` receives event classes with different guarantees:
@@ -4752,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
@@ -7390,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
@@ -9117,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
@@ -12088,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 |
@@ -12318,6 +12583,11 @@ Server-only optional application runtime. See the
 | `AgentHistoryMutationSchema` | schema | typed canonical message mutation applied inside the winning state transaction |
 | `RecoverAgentRunSchema` | schema | explicit abandon/requeue recovery decision; acquired runs require replay-safe evidence |
 | `createMemoryAgentRuntimeStore` | function | process-local reference adapter, not production durability |
+| `purgeAgentConversation` | function | dispatch optional atomic deletion; returns `unsupported`, `active`, `conflict`, `purged` or `already_purged` |
+| `AgentConversationPurgeInputSchema` / `AgentConversationPurgeInput` | schema / _type_ | conversation ID and optional expected snapshot version |
+| `AgentConversationPurgeResultSchema` / `AgentConversationPurgeResult` | schema / _type_ | typed deletion/refusal outcomes; active refusal includes run IDs |
+| `AgentConversationPurgedError` | class | runtime mutation rejected because its conversation ID is permanently purged |
+| `AgentConversationPurgeDriver` | _type_ | optional `driver.conversations` capability: serialized tombstone read and atomic removal of all owned records |
 | `projectAgentHistory` | function | asynchronously project canonical records and resolved multimodal files into provider-valid AI SDK messages |
 | `defineModelRegistry` | function | typed language-model descriptors, capabilities and provider construction |
 | `AgentModelCatalogSchema` / `AgentModelCatalog` | schema / _type_ | provider-neutral complete/partial model catalog with separately sourced popularity, metrics, prices and observation time |
@@ -12337,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 |
@@ -12365,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`,
@@ -12419,6 +12714,12 @@ neither grows with the length of the conversation, and neither needs anything ne
 conversation — that is what the store's reducer validates against, and what the runtime builds a
 prompt from (→ ADR 0112).
 
+`AgentRuntimeStore.purgeConversation` is optional; `purgeAgentConversation(store, input)` explicitly
+handles unsupported stores. Official memory and initialized SQLite stores refuse active runs,
+remove every owned payload and reserve the conversation ID permanently. Empty snapshots are not
+deletion receipts. Consumer metadata, files, event logs and UI cache invalidation remain outside
+the transaction. See [purging a conversation](../guide/agent-runtime.md#purging-a-conversation).
+
 Store command/result exports are `AcceptInputAndAssignRun`, `AcceptInputAndAssignRunSchema`,
 `AcquireAgentRun`, `AcquireAgentRunSchema`, `CheckpointRunAssistant`,
 `CheckpointRunAssistantSchema`, `CommitRunTerminal`, `CommitRunTerminalSchema`,
@@ -12500,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 |
@@ -13028,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.70.5",
+  "version": "0.71.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",
@@ -129,6 +129,10 @@
       "types": "./dist/files.d.ts",
       "import": "./dist/files.js"
     },
+    "./telegram": {
+      "types": "./dist/telegram.d.ts",
+      "import": "./dist/telegram.js"
+    },
     "./declaration": {
       "types": "./dist/declaration.d.ts",
       "import": "./dist/declaration.js"
@@ -145,7 +149,7 @@
     "build:native-contained-files": "node scripts/build-contained-files-native.mjs",
     "check": "bun x tsc --noEmit",
     "build:browser": "bun build src/index.ts src/react.ts src/contract/index.ts src/declaration.ts src/agent-runtime-browser.ts --outdir dist --target node --packages external --splitting --root src",
-    "build:server": "bun build src/server/index.ts src/node.ts src/tools.ts src/tool-invoker.ts src/cli.ts src/remote.ts src/files.ts src/testing.ts src/observability/index.ts src/agent-runtime.ts src/agent-runtime-harness.ts src/agent-runtime-coding-tools.ts src/agent-runtime-openrouter.ts src/agent-runtime-sqlite-bun.ts src/agent-runtime-sqlite-node.ts src/application.ts src/application-grammy.ts src/application-opentelemetry.ts --outdir dist --target node --packages external --splitting --root src",
+    "build:server": "bun build src/server/index.ts src/node.ts src/tools.ts src/tool-invoker.ts src/cli.ts src/remote.ts src/files.ts src/testing.ts src/observability/index.ts src/agent-runtime.ts src/agent-runtime-harness.ts src/agent-runtime-coding-tools.ts src/agent-runtime-openrouter.ts src/agent-runtime-sqlite-bun.ts src/agent-runtime-sqlite-node.ts src/application.ts src/application-grammy.ts src/application-opentelemetry.ts src/telegram.ts --outdir dist --target node --packages external --splitting --root src",
     "build:js": "bun run build:browser && bun run build:server && bun scripts/preserve-webpack-ignore.mjs",
     "build:types": "bun x tsc -p tsconfig.build.json --emitDeclarationOnly && bun scripts/rewrite-declaration-specifiers.mjs",
     "build": "rm -rf dist && bun run build:js && bun run build:types && bun scripts/check-browser-clean.mjs && bun scripts/check-env-live.mjs && bun scripts/check-public-types.mjs",