stitchkit 0.68.11 → 0.70.0

package/llms-full.txt

@@ -59,12 +59,15 @@ own, recorded as an ADR.
 | `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 9 of the 13 minors since 0.56.2, most recently 0.66.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `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/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 |
 | `stitchkit/agent-runtime/browser` | browser + server | evolving | canonical agent records, events and reconnect cursor without execution or sinks |
 | `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/application` | server | evolving<br>_redefined in 3 of the 13 minors since 0.56.2, most recently 0.67.0_ | managed resource graph, readiness, admission, schedules and bounded shutdown |
+| `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/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 
@@ -166,6 +169,8 @@ map — feature → packages:
 | In-process contract tools (`stitchkit/tools/invoker`) | — |
 | MCP / agent adapters (`stitchkit/tools`) | `@modelcontextprotocol/server` `ai` |
 | Agent application runtime (`stitchkit/agent-runtime`) | `ai` |
+| Headless Agent harness (`stitchkit/agent-runtime/harness`) | `ai` |
+| Agent coding tools (`stitchkit/agent-runtime/coding-tools`) | — |
 | OpenRouter runtime adapter (`stitchkit/agent-runtime/openrouter`) | `ai` `@openrouter/ai-sdk-provider` |
 | SQLite agent store (`stitchkit/agent-runtime/sqlite/bun` or `/node`) | — (runtime built-in) |
 | MCP host/client tests | `@modelcontextprotocol/client` |
@@ -213,6 +218,17 @@ For a complete production-shaped app, run `bun create stitchkit my-app`. The
 canonical generated topology is maintained in
 [`packages/create-stitchkit/template`](../../packages/create-stitchkit/template).
 
+For a terminal Agent host instead, run
+`bun create stitchkit my-agent --template agent`, copy `.env.example` to `.env`,
+set `OPENROUTER_API_KEY`, then run `bun run dev` and choose a live tool-capable
+model with `/model`. The provider catalog owns the exact model id and context window and presents
+weekly popularity separately from sourced benchmark observations; `OPENROUTER_MODEL` is only an
+optional preferred row. That profile is a thin `stitchkit.agent.ts` composition over the official
+`stitchkit-tui` package and canonical headless harness:
+durable SQLite history, lazy skills, direct coding tools, approval continuations
+and recovery stay framework-owned primitives, while model choice, permissions,
+executables and OS isolation remain application policy.
+
 
 ==============================================================================
 # Guide: Contracts  (docs/guide/contracts.md)
@@ -3991,33 +4007,97 @@ provider-reported input usage and cost to decide whether the extra search round
 is beneficial. Controller evidence intentionally omits query text, prompts,
 arguments and application context. → ADR 0129.
 
-### Executable headless harness and capability map
+### Published headless harness and structured runner
+
+`stitchkit/agent-runtime/harness` publishes the resource-aware composition over
+`createAgentRuntime`. `createHeadlessAgentHarness` accepts the existing protocol and store,
+caller-provided model resolution, bounded instruction/skill/resource loading, direct tools and a
+prompt-budget callback. Resource names are unique; count, UTF-8 bytes and diagnostics are bounded.
+Invalid resources fail before a provider request. Diagnostics are evidence for the caller: their
+observer is isolated, and the loader decides whether a reported condition is fatal.
+
+`createAgentHarnessFileResources` is the optional filesystem implementation. It reads only
+caller-declared absolute roots, refuses symlinks and reports provenance as
+`rootId:relative/path`. Instructions enter the prompt immediately. Skills and ordinary resources
+enter as bounded name/description summaries; `read_resource` loads one exact body later as
+a normal direct typed tool. Custom loaders remain supported unchanged.
 
-[`packages/core/examples/headless-agent-harness.ts`](../../packages/core/examples/headless-agent-harness.ts)
-is the complete resource-aware recipe. It accepts injected protocol, model,
-tool and store ports, validates resources plus diagnostics, carries provenance
-into the prompt and delegates execution to `createAgentRuntime`. Importing the
-example starts no process, opens no database and discovers no filesystem path.
+Each run may resolve a different provider adapter without changing the harness. The
+`profile-applied` observation records the actual `AgentModelDescriptor`, resource kind/name/
+provenance and sorted direct tool names; it intentionally contains no resource text, prompts,
+arguments or credentials. Observer failure never changes the canonical run outcome.
+
+[`packages/core/examples/headless-agent-runner.ts`](../../packages/core/examples/headless-agent-runner.ts)
+is a reference structured control loop for `submit`, `interrupt`, `snapshot` and bounded `close`.
+It starts no process and chooses no framing, authentication or transport. Importing either example
+has no side effect; an external supervisor owns process placement and restart.
 
 | Concern | Public Stitchkit composition | Boundary |
 | --- | --- | --- |
 | execution loop | `createAgentRuntime` | already available; do not copy a second loop |
 | model choice | `defineModelRegistry` and `models.resolve` | provider credentials/discovery stay application-owned |
-| resources | injected loader → `composeAgentPrompt` sections | paths, trust, precedence and watching stay application-owned |
+| resources | `createHeadlessAgentHarness` → `composeAgentPrompt` | paths, trust, precedence and watching stay application-owned |
 | tools | `mountAgent` + `createAgentToolFenceLifecycle` | auth and domain effects stay application-owned |
 | follow-up | `runs.inputPolicy: 'queue'` | durable FIFO after the current run |
 | interrupt | `interrupt` or `interrupt-next` | `interrupt-next` terminates the active run and gives the new durable admission next priority |
 | recovery | `runtime.recover` + `scanRecoverable` | replay safety and context reconstruction are explicit callbacks |
-| reconnect | canonical snapshot + `advanceAgentRuntimeEventCursor` | transient deltas are replaceable; durable event IDs deduplicate |
+| reconnect | canonical snapshot + `advanceAgentMultiSessionCursor` | conversation/run-scoped gaps require resync |
 | persistence | memory reference, public driver, or SQLite leaf | product rows/outbox remain outside the runtime store |
-
-Pi's steering queue waits for the current tool calls and injects the steering
-message at its next loop boundary. It is therefore not an alias for
-`interrupt-next`: Stitchkit requests termination of the active durable run,
-waits for its terminal settlement, and executes the prioritized successor.
-Pi follow-up is closest to Stitchkit `queue`, while JSONL trees, branching,
-workspace discovery, permissions and terminal UI remain embedding-application
-features rather than runtime requirements.
+| executable lifecycle | structured runner example | framing, auth, process placement, restart and OS isolation stay host-owned |
+
+`createAgentHarnessControlServer` adds transport-neutral correlated requests, shared observers and
+one exclusive controller lease per conversation. `close()` on a connection detaches only that
+client; it never closes the harness. Normal `event` delivery stays serialized. A bounded slow
+consumer is detached and receives `resync-required` through the required synchronous
+`onOverflow` callback; that callback closes/aborts the underlying transport, which then reconnects
+and requests a fresh snapshot. It never writes a second frame concurrently with a blocked
+`deliver`. Browser code uses `createAgentControlView`,
+`reduceAgentControlSnapshot` and `reduceAgentControlEvent`; the reducer owns no renderer and marks a
+conversation `resyncRequired` after a transient sequence gap.
+
+Configure `loop.toolApproval` to use the installed AI SDK approval policy and
+`loop.toolApprovalSecret` to sign exact requests. A request is stored on the terminal assistant
+before any effect. `pendingApprovals()` derives unresolved requests from canonical messages;
+`respondToApproval()` writes one tool-role approval response and queues a successor. The SDK
+revalidates the signature/tool call/input before the original direct tool reaches its existing
+fence. Reconnect and SQLite reopen require no promise registry. Remembered policy and a stronger
+cross-crash exactly-once guarantee remain application concerns.
+
+`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
+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;
+writes and patches revalidate the pinned parent identity; search and resource discovery descend
+only through opened directories. Linux uses `/proc/self/fd`; macOS and FreeBSD use `/dev/fd`.
+Other platforms fail these filesystem operations closed because Node exposes no equivalent
+portable directory-handle-relative API. Writes/edits reject symlink targets, content is strict
+UTF-8 and retained bytes are finite. Shell accepts a finite alias mapped by the host to an absolute executable plus an
+argument array — never a shell command string — and uses only the explicitly supplied environment.
+Arguments, output and time are bounded, while cancellation terminates the child. The configured
+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
+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.
+
+`run_command` treats every invocation as finite. `shellTimeoutMs` bounds normal execution and
+`shellTerminationGraceMs` bounds settlement after timeout, caller cancellation, output overflow or
+parent exit. POSIX hosts launch a dedicated process group and kill every descendant remaining in
+that group; a process that deliberately escapes the group is outside the guarantee. Node's
+portable Windows child-process API cannot kill a complete descendant tree without invoking a
+second host executable, so Windows kills the direct child, destroys retained pipes at the grace
+deadline and makes no descendant-cleanup claim. A signal already aborted before execution returns
+`cancelled` without spawning.
+
+One `createAgentHarnessFileResources` instance represents one immutable discovery generation:
+concurrent and repeated `load()` calls share it, so a direct resource read cannot cross into a
+new catalog unexpectedly. Discovery uses the same descriptor-anchored traversal as coding search;
+construct a new loader to refresh after filesystem changes.
 
 Runtime events preserve reasoning/text/tool lifecycle order. Durable admission,
 checkpoint, run-state and terminal events carry stable identities; transient
