@arnilo/prism 0.3.1 → 0.4.0

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 = 8;
+export const PERSISTENCE_SCHEMA_VERSION = 9;
 /** 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 = [
@@ -157,6 +157,7 @@ export function createPersistenceSchemaModel() {
                     { name: "error", type: "json", nullable: true },
                     ...TENANT_COLUMNS,
                     { name: "metadata", type: "json", nullable: true },
+                    { name: "prompt_version", type: "json", nullable: true },
                 ],
                 foreignKeys: [{ columns: ["session_id"], referencesTable: "prism_sessions", referencesColumns: ["id"] }],
             },
@@ -502,33 +503,35 @@ function migrationStep(version, name, description) {
             ? { indexes: ["prism_agent_events_owner_timestamp_sequence_idx"] }
             : version === 8
                 ? { table: "prism_sessions", columns: ["version"] }
-                : version === 6
-                    ? {
-                        tables: ["prism_agent_event_streams"],
-                        indexes: ["prism_agent_events_run_sequence_idx"],
-                    }
-                    : version === 2
-                        ? { table: "prism_usage", columns: ["scope", "turn", "attempt"], indexes: ["prism_usage_session_scope_recorded_idx"] }
-                        : 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"] }
-                                : version === 5
-                                    ? {
-                                        tables: ["prism_legal_holds", "prism_tenant_quotas"],
-                                        indexes: [
-                                            "prism_legal_holds_owner_resource_idx",
-                                            "prism_legal_holds_created_id_idx",
-                                            "prism_tenant_quotas_owner_kind_idx",
-                                        ],
-                                    }
-                                    : (() => {
-                                        throw new Error(`Unknown migration version ${version}`);
-                                    })();
+                : version === 9
+                    ? { table: "prism_runs", columns: ["prompt_version"] }
+                    : version === 6
+                        ? {
+                            tables: ["prism_agent_event_streams"],
+                            indexes: ["prism_agent_events_run_sequence_idx"],
+                        }
+                        : version === 2
+                            ? { table: "prism_usage", columns: ["scope", "turn", "attempt"], indexes: ["prism_usage_session_scope_recorded_idx"] }
+                            : 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"] }
+                                    : version === 5
+                                        ? {
+                                            tables: ["prism_legal_holds", "prism_tenant_quotas"],
+                                            indexes: [
+                                                "prism_legal_holds_owner_resource_idx",
+                                                "prism_legal_holds_created_id_idx",
+                                                "prism_tenant_quotas_owner_kind_idx",
+                                            ],
+                                        }
+                                        : (() => {
+                                            throw new Error(`Unknown migration version ${version}`);
+                                        })();
     return {
         version,
         name,
@@ -550,6 +553,7 @@ export function createPersistenceMigrationContract() {
             migrationStep(6, "006_agent_event_source", "Add transactional per-run event counters and unique durable event sequencing."),
             migrationStep(7, "007_agent_event_retention_index", "Add an exact-owner durable-event retention cleanup index."),
             migrationStep(8, "008_session_version", "Add a NOT NULL DEFAULT 0 version column to prism_sessions for appendSession metadata CAS."),
+            migrationStep(9, "009_run_prompt_version", "Add a nullable prompt_version JSON provenance ref column to prism_runs."),
         ],
         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/tool-conformance.d.ts

@@ -37,3 +37,28 @@ export declare function dispatchAndCollect(probe: ToolDispatchProbeOptions): Pro
     result: ToolResult;
     events: AgentEvent[];
 }>;
+export interface ToolDisclosureConformanceOptions {
+    /** Host-active tool definitions; may include schema-bearing and oversized-description tools. */
+    readonly tools: readonly ToolDefinition[];
+    /** Host allow/deny bounds applied before disclosure (same input the runtime narrows). */
+    readonly filter?: ToolFilterInput;
+    /** Search options under test (topK). */
+    readonly search?: {
+        readonly topK?: number;
+    };
+    /** Turn text used for the relevance query. Defaults to a zero-match probe. */
+    readonly input?: string;
+    /** Secret values that must never appear in model-facing search output. */
+    readonly secrets?: readonly (string | undefined)[];
+}
+/**
+ * Assert the tool-disclosure contract (plan 041) against the same narrowing the
+ * runtime applies: search mode only narrows (disclosed set is a subset of the
+ * allow/deny-filtered input, never wider, never zero, deterministic order); a
+ * denied tool is never described; the generated `search_tools` tool is always
+ * kept and its output is inert — names plus byte-truncated descriptions only,
+ * no JSON structure, no secret values — and activation stays disclosed beside
+ * the turn top-k next turn. Fails closed: an index over the hard cap discloses
+ * the full eligible list. Throws on the first violation.
+ */
+export declare function assertToolDisclosureConforms(options: ToolDisclosureConformanceOptions): void;

package/dist/testing/tool-conformance.js

