@arnilo/prism 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,3 +1,61 @@
+## [0.4.0] - 2026-09-01 (plan 054)
+
+### Changed
+- **Package consolidation (breaking import/package cut):** 11 active packages replace the 0.3.x graph. Families: `@arnilo/prism-core`, `@arnilo/prism-coding-tools`, `@arnilo/prism-web-tools`, `@arnilo/prism-memory`, `@arnilo/prism-providers` (17 adapter subpaths), `@arnilo/prism-office` (`/documents`, `/sheets`, `/diagrams`). Retired 54 published names stay installable at exact 0.3 pins; npm `legacy` dist-tag + `<0.4.0` deprecation warnings point at `docs/migrate-to-0.4.md`. Profile packages `prism-base`/`prism-code`/`prism-sdk`/`prism-all`/`prism-compaction` are gone — install the families. Peers and internal ranges are `^0.4.0`. No persisted-shape change; rollback = exact 0.3 pins.
+
+## [0.3.3] - 2026-08-31 (plans 041-044, 051, 052, 053)
+
+### Added
+- **Documents engine (`@arnilo/prism-documents@0.3.0`, plan 051)**: Initial release of `@arnilo/prism-documents` with peer `@arnilo/prism@^0.3.0` (independent Decision B publication, omitted from `@arnilo/prism-all` and profile packages) — pure in-memory OpenXML generation, parsing, patching, and bounded preview rendering for Word (`.docx`), Excel (`.xlsx`), and PowerPoint (`.pptx`) artifacts; exact-pinned sub-packages `@office-open/{docx,xlsx,pptx}@0.12.3`; Draft-07 JSON Schema validation with on-demand slicing (`getDocumentModelSchema`) and transitive closures; typed AST patch engine with immutable undo/redo history (`createPatchHistory`); framework-neutral preview blocks and sanitize-by-construction HTML snippets; `SecretRedactor` boundary sanitization hook; dependency-free `DocumentsTelemetry` seam; and documented decimal fidelity ceiling (`{ type: "decimal", value: string }` representation with IEEE-754 round-trip limits in Excel cells).
+- **Spreadsheet & CSV parsing engine (`@arnilo/prism-sheets@0.3.0`, plan 052)**: Initial release of `@arnilo/prism-sheets` with peer `@arnilo/prism@^0.3.0` (independent Decision B publication, omitted from `@arnilo/prism-all` and profile packages) — XLSX (`@office-open/xlsx@0.12.3` exact pin) and zero-dependency RFC 4180 CSV parsing with dialect sniffing (delimiter scoring across `,`, `;`, `\t`, `|`, quoted-region isolation, UTF-8 BOM stripping, UTF-16 rejection); decimal-safe typed schema inference (`inferAndTransformRows`, `normalizeDecimal`) with headline financial precision guarantees (monetary figures and currency patterns inferred as decimal strings `{ type: "decimal", value: string }` with zero floating-point coercion on decimal value paths; ambiguous numerics flagged `numeric-ambiguous`); bounded sampling window with full-parse validation; fail-closed caps (`DEFAULT_SHEETS_CAPS`: 100 MB file, 5M rows, 16k columns, 256 sheets, 500-row sample window, 20 max warnings); structured `InferenceWarning` and `SheetsDialectMismatchWarning` diagnostics; formula cell representation (`{ type: "formula", formula: string, value?: CellValue }`); dependency-free `SheetsTelemetry` seam.
+- **Diagrams & draw.io embed client (`@arnilo/prism-diagrams@0.3.0`, plan 053)**: Initial release of `@arnilo/prism-diagrams` with peer `@arnilo/prism@^0.3.0` (independent Decision B publication, omitted from `@arnilo/prism-all` and profile packages) — origin-enforced iframe embed client (`createDrawioEmbed`) implementing diagrams.net `proto=json` protocol with dual inbound origin/source verification, strict outbound targetOrigin enforcement, and no public SaaS defaults (self-hosting as the documented deployment); typed lifecycle events (`init`, `load`, `save`, `autosave`, `exit`, `configure`, `export`, `error`); save-with-preview workflows generating SVG (`xmlsvg`) or PNG visual snapshots; XXE-safe mxGraph XML validation (`validateDrawioXml`) rejecting DOCTYPE/ENTITY declarations and billion-laughs payloads under strict element/attribute/byte caps; byte-stable deterministic XML canonicalization (`canonicalizeDrawioXml`) for content hashing; Visio binary (`.vsd`) and OpenXML (`.vsdx`) exclusion guard (`assertNotVisio`, P12); and dependency-free telemetry seam (`DiagramsTelemetry`, P15).
+- **Progressive tool loading (plan 041)**: `search_tools({ query, k? })` — bounded inert name+description results (lexical disclosure, never wider than the eligible list, never zero via deterministic prefix), session-scoped activation persisted as names-only, dispatch re-checks allow/deny on every call (disclosure is not an authorization boundary). Benchmark: 86.4% provider-request tool-byte reduction at 128 tools / topK 16.
+- **Prompt provenance (plan 042)**: `RunRecord.promptVersion` refs carried from `RunOptions` to durable run rows; session-store packages add the additive nullable `prompt_version` column + checked migrations (`@arnilo/prism-session-store-{codecs,sqlite,postgres}@0.3.1`); `PERSISTENCE_SCHEMA_VERSION` 8 → 9. `@arnilo/prism-prompts@0.0.1` initial cut ships the versioned immutable prompt store (independent host opt-in).
+- **Docs**: `docs/documents.md` (documents, spreadsheets, and presentations hub guide), `docs/sheets.md` (spreadsheet and CSV parsing guide with decimal-safety invariant), `docs/diagrams.md` (diagramming and draw.io embed guide with origin-enforcement security), `docs/prompt-registry.md` (prompt registry contract), and composite memory recall scoring in `docs/working-and-semantic-memory.md`.
+- **Package consolidation (plan 054, completed in 0.4.0)**: `@arnilo/prism-core` (Task 2) absorbs 16 runtime/session/governance/credentials/enterprise/work/validation packages behind explicit subpaths; `@arnilo/prism-coding-tools` (Task 3) absorbs nine coding/persona packages with the retained `prism-dev` bin; `@arnilo/prism-web-tools` (Task 4) absorbs `@arnilo/prism-browser` and `@arnilo/prism-obscura` as peer-gated `/browser` and `/obscura` subpaths; `@arnilo/prism-memory` (Task 5) absorbs `@arnilo/prism-rag`, both compaction strategies, `@arnilo/prism-graft`, and `@arnilo/prism-wiki` as `/rag`, `/compaction/{llm,observational-memory}`, `/graft`, and `/wiki` subpaths (deleting the `@arnilo/prism-compaction` profile; `prism-wiki` bin and skills ship from the memory tarball); `@arnilo/prism-providers` (Task 6) absorbs all 17 `@arnilo/prism-provider-*` packages as `/<adapter>` subpaths (deleting the standalone provider manifests, the 14-of-17 umbrella dependency set, and the Azure/Bedrock/Vertex all-only special case; the `/ai-sdk` adapter resolves its `@ai-sdk/provider` optional peer lazily at factory time) — public symbols and trust boundaries unchanged except import specifiers. A generated legacy-registry plan (`scripts/phase54-legacy-registry.mjs`) freezes each of the 54 retired names' final published version behind a `legacy` dist-tag and a `<0.4.0` install-time deprecation warning naming its exact 0.4 successor and migration-guide anchor; `--dry-run` verifies versions/anchors without mutating the registry and `--apply --confirm` is the idempotent, fail-closed cutover (Task 9). `@arnilo/prism-office` (Task 8) absorbs the unpublished documents/sheets/diagrams drafts as `/documents`, `/sheets`, `/diagrams` subpaths and deletes the `prism-base`/`prism-code`/`prism-sdk`/`prism-all` profile manifests; the 0.4 migration guide maps every retired name plus the office drafts.
+- Package-level detail: `@arnilo/prism-memory@0.3.2` (composite recall scoring + importance at write), `@arnilo/prism-evals@0.3.1` (trace-to-dataset curation), `@arnilo/prism-documents@0.3.0` (initial cut), `@arnilo/prism-sheets@0.3.0` (initial cut), and `@arnilo/prism-diagrams@0.3.0` (initial cut).
+
+## [0.3.2] - 2026-08-29 (plan 050)
+
+### Added
+- **OKF adoption (`@arnilo/prism-wiki`)**: wiki-init/refresh/lint emit and validate
+  OKF v0.2 bundles (Karpathy prompt retained). See `docs/wiki.md`.
+- **DOCS-1 (Clay integration findings)**: three integrator contracts, in place on
+  the pages that own them — resume-aware workflow nodes (`ctx.resume` or silent
+  re-suspend) in `docs/workflows.md`; supervisor child factories return `Agent`
+  not `AgentSession` (`SupervisorError: child "<id>" factory must return an
+  Agent, got <type>`) plus durable-store nested approvals in `docs/supervisors.md`;
+  task-boundary `session.compact()` fails closed during an active run in
+  `docs/compaction-and-retry.md`. Each block links `examples/autonomous-coding-loop.ts`.
+- **FEATURE-2 (Clay integration findings)**: documented bounded iterate-until-done
+  host-loop pattern in `docs/workflows.md` — one `runWorkflow` per iteration,
+  iteration state in workflow inputs, explicit termination predicate and budgets,
+  typed `BudgetExhaustedError` (fail-closed, never a hang), `replayWorkflow` per
+  iteration run id. Seeded by `examples/autonomous-coding-loop.ts`. Plan 045 `loop`
+  node remains the future in-graph primitive; this intake ships the docs+example
+  minimum only.
+- **FEATURE-6 (Clay integration findings)**: composite `examples/autonomous-coding-loop.ts`
+  conformance reference — goal → roadmap → per-task supervisor children (per-child
+  models) → `runCodingGoalVerify`-style validation → observational-memory attach +
+  task-boundary compact + recall → human gate with simulated restart → host-side
+  bounded iterate-until-done with deterministic budget exhaustion. Mock providers
+  only; no credentials or network.
+- **FEATURE-3 (Clay integration findings)**: host-opt-in command driver hooks.
+  `CommandExecutionContext` gains an optional `drivers?: CommandDrivers`
+  (`startRun` / `startWorkflow` / `steer` — typed minimal handles returning
+  `AgentRunResult`-shaped results / workflow run id + status) so a contributed
+  command can act through host-injected capabilities instead of being
+  re-implemented host-side. The RPC session factory accepts `drivers` and
+  forwards them at the single command-execution site; absent drivers leave
+  the context shape unchanged (no key, no allocation). Drivers are
+  host-injected capabilities, never package-supplied.
+### Fixed
+- **FEATURE-1 (Clay integration findings)**: `resolveAgentDefinition` no longer
+  throws `Agent "<name>" has no model` when the declarative definition omits
+  `model` but `context.overrides.model` supplies one — the fallback is a
+  single `??` at `buildBaseConfig`, the `create()` path is unchanged, and a
+  definition with neither source still fails closed.
+
 ## [0.3.1] - 2026-08-29
 
 > Root + 28 changed packages move to 0.3.1 in the plan 039 changed-package cut; `@arnilo/prism-rag` moves 0.3.1 → 0.3.2; `@arnilo/prism-obscura` publishes new at 0.3.0. Distinct from the 2026-08-26 rag/memory/otel 0.3.1 patch below (independent Decision B tags).