@@ -4444,7 +4524,9 @@ or silently accept an unknown future version.
 - `assistant-checkpoint` follows a successful checkpoint CAS;
 - `run-state` follows durable queue/acquire/interrupt transitions;
 - `tool-status` is transient lifecycle presentation with JSON-safe input on
-  start and output on completion; internal tool failures remain generic;
+  start and output on completion. A mounted typed failure carries the same safe
+  `{ error, details?, _hint? }` envelope as the durable result; an unknown
+  internal cause remains generic and stays in local observability only;
 - `terminal` follows the winning terminal CAS.
 
 These are post-commit notifications, not a transactional outbox: a process can
@@ -4560,6 +4642,14 @@ before a managed side effect and again before accepting its result. Fence loss
 uses an internal control signal: it stops the old loop and is not sent to the
 model as a tool error.
 
+`mountAgent` sends failed runner outcomes through the AI SDK's tool-error
+channel. AgentRuntime persists them with `outcome: 'error'`, publishes the same
+safe envelope, and replays them as an error result on later turns. Classification
+comes from the execution channel, never from inspecting output fields: a valid
+successful result such as `{ error: 'domain value' }` remains successful. Typed
+`AppError` codes and safe details may reach the model; arbitrary thrown causes
+are retained for local hooks and reduced to `INTERNAL_SERVER_ERROR` outside.
+
 The framework cannot undo an already-started non-cooperative external effect.
 Pass the stable call/run idempotency identity into business mutations when the
 effect must be replay-safe.