@@ -7,7 +7,8 @@
 // Error; no test runner, no network. Execution is observed via the
 // tool_execution_started / tool_execution_blocked events the runtime emits,
 // not by mutating the caller's tool.
-import { dispatchToolCall } from "../tools.js";
+import { createActiveToolSet, createSearchToolsTool, createToolSearchState, HARD_MAX_TOOLS_INDEX, SEARCH_TOOLS_TOOL_NAME, selectDisclosedTools, } from "../tool-search.js";
+import { dispatchToolCall, filterTools } from "../tools.js";
 const denyAllPermission = { check: () => ({ allowed: false, reason: "denied" }) };
 const alwaysInvalidValidator = () => "invalid";
 /**
@@ -98,7 +99,133 @@ export async function dispatchAndCollect(probe) {
     });
     return { result, events };
 }
+/**
+ * Assert the tool-disclosure contract (plan 041) against the same narrowing the
+ * runtime applies: search mode only narrows (disclosed set is a subset of the
+ * allow/deny-filtered input, never wider, never zero, deterministic order); a
+ * denied tool is never described; the generated `search_tools` tool is always
+ * kept and its output is inert — names plus byte-truncated descriptions only,
+ * no JSON structure, no secret values — and activation stays disclosed beside
+ * the turn top-k next turn. Fails closed: an index over the hard cap discloses
+ * the full eligible list. Throws on the first violation.
+ */
+export function assertToolDisclosureConforms(options) {
+    const eligible = filterTools(options.tools, options.filter);
+    if (eligible.length === 0)
+        throw new Error("Disclosure conformance needs at least one eligible tool");
+    const activated = createActiveToolSet();
+    const topK = options.search?.topK ?? 16;
+    const state = createToolSearchState({ tools: eligible, activated, search: options.search });
+    const searchTool = createSearchToolsTool(state);
+    const runTools = [...eligible, searchTool];
+    const input = options.input ?? "zzzqqq unmatchable zero-match probe";
+    // 1. Narrowing stays a subset of the eligible list and always keeps search_tools.
+    const disclosed = selectDisclosedTools({ tools: runTools, input, search: options.search, activated });
+    const eligibleNames = new Set(eligible.map((tool) => tool.name));
+    eligibleNames.add(SEARCH_TOOLS_TOOL_NAME);
+    for (const tool of disclosed) {
+        if (!eligibleNames.has(tool.name)) {
+            throw new Error(`Disclosed tool ${tool.name} is not in the eligible list; search must never widen`);
+        }
+    }
+    if (!disclosed.some((tool) => tool.name === SEARCH_TOOLS_TOOL_NAME)) {
+        throw new Error("Disclosed set dropped the generated search_tools tool");
+    }
+    if (disclosed.length === 0)
+        throw new Error("Disclosure disclosed zero tools; fail closed to a bounded non-empty set");
+    // 2. A deny-listed tool is never described to the provider.
+    const deniedName = eligible[0].name;
+    const deniedDisclosed = selectDisclosedTools({
+        tools: filterTools(runTools, { deny: [deniedName] }),
+        input,
+        search: options.search,
+        activated,
+    });
+    if (deniedDisclosed.some((tool) => tool.name === deniedName)) {
+        throw new Error(`Denied tool ${deniedName} was described to the provider`);
+    }
+    // 3. Deterministic order for identical turns.
+    const again = selectDisclosedTools({ tools: runTools, input, search: options.search, activated });
+    if (JSON.stringify(again.map((tool) => tool.name)) !== JSON.stringify(disclosed.map((tool) => tool.name))) {
+        throw new Error("Disclosure order is not deterministic for identical turns");
+    }
+    // 4. Fail closed past the index hard cap: full eligible list, never zero, never wider.
+    const oversized = Array.from({ length: HARD_MAX_TOOLS_INDEX + 1 }, (_, index) => ({
+        name: `cap_${index}`,
+        description: "Fixture tool beyond the frozen index cap.",
+        parameters: { type: "object", properties: {} },
+        execute: () => ({ toolCallId: "x", name: "cap" }),
+    }));
+    const overflowed = selectDisclosedTools({ tools: oversized, input, search: options.search });
+    if (overflowed.length !== oversized.length) {
+        throw new Error(`Index overflow must disclose the full list; disclosed ${overflowed.length} of ${oversized.length}`);
+    }
+    // 5. search_tools output is inert: names + byte-truncated descriptions, no JSON
+    //    structure, no secret values; activation bounded to the eligible set.
+    const oversizedDescription = `${"padding ".repeat(160)}TAIL-MARKER-BEYOND-TRUNCATION`;
+    const probeEligible = [
+        ...eligible,
+        {
+            name: "oversized_desc_tool",
+            description: oversizedDescription,
+            parameters: { type: "object", properties: { untrusted: { type: "string" } } },
+            execute: () => ({ toolCallId: "x", name: "oversized_desc_tool" }),
+        },
+    ];
+    const probeState = createToolSearchState({ tools: probeEligible, activated, search: options.search });
+    const probeTool = createSearchToolsTool(probeState);
+    const probeResult = probeTool.execute({ query: "oversized_desc_tool" }, context("probe"));
+    if (probeResult.error)
+        throw new Error(`search_tools rejected a valid bounded query: ${probeResult.error.message}`);
+    const text = probeResult.content?.find((block) => block.type === "text");
+    if (text?.type !== "text" || !text.text.startsWith("- ")) {
+        throw new Error("search_tools returned no bounded name+description lines");
+    }
+    if (text.text.includes("TAIL-MARKER-BEYOND-TRUNCATION")) {
+        throw new Error("search_tools emitted an untruncated oversized description; descriptions are truncated, descriptions are never executed");
+    }
+    if (/[{}]/.test(text.text)) {
+        throw new Error("search_tools text carries JSON structure; output must be inert name+description lines only");
+    }
+    const activatedCount = activated.list().length;
+    if (activatedCount === 0 || activatedCount > topK)
+        throw new Error(`activation not bounded: ${activatedCount} names`);
+    const probeNames = new Set(probeEligible.map((tool) => tool.name));
+    for (const name of activated.list()) {
+        if (!probeNames.has(name))
+            throw new Error(`activated ${name} is not in the eligible set`);
+    }
+    // 5b. Secret scan: query every eligible tool by name; configured secret values
+    //     must never surface in model-facing search output even when a host
+    //     description carries one.
+    for (const tool of eligible) {
+        const probe = probeTool.execute({ query: tool.name }, context("probe-secret"));
+        const probeBlob = JSON.stringify(probe);
+        for (const secret of options.secrets ?? []) {
+            if (secret && probeBlob.includes(secret)) {
+                throw new Error("search output leaked a configured secret");
+            }
+        }
+    }
+    // 6. Activated tools stay disclosed on the next turn, beside the turn top-k.
+    //    (Names outside the runtime list are inert by design — e.g. the probe's
+    //    synthetic tool above — so only eligible names are asserted.)
+    const nextTurn = selectDisclosedTools({
+        tools: runTools,
+        input: "zzzqqq unmatchable next-turn probe",
+        search: options.search,
+        activated,
+    });
+    for (const name of activated.list()) {
+        if (eligibleNames.has(name) && !nextTurn.some((tool) => tool.name === name)) {
+            throw new Error(`activated tool ${name} was dropped from the next turn's disclosed set`);
+        }
+    }
+}
 function pickPolicy(options) {
     return { permission: options.permission, validate: options.validate, filter: options.filter };
 }