package/README.md

@@ -4,9 +4,9 @@
 bring their tools, providers, credentials, storage, and UI; Prism supplies the
 common contracts, registries, agent/session runtime, replaceable input/prompt
 and compaction strategies, CLI/RPC adapters, and first-party provider/compaction
-packages. The current 0.3.0 line contains 56 publishable manifests, including
-optional Linux desktop control and independent package versioning after the final
-lockstep cut. Prism defines contracts, not apps.
+packages. The current 0.3.3 line contains 11 publishable manifests, including
+optional Linux desktop control, a versioned prompt registry, and independent
+package versioning after the final lockstep cut. Prism defines contracts, not apps.
 
 ## Current scope
 
@@ -20,7 +20,7 @@ lockstep cut. Prism defines contracts, not apps.
   OpenAI/OpenRouter use best-effort explicit cache hints, NeuralWatt uses
   best-effort implicit prefix caching, and other providers have route/model-specific
   or no cache-control support; see [docs/provider-caching.md](docs/provider-caching.md).
-- **First-party packages**: seventeen provider adapters, two compaction strategies,
+- **First-party packages**: seventeen provider adapter subpaths, two compaction strategies,
   coding tools/security, JSON Schema validation, MCP, workflows, OpenTelemetry,
   encrypted credentials, SQLite/PostgreSQL persistence, Linux desktop control,
   and manifest-only install profiles.