@@ -5163,6 +5253,54 @@ replenishes once; it is flow-control credit, not a durable acknowledgement. The
 application snapshot sink now shares the same latest-value mechanics without
 changing its revision or status contract. → ADR 0119.
 
+### Bounded local diagnostic journal
+
+Use `createDiagnosticJournal` when a process needs finite, ordered local metadata evidence and the
+deployment log pipeline is not the right boundary:
+
+```ts
+import { createDiagnosticJournal } from 'stitchkit/application'
+import { z } from 'zod'
+
+const journal = await createDiagnosticJournal({
+  eventSchema: z.object({
+    kind: z.enum(['resource_failed', 'recovery_started']),
+    resource: z.string().max(80),
+  }).strict(),
+  path: '/var/lib/example/diagnostic.jsonl', // operator configuration, never request data
+  limits: {
+    maxEventBytes: 4 * 1024,
+    maxPendingItems: 128,
+    maxPendingBytes: 512 * 1024,
+    maxFileBytes: 8 * 1024 * 1024,
+    maxFiles: 4,
+  },
+  onFailure: (failure) => internalLogger.error(failure),
+})
+
+const result = journal.submit({ kind: 'recovery_started', resource: 'database' })
+if (result.outcome === 'refused') internalCounter.add(1, { reason: result.reason })
+
+// During managed-resource close. Timeout ends this wait, not the physical append.
+await journal.close({ timeoutMs: 5_000 })
+```
+
+The owner schema and JSON serialization run synchronously before admission. Accepted frames carry
+a process epoch and contiguous sequence and retain their complete bytes inside both pending limits
+until their append attempt settles. Capacity, invalid, oversized, closed and terminal-failure
+refusals are explicit; accepted ordered frames are never evicted.
+
+The absolute path's parent must already exist and be operator-controlled. One manager owns it via
+an exclusive `.lock`; new files use mode `0600` by default. `maxFiles` includes the active file,
+and a non-newline startup tail is rotated intact rather than guessed or repaired. An abrupt process
+death may leave the lock for an operator to remove only after proving the former owner is gone.
+
+`flush()` means every accepted append through that call's boundary settled. It is not `fsync`, a
+durable receipt, exactly-once execution or remote delivery. Timeout/cancellation bound only the
+waiter; the writer retains physical capacity until settlement. There is no reader or upload API.
+Use a durable application store or deployment-owned log collector when restart recovery, replay or
+aggregation is required. → [ADR 0134](../decisions/0134-diagnostic-journal-is-bounded-local-evidence.md).
+
 Shutdown performs one phase barrier at a time: stop admission everywhere,
 cancel future schedules, drain admitted work, then close in reverse stable
 topological order. Every hook shares the same grace deadline. Forced cleanup
