@arnilo/prism 0.0.10 → 0.0.12

package/dist/input.js

@@ -3,22 +3,12 @@ import { assertMessagesSupportModelCapabilities } from "./content.js";
 import { loadTextResource } from "./resources.js";
 import { composeSystemPrompt } from "./system-prompts.js";
 import { runInstructionInjectors } from "./instruction-injection.js";
+import { applyContextBudget, CONTEXT_BUDGET_REPORT_METADATA_KEY, } from "./context-budget.js";
 export function createDefaultInputBuilder() {
     return {
         name: "default-input",
         async build(input, context = {}) {
-            const groups = {
-                instructions: [
-                    ...instructionMessages(context.systemInstructions, "System instruction"),
-                    ...instructionMessages(context.developerInstructions, "Developer instruction"),
-                    ...customInstructionMessages(context.instructions),
-                ],
-                summaries: summaryMessages(context.summaries),
-                history: [...(context.history ?? [])],
-                input: inputMessages(input),
-                attachments: await attachmentMessages(context),
-                toolResults: toolResultMessages(context.toolResults),
-            };
+            const groups = await buildDefaultInputMessageGroups(input, context);
             const messages = flattenInputGroups(groups, context.inputLayout ?? "legacy");
             return context.middleware ? context.middleware.run("input_assembly", messages) : messages;
         },
@@ -65,7 +55,6 @@ export function renderPromptTemplate(template, variables, options = {}) {
     });
 }
 export async function assembleProviderInput(options) {
-    const inputBuilder = options.inputBuilder ?? createDefaultInputBuilder();
     const baseContext = {
         sessionId: options.sessionId,
         runId: options.runId,
@@ -92,44 +81,98 @@ export async function assembleProviderInput(options) {
         ? composeSystemPrompt(injectorContribs.instructions, { base: options.systemInstructions })
         : options.systemInstructions;
     const buildContext = { ...options, ...baseContext, systemInstructions };
-    const messages = await inputBuilder.build(options.input, buildContext);
-    const context = await resolveContextProviders({
-        providers: options.contextProviders,
-        messages,
-        injectedBlocks: injectorContribs.contextBlocks.length ? injectorContribs.contextBlocks : undefined,
-        middleware: options.middleware,
-        ...baseContext,
-    });
+    const layout = buildContext.inputLayout ?? "legacy";
+    let messages;
+    let context;
+    let skills = options.skills;
+    let tools = options.tools;
+    let budgetReport;
+    if (options.contextBudget) {
+        // ponytail: budget path always uses default groups so eviction kinds stay deterministic;
+        // custom inputBuilder still honored when contextBudget is absent.
+        const groups = await buildDefaultInputMessageGroups(options.input, buildContext);
+        context = await resolveContextProviders({
+            providers: options.contextProviders,
+            messages: flattenInputGroups(groups, layout),
+            injectedBlocks: injectorContribs.contextBlocks.length ? injectorContribs.contextBlocks : undefined,
+            middleware: options.middleware,
+            ...baseContext,
+        });
+        const applied = applyContextBudget({
+            groups,
+            context,
+            skills: skills ?? [],
+            tools,
+            budget: options.contextBudget,
+            layout,
+        });
+        messages = flattenInputGroups(applied.groups, layout);
+        if (buildContext.middleware)
+            messages = await buildContext.middleware.run("input_assembly", messages);
+        context = applied.context;
+        skills = applied.skills;
+        tools = applied.tools;
+        if (options.contextBudget.reportOmissions)
+            budgetReport = applied.report;
+    }
+    else {
+        const inputBuilder = options.inputBuilder ?? createDefaultInputBuilder();
+        messages = await inputBuilder.build(options.input, buildContext);
+        context = await resolveContextProviders({
+            providers: options.contextProviders,
+            messages,
+            injectedBlocks: injectorContribs.contextBlocks.length ? injectorContribs.contextBlocks : undefined,
+            middleware: options.middleware,
+            ...baseContext,
+        });
+    }
     const promptBuilder = options.promptBuilder ?? createDefaultPromptBuilder();
     const promptRequest = options.middleware
         ? await options.middleware.run("prompt_build", {
             messages,
             context,
-            skills: options.skills,
-            tools: options.tools,
+            skills,
+            tools,
             metadata: options.metadata,
             signal: options.signal,
         })
         : {
             messages,
             context,
-            skills: options.skills,
-            tools: options.tools,
+            skills,
+            tools,
             metadata: options.metadata,
             signal: options.signal,
         };
-    const providerMessages = await promptBuilder.build({ ...promptRequest, tools: options.tools });
+    const providerMessages = await promptBuilder.build({ ...promptRequest, tools });
     assertMessagesSupportModelCapabilities(options.model, providerMessages);
+    const metadata = budgetReport
+        ? { ...options.metadata, [CONTEXT_BUDGET_REPORT_METADATA_KEY]: budgetReport }
+        : options.metadata;
     return {
         model: options.model,
         messages: providerMessages,
-        tools: options.tools,
+        tools,
         context,
         options: options.providerOptions,
-        metadata: options.metadata,
+        metadata,
         signal: options.signal,
     };
 }
+async function buildDefaultInputMessageGroups(input, context) {
+    return {
+        instructions: [
+            ...instructionMessages(context.systemInstructions, "System instruction"),
+            ...instructionMessages(context.developerInstructions, "Developer instruction"),
+            ...customInstructionMessages(context.instructions),
+        ],
+        summaries: summaryMessages(context.summaries),
+        history: [...(context.history ?? [])],
+        input: inputMessages(input),
+        attachments: await attachmentMessages(context),
+        toolResults: toolResultMessages(context.toolResults),
+    };
+}
 function flattenInputGroups(groups, layout) {
     switch (layout) {
         case "cache_aware":

package/dist/node/session-store-jsonl.js

@@ -1,6 +1,6 @@
 import { mkdir, readFile, appendFile } from "node:fs/promises";
 import { dirname } from "node:path";
-import { SESSION_APPEND_CONFLICT_CODE, SessionAppendConflictError, isSessionEntryKind, SESSION_ENTRY_SCHEMA_VERSION } from "../contracts.js";
+import { SESSION_APPEND_CONFLICT_CODE, SessionAppendConflictError, SessionSearchUnsupportedError, isSessionEntryKind, SESSION_ENTRY_SCHEMA_VERSION, } from "../contracts.js";
 import { isNodeErrorCode } from "./config.js";
 export function createJsonlSessionStore(pathOrOptions) {
     const options = typeof pathOrOptions === "string" ? { path: pathOrOptions, createDirectory: true } : pathOrOptions;
@@ -46,6 +46,9 @@ export function createJsonlSessionStore(pathOrOptions) {
         async get(id) {
             return findEntry(path, id);
         },
+        async searchSessions() {
+            throw new SessionSearchUnsupportedError("JSONL session store does not support searchSessions");
+        },
     };
 }
 /** Read a JSONL session file and return both valid entries and per-line parse errors. */

package/dist/rpc.js

@@ -82,8 +82,19 @@ async function handleRequest(request, state, stdout, activeRuns) {
             activeRuns.set(session.id, { requestId: request.id, promise });
             break;
         }
-        case "steer":
-            throw new Error("steer is not supported by the current AgentSession runtime");
+        case "steer": {
+            const input = stringParam(request.params, "input") ?? stringParam(request.params, "prompt");
+            if (!input)
+                throw new Error("steer requires params.input");
+            const softInterrupt = request.params?.softInterrupt === true;
+            state.current.steer(input, softInterrupt ? { softInterrupt: true } : undefined);
+            write(stdout, {
+                id: request.id,
+                ok: true,
+                result: { sessionId: state.current.id },
+            });
+            break;
+        }
         case "abort":
             state.current.abort(stringParam(request.params, "reason"));
             write(stdout, { id: request.id, ok: true, result: { sessionId: state.current.id } });

package/dist/session-stores.d.ts

@@ -1,4 +1,4 @@
-import type { Message, SessionBranchRead, BranchReader, SessionEntry, SessionStore } from "./contracts.js";
+import { type Message, type SessionBranchRead, type BranchReader, type SessionEntry, type SessionStore } from "./contracts.js";
 export interface CreateSessionEntryOptions extends Omit<SessionEntry, "id" | "timestamp"> {
     readonly id?: string;
     readonly timestamp?: string;
@@ -24,4 +24,9 @@ export declare function getSessionBranchEntries(entries: readonly SessionEntry[]
 export declare function listSessionBranches(entries: readonly SessionEntry[]): readonly SessionBranch[];
 export declare function rebuildSessionContext(reader: BranchReader, query: SessionBranchRead): Promise<SessionContextSnapshot>;
 export declare function rebuildSessionContext(entries: readonly SessionEntry[], options?: SessionBranchOptions): SessionContextSnapshot;
-export declare function createMemorySessionStore(initialEntries?: readonly SessionEntry[]): SessionStore;
+export type MemorySessionSearchMode = "linear" | "unsupported";
+export interface CreateMemorySessionStoreOptions {
+    /** Default `"linear"`: capped in-process scan. `"unsupported"`: typed throw. */
+    readonly sessionSearchMode?: MemorySessionSearchMode;
+}
+export declare function createMemorySessionStore(initialEntries?: readonly SessionEntry[], options?: CreateMemorySessionStoreOptions): SessionStore;

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/a2a.md

@@ -92,3 +92,4 @@ Defaults/hard caps include: request 64 KiB/1 MiB; response 1/8 MiB; event 64 KiB
 - [Agent/session runtime](agent-session-runtime.md)
 - [Workflows](workflows.md)
 - [Host security](host-security.md)
+- [Frontend interoperability (AG-UI and ACP)](ag-ui.md): browser/editor protocol adapters over a Prism session; not an A2A card, task lifecycle, or remote-agent transport.