@arnilo/prism 0.3.1 → 0.4.0

package/dist/cli-init.js

@@ -1,4 +1,4 @@
-import { constants as fsConstants, readFileSync } from "node:fs";
+import { existsSync, constants as fsConstants, readdirSync, readFileSync } from "node:fs";
 import { access, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -34,16 +34,76 @@ export function listInitProviders(templatesRoot) {
         return cachedProviderIds;
     return Object.freeze([...loadProvidersCatalog(templatesRoot).keys()]);
 }
-export function getInitUsage(templatesRoot) {
+/** Template list discovered from the templates gallery. */
+export function listInitTemplates(galleryRoot = defaultGalleryRoot()) {
+    try {
+        const entries = readdirSync(galleryRoot, { withFileTypes: true });
+        const templates = [];
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                const manifestPath = join(galleryRoot, entry.name, "manifest.json");
+                if (existsSync(manifestPath)) {
+                    try {
+                        const raw = JSON.parse(readFileSync(manifestPath, "utf8"));
+                        if (raw && typeof raw === "object" && typeof raw.name === "string") {
+                            templates.push({
+                                name: raw.name,
+                                description: typeof raw.description === "string" ? raw.description : "",
+                                version: typeof raw.version === "string" ? raw.version : undefined,
+                                path: join(galleryRoot, entry.name),
+                            });
+                        }
+                    }
+                    catch {
+                        // skip invalid manifests
+                    }
+                }
+                else if (entry.name === "init") {
+                    templates.push({
+                        name: "init",
+                        description: "Minimal starter Prism agent with one selected provider and offline mock test",
+                        path: join(galleryRoot, "init"),
+                    });
+                }
+            }
+        }
+        return Object.freeze(templates.sort((a, b) => {
+            if (a.name === "init")
+                return -1;
+            if (b.name === "init")
+                return 1;
+            return a.name.localeCompare(b.name);
+        }));
+    }
+    catch {
+        return Object.freeze([
+            {
+                name: "init",
+                description: "Minimal starter Prism agent with one selected provider and offline mock test",
+                path: join(galleryRoot, "init"),
+            },
+        ]);
+    }
+}
+export function isInitTemplate(value, galleryRoot) {
+    return listInitTemplates(galleryRoot).some((t) => t.name === value);
+}
+export function getInitUsage(templatesRoot, galleryRoot) {
     const providers = listInitProviders(templatesRoot).join("|");
+    const templates = listInitTemplates(galleryRoot)
+        .map((t) => t.name)
+        .join("|");
     return `Usage: prism init <dir> [options]
+       prism init --list-templates
 
-Create a minimal TypeScript Prism project with one explicit provider and an offline mock test.
+Create a minimal TypeScript Prism project or scaffold from a template gallery.
 
 Arguments:
   <dir>                      Destination directory (created if missing)
 
 Options:
+  --template <name>          Template name (${templates || "init|deep-research"}). Default: init
+  --list-templates           List available templates from the gallery
   --provider <name>          Provider id (${providers}). Default: mock
   --with-workflows           Add optional workflows dependency and example
   --with-evals               Add optional evals dependency and example
@@ -52,19 +112,24 @@ Options:
 
 Examples:
   prism init my-agent
+  prism init my-research --template deep-research
+  prism init --list-templates
   prism init my-agent --provider openai
   prism init my-agent --provider openai --with-workflows
 `;
 }
 export const initUsage = getInitUsage();