+function context(toolCallId) {
+    return { sessionId: "conformance", runId: "r", toolCallId };
+}
 //# sourceMappingURL=tool-conformance.js.map

package/dist/tool-search.d.ts

@@ -0,0 +1,76 @@
+import type { Message, ToolDefinition } from "./contracts.js";
+/** Same shape as `AgentInput`; kept structural here so core's assembler and this module never form a runtime cycle. */
+type ToolSearchInput = string | Message | readonly Message[];
+export type ToolsDisclosure = "all" | "search";
+export interface ToolsSearchOptions {
+    /** Top-k tools disclosed per turn. Default 16; clamped to the hard cap. */
+    readonly topK?: number;
+}
+export declare const SEARCH_TOOLS_TOOL_NAME = "search_tools";
+export declare const DEFAULT_TOOLS_SEARCH_TOP_K = 16;
+export declare const HARD_MAX_TOOLS_SEARCH_TOP_K = 64;
+/** Frozen index cap; larger registries fail closed to full disclosure. */
+export declare const HARD_MAX_TOOLS_INDEX = 1024;
+export declare const DEFAULT_MAX_TOOLS_SEARCH_QUERY_BYTES = 4096;
+export declare const HARD_MAX_TOOLS_SEARCH_QUERY_BYTES = 65536;
+export declare const TOOL_DISCLOSURE_ERROR_CODE: "tool_disclosure_exceeded";
+export declare class ToolDisclosureError extends Error {
+    readonly code: "tool_disclosure_exceeded";
+    constructor(message: string);
+}
+export declare function isToolDisclosureError(error: unknown): error is ToolDisclosureError;
+/** Run options win over agent config (mirrors resolveSkillsDisclosure); default "all". */
+export declare function resolveToolsDisclosure(run?: ToolsDisclosure, agent?: ToolsDisclosure): ToolsDisclosure;
+/** Activation set: same shape as LoadedSkillSet (names-only persistence, per-session instance). */
+export interface ActiveToolSet {
+    has(name: string): boolean;
+    add(name: string): void;
+    list(): readonly string[];
+    clear(): void;
+}
+export declare function createActiveToolSet(): ActiveToolSet;
+interface PostingEntry {
+    readonly toolIndex: number;
+    tf: number;
+}
+export interface ToolSearchIndex {
+    readonly tools: readonly ToolDefinition[];
+    readonly postings: ReadonlyMap<string, PostingEntry[]>;
+}
+/** ponytail: O(n·d) lexical index, rebuilt on registry change by the caller — embedder-backed
+ *  scoring via the @arnilo/prism-memory/rag seam if accuracy fixtures fall short (plan 041). */
+export declare function createToolSearchIndex(tools: readonly ToolDefinition[], skip?: (tool: ToolDefinition) => boolean): ToolSearchIndex;
+export interface ToolSearchMatch {
+    readonly name: string;
+    readonly description?: string;
+    /** Query terms present in name/description, most significant first. */
+    readonly matched: readonly string[];
+}
+/** Bounded lexical scoring: BM25-lite (tf × IDF, registry-derived DF). Ties keep registry order. */
+export declare function scoreTools(index: ToolSearchIndex, query: string, k: number, queryByteCap?: number): readonly ToolSearchMatch[];
+export interface ToolSearchState {
+    readonly index: ToolSearchIndex;
+    readonly activated: ActiveToolSet;
+    readonly topK: number;
+}
+export declare function createToolSearchState(options: {
+    readonly tools: readonly ToolDefinition[];
+    readonly activated: ActiveToolSet;
+    readonly search?: ToolsSearchOptions;
+}): ToolSearchState;
+/** Provider-facing narrowing: activated tools ∪ top-k for the turn. Fails closed — any
+ *  scoring/index error discloses the full input list (never zero, never wider than input). */
+export declare function selectDisclosedTools(options: {
+    readonly tools: readonly ToolDefinition[];
+    readonly input: ToolSearchInput;
+    readonly queryByteCap?: number;
+    readonly search?: ToolsSearchOptions;
+    readonly activated?: {
+        has(name: string): boolean;
+    };
+}): readonly ToolDefinition[];
+/** Model-facing activation tool, generated only in search mode. Results are inert
+ *  name+description lines — no schemas or bodies — and activation re-checks allow/deny
+ *  at dispatch time (blocked-reason matrix unchanged). */
+export declare function createSearchToolsTool(state: ToolSearchState, queryByteCap?: number): ToolDefinition;
+export {};