@@ -6197,7 +6335,10 @@ from the contract and validated on both sides:
 const result = await socket.request(
   'room:join',
   'general',
-  { timeoutMs: 5_000 },
+  {
+    timeoutMs: 5_000,
+    onPhase: (phase) => roomJoinMetrics.record(phase),
+  },
 )
 // result: { joined: boolean }
 ```
@@ -6242,6 +6383,22 @@ closed phase:
 | `timeout` | the existing native acknowledgement timeout won |
 | `disconnected` | the request began disconnected or an in-flight disconnect won |
 
+When a caller needs to join those phases to its own invocation, put `onPhase`
+on that request's options and keep the caller identity in the hook's closure:
+
+```ts
+await socket.request('room:join', 'general', {
+  timeoutMs: 5_000,
+  onPhase: (phase) => recordPhase({ operationId, phase }),
+})
+```
+
+The client-wide hook receives every observed request; a request hook receives
+only its invocation. If the same function is supplied in both places it runs
+once per phase. The closure is local: Stitchkit does not retain `operationId`,
+add it to the event or transmit it to the peer. A request hook works without a
+client-wide hook, and the no-hook path installs no phase listeners.
+
 Engine handoff is not proof of a physical network write. Engine acknowledgement
 receipt is not a remote clock, end-to-end RTT or proof that application
 validation has run. The useful interval is local and monotonic:
@@ -6254,9 +6411,9 @@ with Socket.IO acknowledgement ids, but those ids are never exposed. A timeout
 or disconnect is terminal, a late packet cannot reopen the identity, and sync
 or async observer failures are ignored so telemetry cannot change request
 correctness. With no hook, no request identity, Engine.IO listener or correlation
-map entry is created. The low-level `createSocketIOClient` and non-owning
-`bindRealtimeClient` remain unchanged; this phase surface belongs to the
-canonical composed client that owns both transport and validation.
+map entry is created. The low-level `createSocketIOClient` implements the same
+request option, so a non-owning `bindRealtimeClient` over that transport keeps
+request-scoped observation without opening a second connection.
 
 ## Low-level transport
 
@@ -8737,6 +8894,62 @@ 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.70.0
+
+### Descriptor-backed Agent filesystem containment
+
+Built-in coding file/search tools and `createAgentHarnessFileResources` now require a runtime
+that can address an opened directory descriptor: Linux `/proc/self/fd`, or macOS/FreeBSD
+`/dev/fd`. This is what keeps a mutable parent rename or outside-symlink replacement from changing
+the authorized target between validation and the actual effect.
+
+No call-site change is needed on those platforms. On Windows or another platform without that
+boundary, move the built-in filesystem operations to a supported worker or replace them with
+application-owned tools backed by an equivalent native handle API. They fail closed rather than
+falling back to path spelling. `run_command` remains separately available under its explicit
+executable alias and authorization policy; this change does not claim an executable sandbox.
+
+## Released migration: 0.69.0
+
+### Direct coding-tool operation names
+
+`createAgentCodingTools` no longer prefixes durable operation identity with `coding_`, and the
+unguarded exact-string edit tool is gone. Update approval maps, presenters and tests together:
+
+```ts
+// before
+{ coding_read_file: 'approved', coding_search: 'approved', coding_patch_file: 'user-approval' }
+
+// after
+{ read_file: 'approved', search_files: 'approved', apply_patch: 'user-approval' }
+```
+
+The full mapping is `coding_read_file → read_file`, `coding_write_file → write_file`,
+`coding_search → search_files`, `coding_patch_file → apply_patch`, `coding_shell → run_command`,
+`coding_read_artifact → read_output` and `harness_read_resource → read_resource`. Replace
+`coding_edit_file` with `read_file` followed by guarded `apply_patch`; `read_file` now returns the
+required SHA-256. If the host declares no executable aliases, expect `run_command` to be absent.
+
+### Durable Agent approval message variants
+
+If a renderer, store adapter or export pipeline exhaustively switches over
+`AgentMessage.role`, add the `tool` branch. If it switches over
+`AgentMessagePart.type`, add `tool-approval-request` and `tool-approval-response`.
+They are durable provider-continuation evidence: preserve them in storage and provider history;
+a UI may render them as approval state or intentionally omit their visual row.
+
+```ts
+// before
+const unreachable: never = message.role
+
+// after
+if (message.role === 'tool') renderToolContinuation(message.parts)
+else renderExistingRole(message)
+```
+
+No data migration is needed. The schema still accepts all earlier records, and applications that
+do not exhaustively branch over these unions compile unchanged.
+
 ## Before you bump, if you implement an agent store
 
 One step, and it is mechanical. If your project has an `AgentRuntimeStore` — a
@@ -11298,10 +11511,10 @@ The browser-and-server entrypoint. Re-exports everything from
 | `RealtimeAcknowledgedEvent` | _type_ | event-name union restricted to definitions with an `ack` schema |
 | `RealtimeAcknowledgement` | _type_ | validated acknowledgement output inferred from an event definition |
 | `RealtimeRequestArguments` | _type_ | request arguments inferred from an acknowledged event tuple |
-| `RealtimeRequestOptions` | _type_ | finite positive native acknowledgement `timeoutMs` |
+| `RealtimeRequestOptions` | _type_ | finite positive native acknowledgement `timeoutMs` plus an optional invocation-scoped `onPhase` observer |
 | `RealtimeRequestPhaseSchema` / `RealtimeRequestPhase` | schema / _type_ | closed `engine-handoff` / `engine-ack-received` / `settled` / `timeout` / `disconnected` lifecycle |
 | `RealtimeRequestPhaseEventSchema` / `RealtimeRequestPhaseEvent` | schema / _type_ | strict metadata-only `{ requestId, event, phase, elapsedMs }` observation |
-| `RealtimeRequestPhaseHook` | _type_ | isolated sync/async observer accepted by `RealtimeClientOptions.onRequestPhase` |
+| `RealtimeRequestPhaseHook` | _type_ | isolated sync/async observer accepted globally by `RealtimeClientOptions.onRequestPhase` or per invocation by `RealtimeRequestOptions.onPhase` |
 | `RealtimeRequestTimeoutError` | class | stable `REALTIME_REQUEST_TIMEOUT` rejection |
 | `RealtimeRequestDisconnectedError` | class | stable `REALTIME_REQUEST_DISCONNECTED` rejection, including an immediate disconnected call |
 | `RealtimeRequestInvalidAcknowledgementError` | class | invalid ack was reported through `onRejected` and the request rejected |
@@ -11712,6 +11925,29 @@ cutovers are covered by the executable
 | `CreditWindow` / `CreditWindowSnapshot` / `CreditWindowSnapshotSchema` | _type_ / schema | byte-credit handle and absolute accounting record |
 | `CreditAcquireResult` / `CreditLease` | _type_ | reasoned refusal or idempotently releasable byte-credit lease |
 
+### Bounded diagnostic journal
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createDiagnosticJournal` | function | create one schema-owned FIFO JSONL writer with bounded retained memory, exclusive local path ownership and finite rotation |
+| `DiagnosticJournalConfig` / `DiagnosticJournal` | _type_ | owner schema/path/limits/failure observer and the synchronous `submit`, bounded-wait `flush`/`close`, status handle |
+| `DiagnosticJournalLimitsSchema` / `DiagnosticJournalLimits` | schema / _type_ | positive event, pending-item, pending-byte, file-byte and retained-file limits |
+| `DiagnosticJournalSubmitResultSchema` / `DiagnosticJournalSubmitResult` | schema / _type_ | accepted epoch/sequence or explicit invalid, oversized, capacity, closed or failed refusal |
+| `DiagnosticJournalStatusSchema` / `DiagnosticJournalStatus` | schema / _type_ | state, limits, exact admission/write/failure counters, pending ownership, rotations, partial tails and last safe sequences |
+| `DiagnosticJournalFrameSchema` / `DiagnosticJournalFrame` | schema / _type_ | version-1 JSONL frame carrying process epoch, contiguous accepted sequence and schema-validated JSON event |
+| `DiagnosticJournalWaitResultSchema` / `DiagnosticJournalWaitResult` | schema / _type_ | flush settlement boundary with truthful settled, timed-out or cancelled result |
+| `DiagnosticJournalCloseResultSchema` / `DiagnosticJournalCloseResult` | schema / _type_ | physical close or caller timeout/cancellation without pretending an active write stopped |
+| `DiagnosticJournalStateSchema` / `DiagnosticJournalState` | schema / _type_ | `open \| draining \| closed \| failed` |
+| `DiagnosticJournalRefusalReasonSchema` / `DiagnosticJournalRefusalReason` | schema / _type_ | `closed \| failed \| invalid \| oversized \| item-capacity \| byte-capacity` |
+| `DiagnosticJournalFailurePhaseSchema` / `DiagnosticJournalFailurePhase` | schema / _type_ | internal `write \| rotation \| close` failure phase exposed only to status and the isolated observer |
+| `DiagnosticJournalWaitOptions` / `DiagnosticJournalFailure` | _type_ | caller wait signal/timeout and isolated internal failure callback record |
+
+`accepted` is bounded in-memory admission and `written` is completed append, not `fsync` or durable
+delivery. The journal has no reader/replay/upload API. See the
+[guide](../guide/application-kernel.md#bounded-local-diagnostic-journal),
+[architecture](../architecture/diagnostic-journal.md) and [ADR
+0134](../decisions/0134-diagnostic-journal-is-bounded-local-evidence.md).
+
 ### Managed schedules
 
 | Export | Kind | Summary |
@@ -11823,6 +12059,21 @@ Server-only optional application runtime. See the
 | `createMemoryAgentRuntimeStore` | function | process-local reference adapter, not production durability |
 | `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 |
+| `AgentModelCatalogEntrySchema` / `AgentModelCatalogEntry` | schema / _type_ | one canonical provider model descriptor with optional price, popularity and metric evidence |
+| `AgentModelPriceSchema` / `AgentModelPrice` | schema / _type_ | normalized per-token input/output pricing and source currency |
+| `AgentModelPopularitySchema` / `AgentModelPopularity` | schema / _type_ | independently sourced ranked popularity observation with window and timestamp |
+| `AgentModelMetricSchema` / `AgentModelMetric` | schema / _type_ | independently sourced benchmark measurement with provenance and observation time |
+| `AgentModelCatalogProvider` | _type_ | abortable live catalog loader supplied by a provider adapter or application |
+| `AgentModelSearchInputSchema` / `AgentModelSearchInput` | schema / _type_ | bounded catalog text query and result ceiling |
+| `AgentModelSearchResultSchema` / `AgentModelSearchResult` | schema / _type_ | exact bounded catalog projection with total match count |
+| `searchAgentModelCatalog` | function | deterministic bounded search over a loaded canonical catalog |
+| `AgentModelSelectionSchema` / `AgentModelSelection` / `AgentModelSelectionStore` | schema / _type_ | durable per-conversation model choice; runtime resolvers receive run and snapshot to recover the model pinned to input metadata |
+| `createMemoryAgentModelSelectionStore` | function | process-local selection reference adapter |
+| `AgentConversationReader` | _type_ | optional bounded conversation-summary and message-history reader; not part of the required runtime store contract |
+| `AgentConversationSummarySchema` / `AgentConversationSummary` | schema / _type_ | bounded durable conversation list item with version, activity and preview |
+| `AgentConversationPageSchema` / `AgentConversationPage` | schema / _type_ | cursor-paged conversation summaries |
+| `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 |
 | `createAgentSessionCoordinator` | function | strict process-local queue/interrupt/supersede lifecycle |
@@ -11926,7 +12177,10 @@ History and context-budget exports are `projectAgentHistoryDetailed`,
 `AgentPromptBudget`, `AgentPromptSection`, `AgentPromptSectionContext`, `AgentTokenCount`,
 `AgentTokenCountSchema`, `ComposeAgentPromptOptions` and `ComposedAgentPrompt`. Whole-turn history
 selection never splits a tool chronology and reports why every canonical record was retained or
-removed.
+removed. `AgentHistoryEvidencePolicy` is the shared opt-in for marked failed-assistant evidence in
+projection, budgeting and structured compaction; `isAssistantHistoryEvidence` applies it. The
+compatibility default omits it. Approval message schemas are
+`AgentToolApprovalRequestPartSchema` and `AgentToolApprovalResponsePartSchema`.
 
 Model exports are `AgentLanguageModelProvider`, `AgentModelCapability`,
 `AgentModelCapabilitySchema`, `AgentModelDescriptor`,
@@ -11953,12 +12207,71 @@ Managed effects and operator telemetry additionally export `AgentToolFenceConfig
 may accompany checkpoint/terminal writes and tool context; internal causes are redacted unless an
 operator-only observability sink explicitly opts in.
 
+## `stitchkit/agent-runtime/harness`
+
+Server-only evolving facade over the canonical Agent runtime. It requires the optional `ai` peer
+and introduces no store, queue or model-provider implementation of its own.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createHeadlessAgentHarness` | function | compose one `createAgentRuntime` with caller-supplied model resolution, bounded resources, tools and prompt policy; adds canonical `snapshot` |
+| `HeadlessAgentHarness` / `HeadlessAgentHarnessConfig` | _type_ | runtime facade and injected ownership boundary |
+| `HeadlessAgentModelResolver` | _type_ | per-run preflight/resolve port returning the actual `AgentResolvedModel` |
+| `AgentHarnessResourceSchema` / `AgentHarnessResource` | schema / _type_ | strict instruction, skill or resource with name, text and provenance |
+| `AgentHarnessResourceKindSchema` / `AgentHarnessResourceKind` | schema / _type_ | closed `instruction`, `skill` or `resource` vocabulary |
+| `AgentHarnessResourceResult` | _type_ | one loader result containing resources and diagnostics |
+| `AgentHarnessResourceDiagnosticSchema` / `AgentHarnessResourceDiagnostic` | schema / _type_ | bounded caller evidence; observer failure is isolated |
+| `AgentHarnessLimitsSchema` / `AgentHarnessLimits` | schema / _type_ | resource count, total UTF-8 bytes and diagnostic ceilings |
+| `AgentHarnessProfileEventSchema` / `AgentHarnessProfileEvent` | schema / _type_ | actual model descriptor, non-content resource provenance and sorted direct tool identities applied to one run |
+| `createAgentHarnessFileResources` | function | discover explicit instruction/skill/resource roots with symlink containment, bounded summaries and direct exact reads |
+| `AgentHarnessFileRootSchema` / `AgentHarnessFileRoot` | schema / _type_ | caller-owned absolute path, public root ID and resource kind |
+| `AgentHarnessFileLimitsSchema` / `AgentHarnessFileLimits` | schema / _type_ | file count, depth, per-file and aggregate byte ceilings |
+| `AgentHarnessFileResources` | _type_ | loader plus direct `read_resource` definition for lazy exact content |
+| `createAgentHarnessControlServer` | function | transport-neutral correlated requests, observer attachments and exclusive controller leases |
+| `AgentHarnessControlServer` / `AgentHarnessControlConnection` | _type_ | host server and detachable connection lifecycle; `deliver` is serialized, while required out-of-band `onOverflow` closes/aborts a slow transport before reconnect |
+| `AgentHarnessControlServerConfig` | _type_ | explicit per-connection pending-event bound for failure-isolated control delivery |
+| `AgentHarnessPendingApproval` / `AgentHarnessApprovalDecision` | _type_ | exact durable pending request and allow/deny successor input |
+
+Resources default to at most 64 entries, 1 MiB of total UTF-8 text and 128 diagnostics. Duplicate
+names and exceeded bounds fail before the provider step. Recovery remains the underlying runtime's
+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
+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 require Linux `/proc/self/fd` or macOS/FreeBSD `/dev/fd` descriptor paths and otherwise fail closed |
+| `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 |
+| `AgentCodingToolLimitsSchema` / `AgentCodingToolLimits` | schema / _type_ | explicit path/read/write/argument-count/argument-byte/output/artifact/timeout/termination-grace ceilings |
+| `AgentCodingArtifactStore` | _type_ | host-owned opaque artifact write and bounded read boundary |
+| `FileReadInputSchema` / `FileReadOutputSchema` | schema | bounded strict-UTF-8 byte slice; offsets must align with UTF-8 code-point boundaries |
+| `FileWriteInputSchema` / `FileWriteOutputSchema` | schema | create-only by default or explicit atomic replacement; symlink targets fail closed |
+| `createShellInputSchema` / `ShellOutputSchema` | schema | enumerated executable alias plus arguments and concrete relative cwd; explicit exited/timeout/output-limit/cancelled outcome |
+
+File/search operations pin directory descriptors across authorization and the actual effect;
+resource discovery uses the same ancestor-safe traversal. This closes parent rename/symlink races
+without claiming an executable sandbox. The default ceilings are 4,096 path bytes, 256 KiB read/write/output, 128 shell arguments, 64 KiB
+of aggregate argument text, 4 MiB per artifact and 30 seconds. The root is a path-resolution
+boundary, not an OS sandbox; executable behavior, process
+isolation, credentials and external-effect idempotency remain host responsibilities.
+
 ## `stitchkit/agent-runtime/browser`
 
 Browser-safe canonical agent data. It re-exports the run, message, part, usage,
 terminal and provider-envelope schemas/types listed under
 `stitchkit/agent-runtime`, together with all runtime delivery event schemas,
-`AgentRuntimeEventCursorSchema`, `advanceAgentRuntimeEventCursor` and
+`AgentRuntimeEventCursorSchema`, `advanceAgentRuntimeEventCursor`,
+`AgentControlRequestSchema` / `AgentControlRequest`, `AgentControlResponseSchema` /
+`AgentControlResponse`, `AgentControlDeliverySchema` / `AgentControlDelivery`, `AgentMultiSessionCursorSchema` /
+`AgentMultiSessionCursor`, `AgentConversationView`, `AgentControlView`,
+`advanceAgentMultiSessionCursor`, `createAgentControlView`, `reduceAgentControlSnapshot`,
+`reduceAgentControlEvent` and
 `agentDurableEventId`. It imports no model provider, executor, store, event sink
 or Node context module.
 
@@ -11972,7 +12285,9 @@ Use this entrypoint from client components and shared DTO packages. The full
 | Export | Kind | Summary |
 |--------|------|---------|
 | `openRouterProvider` | function | isolated `@openrouter/ai-sdk-provider` language-model factory |
+| `openRouterModelCatalog` | function | complete tool-capable text catalog plus independent weekly popularity and available benchmark observations |
 | `OpenRouterProviderSettings` | _type_ | official provider settings accepted by the factory |
+| `OpenRouterModelCatalogOptions` / `OpenRouterCatalogFetch` | _type_ | credential, timeout, clock and injected fetch boundary for catalog loading |
 
 ## `stitchkit/agent-runtime/sqlite/bun`
 
@@ -11981,13 +12296,55 @@ loaded by the neutral, browser or Node runtime surfaces.
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `createBunSqliteAgentRuntimeStore` | function | open an owned Bun SQLite connection, initialize/validate schema v1 and return `{ store, close }` |
+| `createBunSqliteAgentRuntimeStore` | function | open an owned Bun SQLite connection, initialize/validate schema v1 and return `{ store, conversations, close }` |
 | `BunSqliteAgentRuntimeStoreConfig` | _type_ | database filename plus optional create and initialization policies |
 | `createSqliteAgentRuntimeStore` | function | build the normalized store over an injected synchronous SQLite boundary |
 | `initializeAgentRuntimeSqlite` | function | initialize or validate only Stitchkit's namespaced SQLite schema |
 | `AgentRuntimeSqliteDatabase` / `AgentRuntimeSqliteStatement` / `AgentRuntimeSqliteValue` | _type_ | minimal runtime-neutral synchronous SQLite boundary |
 | `SqliteAgentRuntimeStore` / `SqliteAgentRuntimeStoreConfig` | _type_ | durable store handle, owned connection lifecycle and initialization policy |
 
+---
+
+## `stitchkit-tui`
+
+Separate optional evolving Bun/OpenTUI package over a caller-composed headless harness.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `defineAgentTui` | function | typed config for title/theme/status rows, model catalog, context, commands, runtime bundle and optional host-evidenced recovery policy; the default never requeues acquired effects |
+| `runAgentTui` | function | start one fresh durable conversation and terminal controller, recover durable work and publish its authenticated local session; `initialConversationId` is an explicit resume override |
+| `defineTuiCommand` / `resolveTuiCommand` | function | typed composable slash-command registry; unknown slash input remains an ordinary model prompt |
+| `createAgentTuiController` | function | single admission, selection, approval, interruption and conversation-switch owner over the harness |
+| `startAgentTuiSessionHost` / `createAgentTuiClient` | function | authenticated mode-`0600` Unix-socket host/client for status, submit and interrupt through that controller |
+| `listAgentTuiSessions` | function | discover live local terminal session IDs and their current conversation |
+| `createAgentTuiComposer` / `navigateAgentTuiHistory` | function | multiline draft and reversible prompt-history state |
+| `defaultAgentTuiStatusLine` / `AgentTuiStatusLineFormatter` | function / _type_ | terminal-native default rows and a host formatter over model capacity, durable snapshot, activity, workspace and local identities; `statusLine: false` hides the rows |
+| `createAgentTuiDiagnosticRecorder` / `AgentTuiDiagnosticEventSchema` | function / schema | bounded per-session metadata journal that rejects prompt, reasoning, tool-input and provider-cause payloads before disk admission |
+
+The `stitchkit-agent` binary loads `stitchkit.agent.ts` by default and also exposes `sessions`,
+`status`, `send` and `interrupt`. `--workspace` addresses a host outside the caller's cwd,
+`send --idempotency-key` accepts caller-owned retry identity, and `interrupt` defaults to the
+active run returned by `status`. Session descriptors and sockets are local control credentials,
+not a remote API.
+Interactive `/resume` and `/sessions` open the durable conversation picker. `/clear` creates a new
+conversation and keeps the previous one available there; it is not a viewport-only operation.
+The slash palette owns its highlighted selection: Up/Down move it, Tab completes it, Enter runs
+the exact command and Escape dismisses it. Partial input is never submitted while the palette is
+active; unknown slash text with no match remains an ordinary model prompt.
+
+### `stitchkit-tui/core`
+
+Renderer-neutral state only. This entrypoint imports neither React/OpenTUI nor the agent runtime.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createTerminalCollection` / `reduceTerminalCollection` | function | identity-stable live collection selection, reconciliation, windowing and resize |
+| `createTerminalFeedViewport` / `reduceTerminalFeedViewport` | function | generic follow-tail, history anchoring, unseen and bounded visible-range state |
+| `createTerminalPaneState` / `reduceTerminalPaneState` | function | bounded split-pane focus, resize and single-pane collapse |
+| `createTerminalCommandPalette` / `terminalCommandMatches` | function | bounded command filtering and keyboard selection over a collision-validated registry |
+| `resolveExactTerminalCommand` / `validateTerminalCommands` | function | exact dispatch and fail-closed name/alias validation |
+| `createTerminalOperationState` / `reduceTerminalOperationState` | function | confirmation and single-pending-operation lifecycle |
+
 ## `stitchkit/agent-runtime/sqlite/node`
 
 Node 22.5+ built-in SQLite persistence. It shares the schema and semantics of
@@ -12100,7 +12457,7 @@ payload.
 | `bindStdioProcessSignals` | function | explicitly bind OS signals to one close-only stdio handle — [guide](../guide/testing-and-deployment.md#stdio-process-signals) |
 | `buildMcpServer` | function | build an `McpServer` from contract/runtime surfaces; no-auth configs omit the second argument |
 | `mountMcp` | function | add contract tools to an existing `McpServer` — [guide](../guide/mcp-and-agents.md#mountmcp) |
-| `mountAgent` | function | a Vercel AI SDK `ToolSet` from a service — [guide](../guide/mcp-and-agents.md#ai-agents--mountagent) |
+| `mountAgent` | function | a Vercel AI SDK `ToolSet` from a service; failed executions reject through the SDK tool-error channel with a safe typed envelope, while successful output is never classified by field name — [guide](../guide/mcp-and-agents.md#ai-agents--mountagent) |
 | `defineRuntimeTool` | function | define one validated pathless operation for explicit MCP, Agent and/or CLI surfaces — [guide](../guide/mcp-and-agents.md#pathless-runtime-tools-and-multimodal-results) |
 | `createRuntimeToolFactory` | function | bind shared identity and Zod-validated per-call context for runtime tools — [guide](../guide/mcp-and-agents.md#pathless-runtime-tools-and-multimodal-results) |
 | `createToolInvoker` | function | compile an exposure-aware in-process dispatcher over the canonical tool runner; use peer-free `stitchkit/tools/invoker`, or the full `stitchkit/tools` adapter barrel — [guide](../guide/mcp-and-agents.md#in-process-calls--createtoolinvoker) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.68.11",
+  "version": "0.70.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",
@@ -84,6 +84,14 @@
       "types": "./dist/agent-runtime.d.ts",
       "import": "./dist/agent-runtime.js"
     },
+    "./agent-runtime/harness": {
+      "types": "./dist/agent-runtime-harness.d.ts",
+      "import": "./dist/agent-runtime-harness.js"
+    },
+    "./agent-runtime/coding-tools": {
+      "types": "./dist/agent-runtime-coding-tools.d.ts",
+      "import": "./dist/agent-runtime-coding-tools.js"
+    },
     "./agent-runtime/browser": {
       "types": "./dist/agent-runtime-browser.d.ts",
       "import": "./dist/agent-runtime-browser.js"
@@ -135,7 +143,7 @@
   "scripts": {
     "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-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 --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",