@arnilo/prism 0.0.10 → 0.0.11

package/dist/session-stores.js

@@ -1,4 +1,4 @@
-import { SESSION_APPEND_CONFLICT_CODE, SessionAppendConflictError } from "./contracts.js";
+import { DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, SESSION_APPEND_CONFLICT_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionSearchUnsupportedError, resolveSessionSearchQuery, } from "./contracts.js";
 import { createId } from "./ids.js";
 export function createSessionEntry(options) {
     const { createId, now, ...entry } = options;
@@ -93,16 +93,17 @@ function rebuildSessionContextCore(entries, options = {}) {
     }
     return { leafId: branch.at(-1)?.id, entries: branch, messages, summaries };
 }
-export function createMemorySessionStore(initialEntries = []) {
+export function createMemorySessionStore(initialEntries = [], options = {}) {
     const byId = new Map();
     const bySession = new Map();
     const leafBySession = new Map();
     const idempotencySeen = new Set();
+    const mode = options.sessionSearchMode ?? "linear";
     for (const entry of initialEntries)
         add(entry);
     return {
-        async append(entry, options) {
-            add(entry, options);
+        async append(entry, appendOptions) {
+            add(entry, appendOptions);
         },
         async list(sessionId) {
             return (bySession.get(sessionId) ?? []).map(cloneEntry);
@@ -111,6 +112,11 @@ export function createMemorySessionStore(initialEntries = []) {
             const entry = byId.get(id);
             return entry ? cloneEntry(entry) : undefined;
         },
+        async searchSessions(query) {
+            if (mode === "unsupported")
+                throw new SessionSearchUnsupportedError();
+            return searchMemorySessionsLinear(bySession, leafBySession, query);
+        },
     };
     function add(entry, options) {
         // ponytail: idempotency dedup keyed on (session, key, expectedParentId) so a
@@ -146,6 +152,170 @@ export function createMemorySessionStore(initialEntries = []) {
         leafBySession.set(entry.sessionId, entry.id);
     }
 }
+function searchMemorySessionsLinear(bySession, leafBySession, query) {
+    const q = resolveSessionSearchQuery(query);
+    q.signal?.throwIfAborted();
+    let sessionsScanned = 0;
+    let entriesScanned = 0;
+    let bytesScanned = 0;
+    const matches = [];
+    for (const [sessionId, entries] of bySession) {
+        if (sessionsScanned >= DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS)
+            break;
+        if (entriesScanned >= DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES)
+            break;
+        if (bytesScanned >= DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES)
+            break;
+        q.signal?.throwIfAborted();
+        sessionsScanned += 1;
+        let updatedAt = "";
+        let label;
+        let summary;
+        let workspaceRoot;
+        let tenantId;
+        let accountId;
+        let userId;
+        let matchedLabel = false;
+        let matchedSummary = false;
+        let matchedQuery = false;
+        let matchedProvider = false;
+        let matchedModel = false;
+        let snippetSource;
+        for (const entry of entries) {
+            if (entriesScanned >= DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES)
+                break;
+            if (bytesScanned >= DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES)
+                break;
+            entriesScanned += 1;
+            const text = entrySearchText(entry);
+            bytesScanned += utf8Bytes(text) + utf8Bytes(entry.label) + utf8Bytes(entry.summary);
+            if (entry.timestamp > updatedAt)
+                updatedAt = entry.timestamp;
+            if (entry.label)
+                label = entry.label;
+            if (entry.summary)
+                summary = entry.summary;
+            const meta = entry.metadata;
+            if (meta) {
+                if (typeof meta[SESSION_SEARCH_WORKSPACE_METADATA_KEY] === "string") {
+                    workspaceRoot = meta[SESSION_SEARCH_WORKSPACE_METADATA_KEY];
+                }
+                if (typeof meta.tenantId === "string")
+                    tenantId = meta.tenantId;
+                if (typeof meta.accountId === "string")
+                    accountId = meta.accountId;
+                if (typeof meta.userId === "string")
+                    userId = meta.userId;
+            }
+            if (q.label && entry.label?.includes(q.label))
+                matchedLabel = true;
+            if (q.summary && entry.summary?.includes(q.summary))
+                matchedSummary = true;
+            if (q.query) {
+                const hay = `${entry.label ?? ""}\n${entry.summary ?? ""}\n${text}`;
+                if (hay.includes(q.query)) {
+                    matchedQuery = true;
+                    snippetSource ??= entry.label ?? entry.summary ?? text;
+                }
+            }
+            if (q.provider && (entry.model?.provider === q.provider || metaProvider(entry) === q.provider))
+                matchedProvider = true;
+            if (q.model && entry.model?.model === q.model)
+                matchedModel = true;
+        }
+        if (q.workspaceRoot && workspaceRoot !== q.workspaceRoot)
+            continue;
+        if (q.tenantId && tenantId !== q.tenantId)
+            continue;
+        if (q.accountId && accountId !== q.accountId)
+            continue;
+        if (q.userId && userId !== q.userId)
+            continue;
+        if (q.label && !matchedLabel)
+            continue;
+        if (q.summary && !matchedSummary)
+            continue;
+        if (q.query && !matchedQuery)
+            continue;
+        if (q.provider && !matchedProvider)
+            continue;
+        if (q.model && !matchedModel)
+            continue;
+        if (q.fromUpdatedAt && updatedAt < q.fromUpdatedAt)
+            continue;
+        if (q.toUpdatedAt && updatedAt > q.toUpdatedAt)
+            continue;
+        matches.push({
+            sessionId,
+            leafId: leafBySession.get(sessionId),
+            updatedAt: updatedAt || undefined,
+            label,
+            summary,
+            snippet: clipSnippet(snippetSource ?? label ?? summary),
+            metadata: workspaceRoot !== undefined ? { [SESSION_SEARCH_WORKSPACE_METADATA_KEY]: workspaceRoot } : undefined,
+        });
+    }
+    matches.sort((a, b) => compareSearchHit(a, b, q.order));
+    const afterCursor = q.cursor ? decodeSearchCursor(q.cursor) : undefined;
+    const filtered = afterCursor
+        ? matches.filter((hit) => isAfterSearchCursor(hit, afterCursor, q.order))
+        : matches;
+    const page = filtered.slice(0, q.limit);
+    const last = page.at(-1);
+    return {
+        items: page,
+        nextCursor: filtered.length > q.limit && last?.updatedAt
+            ? encodeSearchCursor(last.updatedAt, last.sessionId)
+            : undefined,
+    };
+}
+function entrySearchText(entry) {
+    if (!entry.message?.content)
+        return "";
+    const parts = [];
+    for (const block of entry.message.content) {
+        if (block.type === "text" && typeof block.text === "string")
+            parts.push(block.text);
+    }
+    return parts.join("\n");
+}
+function metaProvider(entry) {
+    const value = entry.metadata?.provider;
+    return typeof value === "string" ? value : undefined;
+}
+function utf8Bytes(value) {
+    return value ? new TextEncoder().encode(value).byteLength : 0;
+}
+function clipSnippet(value) {
+    if (!value)
+        return undefined;
+    const encoded = new TextEncoder().encode(value);
+    if (encoded.byteLength <= DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES)
+        return value;
+    return new TextDecoder().decode(encoded.slice(0, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES));
+}
+function encodeSearchCursor(updatedAt, sessionId) {
+    return `${updatedAt}\t${sessionId}`;
+}
+function decodeSearchCursor(cursor) {
+    const tab = cursor.indexOf("\t");
+    if (tab <= 0 || tab === cursor.length - 1)
+        throw new TypeError("SessionSearchQuery.cursor is invalid");
+    return { updatedAt: cursor.slice(0, tab), sessionId: cursor.slice(tab + 1) };
+}
+function compareSearchHit(a, b, order) {
+    const aAt = a.updatedAt ?? "";
+    const bAt = b.updatedAt ?? "";
+    const cmp = aAt < bAt ? -1 : aAt > bAt ? 1 : a.sessionId < b.sessionId ? -1 : a.sessionId > b.sessionId ? 1 : 0;
+    return order === "asc" ? cmp : -cmp;
+}
+function isAfterSearchCursor(hit, cursor, order) {
+    const at = hit.updatedAt ?? "";
+    if (order === "asc") {
+        return at > cursor.updatedAt || (at === cursor.updatedAt && hit.sessionId > cursor.sessionId);
+    }
+    return at < cursor.updatedAt || (at === cursor.updatedAt && hit.sessionId < cursor.sessionId);
+}
 function cloneEntry(entry) {
     return structuredClone(entry);
 }

package/dist/structured-output.d.ts

@@ -1,4 +1,4 @@
-import type { AgentConfig, ModelCapabilities, ModelConfig, ProviderRequestOptions, RunOptions, StructuredOutputOptions } from "./contracts.js";
+import type { AgentConfig, ModelCapabilities, ModelConfig, ProviderRequest, ProviderRequestOptions, RunOptions, StructuredOutputOptions } from "./contracts.js";
 export declare const DEFAULT_MAX_STRUCTURED_OUTPUT_SCHEMA_BYTES = 65536;
 export declare const DEFAULT_MAX_STRUCTURED_OUTPUT_NAME_LENGTH = 128;
 export declare class StructuredOutputError extends Error {
@@ -9,3 +9,7 @@ export declare function modelSupportsStructuredOutput(capabilities?: ModelCapabi
 export declare function validateStructuredOutputOptions(options: StructuredOutputOptions): StructuredOutputOptions;
 export declare function assertStructuredOutputRequestSupported(model: ModelConfig, options?: ProviderRequestOptions): void;
 export declare function resolveRunProviderOptions(runOptions: Pick<RunOptions, "providerOptions" | "loop">, config: Pick<AgentConfig, "providerOptions" | "loop">): ProviderRequestOptions | undefined;
+/** Strip native schema so a tool-eligible turn can call tools freely. */
+export declare function withoutStructuredOutput(request: ProviderRequest): ProviderRequest;
+/** Artifact/revision turn: keep/restore schema and withdraw tools. */
+export declare function artifactStructuredOutputRequest(request: ProviderRequest, schema?: StructuredOutputOptions): ProviderRequest;

package/dist/structured-output.js

@@ -56,4 +56,22 @@ export function resolveRunProviderOptions(runOptions, config) {
         structuredOutput: validateStructuredOutputOptions(loop.structuredOutput),
     });
 }
+/** Strip native schema so a tool-eligible turn can call tools freely. */
+export function withoutStructuredOutput(request) {
+    if (!request.options?.structuredOutput)
+        return request;
+    const { structuredOutput: _drop, ...options } = request.options;
+    return { ...request, options: Object.keys(options).length > 0 ? options : undefined };
+}
+/** Artifact/revision turn: keep/restore schema and withdraw tools. */
+export function artifactStructuredOutputRequest(request, schema) {
+    const structuredOutput = schema ?? request.options?.structuredOutput;
+    if (!structuredOutput)
+        return { ...request, tools: undefined };
+    return {
+        ...request,
+        tools: undefined,
+        options: { ...request.options, structuredOutput },
+    };
+}
 //# sourceMappingURL=structured-output.js.map

package/dist/testing/persistence-schema.d.ts

@@ -1,6 +1,6 @@
 import type { PersistencePage, SessionEntry, SessionEntryQuery } from "../contracts.js";
 /** Current shared persistence schema version for production database adapters. */
-export declare const PERSISTENCE_SCHEMA_VERSION = 3;
+export declare const PERSISTENCE_SCHEMA_VERSION = 4;
 export type PersistenceTableName = "prism_tenants" | "prism_accounts" | "prism_users" | "prism_agent_definitions" | "prism_sessions" | "prism_branches" | "prism_session_entries" | "prism_session_append_idempotency" | "prism_runs" | "prism_agent_events" | "prism_tool_calls" | "prism_usage" | "prism_run_feedback" | "prism_retention_policies" | "prism_migrations";
 export type PersistenceColumnType = "text" | "integer" | "number" | "boolean" | "json" | "timestamp";
 export interface PersistenceColumnDefinition {

package/dist/testing/persistence-schema.js

@@ -4,7 +4,7 @@ import { createHash } from "node:crypto";
 // this module defines the shared table/index/pagination/migration expectations
 // adapter authors implement and test against before shipping dialect-specific DDL.
 /** Current shared persistence schema version for production database adapters. */
-export const PERSISTENCE_SCHEMA_VERSION = 3;
+export const PERSISTENCE_SCHEMA_VERSION = 4;
 /** Guidance adapters must follow: values are bound parameters, never interpolated. */
 export const PARAMETERIZED_QUERY_GUIDANCE = "Bind every user-supplied value (session ids, idempotency keys, tenant ids, timestamps, JSON payloads) as a query parameter. Quote/validate schema and table identifiers only; never interpolate untrusted strings into SQL text.";
 const TENANT_COLUMNS = [
@@ -315,7 +315,12 @@ function migrationStep(version, name, description) {
         }
         : version === 2
             ? { table: "prism_usage", columns: ["scope", "turn", "attempt"], indexes: ["prism_usage_session_scope_recorded_idx"] }
-            : { tables: ["prism_run_feedback"], indexes: model.indexes.filter((index) => index.name.startsWith("prism_run_feedback_")).map((index) => index.name) };
+            : version === 3
+                ? { tables: ["prism_run_feedback"], indexes: model.indexes.filter((index) => index.name.startsWith("prism_run_feedback_")).map((index) => index.name) }
+                : version === 4
+                    // Adapter-local FTS objects (SQLite FTS5 / Postgres tsvector) map to this canonical name.
+                    ? { search: ["prism_session_search"], indexes: ["prism_sessions_updated_id_idx"] }
+                    : (() => { throw new Error(`Unknown migration version ${version}`); })();
     return {
         version,
         name,
@@ -332,6 +337,7 @@ export function createPersistenceMigrationContract() {
             migrationStep(1, "001_init", "Create core session, branch, entry, idempotency, run, ledger, and migration tables."),
             migrationStep(2, "002_usage_scope", "Distinguish provider-turn usage from aggregate run totals."),
             migrationStep(3, "003_run_feedback", "Add immutable ownership-scoped run/trace feedback and evaluation links."),
+            migrationStep(4, "004_session_search", "Add bounded session search indexes and adapter-local FTS objects."),
         ],
         lockGuidance: "Acquire a dialect-specific migration lock before applying steps (PostgreSQL advisory lock; SQLite exclusive transaction). Only one process should migrate at a time.",
         leastPrivilegeGuidance: "Run migrations with a DDL-capable role; use a separate least-privilege runtime role limited to INSERT/SELECT/UPDATE on adapter tables. Never grant migration credentials to the agent runtime.",

package/dist/testing/session-store-conformance.d.ts

@@ -10,6 +10,12 @@ export interface SessionStoreConformanceOptions {
      * when the store does not implement `readBranchPath`.
      */
     readonly exerciseReadBranchPath?: boolean;
+    /**
+     * When true, exercises optional `searchSessions` (empty page, limit cap,
+     * invalid limit/query rejection via `resolveSessionSearchQuery` semantics).
+     * Skipped when the store does not implement `searchSessions`.
+     */
+    readonly exerciseSearchSessions?: boolean;
     /** When true, appends concurrent children of the same parent (fork allowed). */
     readonly exerciseConcurrentParentAppend?: boolean;
     /**

package/dist/testing/session-store-conformance.js

@@ -5,7 +5,7 @@
 // stores already satisfy. Mirrors the assertion shape already repeated across
 // src/__tests__/session-stores.test.ts and node-session-store-jsonl.test.ts so
 // adapter authors do not re-derive them. Throws plain Error; no test runner.
-import { isSessionAppendConflict } from "../contracts.js";
+import { HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, isSessionAppendConflict, resolveSessionSearchQuery, } from "../contracts.js";
 /**
  * Assert that a `SessionStore` implementation satisfies the core adapter
  * contract: round-trip append/list, duplicate-entry-id rejection,
@@ -63,6 +63,9 @@ export async function assertSessionStoreConforms(store, options = {}) {
             throw new Error(`readBranchPath must return the ancestor chain root→leaf in order; got ${JSON.stringify(ids)}`);
         }
     }
+    if (options.exerciseSearchSessions && typeof store.searchSessions === "function") {
+        await assertSessionStoreSearchSessions(store);
+    }
     await assertSessionStoreBranchIsolation(store, options);
     if (options.exerciseConcurrentParentAppend) {
         await assertConcurrentParentAppendAllowed(store, sessionId, now, make);
@@ -104,6 +107,38 @@ export async function runSessionStoreConformance(factory, options = {}) {
         label: "dup",
     }, { idempotencyKey: "reopen-idem", expectedParentId: parent?.id }), (error) => isSessionAppendConflict(error) && error.conflict.idempotencyDuplicate === true, "Restarted store must still deduplicate an exact idempotency retry");
 }
+async function assertSessionStoreSearchSessions(store) {
+    const search = store.searchSessions;
+    await reject(() => search({ limit: 0 }), (error) => error instanceof TypeError, "searchSessions must reject non-positive limit");
+    await reject(() => search({ limit: Number.NaN }), (error) => error instanceof TypeError, "searchSessions must reject NaN limit");
+    await reject(() => search({ limit: HARD_MAX_SESSION_SEARCH_LIMIT + 1 }), (error) => error instanceof TypeError, "searchSessions must reject oversize limit");
+    await reject(() => search({ query: "x".repeat(HARD_MAX_SESSION_SEARCH_QUERY_BYTES + 1) }), (error) => error instanceof TypeError, "searchSessions must reject oversize query string");
+    const empty = await search(resolveSessionSearchQuery({
+        workspaceRoot: "__prism_conformance_empty__",
+        limit: 5,
+    }));
+    if (!Array.isArray(empty.items)) {
+        throw new Error("searchSessions must return a PersistencePage with an items array");
+    }
+    const resolved = resolveSessionSearchQuery({ limit: 1 });
+    const page = await search(resolved);
+    if (page.items.length > resolved.limit) {
+        throw new Error(`searchSessions must honor limit; got ${page.items.length} items for limit ${resolved.limit}`);
+    }
+    for (const hit of page.items) {
+        if (typeof hit.sessionId !== "string" || !hit.sessionId) {
+            throw new Error("searchSessions hits must include a non-empty sessionId");
+        }
+        if ("credential" in hit || "apiKey" in hit || "password" in hit) {
+            throw new Error("searchSessions hits must not include credential fields");
+        }
+    }
+    const unscoped = await search({ limit: 100 });
+    const owned = await search({ tenantId: "__missing_tenant__", limit: 100 });
+    if (owned.items.length > unscoped.items.length) {
+        throw new Error("searchSessions ownership filter must not return more hits than an unscoped search");
+    }
+}
 async function assertSessionStoreBranchIsolation(store, options) {
     const sessionId = options.sessionId ?? "conformance";
     const otherSessionId = options.otherSessionId ?? `${sessionId}-other`;

package/docs/agent-loops.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-Agent loops make the agent's per-run turn-control flow a replaceable strategy without forking the runtime. The runtime owns provider calls, retry, abort, store appends, redaction, and event emission; a loop only orchestrates those shared primitives through a `LoopContext`. The default `singleShotLoop` is the former inline turn loop extracted verbatim — assemble → generate → append assistant message → optional tool dispatch → next turn. `generateValidateReviseLoop` is the first alternative loop: generate → parse → validate → revise up to a budget.
+Agent loops make the agent's per-run turn-control flow a replaceable strategy without forking the runtime. The runtime owns provider calls, retry, abort, store appends, redaction, and event emission; a loop only orchestrates those shared primitives through a `LoopContext`. The default `singleShotLoop` is the former inline turn loop extracted verbatim — optional drain pending steers → assemble → generate → append assistant message → optional tool dispatch → next turn (continue while steers remain even if the provider returned no tool calls). `generateValidateReviseLoop` is the first alternative loop: generate → parse → validate → revise up to a budget.
 
 Loops are opt-in. When no `loop` is configured, the runtime runs `singleShotLoop` and behavior is bit-for-bit with the pre-loop runtime.
 
@@ -58,6 +58,7 @@ await session.run(input, {
     repairer: hostRepairer,  // optional; default stringifies validation.errors[].message
     maxRevisions: 3,         // optional; default 3
     toolCalls: "bounded",    // optional; default "disabled"; uses limits.maxToolRounds
+    structuredOutputTiming: "final-turn-only", // optional; default "every-turn"
   },
 });
 
@@ -82,6 +83,10 @@ type AgentLoopOptions =
       readonly maxRevisions?: number;
       /** Default "disabled". "bounded" dispatches sequentially up to limits.maxToolRounds. */
       readonly toolCalls?: "disabled" | "bounded";
+      readonly structuredOutput?: StructuredOutputOptions;
+      readonly structuredOutputMode?: "native" | "artifact-loop";
+      /** Default "every-turn". "final-turn-only" omits schema while tools may run. */
+      readonly structuredOutputTiming?: "every-turn" | "final-turn-only";
     };
 ```
 
@@ -96,6 +101,8 @@ Host callback contracts (all generic over host `T`):
 | `ArtifactContext` | `{ sessionId, runId, turn, signal, metadata }` — passed to every callback. |
 | `ArtifactParseResult<T>` | `{ ok: boolean; value?: T; error?: string }`. |
 
+Optional steer hooks on `LoopContext` (0.0.11): `hasPendingSteers?()` / `applyPendingSteers?()`. Hosts/custom loops that omit them keep pre-steer behavior; built-in loops drain at turn start.
+
 `LoopContext` (what the runtime builds for the loop each run):
 
 | Field | Purpose |

package/docs/agent-session-runtime.md

@@ -78,7 +78,11 @@ Provider `thinking`/`reasoning` content emitted during a turn is preserved as `t
 
 Missing providers fail closed: `run()` emits `error` and rejects before calling any provider. Provider `error` events emit session `error` and reject unless configured retry handles a transient provider-turn failure before output. Unknown tools fail closed through the tool harness and do not execute. Tool exceptions emit `tool_execution_error`, return an error `ToolResult`, and may still continue to the next provider turn.
 
-Only one `run()` may be active per session. Concurrent `run()` calls emit `error` and reject immediately; Prism does not queue them. Manual `compact()` also rejects while a run is active.
+Only one `run()` may be active per session. Concurrent `run()` / `prompt` / `followUp` calls emit `error` and reject immediately; Prism does not queue second prompts. Manual `compact()` also rejects while a run is active.
+
+### Mid-run steer (0.0.11)
+
+`session.steer(input, options?)` enqueues user text into the **same** active run (fail closed when no run). Default: inject at the next turn boundary (after tool rounds / before next provider assemble). `options.softInterrupt: true` aborts only the current provider stream, then continues the same `runId` with steered text. Pending queue caps: **8** messages / **64 KiB** UTF-8 total (`DEFAULT_MAX_PENDING_STEERS` / `DEFAULT_MAX_PENDING_STEER_BYTES`); overflow throws. Steered messages pass input guardrails + normal session append/redaction. Loops drain via optional `LoopContext.hasPendingSteers` / `applyPendingSteers`.
 
 `session.abort(reason)` aborts the active run. The abort signal is passed to input assembly, provider requests, and tool execution; if a tool/provider path aborts after a tool call, Prism does not start another provider turn.
 

package/docs/cli-rpc.md

@@ -106,7 +106,7 @@ Branch-aware session commands return live handle details:
 
 `sessionId` identifies the durable session. `leafId` is the selected branch tip. `handleId` is the RPC map key used by `switchSession`; forks that share the same `sessionId` get stable ids like `session-1#2` so the parent handle is not overwritten.
 
-Invalid CLI flags return exit code `2`. Invalid JSON, missing ids, unknown RPC commands, unsupported `steer`, unknown command contributions, and runtime failures return `ok: false` response envelopes without executing unknown tools or commands.
+Invalid CLI flags return exit code `2`. Invalid JSON, missing ids, unknown RPC commands, unknown command contributions, and runtime failures return `ok: false` response envelopes without executing unknown tools or commands. `steer` with no active run (or overflow) returns `ok: false`.
 
 ## Request/response example
 
@@ -128,6 +128,7 @@ Invalid CLI flags return exit code `2`. Invalid JSON, missing ids, unknown RPC c
 - `state`, `messages`, `setModel`, `switchSession`, `forkSession`, `cloneSession`, `checkout`, and registered `command` requests are processed immediately.
 - `compact` is fail-closed: if the current session has an active run, it returns `ok: false` because the session rejects compaction during a run.
 - A second `prompt` or `followUp` for the same session while it already has an active run returns `ok: false` immediately instead of blocking the input loop.
+- `steer` enqueues mid-run user text for the active session (`params.input`, optional `params.softInterrupt`). Fails closed when no active run or when the pending steer queue overflows (8 messages / 64 KiB). Soft interrupt aborts the current provider stream only; the run continues.
 
 Events streamed during a run keep the original prompt request id, even when an `abort` with a different request id cancels the run. The completion or error response for the prompt also uses the original prompt request id.
 

package/docs/coding-agent-tools.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-coding-agent` is an optional first-party package that provides host shell/filesystem/repository tools as Prism `ToolDefinition` objects. It ships six default coding tools — `shell`, `read`, `write`, `edit`, `repo_list`, `repo_search` — plus an opt-in structured Git/check set (`createGitTools`) for status/diff/branch/worktree/apply/commit/PR-handoff and named checks. Bounded coding-plan/checkpoint helpers compose ordinary workspace Markdown with workflow checkpoint state (references/hashes/summaries/fingerprints only). The tools are **inert** until a host imports them and registers them into a `ToolRegistry`. Behavior for shell/read/write/edit is a behavioral port of the pi coding agent's tools, adapted to Prism's `ToolDefinition` / `ToolResult` contracts (no `@earendil-works/*` or `typebox` dependencies; only `diff` plus the Node standard library). List/search/Git are native Prism tools with no glob/ripgrep/Git-library dependency.
+`@arnilo/prism-coding-agent` is an optional first-party package that provides host shell/filesystem/repository tools as Prism `ToolDefinition` objects. It ships six default coding tools — `shell`, `read`, `write`, `edit`, `repo_list`, `repo_search` — plus opt-in structured Git/check set (`createGitTools`), opt-in `createAskUserDecisionTool({ ask })`, and bounded coding-plan/checkpoint helpers. The tools are **inert** until a host imports them and registers them into a `ToolRegistry`. Hosts may register any subset, omit aggregators entirely, or mix first-party tools with host-owned `ToolDefinition`s. Behavior for shell/read/write/edit is a behavioral port of the pi coding agent's tools, adapted to Prism's `ToolDefinition` / `ToolResult` contracts (no `@earendil-works/*` or `typebox` dependencies; only `diff` plus the Node standard library). List/search/Git are native Prism tools with no glob/ripgrep/Git-library dependency.
 
 | Export | Purpose |
 | --- | --- |
@@ -17,6 +17,7 @@
 | `createAllTools(cwd, options?)` | Identical to `createCodingTools` (Git tools remain opt-in via `createGitTools`). |
 | `createGitTools(cwd, options?)` | Opt-in Git tools (`git_status`/`git_diff`/`git_branch`/`git_worktree`/`git_apply`/`git_commit`/`git_pr_handoff`) plus optional `coding_check`. |
 | `createCodingCheckTool(cwd, options)` | Named host-declared checks; model selects only a name. |
+| `createAskUserDecisionTool(options)` | Opt-in user decision tool (`ask_user_decision`); host supplies `ask` callback. Not in default aggregators. |
 | `createLocalRepositoryOperations(limits?)` | Default streaming Node filesystem backend for list/search. |
 | `createGitOperations(options)` | Typed Git operations backend (argument arrays, safe config, finite output). |
 | `buildCodingCheckpointMetadata` / `validateCodingCheckpointMetadata` / `assertCodingResumeAllowed` | Bounded durable coding-task metadata for workflow `state.coding` (no second runtime). |
@@ -231,6 +232,72 @@ const gitTools = createGitTools(workspaceRoot, {
 });
 ```
 
+### Ask-user decision (`createAskUserDecisionTool`)
+
+Opt-in `ask_user_decision` for ambiguous, high-impact direction choices. Model must pass a question plus 2+ options, each with **exactly 3 pros and 3 cons**. Host supplies `ask` (blocks until the user picks). Not in `createCodingTools` / `createAllTools` / `createReadOnlyTools`.
+
+| Mode | How |
+| --- | --- |
+| Single (default) | `selectionMode: "single"` → host returns `{ selectedId }` (or length-1 `selectedIds`) |
+| Multi | `selectionMode: "multiple"` → `{ selectedIds: [...] }` (non-empty, known ids) |
+| Free-text | `allowCustom: true` → host may return `{ customText }` **XOR** selection (never both) |
+| Blocking tool | `createAskUserDecisionTool({ ask })` — in-process UI callback |
+| Durable workflow | `suspendAskUserDecision(request)` + `createAskUserDecisionResumeValidator()` / `validateAskUserDecisionResume` on `resumeWorkflow` |
+| Agent durable adapter | `validateAskUserDecisionAgentResume({ request, answer })` — same validation; **no** new `AgentRunInterruption` kinds in 0.0.11 |
+
+Custom-text caps match question defaults (2 KiB / hard 8 KiB). Options default max 6 (hard 16).
+
+```ts
+import { createToolRegistry } from "@arnilo/prism";
+import {
+  createAskUserDecisionTool,
+  createCodingTools,
+  suspendAskUserDecision,
+  createAskUserDecisionResumeValidator,
+} from "@arnilo/prism-coding-agent";
+
+const tools = createToolRegistry([
+  ...createCodingTools(workspaceRoot),
+  createAskUserDecisionTool({
+    ask: async ({ question, options, selectionMode, allowCustom }) =>
+      ui.ask({ question, options, selectionMode, allowCustom }),
+  }),
+]);
+
+// Workflow node:
+return suspendAskUserDecision({
+  question: "Ship sqlite or postgres?",
+  options: [/* ≥2 with 3 pros + 3 cons each */],
+  selectionMode: "single",
+  allowCustom: false,
+});
+// resumeWorkflow(..., { validateResume: createAskUserDecisionResumeValidator() })
+```
+
+### Goal → verify helper (`runCodingGoalVerify`)
+
+Thin composition over existing plan Markdown, named checks, workflow `suspend`/`resumeWorkflow`, and bounded PR handoff. **No Goal table / second runtime.** Peer `@arnilo/prism-workflows`. Example: `examples/coding-goal-verify.ts`.
+
+```ts
+import { runCodingGoalVerify } from "@arnilo/prism-coding-agent";
+
+const result = await runCodingGoalVerify({
+  goal: "Fix the flake",
+  cwd: process.cwd(),
+  taskId: "flake-1",
+  baseBranch: "main",
+  branch: "fix/flake",
+  checkNames: ["test"],
+  checkDefinitions: { test: { file: "/usr/bin/npm", args: ["test"] } },
+  runCheck: hostRunCheck,
+  buildHandoff: hostBuildHandoff,
+  approval: { validateResume: hostValidate },
+  checkpoints,
+  ownership,
+  redactor,
+});
+```
+
 ### Durable coding plans and checkpoints
 
 There is no `CodingRun`, todo database, or second approval engine. Persist executable plan/todos as ordinary workspace Markdown (for example `plans/<task>.md`) and store only bounded metadata under workflow `state.coding`:

package/docs/evaluations.md

@@ -152,5 +152,5 @@ Fixtures reuse `@arnilo/prism-evals` (`defineDataset` / `defineScorer` / `scoreR
 - [Runs and usage ledger](runs-and-usage.md): run/session identity for score linkage
 - [Observability](observability.md): use `onTraceReference` or bounded `traceId(runId)` to supply `ScoreRunOptions.traceId`; evaluation telemetry emits no reason/explanation content
 - [Coding agent tools](coding-agent-tools.md) / [Browser automation](browser-automation.md) / [Workflows](workflows.md): network-free coding-task composition at `examples/durable-coding-workflow.ts`; adversarial coding/browser eval example at `examples/coding-browser-evaluation.ts`
-- [Performance limits](performance.md): `scripts/benchmark-0.0.10.mjs` workspace-mode evidence and `scripts/benchmark-0.0.9.mjs` coding/browser evidence fields
+- [Performance limits](performance.md): `scripts/benchmark-0.0.11.mjs` search/budget evidence, `scripts/benchmark-0.0.10.mjs` workspace-mode evidence, and `scripts/benchmark-0.0.9.mjs` coding/browser evidence fields
 - [Release and install](release-and-install.md): optional package install and protected sandbox-browser workflow