stitchkit 0.68.10 → 0.69.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 14 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 14 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,82 @@ 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
+realpath resolution; 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.
+
+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. 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
@@ -5163,6 +5228,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
@@ -6161,6 +6274,7 @@ const socket = createRealtimeClient(realtimeContract, {
   url: 'https://api.example.com',
   retain: ['note:created'],
   onRejected: (event) => reportClientError(event),
+  onRequestPhase: (event) => metrics.realtimeRequestPhase(event),
 })
 
 socket.connect()
@@ -6196,7 +6310,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 }
 ```
@@ -6215,6 +6332,64 @@ or resumable delivery should use separate correlated events or the async
 operation protocol; keeping one acknowledgement open is not a durable RPC/job
 transport.
 
+### Acknowledged-request phases
+
+`createRealtimeClient` can expose the local boundary that a single Promise
+normally hides:
+
+```ts
+const socket = createRealtimeClient(realtimeContract, {
+  url,
+  onRequestPhase: ({ requestId, event, phase, elapsedMs }) => {
+    requestPhaseHistogram.record(elapsedMs, { requestId, event, phase })
+  },
+})
+```
+
+The hook is opt-in and each record has exactly four metadata fields: an opaque,
+Kit-owned `requestId`, the contract event name, monotonic `elapsedMs`, and one
+closed phase:
+
+| Phase | Exact local boundary |
+|-------|----------------------|
+| `engine-handoff` | Engine.IO created the outbound message packet and accepted it into its write path |
+| `engine-ack-received` | Engine.IO decoded the inbound acknowledgement message, before Socket.IO invokes the acknowledgement callback |
+| `settled` | the acknowledgement callback ran and Stitchkit finished acknowledgement validation |
+| `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:
+`engine-ack-received → settled` isolates callback scheduling plus validation
+from transport waiting.
+
+Records never contain request arguments, acknowledgement values, raw packets,
+credentials, URLs or query data. Concurrent requests are correlated internally
+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` 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
 
 `createSocketIOClient` remains the low-level Socket.IO transport wrapper for
@@ -8694,6 +8869,47 @@ 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.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
@@ -11248,14 +11464,17 @@ The browser-and-server entrypoint. Re-exports everything from
 | `SocketIOClientConfig` | _type_ | config for `createSocketIOClient` (incl. `retain`, `onConnectError`, `onDroppedEmit`) |
 | `SocketEventMap` | _type_ | the shape of an event map |
 | `RealtimeClient` | _type_ | validated client inferred from a realtime contract |
-| `RealtimeClientOptions` | _type_ | transport options and the rejected-event hook for `createRealtimeClient` |
+| `RealtimeClientOptions` | _type_ | transport options plus rejected-event and metadata-only acknowledged-request phase hooks for `createRealtimeClient` |
 | `BoundRealtimeClient` | _type_ | validated non-owning `on`/`emit`/`request` client with no `connect`/`disconnect` |
 | `RealtimeClientTransport` | _type_ | minimal existing transport capability accepted by `bindRealtimeClient` |
 | `BindRealtimeClientOptions` | _type_ | rejection/logger options for a bound existing transport |
 | `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 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 |
@@ -11666,6 +11885,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 |
@@ -11777,6 +12019,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 |
@@ -11880,7 +12137,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`,
@@ -11907,12 +12167,69 @@ 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 |
+| `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 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 |
+
+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.
 
@@ -11926,7 +12243,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`
 
@@ -11935,13 +12254,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.68.10",
+  "version": "0.69.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",

package/dist/{index-pgsyp3xh.js → index-x18ndp4p.js}

@@ -1,9 +1,9 @@
-import {
-  isRecord
-} from "./index-qyrqwr4c.js";
 import {
   AppError
 } from "./index-0w9abg87.js";
+import {
+  isRecord
+} from "./index-qyrqwr4c.js";
 
 // src/contract/define.ts
 import { z } from "zod";