package/dist/tool-search.js

@@ -0,0 +1,199 @@
+export const SEARCH_TOOLS_TOOL_NAME = "search_tools";
+export const DEFAULT_TOOLS_SEARCH_TOP_K = 16;
+export const HARD_MAX_TOOLS_SEARCH_TOP_K = 64;
+/** Frozen index cap; larger registries fail closed to full disclosure. */
+export const HARD_MAX_TOOLS_INDEX = 1024;
+export const DEFAULT_MAX_TOOLS_SEARCH_QUERY_BYTES = 4_096;
+export const HARD_MAX_TOOLS_SEARCH_QUERY_BYTES = 65_536;
+export const TOOL_DISCLOSURE_ERROR_CODE = "tool_disclosure_exceeded";
+export class ToolDisclosureError extends Error {
+    code = TOOL_DISCLOSURE_ERROR_CODE;
+    constructor(message) {
+        super(message);
+        this.name = "ToolDisclosureError";
+    }
+}
+export function isToolDisclosureError(error) {
+    return error instanceof Error && error.code === TOOL_DISCLOSURE_ERROR_CODE;
+}
+/** Run options win over agent config (mirrors resolveSkillsDisclosure); default "all". */
+export function resolveToolsDisclosure(run, agent) {
+    return run ?? agent ?? "all";
+}
+export function createActiveToolSet() {
+    const names = new Set();
+    return {
+        has(name) {
+            return names.has(name);
+        },
+        add(name) {
+            names.add(name);
+        },
+        list() {
+            return [...names];
+        },
+        clear() {
+            names.clear();
+        },
+    };
+}
+/** Fixed tokenization: lowercase alphanumeric runs. No user-controlled regex anywhere. */
+const WORD_SPLIT = /[^a-z0-9]+/;
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(WORD_SPLIT)
+        .filter((token) => token.length > 0);
+}
+/** ponytail: O(n·d) lexical index, rebuilt on registry change by the caller — embedder-backed
+ *  scoring via the @arnilo/prism-memory/rag seam if accuracy fixtures fall short (plan 041). */
+export function createToolSearchIndex(tools, skip) {
+    if (tools.length > HARD_MAX_TOOLS_INDEX) {
+        throw new ToolDisclosureError(`Tool index exceeds hard cap (${HARD_MAX_TOOLS_INDEX} tools)`);
+    }
+    const postings = new Map();
+    for (const [toolIndex, tool] of tools.entries()) {
+        if (skip?.(tool))
+            continue;
+        // Name tokens weigh ×3 so an exact name match outranks description-only matches.
+        const seen = new Map();
+        for (const term of [...tokenize(tool.name), ...tokenize(tool.name), ...tokenize(tool.name), ...tokenize(tool.description ?? "")]) {
+            seen.set(term, (seen.get(term) ?? 0) + 1);
+        }
+        for (const [term, tf] of seen) {
+            const list = postings.get(term) ?? [];
+            list.push({ toolIndex, tf });
+            postings.set(term, list);
+        }
+    }
+    return { tools, postings };
+}
+/** Bounded lexical scoring: BM25-lite (tf × IDF, registry-derived DF). Ties keep registry order. */
+export function scoreTools(index, query, k, queryByteCap = DEFAULT_MAX_TOOLS_SEARCH_QUERY_BYTES) {
+    const bounded = query.slice(0, Math.trunc(queryByteCap));
+    const terms = tokenize(bounded);
+    if (terms.length === 0 || k <= 0 || index.tools.length === 0)
+        return [];
+    const limit = Math.min(Math.trunc(k), index.tools.length);
+    const total = index.tools.filter((tool) => tool.name !== SEARCH_TOOLS_TOOL_NAME).length;
+    const scores = new Array(index.tools.length).fill(0);
+    const matchedTerms = new Map();
+    for (const term of new Set(terms)) {
+        const list = index.postings.get(term);
+        if (!list)
+            continue;
+        const idf = 1 + Math.log(total / list.length);
+        for (const entry of list) {
+            scores[entry.toolIndex] += entry.tf * idf;
+            const names = matchedTerms.get(entry.toolIndex) ?? [];
+            if (names.length < 8)
+                names.push(term);
+            matchedTerms.set(entry.toolIndex, names);
+        }
+    }
+    const ranked = scores
+        .map((score, toolIndex) => ({ score, toolIndex }))
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score || a.toolIndex - b.toolIndex)
+        .slice(0, limit);
+    return ranked.map(({ toolIndex }) => ({
+        name: index.tools[toolIndex].name,
+        description: index.tools[toolIndex].description,
+        matched: matchedTerms.get(toolIndex) ?? [],
+    }));
+}
+export function createToolSearchState(options) {
+    const requested = options.search?.topK;
+    const topK = requested === undefined ? DEFAULT_TOOLS_SEARCH_TOP_K : Math.min(Math.max(1, Math.trunc(requested)), HARD_MAX_TOOLS_SEARCH_TOP_K);
+    // ponytail: index built once per run; mid-run registry mutation is not observed — rebuild by starting a new run.
+    const index = createToolSearchIndex(options.tools, (tool) => tool.name === SEARCH_TOOLS_TOOL_NAME);
+    return { index, activated: options.activated, topK };
+}
+/** Provider-facing narrowing: activated tools ∪ top-k for the turn. Fails closed — any
+ *  scoring/index error discloses the full input list (never zero, never wider than input). */
+export function selectDisclosedTools(options) {
+    if (options.tools.length === 0)
+        return options.tools;
+    try {
+        const keep = new Set();
+        for (const tool of options.tools)
+            if (tool.name === SEARCH_TOOLS_TOOL_NAME || options.activated?.has(tool.name) === true)
+                keep.add(tool.name);
+        const index = createToolSearchIndex(options.tools, (tool) => tool.name === SEARCH_TOOLS_TOOL_NAME);
+        const topK = Math.min(Math.max(1, Math.trunc(options.search?.topK ?? DEFAULT_TOOLS_SEARCH_TOP_K)), HARD_MAX_TOOLS_SEARCH_TOP_K);
+        for (const match of scoreTools(index, inputText(options.input), topK, options.queryByteCap ?? DEFAULT_MAX_TOOLS_SEARCH_QUERY_BYTES))
+            keep.add(match.name);
+        const disclosed = options.tools.filter((tool) => keep.has(tool.name));
+        if (disclosed.length > 0)
+            return disclosed;
+        // Nothing scored or activated and no always-on tools in the list: bounded deterministic
+        // prefix instead of zero tools (the wired session always keeps `search_tools`, so the
+        // un-wired caller is the only one that reaches this).
+        return options.tools.slice(0, Math.min(Math.max(1, Math.trunc(options.search?.topK ?? DEFAULT_TOOLS_SEARCH_TOP_K)) + 1, options.tools.length));
+    }
+    catch {
+        return options.tools;
+    }
+}
+function inputText(input) {
+    if (typeof input === "string")
+        return input;
+    const messages = input === null || input === undefined || Array.isArray(input) === false ? [input] : input;
+    let text = "";
+    for (const message of messages) {
+        for (const block of message.content) {
+            if (block.type === "text") {
+                text += `${block.text}\n`;
+                if (text.length > HARD_MAX_TOOLS_SEARCH_QUERY_BYTES)
+                    return text;
+            }
+        }
+    }
+    return text;
+}
+/** Model-facing activation tool, generated only in search mode. Results are inert
+ *  name+description lines — no schemas or bodies — and activation re-checks allow/deny
+ *  at dispatch time (blocked-reason matrix unchanged). */
+export function createSearchToolsTool(state, queryByteCap = DEFAULT_MAX_TOOLS_SEARCH_QUERY_BYTES) {
+    return {
+        name: SEARCH_TOOLS_TOOL_NAME,
+        description: `Search available tools by relevance. Returns up to k tool names with short descriptions and marks them active so their full definitions appear on the next turn. Try queries made of tool keywords.`,
+        parameters: {
+            type: "object",
+            properties: { query: { type: "string" }, k: { type: "integer", minimum: 1 } },
+            required: ["query"],
+        },
+        execute(args, context) {
+            const fail = (message) => ({
+                toolCallId: context.toolCallId,
+                name: SEARCH_TOOLS_TOOL_NAME,
+                error: { code: "ERR_PRISM_TOOL_SEARCH_INVALID", message },
+            });
+            if (typeof args.query !== "string" || args.query.trim().length === 0)
+                return fail("query must be a non-empty string");
+            if (Buffer.byteLength(args.query, "utf8") > HARD_MAX_TOOLS_SEARCH_QUERY_BYTES)
+                return fail(`query exceeds ${HARD_MAX_TOOLS_SEARCH_QUERY_BYTES} bytes`);
+            const k = args.k === undefined ? state.topK : typeof args.k === "number" && Number.isInteger(args.k) ? args.k : NaN;
+            if (Number.isNaN(k) || k < 1)
+                return fail("k must be an integer >= 1");
+            const matches = scoreTools(state.index, args.query, k, queryByteCap);
+            for (const match of matches)
+                state.activated.add(match.name);
+            return {
+                toolCallId: context.toolCallId,
+                name: SEARCH_TOOLS_TOOL_NAME,
+                content: [
+                    {
+                        type: "text",
+                        text: matches.length === 0
+                            ? `No tools matched ${JSON.stringify(args.query.slice(0, 64))}. Try different keywords.`
+                            : matches
+                                .map((match) => `- ${match.name}${match.description ? `: ${match.description.slice(0, 512)}` : ""} [matched: ${match.matched.join(", ")}]`)
+                                .join("\n"),
+                    },
+                ],
+            };
+        },
+    };
+}
+//# sourceMappingURL=tool-search.js.map