@@ -31,8 +31,8 @@ lockstep cut. Prism defines contracts, not apps.
   layering, and provider-input assembly — every stage replaceable.
 - **Sessions and memory**: in-memory and JSONL session stores, branching/fork/
   clone, default and LLM compaction strategies, retry policy,
-  observational-memory recall/status/view, optional working/semantic memory
-  (`@arnilo/prism-memory`), and bounded text/Markdown RAG (`@arnilo/prism-rag`).
+  observational-memory recall/status/view, and the `@arnilo/prism-memory` family
+  (working/semantic memory plus `/rag`, `/compaction/*`, `/graft`, `/wiki` subpaths).
 - **Extensions and manifests**: extension kernel + event bus, contribution
   registries, middleware hooks, and data-only package manifests.
 - **Config, settings, security**: layered config merge, settings providers,
@@ -55,14 +55,14 @@ a non-optional peer. Install atomic packages directly or choose a manifest-only
 family/profile; profiles install packages but expose no alias exports and activate nothing:
 
 ```bash
-npm install @arnilo/prism @arnilo/prism-provider-openai    # core + one provider
-npm install @arnilo/prism-base                              # core + compaction + validation
-npm install @arnilo/prism-code @arnilo/prism-provider-openai # coding-agent profile
-npm install @arnilo/prism-sdk @arnilo/prism-provider-openai  # application profile
-npm install @arnilo/prism-all                               # broad umbrella (21 direct / 47 workspace packages)
+npm install @arnilo/prism @arnilo/prism-providers            # core + all 17 provider adapters
+npm install @arnilo/prism @arnilo/prism-core @arnilo/prism-memory   # replaces prism-base
+npm install @arnilo/prism @arnilo/prism-coding-tools @arnilo/prism-mcp @arnilo/prism-providers  # replaces prism-code
+npm install @arnilo/prism @arnilo/prism-core @arnilo/prism-mcp @arnilo/prism-providers          # replaces prism-sdk
+npm install @arnilo/prism @arnilo/prism-core @arnilo/prism-providers  # pick families explicitly (no umbrella)
 npm install @arnilo/prism-server @arnilo/prism-workflows    # optional Web API boundary
 npm install @arnilo/prism-supervisor                         # optional local delegation + A2A 1.0
-npm install @arnilo/prism-web-tools                          # optional bounded Brave/Exa/Firecrawl research
+npm install @arnilo/prism-web-tools                          # unified web tools family (root search + /browser + /obscura subpaths)
 ```
 
 See [docs/release-and-install.md](docs/release-and-install.md) for install
@@ -70,15 +70,23 @@ specifiers, tarball contents, and the offline test budget.
 
 ## Quick start
 
-Scaffold a tiny project (offline mock test included):
+Scaffold a project (offline mock test included):
 
 ```bash
 npx --package @arnilo/prism prism init my-agent
-# or, with a real provider package selected:
+# or, scaffold with a real provider package selected:
 npx --package @arnilo/prism prism init my-agent --provider openai
+# or, scaffold a full deep research agent from the template gallery:
+npx --package @arnilo/prism prism init my-research --template deep-research
 cd my-agent && npm install && npm test
 ```
 
+List available template gallery starters:
+```bash
+prism init --list-templates
+```
+
+
 Or embed Prism directly:
 
 ```ts
@@ -118,7 +126,7 @@ Register a first-party provider package through the extension kernel:
 
 ```ts
 import { createExtensionKernel, createEnvCredentialResolver } from "@arnilo/prism";