-export function parseInitArgs(argv, templatesRoot) {
+export function parseInitArgs(argv, templatesRoot, galleryRoot) {
     let directory;
+    let template;
+    let listTemplates = false;
     let provider = "mock";
     let withWorkflows = false;
     let withEvals = false;
     let force = false;
     let help = false;
     const providers = listInitProviders(templatesRoot);
+    const availableTemplates = listInitTemplates(galleryRoot);
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === "-h" || arg === "--help") {
@@ -75,6 +140,10 @@ export function parseInitArgs(argv, templatesRoot) {
             force = true;
             continue;
         }
+        if (arg === "--list-templates") {
+            listTemplates = true;
+            continue;
+        }
         if (arg === "--with-workflows") {
             withWorkflows = true;
             continue;
@@ -83,6 +152,18 @@ export function parseInitArgs(argv, templatesRoot) {
             withEvals = true;
             continue;
         }
+        if (arg === "--template") {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith("-")) {
+                throw new InitUsageError("Missing value for --template");
+            }
+            i += 1;
+            if (!availableTemplates.some((t) => t.name === value)) {
+                throw new InitUsageError(`Unknown template: ${value}. Expected one of ${availableTemplates.map((t) => t.name).join(", ")}`);
+            }
+            template = value;
+            continue;
+        }
         if (arg === "--provider") {
             const value = argv[i + 1];
             if (value === undefined || value.startsWith("-")) {
@@ -103,11 +184,13 @@ export function parseInitArgs(argv, templatesRoot) {
         }
         directory = arg;
     }
-    if (!help && directory === undefined) {
+    if (!help && !listTemplates && directory === undefined) {
         throw new InitUsageError("Missing destination directory");
     }
     return {
         directory: directory ?? ".",
+        template,
+        listTemplates,
         provider,
         withWorkflows,
         withEvals,
@@ -118,20 +201,34 @@ export function parseInitArgs(argv, templatesRoot) {
 export async function runInitCommand(argv, runtime) {
     let options;
     try {
-        options = parseInitArgs(argv, runtime.templatesRoot);
+        options = parseInitArgs(argv, runtime.templatesRoot, runtime.galleryRoot);
     }
     catch (error) {
-        write(runtime.stderr, `${error instanceof Error ? error.message : String(error)}\n${getInitUsage(runtime.templatesRoot)}`);
+        write(runtime.stderr, `${error instanceof Error ? error.message : String(error)}\n${getInitUsage(runtime.templatesRoot, runtime.galleryRoot)}`);
         return 2;
     }
     if (options.help) {
-        write(runtime.stdout, getInitUsage(runtime.templatesRoot));
+        write(runtime.stdout, getInitUsage(runtime.templatesRoot, runtime.galleryRoot));
+        return 0;
+    }
+    if (options.listTemplates) {
+        const templates = listInitTemplates(runtime.galleryRoot);
+        const lines = [
+            "Available templates:",
+            ...templates.map((t) => `  ${t.name.padEnd(16)} - ${t.description}`),
+            "",
+            "Usage:",
+            "  prism init <dir> --template <name>",
+            "",
+        ];
+        write(runtime.stdout, lines.join("\n"));
         return 0;
     }
     try {
         const result = await createInitProject(options, runtime);
         write(runtime.stdout, [
             `Created Prism project in ${result.targetDir}`,
+            ...(result.template ? [`  template: ${result.template}`] : []),
             `  provider: ${result.provider}`,
             `  files: ${result.writtenFiles.length}`,
             `  bytes: ${result.totalBytes}`,
@@ -149,7 +246,7 @@ export async function runInitCommand(argv, runtime) {
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         if (error instanceof InitUsageError) {
-            write(runtime.stderr, `${message}\n${getInitUsage(runtime.templatesRoot)}`);
+            write(runtime.stderr, `${message}\n${getInitUsage(runtime.templatesRoot, runtime.galleryRoot)}`);
             return 2;
         }
         write(runtime.stderr, `${message}\n`);
@@ -163,6 +260,7 @@ export async function createInitProject(options, runtime = {
     const cwd = runtime.cwd ?? process.cwd();
     const targetDir = resolveInitDirectory(options.directory, cwd);
     const templatesRoot = runtime.templatesRoot ?? defaultTemplatesRoot();
+    const galleryRoot = runtime.galleryRoot ?? defaultGalleryRoot();
     const version = runtime.packageVersion ?? (await readPackageVersion());
     const catalog = loadProvidersCatalog(templatesRoot);
     const provider = catalog.get(options.provider);
@@ -171,18 +269,38 @@ export async function createInitProject(options, runtime = {
     }
     const projectName = sanitizePackageName(basenameSafe(targetDir));
     await assertDestinationWritable(targetDir, options.force);
-    const tokens = buildTokens({
-        projectName,
-        version,
-        provider,
-        withWorkflows: options.withWorkflows,
-        withEvals: options.withEvals,
-    });
-    const planned = await planFiles({
-        templatesRoot,
-        withWorkflows: options.withWorkflows,
-        withEvals: options.withEvals,
-    });
+    const isCustomTemplate = Boolean(options.template && options.template !== "init");
+    let planned;
+    let tokens;
+    if (isCustomTemplate) {
+        const templateName = options.template;
+        const templateDir = join(galleryRoot, templateName);
+        if (!(await exists(templateDir))) {
+            const available = listInitTemplates(galleryRoot);
+            throw new InitUsageError(`Unknown template: ${templateName}. Expected one of ${available.map((t) => t.name).join(", ")}`);
+        }
+        planned = await planTemplateFiles(templateDir);
+        tokens = buildTokensForTemplate({
+            projectName,
+            version,
+            templateName,
+            provider,
+        });
+    }
+    else {
+        tokens = buildTokens({
+            projectName,
+            version,
+            provider,
+            withWorkflows: options.withWorkflows,
+            withEvals: options.withEvals,
+        });
+        planned = await planFiles({
+            templatesRoot,
+            withWorkflows: options.withWorkflows,
+            withEvals: options.withEvals,
+        });
+    }
     if (!options.force) {
         for (const file of planned) {
             const dest = join(targetDir, file.relativePath);
@@ -206,6 +324,7 @@ export async function createInitProject(options, runtime = {
     return {
         targetDir,
         writtenFiles,
+        template: options.template,
         provider: options.provider,
         withWorkflows: options.withWorkflows,
         withEvals: options.withEvals,
@@ -215,6 +334,60 @@ export async function createInitProject(options, runtime = {
 export function defaultTemplatesRoot() {
     return join(dirname(fileURLToPath(import.meta.url)), "..", "templates", "init");
 }
+export function defaultGalleryRoot() {
+    return join(dirname(fileURLToPath(import.meta.url)), "..", "templates");
+}
+async function planTemplateFiles(templateDir) {
+    const files = [];
+    async function walk(dir, baseRel = "") {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = join(dir, entry.name);
+            const relPath = baseRel ? `${baseRel}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                await walk(fullPath, relPath);
+            }
+            else if (entry.isFile()) {
+                if (entry.name === "manifest.json")
+                    continue;
+                let targetRel = relPath.endsWith(".tmpl") ? relPath.slice(0, -5) : relPath;
+                if (targetRel.startsWith("src/tests/")) {
+                    targetRel = `src/__tests__/${targetRel.slice("src/tests/".length)}`;
+                }
+                files.push({ relativePath: targetRel, sourcePath: fullPath });
+            }
+        }
+    }
+    await walk(templateDir);
+    return files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+}
+function buildTokensForTemplate(input) {
+    const dependencies = {
+        "@arnilo/prism": input.version,
+        "@arnilo/prism-memory": input.version,
+        "@arnilo/prism-web-tools": input.version,
+        "@arnilo/prism-workflows": input.version,
+    };
+    const dependencyLines = Object.entries(dependencies)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([name, ver]) => `    ${JSON.stringify(name)}: ${JSON.stringify(ver)}`)
+        .join(",\n");
+    return {
+        __PROJECT_NAME__: input.projectName,
+        __PRISM_VERSION__: input.version,
+        __TEMPLATE_NAME__: input.templateName,
+        __PROVIDER_ID__: input.provider.id,
+        __PROVIDER_PACKAGE__: input.provider.packageName ?? "",
+        __DEPENDENCIES__: dependencyLines,
+        __PROVIDER_IMPORTS__: input.provider.imports,
+        __PROVIDER_EXPRESSION__: input.provider.providerExpression,
+        __MODEL_EXPRESSION__: input.provider.modelExpression,
+        __ENV_EXAMPLE__: "",
+        __NEXT_STEPS_LIVE__: "",
+        __OPTIONAL_DOCS__: "",
+        __PROVIDER_README_NOTE__: "",
+    };
+}
 export function isInitProvider(value, templatesRoot) {
     return listInitProviders(templatesRoot).includes(value);
 }

package/dist/cli-runner.d.ts

@@ -58,6 +58,8 @@ export interface CliRuntime {
     readonly globalRoot?: string;
     /** Override init template root (tests). */
     readonly initTemplatesRoot?: string;
+    /** Override template gallery root (tests). */
+    readonly initGalleryRoot?: string;
     /** Override version stamped by `prism init` (tests). */
     readonly initPackageVersion?: string;
     /** Override provider-scaffold template root (tests). */
@@ -66,8 +68,10 @@ export interface CliRuntime {
     readonly providerPackageVersion?: string;
     /** Working directory for relative `prism init` destinations (tests). */
     readonly cwd?: string;
+    /** Test injection for `prism dev`: overrides `@arnilo/prism-dev` resolution. */
+    readonly loadDevCli?: () => Promise<unknown>;
 }
-export declare const usage = "Usage: prism [--mode print|json|rpc] [-p prompt] [options]\n       prism init <dir> [--provider <name>] [--with-workflows] [--with-evals] [--force]\n       prism providers add <name> [--base-url <url>] [--env-key <name>] [--model <id>] [--force]\n\nOptions:\n  -p, --prompt <text>        Prompt to run in print/json mode\n  --provider <name>          Explicit provider id (mock is built in for smoke tests)\n  --model <name>             Explicit model name\n  --session <id>             Session id\n  --system <text>            System instructions\n  --context <text>           Context text\n  --compact <entries>        Auto-compaction threshold\n  --max-tool-rounds <n>      Maximum tool rounds\n  --discover                 Enable workspace contribution discovery (opt-in)\n  --discover-kinds <csv>     Kinds to discover (default: skill; skill,tool,context,instructions)\n  --no-discovery             Disable discovery even if --discover is set\n  --agents-config <path>     App config root holding agents/<name>/AGENT.md bundles (opt-in)\n  --no-agents-md             Skip auto-loading <workspaceRoot>/AGENTS.md\n  --no-system-md             Skip auto-loading the global SYSTEM.md layer\n  --agents-md-file <path>    Read AGENTS.md from <path> instead (trust-gated, source: app)\n  --system-md-file <path>    Read SYSTEM.md from <path> instead (source: user)\n  -h, --help                 Show this help\n";
+export declare const usage = "Usage: prism [--mode print|json|rpc] [-p prompt] [options]\n       prism init <dir> [--template <name>] [--list-templates] [--provider <name>] [--with-workflows] [--with-evals] [--force]\n       prism providers add <name> [--base-url <url>] [--env-key <name>] [--model <id>] [--force]\n       prism dev [--port <n>] [--host <addr>]   (loopback inspector; delegates into @arnilo/prism-dev)\n\n\nOptions:\n  -p, --prompt <text>        Prompt to run in print/json mode\n  --provider <name>          Explicit provider id (mock is built in for smoke tests)\n  --model <name>             Explicit model name\n  --session <id>             Session id\n  --system <text>            System instructions\n  --context <text>           Context text\n  --compact <entries>        Auto-compaction threshold\n  --max-tool-rounds <n>      Maximum tool rounds\n  --discover                 Enable workspace contribution discovery (opt-in)\n  --discover-kinds <csv>     Kinds to discover (default: skill; skill,tool,context,instructions)\n  --no-discovery             Disable discovery even if --discover is set\n  --agents-config <path>     App config root holding agents/<name>/AGENT.md bundles (opt-in)\n  --no-agents-md             Skip auto-loading <workspaceRoot>/AGENTS.md\n  --no-system-md             Skip auto-loading the global SYSTEM.md layer\n  --agents-md-file <path>    Read AGENTS.md from <path> instead (trust-gated, source: app)\n  --system-md-file <path>    Read SYSTEM.md from <path> instead (source: user)\n  -h, --help                 Show this help\n";
 export declare function parseCliArgs(argv: readonly string[]): CliOptions;
 export declare function runCli(argv: readonly string[], runtime: CliRuntime): Promise<number>;
 export declare function runPromptMode(session: AgentSession, options: CliOptions, stdout: Writable, mode: "print" | "json"): Promise<void>;

package/dist/cli-runner.js

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { basename, dirname } from "node:path";
 import process from "node:process";
+import { runPrismDevSubcommand } from "./cli-dev.js";
 import { initUsage, runInitCommand } from "./cli-init.js";
 import { providerAddUsage, runProviderAddCommand } from "./cli-provider-add.js";
 import { createContributionRegistries, registerDiscoveredContributions } from "./contributions.js";
@@ -13,8 +14,10 @@ import { createPathTrustPolicy } from "./node/trust.js";
 import { runRpcServer } from "./rpc.js";
 import { createSkillRegistry } from "./skills.js";
 export const usage = `Usage: prism [--mode print|json|rpc] [-p prompt] [options]
-       prism init <dir> [--provider <name>] [--with-workflows] [--with-evals] [--force]
+       prism init <dir> [--template <name>] [--list-templates] [--provider <name>] [--with-workflows] [--with-evals] [--force]
        prism providers add <name> [--base-url <url>] [--env-key <name>] [--model <id>] [--force]
+       prism dev [--port <n>] [--host <addr>]   (loopback inspector; delegates into @arnilo/prism-dev)
+
 
 Options:
   -p, --prompt <text>        Prompt to run in print/json mode
@@ -201,11 +204,19 @@ function parseKinds(csv, flag) {
     return kinds;
 }
 export async function runCli(argv, runtime) {
+    if (argv[0] === "dev") {
+        return runPrismDevSubcommand(argv.slice(1), {
+            stdout: runtime.stdout,
+            stderr: runtime.stderr,
+            ...(runtime.loadDevCli ? { loadDevCli: runtime.loadDevCli } : {}),
+        });
+    }
     if (argv[0] === "init") {
         const initRuntime = {
             stdout: runtime.stdout,
             stderr: runtime.stderr,
             ...(runtime.initTemplatesRoot !== undefined ? { templatesRoot: runtime.initTemplatesRoot } : {}),
+            ...(runtime.initGalleryRoot !== undefined ? { galleryRoot: runtime.initGalleryRoot } : {}),
             ...(runtime.initPackageVersion !== undefined ? { packageVersion: runtime.initPackageVersion } : {}),
             ...(runtime.cwd !== undefined ? { cwd: runtime.cwd } : {}),
         };

package/dist/contracts-core/agent.d.ts

@@ -1,7 +1,7 @@
 /** Contracts-core agent family (0.2.5 plan 025 Task 1 split).
  * Moved verbatim from contracts-core.ts; public surface unchanged behind the barrel. */
-import type { InputAssemblyLayout, RunLedger, ToolDefinition, ToolEffectStore, ToolRegistry } from "../contracts-protocol.js";
-import type { AgentRunStateOptions, AgentSession } from "../contracts-run-state.js";
+import type { InputAssemblyLayout, RunLedger, RunOptions, ToolDefinition, ToolEffectStore, ToolRegistry } from "../contracts-protocol.js";
+import type { AgentRunResult, AgentRunStateOptions, AgentSession } from "../contracts-run-state.js";
 import type { ContributionRegistries } from "../contributions.js";
 import type { MiddlewareRegistry } from "../middleware.js";
 import type { SecretRedactor } from "../redaction.js";
@@ -59,6 +59,9 @@ export interface AgentConfig {
     readonly activateAllSkills?: true;
     /** Progressive: catalog (name+description) unless loaded; eager: full instructions every turn. Default progressive. */
     readonly skillsDisclosure?: import("../skill-disclosure.js").SkillsDisclosure;
+    /** Tools disclosure: "all" (default) sends every active tool schema; "search" sends top-k + the generated `search_tools` tool. */
+    readonly toolsDisclosure?: import("../tool-search.js").ToolsDisclosure;
+    readonly toolsSearch?: import("../tool-search.js").ToolsSearchOptions;
     /** Opt-in projection-only fold for aged large tool results in provider view; store untouched. */
     readonly toolResultFold?: import("../tool-result-fold.js").ToolResultFoldOptions;
     readonly inputBuilder?: InputBuilder;
@@ -147,6 +150,27 @@ export interface CommandExecutionContext {
     readonly runId?: string;
     readonly signal?: AbortSignal;
     readonly metadata?: Readonly<Record<string, unknown>>;
+    /** Host-injected driver capabilities (host-opt-in; never package-supplied).
+     *  Absent in hosts that don't supply them — commands stay inert data there. */
+    readonly drivers?: CommandDrivers;
+}
+/** Minimal run reference returned by {@link CommandDrivers.startWorkflow}. */
+export interface CommandWorkflowRun {
+    readonly runId: string;
+    readonly status: string;
+}
+/** Host-injected capabilities a contributed command may act through when the
+ *  host opts in. Drivers are supplied by the host at context construction
+ *  (e.g. the RPC session factory), never by packages; core only types and
+ *  forwards them. `metadata.trust` labeling is unaffected. */
+export interface CommandDrivers {
+    /** Start a session run. */
+    startRun(input: string, options?: RunOptions): Promise<AgentRunResult> | AgentRunResult;
+    /** Start a run on a host-understood orchestration definition. Returns at
+     *  minimum the run id and status; richer host shapes pass through as-is. */
+    startWorkflow(definition: object, input: unknown, options?: Readonly<Record<string, unknown>>): Promise<CommandWorkflowRun>;
+    /** Steer an active run with additional input. */
+    steer(runId: string, input: string): Promise<void> | void;
 }
 export interface CommandResult {
     readonly name: string;
@@ -231,6 +255,9 @@ export interface PromptBuildRequest {
     readonly skills?: readonly Skill[];
     readonly skillsDisclosure?: import("../skill-disclosure.js").SkillsDisclosure;
     readonly loadedSkills?: import("../skill-disclosure.js").LoadedSkillSet;
+    /** Tools disclosure: "all" (default) sends every active tool schema; "search" sends top-k + the generated `search_tools` tool. */
+    readonly toolsDisclosure?: import("../tool-search.js").ToolsDisclosure;
+    readonly toolsSearch?: import("../tool-search.js").ToolsSearchOptions;
     /** Skills demoted to catalog-only by context budget this turn. */
     readonly demotedSkillBodies?: readonly string[];
     readonly tools?: readonly ToolDefinition[];

package/dist/contracts-protocol.d.ts

@@ -57,6 +57,17 @@ export type RealtimeEvent = {
 /** Neutral bidirectional realtime session seam. The provider owns the transport
  *  (e.g. WebSocket); the host owns audio capture/playback and session lifecycle. */
 export type InputAssemblyLayout = "legacy" | "cache_aware";
+/** Opaque provenance ref for the resolved prompt version that produced a run
+ *  (plan 042). Identity only — never prompt content; the body is recoverable
+ *  from the prompt store via `hash`. */
+export interface PromptVersionRef {
+    /** Prompt name within the host's prompt store. */
+    readonly name: string;
+    /** Immutable version number assigned by the prompt store. */
+    readonly version: number;
+    /** Content hash of the exact UTF-8 body bytes: `sha256:<64 lowercase hex>`. */
+    readonly hash: string;
+}
 export interface RunOptions {
     readonly signal?: AbortSignal;
     readonly model?: ModelConfig;
@@ -84,6 +95,9 @@ export interface RunOptions {
     readonly activateAllSkills?: true;
     /** Progressive: catalog (name+description) unless loaded; eager: full instructions every turn. Default progressive. */
     readonly skillsDisclosure?: import("./skill-disclosure.js").SkillsDisclosure;
+    /** Tools disclosure: "all" (default) sends every active tool schema; "search" sends top-k + the generated `search_tools` tool. */
+    readonly toolsDisclosure?: import("./tool-search.js").ToolsDisclosure;
+    readonly toolsSearch?: import("./tool-search.js").ToolsSearchOptions;
     /** Opt-in projection-only fold for aged large tool results in provider view; store untouched. */
     readonly toolResultFold?: import("./tool-result-fold.js").ToolResultFoldOptions;
     readonly instructionInjectors?: readonly InstructionInjector[];
@@ -93,6 +107,8 @@ export interface RunOptions {
     readonly guardrails?: Guardrails;
     /** Opt-in durable interruption/checkpointing. */
     readonly runState?: AgentRunStateOptions;
+    /** Prompt provenance: copied verbatim onto this run's start and finish ledger records. */
+    readonly promptVersion?: PromptVersionRef;
 }
 export interface ProviderTurnMetadata {
     readonly providerId: string;
@@ -493,6 +509,8 @@ export interface RunRecord extends OwnershipScope {
     readonly abortReason?: string;
     readonly error?: ErrorInfo;
     readonly metadata?: Readonly<Record<string, unknown>>;
+    /** Provenance ref copied from `RunOptions.promptVersion` when the host supplied one. */
+    readonly promptVersion?: PromptVersionRef;
 }
 export type AgentEventType = AgentEvent["type"];
 /** Stored agent event ledger row. The `event` payload should be redacted before storage when secrets are present. */

package/dist/contracts-run-state.d.ts

@@ -1,6 +1,5 @@
-import type { AgentSessionCloneOptions, AgentSessionForkOptions, CompactionOptions, CompactionResult, ContentBlock, ErrorInfo, JsonObject, JsonValue, Message, ModelConfig, RunLimitBreach, SessionEntry, ToolCallContent, Usage } from "./contracts-core.js";
+import type { AgentSessionCloneOptions, AgentSessionForkOptions, CheckpointStore, CompactionOptions, CompactionResult, ContentBlock, ErrorInfo, JsonObject, JsonValue, Message, ModelConfig, OwnershipScope, RunLimitBreach, SessionEntry, SubscribeOptions, ToolCallContent, Usage } from "./contracts-core.js";
 import type { AgentEvent, RunOptions, ToolEffectKind } from "./contracts-protocol.js";
-import type { CheckpointStore, OwnershipScope, SubscribeOptions } from "./contracts-core.js";
 export type AgentRunStatus = "succeeded" | "failed" | "aborted" | "suspended" | "denied";
 export type AgentRunInterruptionKind = "input_guardrail" | "tool_approval" | "elicitation";
 export type ApprovalOutcome = "allow_once" | "allow_for_run" | "reject_once" | "reject_for_run";

package/dist/index.d.ts

@@ -109,11 +109,13 @@ export type { ToolEffectErrorCode } from "./tool-effects.js";
 export { createMemoryToolEffectStore, ToolEffectError } from "./tool-effects.js";
 export type { FoldToolResultsContext, ResolvedToolResultFoldOptions, ToolResultFoldInput, ToolResultFoldOptions, } from "./tool-result-fold.js";
 export { DEFAULT_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES, DEFAULT_TOOL_RESULT_FOLD_MIN_AGE_TURNS, DEFAULT_TOOL_RESULT_FOLD_MIN_BYTES, foldedToolResultHeader, foldToolResultHistory, foldToolResults, formatFoldedToolResult, HARD_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES, resolveToolResultFold, TOOL_RESULT_FOLD_TURN_METADATA_KEY, } from "./tool-result-fold.js";
+export type { ActiveToolSet, ToolSearchIndex, ToolSearchMatch, ToolSearchState, ToolsDisclosure, ToolsSearchOptions, } from "./tool-search.js";
+export { createActiveToolSet, createSearchToolsTool, createToolSearchIndex, createToolSearchState, DEFAULT_MAX_TOOLS_SEARCH_QUERY_BYTES, DEFAULT_TOOLS_SEARCH_TOP_K, HARD_MAX_TOOLS_INDEX, HARD_MAX_TOOLS_SEARCH_QUERY_BYTES, HARD_MAX_TOOLS_SEARCH_TOP_K, isToolDisclosureError, resolveToolsDisclosure, SEARCH_TOOLS_TOOL_NAME, scoreTools, selectDisclosedTools, TOOL_DISCLOSURE_ERROR_CODE, ToolDisclosureError, } from "./tool-search.js";
 export type { DispatchToolCallOptions, ToolArgumentValidationError, ToolArgumentValidationResult, ToolArgumentValidator, ToolFilter, ToolFilterInput, ToolParameterValidatorOptions, ToolRegistryOptions, ToolValidator, } from "./tools.js";
 export { createToolParameterValidator, createToolRegistry, dispatchToolCall, filterTools } from "./tools.js";
 export { trimTrailingSlashes } from "./trim-trailing-slashes.js";
 export type { ResolvedUseCaseModel, ResolveUseCaseModelInput, UseCaseModelBinding, } from "./use-case-model.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export declare const name = "prism";
-export declare const version = "0.3.1";
+export declare const version = "0.4.0";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -60,10 +60,11 @@ export { assertAgentEventSourceConforms } from "./testing/agent-event-source-con
 export { applyThinkingLevel, isThinkingLevel, normalizeThinkingLevel, THINKING_LEVELS, thinkingCompatFor, thinkingFamilyForModel, } from "./thinking.js";
 export { createMemoryToolEffectStore, ToolEffectError } from "./tool-effects.js";
 export { DEFAULT_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES, DEFAULT_TOOL_RESULT_FOLD_MIN_AGE_TURNS, DEFAULT_TOOL_RESULT_FOLD_MIN_BYTES, foldedToolResultHeader, foldToolResultHistory, foldToolResults, formatFoldedToolResult, HARD_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES, resolveToolResultFold, TOOL_RESULT_FOLD_TURN_METADATA_KEY, } from "./tool-result-fold.js";
+export { createActiveToolSet, createSearchToolsTool, createToolSearchIndex, createToolSearchState, DEFAULT_MAX_TOOLS_SEARCH_QUERY_BYTES, DEFAULT_TOOLS_SEARCH_TOP_K, HARD_MAX_TOOLS_INDEX, HARD_MAX_TOOLS_SEARCH_QUERY_BYTES, HARD_MAX_TOOLS_SEARCH_TOP_K, isToolDisclosureError, resolveToolsDisclosure, SEARCH_TOOLS_TOOL_NAME, scoreTools, selectDisclosedTools, TOOL_DISCLOSURE_ERROR_CODE, ToolDisclosureError, } from "./tool-search.js";
 export { createToolParameterValidator, createToolRegistry, dispatchToolCall, filterTools } from "./tools.js";
 export { trimTrailingSlashes } from "./trim-trailing-slashes.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export const name = "prism";
-export const version = "0.3.1";
+export const version = "0.4.0";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/dist/input.d.ts

@@ -4,6 +4,7 @@ import type { MiddlewareRegistry } from "./middleware.js";
 import type { SecretRedactor } from "./redaction.js";
 import { type LoadedSkillSet, type SkillsDisclosure } from "./skill-disclosure.js";
 import { type ResolvedToolResultFoldOptions } from "./tool-result-fold.js";
+import { type ToolsDisclosure, type ToolsSearchOptions } from "./tool-search.js";
 export type AgentInput = string | Message | readonly Message[];
 export interface PromptInstruction {
     readonly text: string;
@@ -58,6 +59,13 @@ export interface AssembleProviderInputOptions extends DefaultInputBuildContext {
     readonly skillsDisclosure?: SkillsDisclosure;
     readonly loadedSkills?: LoadedSkillSet;
     readonly tools?: readonly ToolDefinition[];
+    /** Tools disclosure: "search" narrows the disclosed tool list (activated ∪ top-k); default "all" is unchanged. */
+    readonly toolsDisclosure?: ToolsDisclosure;
+    readonly toolsSearch?: ToolsSearchOptions;
+    /** Per-run activated names from `search_tools`; intersected at disclosure only — dispatch re-checks. */
+    readonly activatedTools?: {
+        has(name: string): boolean;
+    };
     readonly providerOptions?: ProviderRequestOptions;
     /** Assembler-time eviction; does not delete session store history. */
     readonly contextBudget?: ContextBudget;

package/dist/input.js

@@ -6,6 +6,7 @@ import { loadTextResource } from "./resources.js";
 import { skillMessages as buildSkillMessages } from "./skill-disclosure.js";
 import { composeSystemPrompt } from "./system-prompts.js";
 import { foldToolResultHistory, foldToolResults } from "./tool-result-fold.js";
+import { selectDisclosedTools } from "./tool-search.js";
 export function createDefaultInputBuilder() {
     return {
         name: "default-input",
@@ -120,6 +121,9 @@ export async function assembleProviderInput(options) {
     let context;
     let skills = options.skills;
     let tools = options.tools;
+    if (options.toolsDisclosure === "search" && tools?.length) {
+        tools = selectDisclosedTools({ tools, input: options.input, search: options.toolsSearch, activated: options.activatedTools });
+    }
     let demotedSkillBodies;
     let budgetReport;
     if (options.contextBudget) {

package/dist/rpc.d.ts

@@ -1,5 +1,5 @@
 import type { Readable, Writable } from "node:stream";
-import type { AgentSession, CommandDefinition, InstructionInjector } from "./contracts.js";
+import type { AgentSession, CommandDefinition, CommandDrivers, InstructionInjector } from "./contracts.js";
 import type { ContributionRegistry } from "./contributions.js";
 export type RpcCommandName = "prompt" | "steer" | "followUp" | "abort" | "state" | "messages" | "setModel" | "compact" | "switchSession" | "forkSession" | "cloneSession" | "checkout" | "command";
 export interface RpcRequest {
@@ -10,6 +10,9 @@ export interface RpcRequest {
 export interface RpcSessionFactory {
     createSession(id?: string): AgentSession;
     readonly commands?: readonly CommandDefinition[];
+    /** Host-opt-in driver capabilities forwarded to contributed commands on the
+     *  `command` execution context. Absent ⇒ context shape unchanged. */
+    readonly drivers?: CommandDrivers;
     /** Optional registry for resolving `instructionInjectors` names in `prompt`/`followUp`
      *  params (Phase 30). Names resolve fail-closed. */
     readonly instructionInjectors?: ContributionRegistry<InstructionInjector>;

package/dist/rpc.js

@@ -9,6 +9,7 @@ export async function runRpcServer(options) {
         sessions: new Map([[first.id, first]]),
         commands: new Map((options.commands ?? []).map((command) => [command.name, command])),
         createSession: options.createSession,
+        ...(options.drivers ? { drivers: options.drivers } : {}),
         ...(options.instructionInjectors ? { instructionInjectors: options.instructionInjectors } : {}),
     };
     const activeRuns = new Map();
@@ -181,7 +182,10 @@ async function handleRequest(request, state, stdout, activeRuns) {
             if (!command)
                 throw new Error(`Unknown command: ${name}`);
             const args = objectParam(request.params, "args") ?? {};
-            const result = await command.execute(args, { sessionId: state.current.id });
+            const result = await command.execute(args, 
+            // FEATURE-3 (plan 050 Task 5): host-opt-in drivers forwarded verbatim; the
+            // context carries no `drivers` key when the host supplied none.
+            state.drivers ? { sessionId: state.current.id, drivers: state.drivers } : { sessionId: state.current.id });
             write(stdout, { id: request.id, ok: true, result });
             break;
         }

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 = 8;
+export declare const PERSISTENCE_SCHEMA_VERSION = 9;
 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_agent_event_streams" | "prism_tool_calls" | "prism_usage" | "prism_run_feedback" | "prism_retention_policies" | "prism_legal_holds" | "prism_tenant_quotas" | "prism_migrations";
 export type PersistenceColumnType = "text" | "integer" | "number" | "boolean" | "json" | "timestamp";
 export interface PersistenceColumnDefinition {