package/docs/0.1.0-readiness.md

@@ -1,6 +1,6 @@
 # 0.1.0 / 1.0 Readiness Gates
 
-Status: **0.3.0** is the current release line (the final 0.3.x lockstep cut: Linux desktop wrapper, coding/ACP closeouts, and independent package versions with Decision B `^0.3.0` ranges); **0.1.7** was the terminal 0.1.x baseline; **1.0** readiness remains operator-gated, not automatic.
+Status: **0.4.0** is the current release line (plan 054 package consolidation: 11 active packages, family subpaths, `^0.4.0` peers); **0.3.3** was the terminal 0.3.x cut; **0.1.7** was the terminal 0.1.x baseline; **1.0** readiness remains operator-gated, not automatic.
 
 This page distills runnable readiness gates into one command-per-gate table.
 The **Last evidence** column records the 0.1.0-tree snapshot (plan 012 Tasks
@@ -20,7 +20,7 @@ Historical release lines (0.0.16 floor → 0.0.27 Phase 10 ACP interop → 0.1.0
 keep their per-phase evidence in the pages above; this page records the 0.2.6
 snapshot (plan 026) with the 0.1.x tables below as the historical record.
 
-## Current line (0.3.1)
+## Current line (0.4.0)
 
 | Item | Status |
 |---|---|

package/docs/acp-agent.md

@@ -56,7 +56,7 @@ The binary is pure wiring (~200 lines) — no protocol code lives here. It build
 
 ```ts
 import { createSpawnableAgent, loadConfig } from "@arnilo/prism-acp-agent";
-import { createOpenAIResponsesProvider } from "@arnilo/prism-provider-openai";
+import { createOpenAIResponsesProvider } from "@arnilo/prism-providers/openai";
 
 const agent = createSpawnableAgent({
   config: loadConfig("prism-acp-agent.json"),

package/docs/agent-definitions.md

@@ -27,7 +27,7 @@ Do not use the bundle loader to discover providers — provider/model packages s
 | --- | --- |
 | `name` | Required agent name. |
 | `description?` | Optional description. |
-| `model?` | `ModelConfig` object, or a `"<provider>/<model>"` string resolved through `registries.models`. |
+| `model?` | `ModelConfig` object, or a `"<provider>/<model>"` string resolved through `registries.models`. Optional at authoring time: when omitted, resolution falls back to `context.overrides.model` (host-injected selection); an explicit definition `model` drives registry resolution, and neither present fails closed with `Agent "<name>" has no model`. |
 | `tools?` | Tool names to activate from the active tool registry / `registries.tools`. Omitted means no active tools unless `activateAllCapabilities: true` is passed for migration. |
 | `skills?` | Skill names resolved via `resolveActiveSkills()`; omitted means no active skills unless `activateAllCapabilities: true` is passed for migration. `toolNames` enforcement applies at activation. |
 | `context?` | Context provider names from `registries.contextProviders`. |

package/docs/antigravity-agent.md

@@ -23,7 +23,7 @@ Use `@arnilo/prism-antigravity-agent` when:
 - You want conversation continuation across multiple user turns in a persistent session.
 
 Do **not** use it:
-- As a generic LLM model provider. For direct Gemini API or Vertex AI foundation model inference without an autonomous loop, use [`@arnilo/prism-provider-google`](providers/google.md) or [`@arnilo/prism-provider-vertex`](providers/vertex.md).
+- As a generic LLM model provider. For direct Gemini API or Vertex AI foundation model inference without an autonomous loop, use [`@arnilo/prism-providers/google`](providers/google.md) or [`@arnilo/prism-providers/vertex`](providers/vertex.md).
 - If you require step-by-step turn replacement of Antigravity's internal model loop, compaction, or planning strategy.
 - If you require unreleased raw internal chain-of-thought text. Antigravity reasoning effort is projected as token counts and timeline activity steps, not raw hidden thoughts.
 

package/docs/browser-automation.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-browser` exposes six exclusive model-facing tools—`browser_open`, `browser_snapshot`, `browser_act`, `browser_close`, `browser_evaluate`, and `browser_observe`—over a host-supplied Playwright `Browser`. Prism creates one non-persistent `BrowserContext` per run, serializes actions, returns bounded AI-mode accessibility snapshots with snapshot-scoped refs, enforces egress/side-effect/upload/download/screenshot policy, and closes context/pages/listeners/quarantined downloads on close, abort, or manager disposal. Since 0.1.4 the package also rides playwright-core's existing CDP transport for bounded page evaluation, console/network observation, and network/emulation control on Chromium hosts — zero new dependencies, Prism still never launches or downloads browsers.
+The `@arnilo/prism-web-tools/browser` subpath exposes six exclusive model-facing tools—`browser_open`, `browser_snapshot`, `browser_act`, `browser_close`, `browser_evaluate`, and `browser_observe`—over a host-supplied Playwright `Browser`. Prism creates one non-persistent `BrowserContext` per run, serializes actions, returns bounded AI-mode accessibility snapshots with snapshot-scoped refs, enforces egress/side-effect/upload/download/screenshot policy, and closes context/pages/listeners/quarantined downloads on close, abort, or manager disposal. Since 0.1.4 the package also rides playwright-core's existing CDP transport for bounded page evaluation, console/network observation, and network/emulation control on Chromium hosts — zero new dependencies, Prism still never launches or downloads browsers.
 
 ## When to use it
 
@@ -65,8 +65,8 @@ import {
   createBrowserManager,
   createBrowserTools,
   createSharedSandboxBrowserOptions,
-} from "@arnilo/prism-browser";
-import { assertBrowserSandboxNetwork } from "@arnilo/prism-coding-security";
+} from "@arnilo/prism-web-tools/browser";
+import { assertBrowserSandboxNetwork } from "@arnilo/prism-coding-tools/security";
 
 assertBrowserSandboxNetwork({
   mode: "custom",
@@ -106,7 +106,7 @@ await browser.close();
 - `networkPolicy` defaults to `requireContainedProxy: true` (fail closed). Hosts must supply `containedProxyAttestation: { proxyEndpoint, denyDirectEgress: true }`. Private/loopback/link-local, `file`/`data`/`blob`/`javascript`/`devtools` schemes are denied by default. Playwright routing is defense in depth — production DNS/private egress is a host firewall/proxy.
 - Uploads require absolute paths under `uploads.roots` (realpath-contained; symlink escapes rejected). Downloads stream into `downloads.quarantine` with SHA-256/MIME/name metadata; `download_release` requires host `approveRelease`. Screenshots return bounded `ImageContent`.
 - Observation (`snapshot`, `wait`, open-without-url, `close`) vs mutation/high-impact (`navigate`, click/form, dialog accept, upload, download release, popup select) is classified for `ExecutionPolicy` / `beforeSideEffect`.
-- `createSharedSandboxBrowserOptions()` aligns browser uploads/downloads with Task 1 sandbox `/workspace` and `/downloads`. `assertBrowserSandboxNetwork()` in `@arnilo/prism-coding-security` fails closed for custom Docker networks without browser egress attestation.
+- `createSharedSandboxBrowserOptions()` aligns browser uploads/downloads with Task 1 sandbox `/workspace` and `/downloads`. `assertBrowserSandboxNetwork()` in `@arnilo/prism-coding-tools/security` fails closed closed for custom Docker networks without browser egress attestation.
 - Raw CSS/XPath: since 0.1.4 `{ css }` / `{ xpath }` targets resolve via Playwright's selector engine (`locator(css)` / `locator("xpath=…")`); ref resolution keeps the built-in `aria-ref=` selector with a package-owned snapshot ref table for staleness checks.
 - CDP capabilities (0.1.4): `browser_evaluate` (bounded `Runtime.evaluate`), `browser_observe` (Runtime console/exception + Network request/response/failed events in a bounded ring with drain-on-read), and `block_urls`/`unblock_urls` (`Network.setBlockedURLs`), `throttle` (`Network.emulateNetworkConditions`), `emulate` (`Emulation.setDeviceMetricsOverride` + optional `setUserAgentOverride`). All CDP sessions are per-page via `context.newCDPSession(page)` and are detached on run close — network/emulation changes are run-scoped and reset with `browser_close`. `BrowserCdpOptions.mode` (`auto` | `on` | `off`, default `auto`) gates the surface: non-Chromium hosts or mode `off` return `ERR_PRISM_BROWSER_CDP_UNAVAILABLE` without affecting Playwright-only tools. Domains are limited to the Runtime/Network/Emulation allowlist — cookies, tracing, performance profiles, IndexedDB, and worker debugging are not exposed. CDP is not an egress bypass: page network still routes through the run's routing/blocking and `networkPolicy`.
 - CDP bounds (0.1.4): evaluate expression ≤ `maxActionInputBytes` (64 KiB default / 256 KiB hard) and result capped at `maxEvaluateResultBytes` (64 KiB / 256 KiB) with truncation marking; `browser_observe` rings capped at `maxConsoleEntries` (200/500) and `maxNetworkRequests`; `block_urls` patterns ≤ `maxBlockedUrlPatterns` (32/128); throttle latency ≤ 120 s and throughput ≤ 1 Gbps; emulate dimensions ≤ 16 384 and scale ≤ 10, user agent ≤ 2 KiB. Evaluate is classified high-impact (arbitrary page-context code execution): `ExecutionPolicy` approval and the `beforeSideEffect` hook are mandatory, it charges the action budget, and results are marked `untrusted_external`. `browser_observe` is observation-only (no side-effect hook, no action charge) and **never captures request/response bodies, cookies, or auth headers** — only bounded URL/method/status/error-text/arg previews.
@@ -118,7 +118,7 @@ Observation tools declare `kind: none`; mutations are `external_mutation`/`unsup
 
 Import is inert. Construction fails clearly when neither `browser` nor `manager` is supplied. Browser installation, launch, version, and control endpoint are host-owned. Prism never exposes init scripts, extensions, persistent profiles, or model-supplied Playwright launch options; CDP exposure is limited to the allowlisted Runtime/Network/Emulation surface above (evaluate is policy-gated arbitrary code execution — treat results as untrusted). Secrets and storage state must not appear in snapshots, tool results, logs, or checkpoints. Finite caps charge before context/page/action/queue/snapshot/network/artifact retention; snapshots retain no unbounded DOM, console, request, response, or trace history. Unreleased downloads are deleted on context close.
 
-Default tests use fake Playwright APIs only. Protected live gate: `PRISM_LIVE_PLAYWRIGHT=1` (or `PRISM_TEST_PLAYWRIGHT=1`) `npm run test:live -w @arnilo/prism-browser` exercises a local loopback hostile HTML fixture for snapshot refs, stale-ref rejection, css/xpath targets, private/file deny, upload containment, screenshot bounds, download quarantine/release, and the CDP leg (real evaluate, observe, and emulate). Missing browser binaries fail closed when the gate is enabled. The protected coding journey (0.2.6, plan 026 Task 7) additionally runs a real browser inspection leg (local loopback fixture page, snapshot text assertion, run-owned context closed before the host browser) inside the packed consumer as part of scripts/phase26-coding-journey.test.mjs, gated by PRISM_LIVE_PLAYWRIGHT with the pinned playwright-core installed into the consumer; browser storage never appears in the retained report. Adversarial network-free fixtures live in `eval-fixtures.test.ts`; see [Evaluations](evaluations.md) and `examples/coding-browser-evaluation.ts`.
+Default tests use fake Playwright APIs only. Protected live gate: `PRISM_LIVE_PLAYWRIGHT=1` (or `PRISM_TEST_PLAYWRIGHT=1`) `npm run test:live -w @arnilo/prism-web-tools` exercises a local loopback hostile HTML fixture for snapshot refs, stale-ref rejection, css/xpath targets, private/file deny, upload containment, screenshot bounds, download quarantine/release, and the CDP leg (real evaluate, observe, and emulate). Missing browser binaries fail closed when the gate is enabled. The protected coding journey (0.2.6, plan 026 Task 7) additionally runs a real browser inspection leg (local loopback fixture page, snapshot text assertion, run-owned context closed before the host browser) inside the packed consumer as part of scripts/phase26-coding-journey.test.mjs, gated by PRISM_LIVE_PLAYWRIGHT with the pinned playwright-core installed into the consumer; browser storage never appears in the retained report. Adversarial network-free fixtures live in `eval-fixtures.test.ts`; see [Evaluations](evaluations.md) and `examples/coding-browser-evaluation.ts`.
 
 ## Related APIs