@arnilo/prism 0.0.10 → 0.0.12

package/docs/review-coverage-2026-07-22-phase-6.md

@@ -0,0 +1,209 @@
+# Review coverage — 2026-07-22 Phase 6
+
+Working evidence for Plan 074 Task 0. Freezes Phase 6 / Release **0.0.11** scope, primitive ownership, finite limits, threats, tests, docs, and release gates before implementation.
+
+**Evidence frozen:** 2026-07-22. **Prism source:** `a677113a409b1b60a3361a76c980e7411013916a` (post-0.0.10 / Task 0 freeze). **Release target:** 0.0.11. **Default test rule:** network-free fakes/fixtures; provider live canaries remain gated (`PRISM_LIVE_PROVIDER_TESTS=1` + host keys).
+
+## Status legend
+
+| Status | Meaning |
+| --- | --- |
+| `existing` | Current public contract covers the requirement. |
+| `extend` | Owning task extends an existing core/package contract. |
+| `new-package` | New optional workspace package behind existing provider-package seams. |
+| `compose` | Existing public primitives suffice; package-local glue / docs / examples only. |
+| `out-of-scope` | Coding-harness P2+ or later release; must not land in 0.0.11 tasks. |
+
+## Frozen product decision
+
+0.0.11 closes **coding-harness P1 fundamentals** only: bounded session search/index, assembler-time context budgets with omission reports, native Anthropic then Google provider packages, and a thin goal→verify coding helper/example.
+
+**Not in 0.0.11** (owned by later phases — do not implement here):
+
+| Deferred item | Owner phase |
+| --- | --- |
+| Additional subscription OAuth adapters | 0.0.12 Phase 7 |
+| AG-UI/ACP-facing event adapter | 0.0.12 Phase 7 |
+| Coding-aware compaction preset | 0.0.12 Phase 7 |
+| Enterprise identity / Azure·Bedrock·Vertex / work connectors | 0.0.13+ |
+| Always-on FTS reindex workers / indexer daemons | never in 0.0.11 |
+| Goal database / second agent or workflow runtime | never in 0.0.11 |
+| Shared core Anthropic Messages serializer extraction | defer until ≥2 byte-identical non-test consumers |
+| Soft-raising hard caps; unbounded full-store scans as default search | never in 0.0.11 |
+
+## Frozen external revisions
+
+| Surface | Frozen reference | Compatibility decision |
+| --- | --- | --- |
+| Prism | [`a677113a409b1b60a3361a76c980e7411013916a`](../plans/074-release-0-0-11-coding-harness-fundamentals.md) | Caller/limit claims checked against shipped 0.0.10 tree. |
+| Node.js | Local reference `v24.18.0`; release support remains Node 20 and current | Providers use `fetch` + existing `@arnilo/prism/providers/transport` SSE helpers; no vendor SDKs. |
+| Anthropic Messages | ctx7 `/anthropics/anthropic-sdk-typescript` + official Messages docs at impl time | Stream SSE, tools, `cache_control` ephemeral `5m`/`1h`, thinking blocks, usage; package-local wire (OpenCode Go route is pattern only). |
+| Google Gemini | ctx7 `/websites/ai_google_dev_gemini-api` + Gemini `generateContent` / stream docs at impl time | Tools/function calling, multimodal `inlineData`, usage metadata; Vertex enterprise identity stays 0.0.13. |
+| SQLite FTS5 / PostgreSQL FTS | Adapter docs at impl time | Dialect-local FTS; metadata filters shared shape. |
+
+## Frozen API and mode contract
+
+| Decision | Frozen choice |
+| --- | --- |
+| Search interface | `SessionIndex` with `search(query: SessionSearchQuery): Promise<PersistencePage<SessionSearchHit>>`. Optional on stores via `searchSessions?` **or** returned companion index — adapters implement one authoritative path; hosts must not need both. |
+| Query / hit types | `SessionSearchQuery`, `SessionSearchHit` in core (next to session/persistence contracts). |
+| Hit fields | Required: `sessionId`. Optional: `leafId` (branch tip for `checkout`), `updatedAt`, `label`, `summary`, `snippet`, safe display metadata. **Never** credentials, raw message bodies wholesale, or secret-looking payloads. |
+| Workspace filter | Host-written `metadata.workspaceRoot` (string path/key). No first-class `prism_sessions.workspace` column in 0.0.11. Query field name: `workspaceRoot`. |
+| Text / filters | Optional `query` (FTS/message+summary); `provider` / `model`; `label`/`summary` substring or FTS per adapter; `fromUpdatedAt`/`toUpdatedAt`; `OwnershipScope` (`tenantId`/`accountId`/`userId`). |
+| Pagination | Reuse `PersistencePage` + `limit`/`cursor`/`order`. |
+| Memory search | `createMemorySessionStore(entries?, options?)` with `sessionSearchMode: "linear" \| "unsupported"`; **default `"linear"`**. `"unsupported"` throws typed error (not empty success). JSONL: document unsupported unless a thin linear path is trivial — prefer explicit unsupported. |
+| Context budget | `contextBudget` on `AssembleProviderInputOptions` (and forward from `AgentConfig`/`RunOptions` only if needed). Shape: `{ maxInputTokens?: number; maxInputBytes?: number; reportOmissions?: boolean }`. At least one max required when budget object present. |
+| Eviction priority | Keep first: **system/AGENTS instructions → skills → context blocks → history/tool results** (drop from the end of that priority stack). Current user `input` and mandatory system prefix fail closed if they cannot fit. |
+| Omission report | Prefer non-breaking: `ProviderRequest.metadata.contextBudgetReport` + typed helper `getContextBudgetReport(request)`. Report ids/kinds/sizes/tokenEstimates — not secret values. Raw session store entries untouched. |
+| Token estimate | Finite heuristic: **UTF-16 code units / 4** (chars÷4) unless model supplies a cheaper local estimator later. Document as estimate, not billing. |
+| Anthropic package | `@arnilo/prism-provider-anthropic`; exports `createAnthropicProviderPackage`, `createAnthropicMessagesProvider`, `listAnthropicModels` (caller-gated). |
+| Google package | `@arnilo/prism-provider-google`; exports `createGoogleProviderPackage`, Gemini provider factory, `listGoogleModels` (caller-gated). |
+| Goal/verify | `runCodingGoalVerify` exported from `@arnilo/prism-coding-agent`; example `examples/coding-goal-verify.ts`. No Goal table. |
+| Package count | 0.0.10 graph **32** publishable packages → **34** after anthropic + google (**confirmed** at Task 13). |
+
+## Capability traceability matrix
+
+| Phase 6 roadmap criterion | Current 0.0.10 surface | Minimum 0.0.11 gap | Status / owner | Required proof | Docs | Release gate |
+| --- | --- | --- | --- | --- | --- | --- |
+| Bounded `SessionIndex` lists/filters by workspace, time, model/provider, label/summary, optional message FTS; hits return `sessionId` + optional `leafId` | `ProductionPersistenceStore.querySessions` metadata-only (`SessionQuery`); no text/FTS/workspace filters; `SessionStore` has no search | Core `SessionIndex` + query/hit types + optional store seam | `extend` / Task 1 | type/export smoke; invalid limit/query rejected; conformance empty/pagination/ownership | `public-contracts.md`, `session-stores.md` | offline + conformance |
+| SQLite + PostgreSQL implement search with finite pages | DDL has `metadata`, entry `label`/`summary`; no FTS objects | Migrations + adapter `search`; metadata filters + optional FTS | `extend` / Task 2 | pagination, label/summary/FTS hits, ownership isolation, resume via `leafId`, migration drift | `sqlite-persistence.md`, `postgres-persistence.md` | offline adapter tests |
+| Memory: linear fallback **or** explicit unsupported | `createMemorySessionStore(entries)` only; no options | Both modes; default linear; unsupported throws typed | `extend` / Task 3 | hit/miss/cap; unsupported ≠ empty | `session-stores.md` | offline |
+| Token/context budget + omission report; no raw history delete | `assembleProviderInput` / message groups; no budget | `contextBudget` + deterministic eviction + report | `extend` / Task 4 | eviction order; omission completeness; zero-budget fail; cache-aware prefix when under budget | `input-and-prompt-assembly.md` | offline |
+| Native Anthropic Messages package | OpenCode Go Anthropic **route** only; AI SDK escape hatch | New `@arnilo/prism-provider-anthropic` | `new-package` / Task 5 | offline conformance matrix + gated live | `providers/anthropic.md` | offline + opt-in live |
+| Native Google Gemini package | No first-party Google package | New `@arnilo/prism-provider-google` after Anthropic | `new-package` / Task 6 | same conformance bar; Vertex out of scope | `providers/google.md` | offline + opt-in live |
+| Thin goal→verify helper + example; no Goal DB / second runtime | `createCodingPlanMarkdown`, checks, `git_pr_handoff`, `suspend`/`resumeWorkflow`, `examples/durable-coding-workflow.ts` | `runCodingGoalVerify` + `examples/coding-goal-verify.ts` | `compose` / Task 7 | fail→suspend→approve→resume; bounded handoff; no secrets in plan state | `coding-agent-tools.md`, `agent-loops.md`, `workflows.md` | offline + example |
+| Performance: finite search/budget; network-free benches | `querySessions` default `limit ?? 100`; no search/budget benches | Caps below; `scripts/benchmark-0.0.11.mjs` | `extend` / Tasks 1–4, 9 | schema/bounds; search+budget benches | `performance.md` | benchmark + `sdk:ready` |
+| Code quality: optional seams; optional provider pkgs; helper composition | Provider package pattern; optional `readBranchPath` | Same pattern for search/budget; no core Anthropic extract | `compose` / Tasks 1–7 | ≥2-consumer rule for shared extract; package-local first | provider/session docs | pack/install |
+| Security: ownership on search; no creds in hits/omissions; late-bound provider creds | `OwnershipScope` on persistence queries; provider redaction | Enforce on search; redact snippets/reports | `extend` / Tasks 1–6 | ownership empty/forbidden; secret scan fixtures | session + provider docs | offline + audit |
+| Docs/migration 0.0.10 → 0.0.11 | Phase 5 docs | Update functional pages + two provider pages | `extend` / Task 8 | docs.test assertions | `migration.md`, index | docs tests |
+| Version/release 0.0.11 | Graph at `0.0.10` | Bump to `0.0.11`; umbrella deps; dry-run | `extend` / Task 9 (renumbered Task 13) **done** | `sdk:ready` + release dry-run | `release-and-install.md` | Task 9/13 gates |
+
+## Primitive and caller inventory
+
+Frozen at `a677113a409b1b60a3361a76c980e7411013916a` (+ this evidence page).
+
+| Primitive / symbol | Existing contract / callers | Phase 6 disposition |
+| --- | --- | --- |
+| `SessionStore` / `readBranchPath?` | Core; memory/JSONL omit path; sqlite/postgres implement | **Extend optional** with search seam (`searchSessions?` or companion `SessionIndex`). Do not require FTS on memory/JSONL. |
+| `ProductionPersistenceStore.querySessions` | Metadata listing; sqlite/postgres | **Keep** for admin listing. Search is separate (`SessionIndex.search`); do not overload `SessionQuery` as sole FTS surface. |
+| `SessionQuery` / `SessionRecord` / `OwnershipScope` / `PersistencePage` | Core contracts | Reuse ownership + page shape; add parallel search types. |
+| `prism_sessions.metadata`, entry `label`/`summary` | sqlite/postgres DDL | Reuse for workspace/label/summary filters; FTS tables adapter-local. |
+| `assembleProviderInput` / `createDefaultInputBuilder` / groups / `legacy`\|`cache_aware` | `src/input.ts` | **Extend** with `contextBudget` after groups built / before final request; no parallel assembler. |
+| `ProviderRequest.metadata` | Core | Host omission report via frozen metadata key + helper. |
+| Provider package setup (`defineProviderPackage`, conformance, transport SSE, media SSRF) | openai/kimi/opencode-go/… | Reuse. New anthropic/google packages follow same layout. |
+| `packages/provider-opencode-go/src/anthropic-messages.ts` | Vendor OpenCode route | **Pattern only.** No shared core extract in 0.0.11. |
+| Kimi Anthropic-compatible route | package-local | Unchanged; not a consumer of new anthropic package serializer. |
+| `createCodingPlanMarkdown` / checks / `git_pr_handoff` / coding-checkpoint limits | coding-agent | Reuse inside `runCodingGoalVerify`. |
+| `suspend` / `resumeWorkflow` | `@arnilo/prism-workflows` | Reuse; helper does not fork workflow engine. |
+| `examples/durable-coding-workflow.ts` | Example pattern | Pattern for `examples/coding-goal-verify.ts`. |
+| AI SDK provider package | Escape hatch | Remains escape hatch; not primary Anthropic/Google path. |
+
+### Primitive decision
+
+**Authorized new/extended core seams (minimal):**
+
+1. `SessionIndex` / `SessionSearchQuery` / `SessionSearchHit` + finite search-cap constants.
+2. Optional `SessionStore` search hook (or documented companion index from adapter factories).
+3. `contextBudget` on assemble options + `getContextBudgetReport` (+ estimate/apply helpers; may live in `src/context-budget.ts` re-exported).
+4. Memory store options: `sessionSearchMode`.
+
+**Authorized new packages:** `@arnilo/prism-provider-anthropic`, `@arnilo/prism-provider-google`.
+
+**Authorized package-local compose:** `runCodingGoalVerify` in coding-agent + example.
+
+**Rejected for 0.0.11:** Goal DB; second runtime; always-on indexer; `ToolDefinition.metadata`; core Anthropic shared serializer; Vertex/Bedrock/Azure enterprise adapters; raising hard caps; default unbounded full-store scan.
+
+Promote additional shared helpers to core only with ≥2 non-test consumers **and** migration/conformance evidence.
+
+## Frozen capability boundary
+
+| Surface | Supported in 0.0.11 | Explicitly unsupported |
+| --- | --- | --- |
+| Session search | Metadata filters + optional FTS; finite pages; memory linear (capped) or unsupported throw | Daemon indexer; silent empty on unsupported; credential fields on hits; first-class workspace column |
+| Context budget | Assembler eviction + omission report; heuristic estimate | Compaction/summarization as budget (0.0.12 preset); deleting store history; provider round-trip for count |
+| Anthropic | Native Messages HTTP package; tools/cache/thinking/media/usage/discovery | Subscription OAuth (0.0.12); official SDK dependency; env scan at import |
+| Google | Native Gemini HTTP package for coding-host semantics | Vertex enterprise identity (0.0.13); `@google/genai` runtime dep unless fetch proven impossible at impl (prefer fetch) |
+| Goal/verify | Thin coding-agent helper + network-free example | Goal table; second workflow/agent engine; auto-push/PR network |
+
+## Frozen finite limits and charging points
+
+**Rule:** Search and budget paths must validate caps in O(1) before scan/query. No always-on watchers. Do not raise hard caps in Tasks 1–9 without updating this page + tests + docs.
+
+### Session search (new — freeze defaults)
+
+| Resource | Default / hard cap | Charge/check point | Failure/cleanup owner |
+| --- | --- | --- | --- |
+| Page `limit` | 20 / 100 | Before query/scan | Task 1 validation; Task 2–3 adapters |
+| Query string bytes | 4 KiB / 16 KiB | Before parse/FTS | Task 1 |
+| Snippet bytes per hit | 512 / 4 KiB | Before hit assembly | Task 2–3 |
+| Cursor bytes | 1 KiB / 4 KiB | Before decode | Task 1–2 |
+| Memory linear: sessions scanned | 1,000 / 5,000 | During scan; abort on signal | Task 3 |
+| Memory linear: entries scanned | 10,000 / 50,000 | During scan | Task 3 |
+| Memory linear: bytes scanned | 8 MiB / 64 MiB | During scan (serialized entry text) | Task 3 |
+| DB FTS match candidates before page trim | adapter-local ≤ 1,000 / 5,000 | Before materializing snippets | Task 2 |
+
+**Forbidden:** default path that scans entire store with no limit; background reindex workers; retaining unbounded snippet corpora.
+
+Existing `querySessions` default `limit ?? 100` stays for admin listing; search defaults are tighter (20).
+
+### Context budget (new — freeze defaults)
+
+| Resource | Default / hard cap | Charge/check point | Owner |
+| --- | --- | --- | --- |
+| `maxInputTokens` when set | caller-required; hard max 2_000_000 | Before eviction | Task 4 |
+| `maxInputBytes` when set | caller-required; hard max 32 MiB | Before eviction | Task 4 |
+| Estimate cost | O(assembled messages); no network | During estimate | Task 4 |
+| Omission report entries | 256 / 1,024 | When `reportOmissions` | Task 4 |
+
+**Forbidden:** provider call for budgeting; mutating/deleting `SessionStore` entries from budget path.
+
+### Providers / coding helper (reuse existing)
+
+| Resource | Disposition |
+| --- | --- |
+| Stream/SSE/media/run limits | Reuse existing provider transport + run-limit ceilings (Tasks 5–6) |
+| Coding checkpoint / check / PR handoff bytes | Reuse `packages/coding-agent` `DEFAULT_*` / `HARD_*` (Task 7) |
+| Workflow suspend/resume | Existing workflow limits unchanged |
+
+## Threat and authority matrix
+
+| Boundary | Trusted authority | Untrusted input | Mandatory control | Default / unsupported |
+| --- | --- | --- | --- | --- |
+| Search ownership | Host passes `OwnershipScope` | Model-supplied tenant ids | Adapters filter tenant/account/user when present; mismatch → empty or typed forbidden per existing persistence norms | Cross-tenant search unsupported |
+| Search snippets | Adapter redaction-safe projection | Message/tool payloads | Snippet caps; never copy credential fields; prefer label/summary/FTS fragment | Raw full transcript as hit unsupported |
+| Budget omissions | Assembler metadata helper | Dropped block contents | Report kinds/ids/sizes only; redactor still applies to provider messages | Secret values in omission report unsupported |
+| Provider credentials | Host `CredentialValueSource` late-bound | Env/process ambient keys | No import/setup network or keychain scan; redact errors | Env auto-discovery unsupported |
+| Goal/verify approval | Host approval policy | Model “approved” claims | Fail closed without approval; suspend/resume via workflows | Implicit approve unsupported |
+| Provider headers | Provider-owned required headers win | Host override attempts on reserved names | Existing header-ownership rules | Host overwrite of provider auth headers unsupported |
+
+## Validation matrix for Task 0
+
+| Check | Frozen assertion |
+| --- | --- |
+| Traceability | Every Phase 6 roadmap criterion maps to exactly one primary owner among Tasks 1–9; 0.0.12+ items listed only under out-of-scope. |
+| Primitive reuse | Only authorized core seams above; Anthropic/Google are new optional packages; goal/verify is compose-only. Shared Anthropic extract deferred (≥2-consumer rule). |
+| Finite resources | Search/budget caps table enforced; no indexer daemons; no unbounded default scans. |
+| Security claims | Ownership on search; hits/omissions credential-free; provider creds late-bound/redacted. |
+| API names | `SessionIndex` / `SessionSearchQuery` / `SessionSearchHit`; `contextBudget` + `getContextBudgetReport`; `sessionSearchMode`; `createAnthropicProviderPackage` / `createGoogleProviderPackage`; `runCodingGoalVerify`; workspace key `metadata.workspaceRoot`. |
+| Eviction order | system/AGENTS → skills → context → history/tool results. |
+
+## Post-freeze extensions (Tasks 8–11)
+
+Plan 074 inserted mid-run steer + ask_user_decision multi/free-text/suspend before docs/release (renumbered Tasks 12–13). Still inside 0.0.11; no Goal DB / no new `AgentRunInterruption` kinds.
+
+| Extension | Frozen choice | Docs | Proof |
+| --- | --- | --- | --- |
+| Mid-run `steer` | Queue ≤8 / ≤64 KiB; softInterrupt aborts provider stream only; same `runId`; fail closed with no active run | `agent-session-runtime.md`, `cli-rpc.md`, `agent-loops.md` | agent + RPC tests |
+| ask_user multi | `selectionMode: "multiple"` → `selectedIds` | `coding-agent-tools.md` | coding-agent tests |
+| ask_user free-text | `allowCustom` + XOR `customText` | `coding-agent-tools.md` | coding-agent tests |
+| ask_user suspend glue | `suspendAskUserDecision` + resume validators; agent adapter only | `coding-agent-tools.md`, `workflows.md` | workflow suspend→approve test |
+
+## Documentation and release ownership
+
+- Task 0 (this page): scope freeze, index link, docs.test evidence assertions.
+- Tasks 1–7: original Phase 6 implementation owners (search/budget/providers/goal-verify).
+- Tasks 8–11: steer + ask_user_decision multi/free-text/suspend glue.
+- Task 12: session/input/provider/coding/workflows/migration/performance docs, READMEs/CHANGELOGs, index summaries.
+- Task 13: version `0.0.11`, benchmarks, `sdk:ready`, pack/install/supply-chain, release dry-run — **done** (2,047 tests / 2,014 pass / 33 skip; 34/34 dry-run; no tag/publish).
+
+No public implementation API changes in Task 0. This page, `roadmap.md` Phase 6, and Plan 074 are the authoritative pre-implementation boundary; later tasks may tighten defaults but cannot raise hard caps, add daemons/Goal DB/second runtime, or pull 0.0.12+ items without updating tests, docs, and this evidence.