-import { createOpenAIProviderPackage } from "@arnilo/prism-provider-openai";
+import { createOpenAIProviderPackage } from "@arnilo/prism-providers/openai";
 
 const kernel = createExtensionKernel();
 await kernel.load([
@@ -153,47 +161,16 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' \
 | package | purpose |
 |---------|---------|
 | `@arnilo/prism` | core contracts, runtime, registries, CLI/RPC |
-| `@arnilo/prism-provider-openai` | OpenAI Responses + Codex OAuth provider |
-| `@arnilo/prism-provider-opencode-go` | OpenCode Go provider |
-| `@arnilo/prism-provider-openrouter` | OpenRouter provider with per-model cache control |
-| `@arnilo/prism-provider-zai` | ZAI GLM provider |
-| `@arnilo/prism-provider-kimi` | Kimi For Coding provider |
-| `@arnilo/prism-provider-neuralwatt` | NeuralWatt provider with implicit vLLM prefix caching |
-| `@arnilo/prism-provider-alibaba` | Alibaba Cloud (Model Studio / DashScope + Coding Plan) provider with dynamic discovery and explicit/implicit caching |
-| `@arnilo/prism-provider-ollama` | Ollama Cloud / local provider with dynamic discovery and implicit-only caching |
-| `@arnilo/prism-provider-anthropic` | Anthropic Messages provider |
-| `@arnilo/prism-provider-google` | Google Gemini provider |
-| `@arnilo/prism-provider-deepseek` | DeepSeek Chat Completions provider |
-| `@arnilo/prism-provider-xai` | xAI Grok Completions + SuperGrok OAuth |
-| `@arnilo/prism-provider-clinepass` | ClinePass OpenAI-compatible gateway |
-| `@arnilo/prism-provider-azure` | Azure OpenAI provider |
-| `@arnilo/prism-provider-bedrock` | AWS Bedrock provider |
-| `@arnilo/prism-provider-vertex` | Google Vertex provider |
-| `@arnilo/prism-provider-ai-sdk` | AI SDK interoperability adapter |
-| `@arnilo/prism-browser` | optional host-wired Playwright browser automation (not core; not auto-activated) |
-| `@arnilo/prism-obscura` | optional Obscura headless-browser engine over a host-installed binary: MCP surface, CDP + Playwright, bounded CLI web tools (not in umbrellas; install explicitly) |
-| `@arnilo/prism-computer-use-linux` | optional Linux desktop-control tools over a host-owned `computer-use-linux` MCP binary |
-| `@arnilo/prism-antigravity-agent` | optional Antigravity CLI delegated agent adapter with per-run Prism MCP capability exposure |
-| `@arnilo/prism-wiki` | optional Karpathy LLM Wiki knowledge compiler with local `qmd` hybrid search and Context7 line navigation |
-| `@arnilo/prism-compaction-llm` | provider-backed compaction strategy |
-| `@arnilo/prism-compaction-observational-memory` | source-backed memory + recall tool |
-| `@arnilo/prism-coding-agent` | bounded shell/read/write/edit tools |
-| `@arnilo/prism-coding-security` | coding approval, containment, and sandbox adapters |
-| `@arnilo/prism-tool-validator-json-schema` | bounded JSON Schema tool validation |
-| `@arnilo/prism-mcp` | MCP client/tool bridge |
-| `@arnilo/prism-workflows` | bounded DAG workflows, durable suspend/resume, schedules/background runs, composition/state/replay, and multi-process coordination |
-| `@arnilo/prism-supervisor` | bounded local child delegation and A2A 1.0 interoperability |
-| `@arnilo/prism-web-tools` | host-selected bounded Brave/Exa search and Firecrawl Markdown/schema extraction |
-| `@arnilo/prism-observability-opentelemetry` | optional OpenTelemetry adapter |
-| `@arnilo/prism-credentials-node` | encrypted-file and keychain credentials |
-| `@arnilo/prism-session-store-sqlite` | SQLite persistence/checkpoints/leases/owned run feedback |
-| `@arnilo/prism-session-store-postgres` | PostgreSQL persistence/checkpoints/leases/owned run feedback |
-| `@arnilo/prism-providers` | family: 14 of 17 first-party provider adapters (omits Azure, Bedrock, Vertex, which `prism-all` adds separately), including AI SDK interoperability |
-| `@arnilo/prism-compaction` | family: both compaction strategies |
-| `@arnilo/prism-base` | profile: core + compaction + JSON Schema validation |
-| `@arnilo/prism-code` | profile: base + coding tools/security + MCP |
-| `@arnilo/prism-sdk` | profile: base + workflows + MCP + credentials + OpenTelemetry |
-| `@arnilo/prism-all` | broad umbrella: 21 first-party packages (47 transitive) across a 47-package workspace closure — omits document-reader, OpenAPI tools, NATS, Caveman, Ponytail, Impeccable, computer-use-linux, antigravity-agent, Graft, Obscura, and wiki |
+| `@arnilo/prism-core` | runtime/sessions/governance/credentials/enterprise/work/validation family |
+| `@arnilo/prism-providers` | all 17 first-party adapters as `/<adapter>` subpaths (openai, anthropic, google, azure, bedrock, vertex, deepseek, xai, zai, alibaba, kimi, clinepass, neuralwatt, ollama, opencode-go, openrouter, ai-sdk) |
+| `@arnilo/prism-coding-tools` | `/agent`, `/security`, `/document-reader`, `/openapi`, `/computer-use-linux`, `/dev`, `/caveman`, `/ponytail`, `/impeccable` |
+| `@arnilo/prism-web-tools` | Brave/Exa/Firecrawl plus peer-gated `/browser` and `/obscura` |
+| `@arnilo/prism-memory` | memory plus `/rag`, `/compaction/{llm,observational-memory}`, `/graft`, `/wiki` |
+| `@arnilo/prism-mcp` | MCP client/server/OAuth interop |
+| `@arnilo/prism-acp-agent` | ACP adapter |
+| `@arnilo/prism-ag-ui` | AG-UI/A2A/A2UI adapter |
+| `@arnilo/prism-antigravity-agent` | Antigravity CLI adapter |
+| `@arnilo/prism-office` | `/documents`, `/sheets`, `/diagrams` |
 
 ## Scripts
 
@@ -207,6 +184,6 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' \
 ## Non-goals (v1)
 
 - Privileged tools, MCP servers, telemetry, credentials, or databases activated by install — hosts explicitly configure and register every capability.
-- Browser automation or interactive terminal UI in core — hosts may opt into `@arnilo/prism-browser` with their own Playwright lifecycle; Prism does not auto-start browsers or ship a TUI.
+- Browser automation or interactive terminal UI in core — hosts may opt into the `@arnilo/prism-web-tools/browser` subpath with their own Playwright lifecycle; Prism does not auto-start browsers or ship a TUI.
 - Provider, credential, extension, or package auto-discovery.
 - Core-owned database drivers, secret persistence, sandbox, or application policy — optional packages implement adapters over host-owned boundaries.

package/dist/agent-definitions.js

@@ -20,7 +20,10 @@ export function resolveAgentDefinition(def, context) {
     return createAgent(applyConfigOverrides(baseConfig, context.overrides));
 }
 function buildBaseConfig(def, context) {
-    const model = resolveModel(def.name, def.model, context);
+    // Model precedence: explicit def.model wins; a definition without a model
+    // falls back to context.overrides.model (host-injected selection). Neither
+    // present still fails closed in resolveModel.
+    const model = resolveModel(def.name, def.model ?? context.overrides?.model, context);
     const tools = resolveTools(def.tools, context);
     const skills = resolveSkills(def.skills, tools, context);
     return {

package/dist/agent-run-lifecycle.js

@@ -101,6 +101,10 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
     if (options.persistSessionState && state.sessionState?.loadedSkillNames) {
         session.restoreLoadedSkills(state.sessionState.loadedSkillNames);
     }
+    // Plan 041: re-add search-activated tool names (names only; absent tools stay inert until re-searched).
+    if (options.persistSessionState && state.sessionState?.activatedToolNames) {
+        session.restoreActivatedTools(state.sessionState.activatedToolNames);
+    }
     // Plan 018 Task 6 (closeout `checkpoint-bodies`): restore exact instructions so the
     // resumed session renders them registry-independently (no load_skill round-trip).
     if (options.persistSessionState && options.includeSkillBodies && state.sessionState?.loadedSkillBodies) {

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

@@ -43,11 +43,15 @@ export interface StoredAgentRunState extends AgentRunState {
     readonly sessionState?: {
         readonly loadedSkillNames?: readonly string[];
         readonly loadedSkillBodies?: readonly LoadedSkillBodiesEntry[];
+        /** Plan 041: tools activated via `search_tools` (names only; inert for absent tools on restore). */
+        readonly activatedToolNames?: readonly string[];
     };
 }
 /** Session-state caps (plan 015 Task 4): bounded names charged against the run-state byte budget. */
 export declare const MAX_PERSISTED_SKILL_NAMES = 64;
 export declare const MAX_PERSISTED_SKILL_NAME_CHARS = 256;
+/** Plan 041: activated-tool names ride the same budget discipline (cap 128; multiple searches accumulate). */
+export declare const MAX_PERSISTED_ACTIVATED_TOOL_NAMES = 128;
 /** Revision stamps of the built-in loops; custom strategies declare their own `revision`. */
 export declare const BUILT_IN_LOOP_REVISIONS: Readonly<Record<string, string>>;
 /** Validate a strategy snapshot as JSON-compatible and package it for the durable envelope. */

package/dist/agent-run-state.js

@@ -10,6 +10,8 @@ const MAX_PROPERTIES = 256;
 /** Session-state caps (plan 015 Task 4): bounded names charged against the run-state byte budget. */
 export const MAX_PERSISTED_SKILL_NAMES = 64;
 export const MAX_PERSISTED_SKILL_NAME_CHARS = 256;
+/** Plan 041: activated-tool names ride the same budget discipline (cap 128; multiple searches accumulate). */
+export const MAX_PERSISTED_ACTIVATED_TOOL_NAMES = 128;
 /** Revision stamps of the built-in loops; custom strategies declare their own `revision`. */
 export const BUILT_IN_LOOP_REVISIONS = {
     "single-shot": "1",
@@ -252,14 +254,25 @@ function validateSessionState(sessionState) {
         }
     }
     const names = sessionState.loadedSkillNames;
-    if (names === undefined)
+    if (names !== undefined) {
+        if (!Array.isArray(names) || names.length > MAX_PERSISTED_SKILL_NAMES) {
+            throw new AgentRunStateError(`Loaded-skill names exceed ${MAX_PERSISTED_SKILL_NAMES} entries`);
+        }
+        for (const name of names) {
+            if (typeof name !== "string" || name.length > MAX_PERSISTED_SKILL_NAME_CHARS) {
+                throw new AgentRunStateError(`Loaded-skill name exceeds ${MAX_PERSISTED_SKILL_NAME_CHARS} chars`);
+            }
+        }
+    }
+    const activated = sessionState.activatedToolNames;
+    if (activated === undefined)
         return;
-    if (!Array.isArray(names) || names.length > MAX_PERSISTED_SKILL_NAMES) {
-        throw new AgentRunStateError(`Loaded-skill names exceed ${MAX_PERSISTED_SKILL_NAMES} entries`);
+    if (!Array.isArray(activated) || activated.length > MAX_PERSISTED_ACTIVATED_TOOL_NAMES) {
+        throw new AgentRunStateError(`Activated-tool names exceed ${MAX_PERSISTED_ACTIVATED_TOOL_NAMES} entries`);
     }
-    for (const name of names) {
+    for (const name of activated) {
         if (typeof name !== "string" || name.length > MAX_PERSISTED_SKILL_NAME_CHARS) {
-            throw new AgentRunStateError(`Loaded-skill name exceeds ${MAX_PERSISTED_SKILL_NAME_CHARS} chars`);
+            throw new AgentRunStateError(`Activated-tool name exceeds ${MAX_PERSISTED_SKILL_NAME_CHARS} chars`);
         }
     }
 }

package/dist/agent-session/session.d.ts

@@ -26,6 +26,7 @@ export declare class RuntimeAgentSession implements AgentSession {
     private activeIdempotencyKey?;
     private activeGuardrails?;
     private activeMetadata?;
+    private activePromptVersion?;
     private activeLimits?;
     private activeLimitOutputBuffer;
     private activeDurable?;
@@ -34,12 +35,18 @@ export declare class RuntimeAgentSession implements AgentSession {
     private activeGatedRound?;
     private activeLoopTurn;
     private readonly loadedSkills;
+    /** Tools activated via `search_tools` this session (plan 041); names-only in persistence. */
+    private readonly activatedTools;
     /** Plan 018 Task 6 (closeout `checkpoint-bodies`): persisted exact instructions, registry-independent. */
     private restoredSkillBodies;
     /** Skills of the current run (for the bodies snapshot); replaced at each run start. */
     private activeRunSkills;
     /** Plan 015 Task 4: re-add persisted loaded-skill names (names only; bodies re-resolve on demand). */
     restoreLoadedSkills(names: readonly string[]): void;
+    /** Plan 041: re-add persisted activated-tool names (names only; inert for absent tools). */
+    restoreActivatedTools(names: readonly string[]): void;
+    /** Plan 041: host reset of search-activated tools. */
+    clearActivatedTools(): void;
     /** Plan 018 Task 6: restore persisted loaded-skill bodies (already validated fail-closed at load). */
     restoreLoadedSkillBodies(bodies: readonly LoadedSkillBodiesEntry[]): void;
     private ledgerChain;

package/dist/agent-session/session.js

@@ -23,10 +23,31 @@ import { assertStructuredOutputRequestSupported, resolveRunProviderOptions } fro
 import { composeSystemPrompt, mergeSystemPromptConfig } from "../system-prompts.js";
 import { canonicalToolEffectJson, toolEffectArgumentsHash } from "../tool-effects.js";
 import { resolveToolResultFold } from "../tool-result-fold.js";
-import { dispatchToolCall, resolveToolEffectDeclaration } from "../tools.js";
+import { createActiveToolSet, createSearchToolsTool, createToolSearchState, resolveToolsDisclosure } from "../tool-search.js";
+import { createToolRegistry, dispatchToolCall, resolveToolEffectDeclaration } from "../tools.js";
 import { createAgentSession } from "./create-agent.js";
 import { EventSubscriber } from "./event-subscriber.js";
 import { bridgeAbort, createUsageAccumulator, errorFromInfo, finalAssistantMessage, inputToMessages, isDurableLoop, isSteerSoftInterrupt, jsonBytes, mergeCompaction, mergeGuardrails, mergeRetry, messageTextBytes, ProviderTurnFailure, providerContent, randomId, reconstructMissingToolCalls, SteerSoftInterrupt, throwIfAborted, throwIfAbortedSignal, withoutTrailingInput, } from "./helpers.js";
+const PROMPT_VERSION_MAX_NAME_BYTES = 256;
+const PROMPT_VERSION_HASH_PATTERN = /^sha256:[0-9a-f]{64}$/;
+/** Plan 042: validate the opaque provenance ref fail-closed before any session mutation. */
+function assertPromptVersionRef(ref) {
+    if (ref === undefined)
+        return undefined;
+    if (typeof ref !== "object" || ref === null)
+        throw new TypeError("RunOptions.promptVersion must be a PromptVersionRef object");
+    const { name, version, hash } = ref;
+    if (typeof name !== "string" || name.length === 0 || Buffer.byteLength(name, "utf8") > PROMPT_VERSION_MAX_NAME_BYTES) {
+        throw new TypeError(`RunOptions.promptVersion.name must be 1-${PROMPT_VERSION_MAX_NAME_BYTES} UTF-8 bytes`);
+    }
+    if (!Number.isInteger(version) || version < 1 || version > 0x7fffffff) {
+        throw new TypeError("RunOptions.promptVersion.version must be an integer in [1, 2147483647]");
+    }
+    if (typeof hash !== "string" || !PROMPT_VERSION_HASH_PATTERN.test(hash)) {
+        throw new TypeError('RunOptions.promptVersion.hash must be "sha256:" plus 64 lowercase hex characters');
+    }
+    return ref;
+}
 export class RuntimeAgentSession {
     id;
     agent;
@@ -50,6 +71,7 @@ export class RuntimeAgentSession {
     activeIdempotencyKey;
     activeGuardrails;
     activeMetadata;
+    activePromptVersion;
     activeLimits;
     activeLimitOutputBuffer = false;
     activeDurable;
@@ -58,6 +80,8 @@ export class RuntimeAgentSession {
     activeGatedRound;
     activeLoopTurn = 1;
     loadedSkills = createLoadedSkillSet();
+    /** Tools activated via `search_tools` this session (plan 041); names-only in persistence. */
+    activatedTools = createActiveToolSet();
     /** Plan 018 Task 6 (closeout `checkpoint-bodies`): persisted exact instructions, registry-independent. */
     restoredSkillBodies = [];
     /** Skills of the current run (for the bodies snapshot); replaced at each run start. */
@@ -67,6 +91,15 @@ export class RuntimeAgentSession {
         for (const name of names)
             this.loadedSkills.add(name);
     }
+    /** Plan 041: re-add persisted activated-tool names (names only; inert for absent tools). */
+    restoreActivatedTools(names) {
+        for (const name of names)
+            this.activatedTools.add(name);
+    }
+    /** Plan 041: host reset of search-activated tools. */
+    clearActivatedTools() {
+        this.activatedTools.clear();
+    }
     /** Plan 018 Task 6: restore persisted loaded-skill bodies (already validated fail-closed at load). */
     restoreLoadedSkillBodies(bodies) {
         validateLoadedSkillBodies(bodies);
@@ -167,6 +200,7 @@ export class RuntimeAgentSession {
         if (legacyMaxToolRounds !== undefined) {
             throw new TypeError("RunOptions.maxToolRounds was removed in 0.1.5; use RunOptions.limits.maxToolRounds instead");
         }
+        const promptVersion = assertPromptVersionRef(options.promptVersion);
         if (this.agent.config.secure &&
             (options.redactor !== undefined ||
                 options.ownership !== undefined ||
@@ -228,6 +262,7 @@ export class RuntimeAgentSession {
             ...(this.activeIdentity ? identityTelemetryAttributes(this.activeIdentity) : {}),
         };
         this.activeMetadata = metadata;
+        this.activePromptVersion = promptVersion;
         const limits = new RunLimitTracker(resolvedLimits, {
             onExceeded: (breach) => {
                 this.emit({ type: "run_limit_exceeded", sessionId: this.id, runId, breach });
@@ -253,11 +288,27 @@ export class RuntimeAgentSession {
                 idempotencyKey: this.activeIdempotencyKey,
                 status: "running",
                 startedAt,
+                ...(promptVersion ? { promptVersion } : {}),
                 ...this.activeOwnership,
             };
             await this.activeLedger?.appendRun(redactRunLedgerRecord(startRecord, this.activeRedactor));
             await this.rebuildHistory();
-            const { registry, tools } = activeTools(this.agent.config.tools);
+            const { registry: baseRegistry, tools: activeToolList } = activeTools(this.agent.config.tools);
+            const toolsDisclosure = resolveToolsDisclosure(options.toolsDisclosure, this.agent.config.toolsDisclosure);
+            // Search mode: run-local registry copy plus the generated `search_tools` tool; the host
+            // registry is never mutated. Activation names are intersected at disclosure only.
+            const toolSearch = toolsDisclosure === "search" && activeToolList.length > 0
+                ? {
+                    state: createToolSearchState({
+                        tools: activeToolList,
+                        activated: this.activatedTools,
+                        search: this.agent.config.toolsSearch,
+                    }),
+                }
+                : undefined;
+            const searchTool = toolSearch ? createSearchToolsTool(toolSearch.state) : undefined;
+            const registry = searchTool ? createToolRegistry([...activeToolList, searchTool]) : baseRegistry;
+            const tools = searchTool ? [...activeToolList, searchTool] : activeToolList;
             const activeSkills = this.resolveRunSkills(options, tools);
             this.activeRunSkills = activeSkills; // for the durable bodies snapshot (plan 018 Task 6)
             if (options.model && JSON.stringify(options.model) !== JSON.stringify(this.agent.config.model)) {
@@ -471,6 +522,9 @@ export class RuntimeAgentSession {
                         contextProviders,
                         skills: this.restoredSkillBodies.length ? applyRestoredSkillBodies(activeSkills, this.restoredSkillBodies) : activeSkills,
                         skillsDisclosure: resolveSkillsDisclosure(options.skillsDisclosure, this.agent.config.skillsDisclosure),
+                        toolsDisclosure,
+                        toolsSearch: this.agent.config.toolsSearch,
+                        activatedTools: this.activatedTools,
                         toolResultFold: resolveToolResultFold(options.toolResultFold, this.agent.config.toolResultFold),
                         loadedSkills: this.loadedSkills,
                         tools,
@@ -920,6 +974,7 @@ export class RuntimeAgentSession {
                         finishedAt: new Date().toISOString(),
                         abortReason: controller.signal.aborted ? String(controller.signal.reason) : undefined,
                         error: runError,
+                        ...(this.activePromptVersion ? { promptVersion: this.activePromptVersion } : {}),
                         ...this.activeOwnership,
                     };
                     await this.activeLedger.appendRun(redactRunLedgerRecord(finishRecord, this.activeRedactor));
@@ -935,6 +990,7 @@ export class RuntimeAgentSession {
                 this.activeIdempotencyKey = undefined;
                 this.activeGuardrails = undefined;
                 this.activeMetadata = undefined;
+                this.activePromptVersion = undefined;
                 this.activeLimits?.dispose();
                 this.activeLimits = undefined;
                 this.activeLimitOutputBuffer = false;
@@ -1124,6 +1180,7 @@ export class RuntimeAgentSession {
                 ...state,
                 sessionState: {
                     loadedSkillNames: this.loadedSkills.list(),
+                    ...(this.activatedTools.list().length ? { activatedToolNames: this.activatedTools.list() } : {}),
                     ...(durable.options.includeSkillBodies
                         ? {
                             loadedSkillBodies: snapshotLoadedSkillBodies(this.activeRunSkills, this.loadedSkills, this.restoredSkillBodies.length ? new Map(this.restoredSkillBodies.map((e) => [e.name, e.instructions])) : undefined),

package/dist/cli-dev.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Plan 040 Task 4 — `prism dev` delegation into `@arnilo/prism-dev`.
+ * The core deliberately holds no compile-time dependency on the dev package
+ * (dev-only surface, omitted from umbrellas): the subcommand resolves the
+ * package from the current project's own `node_modules` and hands the CLI
+ * over. Unresolvable → actionable install hint, exit 2.
+ */
+import type { Writable } from "node:stream";
+export interface DevCliModule {
+    runDevCli(argv: readonly string[], runtime: {
+        stdout: Writable;
+        stderr: Writable;
+        cwd?: string;
+    }): Promise<number>;
+}
+export type PrismDevLoader = () => Promise<DevCliModule | undefined>;
+export interface PrismDevSubcommandRuntime {
+    readonly stdout: Writable;
+    readonly stderr: Writable;
+    /** Test injection: overrides project-level `@arnilo/prism-dev` resolution. */
+    readonly loadDevCli?: PrismDevLoader;
+}
+/**
+ * Default loader: resolve `@arnilo/prism-coding-tools/dev/cli` (or `@arnilo/prism-dev/cli`)
+ * from the project the user is standing in, falling back to this CLI's own installation.
+ */
+export declare const defaultLoadDevCli: PrismDevLoader;
+/** Runs the `prism dev` subcommand by delegating into the resolved package. */
+export declare function runPrismDevSubcommand(argv: readonly string[], runtime: PrismDevSubcommandRuntime): Promise<number>;

package/dist/cli-dev.js

@@ -0,0 +1,52 @@
+/**
+ * Plan 040 Task 4 — `prism dev` delegation into `@arnilo/prism-dev`.
+ * The core deliberately holds no compile-time dependency on the dev package
+ * (dev-only surface, omitted from umbrellas): the subcommand resolves the
+ * package from the current project's own `node_modules` and hands the CLI
+ * over. Unresolvable → actionable install hint, exit 2.
+ */
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+const installHint = "prism dev requires the dev inspector package in this project.\n" +
+    "  npm install --save-dev @arnilo/prism-coding-tools\n" +
+    "(Scaffolded projects from newer `prism init` templates already include it.)\n";
+/**
+ * Default loader: resolve `@arnilo/prism-coding-tools/dev/cli` (or `@arnilo/prism-dev/cli`)
+ * from the project the user is standing in, falling back to this CLI's own installation.
+ */
+export const defaultLoadDevCli = async () => {
+    const specifiers = ["@arnilo/prism-coding-tools/dev/cli", "@arnilo/prism-dev/cli"];
+    for (const specifier of specifiers) {
+        try {
+            const require = createRequire(join(process.cwd(), "package.json"));
+            const resolved = require.resolve(specifier);
+            const mod = (await import(pathToFileURL(resolved).href));
+            if (typeof mod.runDevCli === "function")
+                return mod;
+        }
+        catch {
+            try {
+                const mod = (await import(specifier));
+                if (typeof mod.runDevCli === "function")
+                    return mod;
+            }
+            catch {
+                // try next specifier
+            }
+        }
+    }
+    return undefined;
+};
+/** Runs the `prism dev` subcommand by delegating into the resolved package. */
+export async function runPrismDevSubcommand(argv, runtime) {
+    const load = runtime.loadDevCli ?? defaultLoadDevCli;
+    const mod = await load();
+    if (!mod || typeof mod.runDevCli !== "function") {
+        runtime.stderr.write(installHint);
+        return 2;
+    }
+    return mod.runDevCli(argv, { stdout: runtime.stdout, stderr: runtime.stderr });
+}
+//# sourceMappingURL=cli-dev.js.map

package/dist/cli-init.d.ts

@@ -4,6 +4,8 @@ export declare class InitUsageError extends Error {
 export type InitProvider = string;
 export interface InitOptions {
     readonly directory: string;
+    readonly template?: string;
+    readonly listTemplates?: boolean;
     readonly provider: InitProvider;
     readonly withWorkflows: boolean;
     readonly withEvals: boolean;
@@ -15,6 +17,8 @@ export interface InitRuntime {
     readonly stderr: Writable;
     /** Override template root (tests). Defaults to package `templates/init`. */
     readonly templatesRoot?: string;
+    /** Override gallery root (tests). Defaults to package `templates`. */
+    readonly galleryRoot?: string;
     /** Override package version stamped into generated package.json. */
     readonly packageVersion?: string;
     /** Working directory used to resolve relative destinations. Defaults to process.cwd(). */
@@ -23,17 +27,28 @@ export interface InitRuntime {
 export interface InitResult {
     readonly targetDir: string;
     readonly writtenFiles: readonly string[];
+    readonly template?: string;
     readonly provider: InitProvider;
     readonly withWorkflows: boolean;
     readonly withEvals: boolean;
     readonly totalBytes: number;
 }
+export interface TemplateInfo {
+    readonly name: string;
+    readonly description: string;
+    readonly version?: string;
+    readonly path: string;
+}
 /** Provider ids supported by `prism init --provider`. Loaded from templates data. */
 export declare function listInitProviders(templatesRoot?: string): readonly string[];
-export declare function getInitUsage(templatesRoot?: string): string;
+/** Template list discovered from the templates gallery. */
+export declare function listInitTemplates(galleryRoot?: string): readonly TemplateInfo[];
+export declare function isInitTemplate(value: string, galleryRoot?: string): boolean;
+export declare function getInitUsage(templatesRoot?: string, galleryRoot?: string): string;
 export declare const initUsage: string;
-export declare function parseInitArgs(argv: readonly string[], templatesRoot?: string): InitOptions;
+export declare function parseInitArgs(argv: readonly string[], templatesRoot?: string, galleryRoot?: string): InitOptions;
 export declare function runInitCommand(argv: readonly string[], runtime: InitRuntime): Promise<number>;
 export declare function createInitProject(options: InitOptions, runtime?: InitRuntime): Promise<InitResult>;
 export declare function defaultTemplatesRoot(): string;
+export declare function defaultGalleryRoot(): string;
 export declare function isInitProvider(value: string, templatesRoot?: string): value is InitProvider;