package/docs/review-coverage-2026-07-22-phase-7.md

@@ -0,0 +1,173 @@
+# Review coverage — 2026-07-22 Phase 7
+
+Working evidence for Plan 075 Task 0. Freezes Phase 7 / Release **0.0.12** scope, protocol revisions, primitive ownership, finite limits, OAuth eligibility, threats, tests, docs, and release gates before implementation.
+
+**Evidence frozen:** 2026-07-22. **Prism source:** `f9630a9bd12f299fdf473640e3869eea050b786f`. **Release target:** 0.0.12. **Default test rule:** network-free fakes and protocol fixtures; provider live canaries remain explicit host/operator gates.
+
+## Status legend
+
+| Status | Meaning |
+| --- | --- |
+| `existing` | Current public contract covers the requirement. |
+| `extend` | Owning task adds a generic reusable contract to an existing seam. |
+| `new-package` | New optional workspace package; core remains protocol/UI-free. |
+| `compose` | Existing public primitives suffice; package-local wiring only. |
+| `out-of-scope` | Later phase or deliberately unsupported; must not land in 0.0.12. |
+
+## Frozen product decision
+
+0.0.12 closes **coding-harness P2 interoperability** only: one optional AG-UI package with a stable ACP sibling, one generic streamed durable-resume seam, and a thin coding-focused LLM compaction preset.
+
+**Not in 0.0.12** (do not implement here):
+
+| Deferred or rejected item | Owner / reason |
+| --- | --- |
+| Conversation storage/service, artifacts API, personal-agent UX, device sync | 0.0.13+ product scope. |
+| Enterprise identity, Azure/Bedrock/Vertex, work connectors, policy ledger | 0.0.13+ enterprise scope. |
+| Prism TUI, desktop app, browser UI framework, server route | Host-owned UI; adapter uses Web `Request`/`Response` only. |
+| ACP terminal, filesystem, editor, process, diff, or MCP implementation | Host/editor responsibility; stable sibling maps only shared message/tool/approval lifecycle. |
+| Protocol types or AG-UI/ACP dependencies in `@arnilo/prism` core | Optional package owns protocol dependencies. |
+| Second agent runtime, event daemon, polling worker, UI state database, replay cache | Reuse session/event/ledger/checkpoint seams; no background process. |
+| Raw event passthrough, client-defined executable tools, client state mutation, raw tool args/results, local paths | Default-deny projection boundary. |
+| Anthropic Claude Code or Google Gemini CLI subscription OAuth/token reuse | Current provider terms prohibit third-party subscription credential routing/piggybacking. |
+| Generic OAuth framework or credential-file/CLI scraping | Provider-local supported flow only; current core OAuth seams already suffice. |
+| Observational-memory coding runtime/profile | LLM preset is sufficient; do not add a second coding memory system. |
+
+## Frozen external revisions
+
+| Surface | Frozen reference | Compatibility decision |
+| --- | --- | --- |
+| Prism | [`f9630a9bd12f299fdf473640e3869eea050b786f`](../plans/075-release-0-0-12-coding-harness-interoperability.md) | Existing core/session/server/compaction contracts inventoried below. |
+| Node.js | Release support remains Node 20+ | Optional package uses Web `Request`/`Response`, `ReadableStream`, native abort, and existing bounded SSE patterns; no framework dependency. |
+| AG-UI | `@ag-ui/core` **0.0.57**; [Events](https://docs.ag-ui.com/concepts/events), [Interrupts](https://docs.ag-ui.com/concepts/interrupts), [Serialization](https://docs.ag-ui.com/concepts/serialization), [TypeScript schemas](https://github.com/ag-ui-protocol/ag-ui/tree/main/sdks/typescript/packages/core) | Pin the official schema package. Validate produced events with `EventSchemas`; close active message/tool sequences before `RUN_FINISHED` or `RUN_ERROR`. |
+| ACP | `@agentclientprotocol/sdk` **1.3.0** stable root; [overview](https://agentclientprotocol.com/protocol/overview), [tool calls](https://agentclientprotocol.com/protocol/tool-calls), [TypeScript SDK](https://agentclientprotocol.com/libraries/typescript) | Use stable `session/update` and `session/request_permission` contracts only. Exclude `./experimental/v2`. |
+| OpenAI Codex OAuth | Existing `packages/provider-openai/src/oauth.ts`; [OpenAI provider docs](providers/openai.md) | Existing RFC 7636 PKCE browser/device-code flow is retained, host-invoked, abortable, bounded, and redacted. |
+| Anthropic Claude Code auth/legal | [Authentication](https://docs.anthropic.com/en/docs/claude-code/authentication), [legal and compliance](https://docs.anthropic.com/en/docs/claude-code/legal-and-compliance) | No third-party Claude.ai subscription OAuth adapter: Anthropic directs third-party products to API keys or cloud providers. |
+| Gemini CLI auth/terms | [Authentication](https://github.com/google-gemini/gemini-cli/blob/main/docs/get-started/authentication.mdx), [FAQ](https://github.com/google-gemini/gemini-cli/blob/main/docs/resources/faq.md), [terms/privacy](https://github.com/google-gemini/gemini-cli/blob/main/docs/resources/tos-privacy.md) | No Gemini CLI OAuth adapter or token import: terms prohibit third-party software use of Gemini CLI OAuth; use API key or Vertex instead. |
+
+## Frozen package and API contract
+
+| Decision | Frozen choice |
+| --- | --- |
+| Package | New optional `@arnilo/prism-ag-ui`; it depends on `@arnilo/prism` and pinned protocol packages. `@arnilo/prism` remains dependency-free and protocol-free. |
+| Subpath | `@arnilo/prism-ag-ui/acp` is the only ACP export. It uses the stable ACP SDK root, never the experimental v2 subpath. |
+| Root exports | `createAgUiEventMapper`, `createAgUiHandler`, `createPersistenceAgUiReplay`, and package-local limits/projection types. |
+| ACP exports | `createAcpEventMapper`, `createPrismAcpAgent`. No terminal/filesystem/editor/process/MCP export. |
+| Generic core gap | Add `resumeAgentRunStream()` and `AgentRunLifecycle.resumeStream()`. Both reuse one private resume preparation/CAS path with existing `resumeAgentRun()`; no AG-UI/ACP type enters core. |
+| AG-UI run input | Parse official `RunAgentInput` before host capability resolution. Host rebinds `threadId`/`runId` to authorized session/run ownership; default input selection is final accepted user text only. |
+| AG-UI lifecycle | Map Prism lifecycle/message/tool events to official `RUN_*`, `TEXT_MESSAGE_*`, and `TOOL_CALL_*` schemas. Close open text/tool sequences before terminal events. Map durable suspension to `RUN_FINISHED` with `{ type: "interrupt", interrupts }`; map failure to one `RUN_ERROR`. |
+| Durable approval | Exact checkpoint `runId`, authorized ownership, interruption, and `expectedVersion` are required. AG-UI resume resolves every pending interrupt in one payload; ACP unknown/cancel/reject choices deny. No side effect is replayed after an ambiguous dispatched tool. |
+| Replay | `createPersistenceAgUiReplay` adapts ownership-scoped `ProductionPersistenceStore.queryEvents({ sessionId, runId, ... })`. It pages durable redacted rows, then attaches to a live bounded subscriber. Delivery is at-least-once across page/live boundary; stable event/message/tool IDs permit client deduplication. Terminal replay never invokes a provider or tool. |
+| Projection | Default deny: tool name/status only; no args, result, progress payload, raw event, local path, frontend tool, or arbitrary state. Host must explicitly provide redaction-safe projectors for any exposed value. |
+| ACP parity | Map assistant chunks, safe tool status, usage, errors, and durable permissions over same projection/limits/ownership contracts. ACP `session/update` does not create a second run runtime. |
+| Coding compaction | `createCodingCompactionStrategy()` lives in `@arnilo/prism-compaction-llm`, wraps `createLlmCompactionStrategy()`, enables existing file-operation retention, and adds coding instructions. It produces normal `kind: "compaction"` entries; raw history remains. |
+| Release graph | Task 8 adds one publishable package (34 → 35) and includes it only in `@arnilo/prism-all`, never `@arnilo/prism-code` or `@arnilo/prism-sdk`. |
+
+## Capability traceability matrix
+
+| Phase 7 roadmap criterion | Existing surface | Minimum gap | Status / owner | Required proof | Docs | Release gate |
+| --- | --- | --- | --- | --- | --- | --- |
+| Provider-authorized subscription OAuth behind existing seams | `OAuthProvider`, `refreshOAuthCredential`, Node OAuth store, OpenAI Codex PKCE/device flow | Support matrix and eligibility gate; no currently eligible Anthropic/Google flow | `compose` / Task 6 | provider registration absence; existing Codex OAuth tests | credential + provider pages | offline + provider-policy review |
+| AG-UI event mapping without core/UI coupling | Redacted ordered `AgentEvent`, session `stream()`/`subscribe()` | Optional mapper over official schemas and projection policy | `new-package` / Task 2 | schema/lifecycle/redaction/limit fixtures | `ag-ui.md`, agent events | offline package test |
+| Host TUI/desktop run, approval, resume, reconnect | Durable run state, `AgentRunLifecycle`, `AgentEventRecord`, `queryEvents`, server SSE limits | Generic streamed durable resume + handler/replay adapter | `extend` / Task 1; `new-package` / Task 3 | CAS/ownership/reconnect/no-rerun/overflow fixtures | runtime, runs, server, security | offline integration |
+| ACP parity where event/tool/approval contracts overlap | Same agent event, interruption, and lifecycle seams | Stable sibling mapper/agent over shared policy | `new-package` / Task 4 | stable SDK type/permission/subpath packed-consumer tests | AG-UI, A2A, security | offline package test |
+| Coding-aware compaction retaining path/diff/check/plan signals | LLM `CompactionStrategy`, file-operation collection, coding checkpoints/check summaries | Thin LLM preset and fixture | `compose` / Task 5 | prompt/redaction/repeated-compaction/conformance fixtures | compaction + coding docs | offline package test |
+| Finite protocol/reconnect/compaction behavior | Server/SSE, subscriber, persistence, compaction limits | Package-local resolved limits plus benchmark | `new-package` / Tasks 2–3; `compose` / Task 5; Task 8 | hostile-input and benchmark schema/budget tests | performance + AG-UI docs | benchmark + `sdk:ready` |
+| No product/UI/enterprise scope creep | Host-owned UI/product boundaries | Explicit negative tests and release guard | `compose` / Tasks 0, 8 | source/package/export scope assertions | review + migration docs | pack/install + diff review |
+
+## Primitive and caller inventory
+
+| Primitive / symbol | Existing contract and callers | Phase 7 disposition |
+| --- | --- | --- |
+| `AgentEvent`, `redactAgentEvent`, `AgentSession.stream()` / `subscribe()` | Core redacted ordered live events; subscriber default queue 1024 and close/drop policies | Reuse. Adapter owns protocol event correlation and projected payload. |
+| `AgentEventRecord`, `RunLedger`, `ProductionPersistenceStore.queryEvents()` | Redacted durable event rows; SQLite/Postgres persistence queries | Reuse for replay only after host ownership binding. Add no event store/cache. |
+| `resumeAgentRun`, `AgentRunLifecycle.resume()` | CAS, exact ownership/ref/session/fingerprint/revision, denial, dispatched-tool ambiguity protection | **Extend once** with streamed resume wrappers used by AG-UI and ACP. |
+| `StoredAgentRunState`, `AgentRunInterruption`, checkpoint store | Redacted versioned pre-side-effect durable state; 256 KiB default / 1 MiB hard | Reuse. Adapter exposes only public interruption/status/version. |
+| `PrismServerLimits` and server SSE handler | Existing Web request/response, abort, bounded stream/event/queue/time controls | Reuse values/pattern; AG-UI remains package-local and does not add server route. |
+| `SecretRedactor`, credential resolver/OAuth store | Exact known-secret redaction; host-owned late-bound credentials/storage | Reuse. Project before transport/persistence; do not scan CLI credentials. |
+| `OAuthProvider`, `refreshOAuthCredential`, `createOAuthCredentialStoreAdapter` | Generic login/refresh/store seam, OpenAI provider implementation | Reuse unchanged. Future provider OAuth stays provider-local and eligibility-gated. |
+| `CompactionStrategy`, LLM preparation/file operations | Standard append semantics; LLM tracks read/modified files and caps summary/provider output | Reuse. Implement preset, not a memory runtime. |
+| Observational-memory strategy | Optional projection/ledger/fold rendering workers | Leave unchanged; no coding profile needed. |
+| Coding checkpoint and named check summaries | Bounded plan/todo/artifact/check references and fixed command checks | Supply coding signals to LLM compaction fixture/instructions; do not expose raw checkpoint/path data by default. |
+
+### Primitive decision
+
+**Authorized generic core extension:** `resumeAgentRunStream()` and `AgentRunLifecycle.resumeStream()` only. The implementation must share resume validation/CAS/dispatch preparation with `resumeAgentRun()` and use the existing bounded event subscriber. Both AG-UI and ACP consume it.
+
+**Authorized new package:** `@arnilo/prism-ag-ui`, including its `./acp` sibling and package-local mapper, handler, replay, SSE, projection, and limit code.
+
+**Authorized package-local composition:** `createCodingCompactionStrategy()` in `@arnilo/prism-compaction-llm`; provider support documentation/negative guards.
+
+**Rejected:** protocol types in core; UI framework/server route; new runtime/store/worker; generic OAuth abstraction; observational-memory coding runtime; client-controlled tools/state; raw event passthrough; Claude/Gemini CLI credential reuse.
+
+## Frozen finite limits and charging points
+
+**Rule:** adapter validates every incoming selector/body/count before resolving a session, invoking resume, querying replay, or subscribing. It checks every outgoing projected field before enqueue/serialization. Task 2/3 must implement these exact defaults and hard caps; they may tighten a default but must not raise a hard cap without updating this page, tests, and docs.
+
+| Resource | Default / hard cap | Charge/check point | Failure/cleanup owner |
+| --- | ---: | --- | --- |
+| Request body | 64 KiB / 1 MiB | Before AG-UI parse | Task 3 returns bounded client error. |
+| Input messages | 128 / 1,024 | Before host input resolver | Task 3 rejects; never silently truncates user intent. |
+| Input text or one content value | 64 KiB / 1 MiB | Before message projection/host resolver | Task 3 rejects. |
+| Frontend tools / frontend state mutation | 0 / 0 | Before session/run lookup | Task 3 rejects unless a later scope revises this freeze. |
+| Replay cursor | 4 KiB / 16 KiB | Before durable query | Task 3 rejects malformed/oversized cursor. |
+| Replay page rows | 100 / 500 | Before `queryEvents` | Task 3 pages; never full-scans. |
+| Outbound projected event | 64 KiB / 1 MiB | Before SSE/ACP enqueue | Tasks 2–4 close/fail safely; do not split JSON. |
+| Outbound text, tool display, state snapshot | 64 KiB / 1 MiB | Before schema serialization | Tasks 2–4 omit/truncate only with explicit bounded marker. |
+| Tool args/results/progress payload | 0 / 0 by default | Projection | Tasks 2–4 omit. Any later host projector remains inside outbound-event cap. |
+| Error detail | 8 KiB / 64 KiB | Before protocol error event | Tasks 2–4 redact and truncate. |
+| Stream events / aggregate bytes | 10,000 / 100,000; 10 MiB / 64 MiB | Before each enqueue | Task 3 closes stream with bounded terminal error. |
+| Subscriber queue | 128 / 4,096 | Existing `SubscribeOptions` passed by adapter | Tasks 1/3 use `overflow: "close"`; no hidden queue. |
+| Request/run wall time | 120 s / 30 min | Adapter-owned abort signal | Task 3 aborts/cleans up; background completion is explicit host policy only. |
+| Coding compaction output | reuse 16,384 / 131,072 tokens; error 1 KiB / 8 KiB | Existing LLM strategy | Task 5 adds no provider call or unbounded parser. |
+
+The request/event/aggregate/queue/time values intentionally match existing `@arnilo/prism-server` defaults and hard caps. Replay page and cursor values reuse bounded persistence/MCP conventions. The `0 / 0` tool/state rows are a capability denial, not a zero-length serialization limit.
+
+**Forbidden:** unbounded replay, polling, background queue, raw tool payload forwarding, arbitrary client state patch, local path disclosure, auto OAuth refresh timer, CLI credential scan, second compaction call, or hard-cap increase.
+
+## OAuth eligibility matrix
+
+| Provider surface | 0.0.12 status | Allowed auth | Explicitly prohibited / absent | Future eligibility evidence |
+| --- | --- | --- | --- | --- |
+| OpenAI Codex | supported existing flow | `createOpenAICodexOAuthProvider`; host-invoked browser/device code, PKCE, abort, refresh/store seam | automatic login, ambient credential discovery | Existing protocol/abort/refresh/redaction/store tests remain required. |
+| Anthropic provider | API key only | Host-supplied `apiKey` | `createAnthropicSubscriptionOAuthProvider`, Claude Code credential file/token import, Claude.ai subscription routing | Provider-published third-party authorization plus exact flow/scopes, terms review, network-free fixtures. |
+| Google provider | API key only | Host-supplied `apiKey`; Vertex remains later enterprise scope | `createGeminiCliOAuthProvider`, Gemini CLI credential/token import | Provider-published third-party authorization plus exact flow/scopes, terms review, network-free fixtures. |
+
+A future provider-local subscription adapter requires all of: explicit provider permission for third-party products; exact authorize/token/refresh documentation; abort and expiry behavior; PKCE/state where required; bounded request/response handling; token/code/error redaction; durable store round trip; no import/setup network; protocol conformance; legal review. Until then absence is correct behavior, not a missing stub.
+
+## Threat and authority matrix
+
+| Boundary | Trusted authority | Untrusted input | Mandatory control | Default / unsupported |
+| --- | --- | --- | --- | --- |
+| AG-UI thread/run IDs | Host `authorize` and session/run resolver | Client `threadId`, `runId`, cursor | Rebind to exact ownership/session/run; validate checkpoint version | Cross-owner replay/resume unsupported. |
+| Resume/approval | Durable checkpoint + host policy | Resume payload/permission result | Exact run/interruption/version; all open interrupts addressed; CAS before side effect | Partial, stale, unknown, or ambiguous resumes fail. |
+| Event/replay payload | Runtime redactor + host projection | Messages, tool events, ledger rows | Redact then allow-list/project/cap before transport | Raw events/paths/args/results/state unsupported. |
+| Client tools/state | Host tool registry/session state | `RunAgentInput.tools`, state, custom fields | Reject before agent lookup | Client cannot grant capabilities or mutate backend state. |
+| ACP permissions | Host permission policy + checkpoint | ACP option/outcome | Only known allow-once/reject selection maps to exact resume; unknown/cancel denies | Allow-always persistence is not added in 0.0.12. |
+| OAuth | Provider terms + host credential ownership | OAuth code/token/CLI credential files | Explicit authorized flow, bounded calls, redaction, host store | Claude/Gemini CLI subscription credential use unsupported. |
+| Compaction | Existing LLM redactor/limits/provider | Paths, diffs, command/check output, previous summary | Existing serialization/redaction/caps; retain signal summary only | Full diff/transcript retention and second memory runtime unsupported. |
+
+## Validation matrix for Task 0
+
+| Check | Frozen assertion |
+| --- | --- |
+| Traceability | Every Phase 7 roadmap criterion has one primary Task 1–8 owner; 0.0.13+ conversations/artifacts/enterprise identity have none. |
+| Protocol revisions | `@ag-ui/core@0.0.57`; `@agentclientprotocol/sdk@1.3.0` stable root; official AG-UI schemas validate mapped events. |
+| Primitive reuse | Only streamed durable resume is a generic core extension with two consumers; all AG-UI/ACP types stay optional-package-local. |
+| Lifecycle | `RUN_FINISHED` closes text/tool lifecycle; durable suspension is interrupt outcome; terminal replay never reruns work. |
+| Finite resources | All request/event/page/queue/text/tool/state/error/time caps above are enforced; no polling/daemon/unbounded scan. |
+| Security | Ownership before data, exact-version approvals, default-deny projection, redaction before transport, and no frontend capability grant. |
+| OAuth policy | OpenAI Codex remains only subscription OAuth; Anthropic/Google register API key only and expose no forbidden factory. |
+| Coding compaction | One LLM preset reuses file operations/standard entries/redaction/caps; raw session history stays intact. |
+
+## Documentation and release ownership
+
+- Task 0: this evidence page, `docs/index.md`, and `docs.test.ts` regression guard.
+- Task 1: generic streamed durable resume; runtime/events/public-contract docs.
+- Tasks 2–4: optional AG-UI/ACP mapper, handler/replay, and stable sibling; AG-UI/security/A2A docs.
+- Task 5: coding LLM compaction preset and docs.
+- Task 6: OAuth support-matrix docs and absence guards.
+- Task 7: canonical docs, examples, migration, package metadata/navigation.
+- Task 8: 0.0.12 graph, benchmark, pack/install, supply-chain, dry-run publish, and roadmap completion evidence.
+
+No public implementation API changes land in Task 0. This page, `roadmap.md` Phase 7, and Plan 075 are authoritative until implementation; later tasks may tighten defaults but cannot widen scope, raise hard caps, add protocol types to core, add a background worker/store, or enable unsupported subscription OAuth without updating this evidence, tests, docs, and plan.

package/docs/runs-and-usage.md

@@ -315,3 +315,4 @@ Runtime session snapshots cache one leaf/generation for at most one second. Succ
 - [Provider caching](provider-caching.md): cache hints and `cacheUsageReport()` diagnostics.
 - [Observability](observability.md): `provider_turn_*` events, tool duration metadata, OpenTelemetry adapter.
 - [Public contracts](public-contracts.md): full contract inventory.
+- [Frontend interoperability (AG-UI and ACP)](ag-ui.md): `AgentEventRecord` pages become redacted, ownership-scoped, at-least-once replay only through an explicit host adapter.

package/docs/server.md

@@ -139,4 +139,5 @@ A2A routes are not added to `createPrismHandler()`. Install `@arnilo/prism-super
 - [MCP client and server exposure](mcp-tools.md): selected MCP capabilities and web-standard MCP transport.
 - [Host security guide](host-security.md): remote-boundary checklist.
 - [A2A interoperability](a2a.md): separately mounted A2A 1.0 handler/client.
+- [Frontend interoperability (AG-UI and ACP)](ag-ui.md): separately installed authorized AG-UI Web handler; it is not a `@arnilo/prism-server` route.
 - [Release and install](release-and-install.md): optional package installation and profiles.

package/docs/session-store-conformance.md

@@ -25,6 +25,8 @@ Use this helper when implementing a DB-backed `SessionStore` (for example, the r
 - session ids remain isolated (`assertSessionStoreConforms` always probes a secondary session)
 - optional concurrent fork children of the same parent succeed when `exerciseConcurrentParentAppend: true`
 - optional durable reopen/idempotency survival when `runSessionStoreConformance(..., { exerciseReopen: true })`
+- optional `searchSessions` bounds/ownership/empty-page checks when `exerciseSearchSessions: true` (`assertSessionStoreSearchSessions`)
+- optional `searchSessions` bounds/ownership/empty-page checks when `exerciseSearchSessions: true` (`assertSessionStoreSearchSessions`)
 
 ## Inputs / request
 

package/docs/session-stores.md

@@ -24,13 +24,16 @@ import type { SessionStore, SessionEntry } from "@arnilo/prism";
 | `list(sessionId)` | Return all entries for one session in stored order. Development fallback for branch reads. |
 | `get?(id)` | Return one entry by id, if present. Optional. |
 | `readBranchPath?(query)` | Optional DB-friendly branch read. Return one branch's ancestor chain as a `PersistencePage<SessionEntry>` so the runtime can avoid `list(sessionId)`. |
+| `searchSessions?(query)` | Optional bounded session search (`SessionSearchQuery` → `PersistencePage<SessionSearchHit>`). SQLite/Postgres implement FTS + metadata filters; memory default is linear; JSONL throws `SessionSearchUnsupportedError`. |
 
 Public helpers:
 
 | Helper | Purpose |
 | --- | --- |
 | `createSessionEntry(options)` | Build a `SessionEntry` with generated `id`/`timestamp` when omitted. |
-| `createMemorySessionStore(initialEntries?)` | Built-in in-memory `SessionStore`. |
+| `createMemorySessionStore(initialEntries?, options?)` | Built-in in-memory `SessionStore`. `options.sessionSearchMode`: `"linear"` (default) or `"unsupported"` (throws `SessionSearchUnsupportedError`). |
+| `resolveSessionSearchQuery(query)` | Validate/clamp search limits (page, query bytes, snippet, cursor, linear/FTS caps). |
+| `SessionIndex` | Narrow search seam (`search(query)`); adapters may expose this instead of `SessionStore.searchSessions`. |
 | `getSessionBranchEntries(entries, options)` | Return root-to-leaf entries for a leaf id (sync array path). |
 | `getSessionBranchEntries(reader, query)` | Async overload for a `BranchReader` / `readBranchPath` implementation. |
 | `listSessionBranches(entries)` | List every branch handle as `{ leafId, entries }`. Pair with `sessionId` for a durable `(sessionId, leafId)` branch handle. |
@@ -107,6 +110,42 @@ Recognize it with `isSessionAppendConflict(error)`, not message text. Built-in s
 - Branch semantics are parent links plus a leaf id. External UIs should keep branch handles as `(sessionId, leafId)`; RPC exposes an additional `handleId` for active handles.
 - Development stores can omit `readBranchPath`; the runtime falls back to `list(sessionId)` and the pure in-memory branch walk. Database-backed stores should implement `readBranchPath` so `entries()`, `clone()`, and context rebuild read only the selected ancestor chain.
 
+## Session search (0.0.11)
+
+Bounded `SessionIndex` / `searchSessions` lists sessions by optional `workspaceRoot` (`metadata.workspaceRoot`), provider/model, label/summary, time range, ownership, and optional text `query` (FTS on SQLite/Postgres; case-sensitive substring on memory linear). Hits require `sessionId` and may include `leafId` for `checkout`; never credentials or whole transcripts.
+
+```ts
+import { createMemorySessionStore, resolveSessionSearchQuery } from "@arnilo/prism";
+
+const store = createMemorySessionStore([], { sessionSearchMode: "linear" });
+const page = await store.searchSessions!({
+  workspaceRoot: "/repo",
+  query: "flake",
+  limit: 20,
+});
+// Opt out: createMemorySessionStore([], { sessionSearchMode: "unsupported" })
+```
+
+Finite caps (defaults / hard): page 20/100; query string 4 KiB/16 KiB; snippet 512 B/4 KiB; cursor 1 KiB/4 KiB; memory linear sessions 1000/5000, entries 10000/50000, bytes 8 MiB/64 MiB; DB FTS candidates 1000/5000. Overflow fails closed via `resolveSessionSearchQuery`. See [Phase 6 evidence](review-coverage-2026-07-22-phase-6.md).
+
+## Session search (0.0.11)
+
+Bounded `SessionIndex` / `searchSessions` lists sessions by optional `workspaceRoot` (`metadata.workspaceRoot`), provider/model, label/summary, time range, ownership, and optional text `query` (FTS on SQLite/Postgres; case-sensitive substring on memory linear). Hits require `sessionId` and may include `leafId` for `checkout`; never credentials or whole transcripts.
+
+```ts
+import { createMemorySessionStore, resolveSessionSearchQuery } from "@arnilo/prism";
+
+const store = createMemorySessionStore([], { sessionSearchMode: "linear" });
+const page = await store.searchSessions!({
+  workspaceRoot: "/repo",
+  query: "flake",
+  limit: 20,
+});
+// Opt out: createMemorySessionStore([], { sessionSearchMode: "unsupported" })
+```
+
+Finite caps (defaults / hard): page 20/100; query string 4 KiB/16 KiB; snippet 512 B/4 KiB; cursor 1 KiB/4 KiB; memory linear sessions 1000/5000, entries 10000/50000, bytes 8 MiB/64 MiB; DB FTS candidates 1000/5000. Overflow fails closed via `resolveSessionSearchQuery`. See [Phase 6 evidence](review-coverage-2026-07-22-phase-6.md).
+
 ## Security and performance notes
 
 - Do not store provider credentials, credential resolvers, provider instances, or unredacted secrets in session entries, append options, idempotency keys, or branch records.

package/docs/sqlite-persistence.md

@@ -4,7 +4,7 @@
 
 The optional `@arnilo/prism-session-store-sqlite` package ships a production-oriented SQLite adapter that implements:
 
-- `SessionStore` — atomic `append` / `list` / `get` / `readBranchPath`
+- `SessionStore` — atomic `append` / `list` / `get` / `readBranchPath` / bounded `searchSessions` / bounded `searchSessions`
 - `RunLedger` — durable run, event, tool-call, and usage rows
 - `ProductionPersistenceStore` — cursor-paginated `query*` reads plus generic `checkpoints` and atomic `leases` capabilities
 
@@ -56,7 +56,7 @@ import { createSqlitePersistence } from "@arnilo/prism-session-store-sqlite";
 | `leases` | Atomic `LeaseStore` backed by `prism_leases`; database-clock expiry, opaque renew/release token, monotonic takeover fence. |
 | `close()` | Closes the underlying database when the adapter opened it. |
 
-Migrations run automatically on open and are idempotent across reopen. Under the SQLite migration transaction, startup checks ordered contract name/version/SHA-256 rows plus full schema-v3 PRAGMA/catalog shape (all required tables, columns/types/nullability/defaults, PK/unique/FK keys, and named indexes) before any runtime write. A complete legacy 0.0.5 history with all `checksum` values `NULL` is shape-verified then backfilled transactionally once. Unknown, duplicate, out-of-order, partial-legacy, checksum, or shape drift rejects open; restore or apply reviewed DDL rather than editing migration rows.
+Migrations run automatically on open and are idempotent across reopen. Under the SQLite migration transaction, startup checks ordered contract name/version/SHA-256 rows plus full schema-v4 PRAGMA/catalog shape (all required tables, columns/types/nullability/defaults, PK/unique/FK keys, and named indexes) before any runtime write. A complete legacy 0.0.5 history with all `checksum` values `NULL` is shape-verified then backfilled transactionally once. Unknown, duplicate, out-of-order, partial-legacy, checksum, or shape drift rejects open; restore or apply reviewed DDL rather than editing migration rows.
 
 ## Request/response example
 
@@ -99,7 +99,7 @@ For resume/timeline flows, use `queryRuns`, `queryEvents`, `queryToolCalls`, and
 - The package is optional and workspace-local; `@arnilo/prism` core has no SQLite dependency.
 - Hosts choose the database path and own backup, retention enforcement, and filesystem permissions.
 - `SessionAppendOptions` idempotency rows are durable in `prism_session_append_idempotency` and survive reopen.
-- Schema version **3** applies `001_init`, additive `002_usage_scope`, and `003_run_feedback`. Migration 003 adds immutable `prism_run_feedback` rows with run FK/cascade deletion and owner/run/trace cursor indexes. `persistence.feedback` validates exact run ownership, bounds/redacts through optional `feedbackRedactor`, queries bounded pages, and deletes only exact-owned IDs. PostgreSQL shares the same model with dialect-local DDL.
+- Schema version **4** applies `001_init`, `002_usage_scope`, `003_run_feedback`, and `004_session_search`. Migration 003 adds immutable `prism_run_feedback` rows with run FK/cascade deletion and owner/run/trace cursor indexes. Migration 004 adds session search FTS (FTS5 virtual table `prism_session_search_fts` dual-written on append) plus `prism_sessions(updated_at, id)` cursor index; existing entries are backfilled once. `persistence.feedback` validates exact run ownership, bounds/redacts through optional `feedbackRedactor`, queries bounded pages, and deletes only exact-owned IDs. Search hits never include credentials; ownership filters apply when present. PostgreSQL shares the same model with dialect-local DDL.
 - Pass an existing `better-sqlite3` `Database` via `database` when your host already manages connections.
 
 ## Security and performance notes

package/docs/structured-output.md

@@ -49,8 +49,11 @@ await session.run(input, {
     parser,            // optional; default treats assistant text as the value
     repairer,          // optional; default stringifies validation.errors[].message
     maxRevisions: 3,   // optional; default 3
+    toolCalls: "bounded", // optional; default "disabled"
     structuredOutput: { name: "answer", schema, strict: true }, // optional native mode
     structuredOutputMode: "native", // or "artifact-loop" to skip provider-native schema
+    // Opt-in: schema only on artifact/revision turns (tools free on earlier turns).
+    structuredOutputTiming: "final-turn-only", // default "every-turn"
   },
   providerOptions: {
     structuredOutput: { name: "answer", schema, strict: true }, // direct native request
@@ -58,6 +61,8 @@ await session.run(input, {
 });
 ```
 
+`structuredOutputTiming: "final-turn-only"` (with `toolCalls: "bounded"` and native schema) sends tool-eligible turns **without** `response_format` so models can call tools; once the model returns a call-free candidate (or tool rounds are exhausted), the next turn withdraws tools and attaches schema. Revision turns stay schema-on / tools-off. Default `"every-turn"` keeps legacy behavior (schema on every provider request).
+
 ## Outputs / response / events
 
 `generateValidateReviseLoop.run(ctx)` returns `Promise<Usage | undefined>`. Observable behavior is emitted through `AgentEvent` artifact variants (zero emitted by `singleShotLoop`):
@@ -230,11 +235,12 @@ Key cross-seam points:
 
 - `generate-validate-revise` is selected via `AgentConfig.loop` / `RunOptions.loop` (`RunOptions.loop` wins). See [Agent loops](agent-loops.md). `resolveLoop()` maps the options form to the factory; an unknown `strategy` throws before the first turn; a custom `AgentLoopStrategy` instance bypasses the options form.
 - Native structured output uses provider-neutral `StructuredOutputOptions` on `ProviderRequestOptions` / loop options. Capable OpenAI-family providers map to JSON-schema wire fields; unsupported models fail before fetch unless the host sets `structuredOutputMode: "artifact-loop"` and relies on parser/validator/repairer only.
+- `structuredOutputTiming: "final-turn-only"` (opt-in; default `"every-turn"`) with `toolCalls: "bounded"` omits native schema on tool-eligible turns and attaches schema only on artifact/revision turns (tools withdrawn). Call-free tool-phase output promotes to one schema turn before parse/validate.
 - `validateStructuredOutputOptions()` enforces JSON-safe schemas, forbidden prototype-pollution keys, and a 64 KiB schema size cap.
 - The default parser treats non-empty assistant text as the value (`{ ok: true, value: text }`); empty/whitespace-only call-free text is a `parse_error` before the parser. Supply a host parser whenever `T` is not `string`.
 - The default repairer builds a user message from `validation.errors[].message`; supply a host repairer for schema-specific guidance.
 - `maxRevisions` (default 3) bounds revision turns; budget exhaustion ends the loop and emits `artifact_failed`. Session runs then fail with `AgentRunError` unless `artifact_finished` occurred (direct `loop.run` still returns usage without throwing).
-- Tools are inert in artifact turns unless `loop.toolCalls: "bounded"` is explicit. Bounded mode uses run-global `maxToolRounds`, dispatches calls sequentially through normal runtime guards, skips parser/validator for tool-calling responses, and permits at most `1 + maxRevisions + maxToolRounds` provider turns. An extra tool response yields terminal `artifact_failed` with `result.metadata.reason === "tool_round_limit"` and executes nothing.
+- Tools are inert in artifact turns unless `loop.toolCalls: "bounded"` is explicit. Bounded mode uses run-global `maxToolRounds`, dispatches calls sequentially through normal runtime guards, skips parser/validator for tool-calling responses, and permits at most `1 + maxRevisions + maxToolRounds` provider turns (plus one extra schema turn under `final-turn-only` when a tool-phase call-free draft promotes). An extra tool response yields terminal `artifact_failed` with `result.metadata.reason === "tool_round_limit"` and executes nothing.
 
 ## Security and performance notes
 

package/docs/workflows.md

@@ -72,6 +72,8 @@ All workflow limits and runtime `concurrency` reject non-safe integers, zero, ne
 
 A function node returns `suspend({ reason, data?, resumeSchema? })` to persist `status: "suspended"`. Its next invocation receives `ctx.resume` only after an approved resume. `resumeWorkflow(workflow, { runId }, options)` validates schema/version/ownership/`definitionHash`, claims the checkpoint before node execution, and continues the suspended node. Denial persists terminal `denied` status without invoking it. Existing failed/aborted checkpoint resume remains available without a human decision.
 
+Coding-agent ask-user glue (opt-in, no Goal DB): `suspendAskUserDecision(request)` wraps `suspend` with durable question/options/`selectionMode`/`allowCustom` data + resume schema; resume with `createAskUserDecisionResumeValidator()` or `validateAskUserDecisionResume`. Goal→verify: `runCodingGoalVerify` / `createCodingGoalVerifyWorkflow` compose plan Markdown → named checks → approve suspend → bounded handoff over the same primitives (`examples/coding-goal-verify.ts`).
+
 Every node receives bounded `ctx.state`, `ctx.stateVersion`, and async `ctx.updateState(patch, { mode: "merge" | "replace" })`. Updates serialize, validate, redact, and snapshot before checkpoint save. `workflowNode({ workflow })` runs its child with the same ownership, agent/tool registries, execution policy, redactor, signal, checkpoints, and event bus; child state replaces parent state after success.
 
 `replayWorkflow(workflow, { sourceRunId, fromNodeId, runId? }, options)` requires a succeeded source/node, creates a new checkpoint, copies terminal evidence outside the selected node's downstream closure, restores selected-node pre-state, and records `{ sourceRunId, fromNodeId, rootRunId, depth }`. Source evidence is untouched. Copying any prior nested/tool approval is rejected; replay from that approval node or earlier so Phase 8 approval executes again.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "Agent harness for AI providers, agents, sessions, and tools.",
   "type": "module",
   "main": "./dist/index.js",
@@ -111,15 +111,16 @@
     "packages/credentials-node",
     "packages/mcp",
     "packages/evals",
+    "packages/workflows",
     "packages/coding-agent",
     "packages/coding-security",
-    "packages/workflows",
     "packages/memory",
     "packages/rag",
     "packages/server",
     "packages/supervisor",
     "packages/web-tools",
     "packages/browser",
+    "packages/ag-ui",
     "packages/prism-*"
   ],
   "scripts": {