@arnilo/prism 0.3.2 → 0.4.0

package/docs/migration.md

@@ -1,5 +1,27 @@
 # Migration guide
 
+## 0.3.3 → 0.4.0 package reorganization (breaking)
+
+Prism 0.4 consolidates package names into explicit family subpaths. It is a dependency and import-specifier migration, not a persisted-data migration. See the complete [legacy 0.3 → 0.4 guide](migrate-to-0.4.md) for all 54 retired package mappings, profile replacements, optional peers/host binaries, security checks, rollback, and npm legacy-warning behavior.
+
+## 0.3.1 → 0.3.2: bounded workflow loop durability (additive, no migration)
+
+`@arnilo/prism-workflows@0.3.2` adds the bounded `loopNode` durable extension. It adds optional `WorkflowNodeCheckpoint.iterations` records, each carrying `schemaVersion: 1`, a zero-based `iteration`, stable `iterationId`, and bounded/redacted output. Existing `WorkflowCheckpointValue.schemaVersion` remains `1`; older checkpoints without `iterations` remain readable through the legacy `iteration`/`lastOutput` cursor, and older hosts ignore the additive field. No SQL or generic checkpoint-store migration is required. Replay creates a new run and never mutates source iteration evidence. Hosts using saga compensation keep one saga step/aggregate and register per-iteration compensation by `iterationId` in reverse order.
+
+This independent package patch freezes budget accounting: `maxNodes` counts declared DAG nodes once, while loop body executions consume only the required hard-capped `maxIterations` budget. Rollback is package-version rollback; no persisted migration is needed.
+
+## 0.3.2 → 0.3.3: run-ledger prompt provenance (additive, schema version 9)
+
+Plan 042 adds an optional typed `promptVersion` ref (`{ name, version, hash }`) to `RunOptions` and `RunRecord`. Hosts resolve a prompt from `@arnilo/prism-prompts` and stamp the run: the ref is copied onto the start/finish ledger records and persisted by the first-party SQLite/PostgreSQL stores as a nullable `prompt_version` JSON column (shared schema migration `009_run_prompt_version`, schema version 8 → 9, forward-only and applied automatically by the adapters' checksummed `prism_migrations`). Strictly additive: unset `promptVersion` produces byte-identical rows and records, legacy rows read back without the field, and no exported declaration was removed. The ref carries identity only (`sha256:` body hash) — prompt bodies stay in the separate `@arnilo/prism-prompts` tables and out of run rows, metadata, and telemetry.
+
+## 0.3.2 → 0.3.3: tool progressive disclosure (additive, no migration)
+
+Plan 041 adds opt-in progressive tool loading to `@arnilo/prism`: `toolsDisclosure` (default `"all"`, byte-identical to previous releases) and `toolsSearch.topK` on `AgentConfig` / `RunOptions`, plus the generated `search_tools` tool in search mode. Strictly additive — no exported declaration removed, no persisted shape repurposed. Durable run state gains an optional `sessionState.activatedToolNames` (names only, capped at 128); stores that ignore it resume exactly as before. Set nothing and behavior is unchanged; see [Tools](tools.md#tool-disclosure-progressive-tool-loading).
+
+## 0.3.1 → 0.3.2 memory package: composite recall scoring (additive, no migration)
+
+`@arnilo/prism-memory@0.3.2` adds opt-in `RecallOptions.scoring`: sum-normalized similarity/recency/importance blending, with a positive `halfLifeMs` required only when `recencyWeight > 0`. Default recall (no `scoring`) keeps its existing ordering and query count. `MemoryVectorRecord.importance?` persists through an additive nullable `importance REAL` column (`ADD COLUMN IF NOT EXISTS`); legacy NULL rows score neutral `1.0`, so no re-index or data migration is required. At write, hosts may pass a clamped `[0,1]` `entry.importance` or an `importanceFrom` hook over a redacted reflection; it runs once at write, never at recall. Rollback is package-version rollback only: old readers ignore the nullable column, and new readers treat absent values neutrally.
+
 ## 0.3.0 → 0.3.1 production RAG engine (independent patch)
 
 Only `@arnilo/prism-rag`, `@arnilo/prism-memory`, and `@arnilo/prism-observability-opentelemetry` move to `0.3.1`. Keep every other first-party package on `^0.3.0` — those ranges already satisfy `0.3.1`.

package/docs/model-routing.md

@@ -156,4 +156,4 @@ await router.recordOutcome({ identity, provider, model, success: true, latencyMs
 - [Policy and audit](policy-and-audit.md)
 - [Agent identity](agent-identity.md)
 - [Enterprise PostgreSQL state](enterprise-postgres-state.md): durable router state, migration, cleanup, and ownership requirements.
-- Package README: [`@arnilo/prism-model-router`](../packages/model-router/README.md)
+- Package README: [`@arnilo/prism-core`](../packages/prism-core/README.md)

package/docs/multi-agent-patterns.md

@@ -0,0 +1,177 @@
+# Multi-agent patterns: handoff, hierarchical crew, supervisor delegation, A2A
+
+## What it does
+
+Maps the four Prism answers for "more than one agent" onto one decision table. All four compose existing seams — none introduces a new runtime:
+
+- **In-session handoff (swarm)** — agent A transfers control of the ongoing conversation to agent B by calling a host-built `handoff` tool; the host resolves the target `AgentDefinition` with `resolveAgentDefinition` and opens the specialist against the same session (same store + session id, previous run's `leafId`). One transcript, no new session. No helper primitive ships; the tool factory lives in [`examples/handoff-swarm.ts`](../examples/handoff-swarm.ts).
+- **Hierarchical crew** — a manager agent decomposes a goal into typed tasks (`{ tasks: [{ role, instruction }] }`) via structured output ([`Artifact*`](structured-output.md)), fans out to parallel role specialists with bounded `maxFanOut` ([`fanOutNode`](workflows.md)), aggregates deliverables with host reduce ([`joinNode`](workflows.md)), and validates outputs with conditional routing to completion or revision ([`conditionalNode`](workflows.md)). The entire process is a deterministic DAG workflow with zero new runtime primitives. Live demo in [`examples/crew-hierarchy.ts`](../examples/crew-hierarchy.ts).
+- **Supervisor delegation** — `@arnilo/prism-supervisor` `delegate()` invokes allow-listed child agents as bounded runs and returns their result to the parent. Separate child transcripts, hooks, budgets, narrowing.
+- **A2A 1.0** — cross-service interop over the JSON-RPC/HTTPS binding; the remote peer's lifecycle is host-owned behind `A2ATaskLifecycle`.
+
+## When to use it
+
+| Pattern | Use when | Conversation boundary | Ownership / identity | Telemetry |
+| --- | --- | --- | --- | --- |
+| In-session handoff | One host, one ongoing conversation; the model decides **when** to transfer; specialists are alternate definitions of the same app | One continuous transcript chain (same store, session id, `leafId`) | Same session scope; give the specialist its own identity via its definition (`AgentConfig.identity` / `RunOptions.identity`) | Attribution is per-run: each `session.run()`'s events/result belong to the active definition — record the swap in host bookkeeping; no `delegated_agent_step` event exists for in-process swaps |
+| Hierarchical crew | A goal requires dynamic decomposition by a manager LLM, parallel execution by role specialists, host aggregation, and conditional validation/revision loop | Workflow DAG execution — each specialist executes a bounded child task session; final deliverable returns to host | Workflow tenant/ownership scopes propagate; specialists activate only their own narrowed `tools` | Workflow node events (`node_started`/`node_finished`/`agent_event`); task attribution per role in the aggregated deliverable |
+| Supervisor delegation | Parent agent needs a child as a *tool call*: bounded budget, hooks that redact/narrow, nested delegation, durable child approvals | Separate runs; child result returns to the parent transcript | Parent identity/effectStore propagate; child factories receive derived resource/thread ids and AND-composed permission | Dedicated `delegation_started/finished/rejected/error` events, projectable through observability `handleDelegation()`; opt-in `delegation_child_event` passthrough |
+| A2A 1.0 | The other agent is owned by a **different service/deployment**; cross-org or cross-cluster; needs durable task lifecycle, push configs, streaming | Protocol boundary (JSON-RPC/HTTPS agent card); replay/reconnect via host-owned task adapter | Exact-origin verified client, `A2AAuthorization` per operation, principal-scoped push configs | Host-owned task adapter records the remote lifecycle; Prism creates no worker/store |
+
+Rule of thumb: same conversation → handoff; dynamic task decomposition + parallel execution → hierarchical crew; same process but a subtask → supervisor delegation; different deployment/trust boundary → A2A.
+
+## How in-session handoff works
+
+The pattern is a definition swap over existing seams — triage keeps calling `handoff(target)`; the host authorizes, swaps, and continues the same session:
+
+```ts
+// Host-built allow-list tool; untrusted target -> fail-closed tool error result.
+const handoffTool: ToolDefinition = {
+  name: "handoff",
+  description: "Transfer this conversation to a named specialist agent.",
+  parameters: { type: "object", required: ["target"], properties: { target: { type: "string" } } },
+  execute(args, ctx): ToolResult {
+    const target = String((args as { target: string }).target);
+    if (!(target in handoffTargets)) {
+      return { toolCallId: ctx.toolCallId, name: "handoff", error: { message: `Unknown handoff target: ${target}` } };
+    }
+    return { toolCallId: ctx.toolCallId, name: "handoff", value: { transferredTo: target } };
+  },
+};
+
+// Host authorizes the transfer mid-run: resolve the target definition and
+// continue the SAME session (same store + sessionId). The previous run's
+// leafId carries the transcript pointer; without it the next append forks
+// a sibling branch and the specialist loses the carried context.
+const specialist = await resolveAgentDefinition(handoffTargets[target], {
+  tools: [refundTool],              // narrowed: no handoff tool unless the host allows it
+  overrides: { provider: specialistProvider },
+});
+const specialistSession = createAgentSession({ agent: specialist, store, id: "handoff-demo", leafId: triageRun.leafId });
+```
+
+Live demo: [`examples/handoff-swarm.ts`](../examples/handoff-swarm.ts) — triage → billing transfer with fail-closed unknown target, a specialist whose re-handoff attempt is blocked (`unknown_tool`), and zero provider calls for the swap (it is a registry-level operation).
+
+Two non-obvious details the example encodes:
+
+1. **`leafId` carries the transcript pointer.** The specialist session must pass the triage run's `leafId`; creating the session without it appends to a sibling branch and the specialist loses the carried context.
+2. **Carried context is the transcript chain itself.** Handoff is not delegation: there is no input-payload boundary to sanitize; whatever was said to triage is what the specialist reads.
+
+## How hierarchical crew orchestration works
+
+Hierarchical multi-agent orchestration (the CrewAI "Hierarchical Process" pattern) decomposes a high-level goal into structured tasks, assigns each task to a role specialist agent in parallel, aggregates deliverables, and validates the outcome in a deterministic workflow:
+
+```ts
+// 1. Manager produces a typed task plan via structured output.
+//    Untrusted model output is validated against the schema before updating state.
+const manager = agentNode({
+  agent: "manager",
+  input: (ctx) => ({ goal: ctx.workflowInput }),
+  output: async (ctx) => {
+    const plan = parseTaskPlan(await getSessionOutput(ctx.session));
+    if (!plan.ok) throw new Error(`Invalid task plan: ${plan.error}`);
+    await ctx.updateState({ plan: plan.value });
+    return plan.value;
+  },
+});
+
+// 2. fan_out maps each task item to its corresponding role specialist.
+const fan = fanOutNode({
+  items: (ctx) => (ctx.state.plan as TaskPlan).tasks,
+  map: async (task, _index, _ctx) => {
+    const agent = await resolveAgentDefinition(definitions[task.role], { tools });
+    const session = createAgentSession({ agent });
+    const result = await session.run(task.instruction);
+    return { role: task.role, result: result.text, attribution: { agent: task.role } };
+  },
+  maxFanOut: 8,
+});
+
+// 3. join aggregates all specialist deliverables and computes per-role attribution.
+const aggregate = joinNode({
+  from: "fan",
+  reduce: async (items, ctx) => ({
+    deliverables: items,
+    summary: items.map((d) => `[${d.role}]: ${d.result}`).join("\n"),
+    validationPassed: evaluateQuality(items),
+  }),
+});
+
+// 4. conditional validation routes to completion or revision.
+const validate = conditionalNode({
+  when: async (ctx) => Boolean((ctx.upstream.aggregate as AggregatedDeliverable).validationPassed),
+  then: ["complete"],
+  else: ["revise"],
+});
+
+const complete = functionNode({ execute: async (ctx) => formatDeliverable(ctx.upstream.aggregate) });
+const revise = functionNode({ execute: async (ctx) => formatRevision(ctx.upstream.aggregate) });
+
+// 5. Entire flow is a single defineWorkflow DAG with fixed revision ID.
+const crewWorkflow = defineWorkflow({
+  revision: "crew-demo-1",
+  id: "hierarchical-crew",
+  nodes: { manager, fan, aggregate, validate, complete, revise },
+  edges: [
+    ["manager", "fan"],
+    ["fan", "aggregate"],
+    ["aggregate", "validate"],
+    ["validate", "complete"],
+    ["validate", "revise"],
+  ],
+  limits: { maxFanOut: 8, maxConcurrency: 4, maxNodes: 32 },
+});
+```
+
+Live demo: [`examples/crew-hierarchy.ts`](../examples/crew-hierarchy.ts) — manager structured task decomposition, parallel role specialists (`researcher`, `writer`), host reduce aggregation with per-role attribution, and conditional validation/revision routing.
+
+## CrewAI to Prism mapping table
+
+| CrewAI Concept | Prism Primitive | Notes & Documentation |
+| --- | --- | --- |
+| **Crew** | Workflow ([`defineWorkflow`](workflows.md)) | A deterministic DAG with explicit revision id, node concurrency, and checkpoint persistence. |
+| **Manager Agent** | Agent Node ([`agentNode`](workflows.md)) + Structured Output ([`generateValidateReviseLoop`](structured-output.md)) | Manager emits a typed `{ tasks: [{ role, instruction }] }` schema via `ArtifactValidator`/`ArtifactParser`. |
+| **Task** | Fan-out item ([`fanOutNode`](workflows.md)) | Bounded dynamic fan-out (`maxFanOut`), mapping each decomposed task to a role specialist session. |
+| **Role Agent (Specialist)** | Agent Definition ([`resolveAgentDefinition`](agent-definitions.md)) | Declarative agent with fail-closed tool narrowing; activated per role during `fan_out.map`. |
+| **Process (Sequential / Hierarchical)** | Workflow DAG ([`defineWorkflow`](workflows.md) / Edges) | Edges define data and execution dependencies; no unconstrained agent-to-agent loops. |
+| **Task Output Aggregation** | Join Node ([`joinNode`](workflows.md) + `reduce`) | Host-controlled reduction aggregating specialist outputs and computing per-role attribution. |
+| **Validation & Quality Review** | Conditional Node ([`conditionalNode`](workflows.md)) | Deterministic branch routing to `complete` or `revise` based on validation criteria. |
+| **Process Revision Loop** | Node Retries / DAG Branching / Loop Node ([`loopNode`](workflows.md)) | Bounded retry/revision path or bounded in-graph loop iteration. |
+
+## Where Prism is stronger
+
+- **Durable Human-in-the-Loop (HITL)**: Prism workflows support durable pause and resume via [`suspend()`](workflows.md#durable-suspension-and-resumption) and [`resumeWorkflow()`](workflows.md) across worker restarts or approval gates ([Agent durable approval](agent-session-runtime.md)).
+- **Strict Budget & Concurrency Caps**: Workflows enforce hard limits on `maxNodes`, `maxFanOut`, `maxConcurrency`, and timeout bounds ([Workflow limits](workflows.md)).
+- **Fail-Closed Capability Narrowing**: Specialists receive only their explicitly authorized `tools` via [`resolveAgentDefinition`](agent-definitions.md); managers cannot invoke specialist tools directly, preventing accidental tool leakage.
+- **Untrusted Model Output Validation**: Manager task plans are treated as untrusted LLM output and validated against a typed schema before triggering fan-out ([Structured output](structured-output.md)).
+- **Durable Audit & Telemetry**: Every node start/finish and agent event is emitted with deterministic sequence numbers and can be persisted to signed audit ledgers ([Policy and audit](policy-and-audit.md), [Observability](observability.md)).
+
+## Security and performance notes
+
+- **Transfers are explicit model-initiated, host-authorized.** The `handoff` tool exists on the triage agent's allow-list only; the target name is validated against the host-authored targets map before any definition resolves. Unknown names fail closed as a standard tool error (`Unknown handoff target: <name>`).
+- **No permission escalation through handoff or delegation.** The specialist's capabilities come solely from its own `AgentDefinition` as resolved by `resolveAgentDefinition` (fail-closed for omitted capabilities). Handoff or fan-out grants nothing: tools/identity are what the host put on that definition. The specialist cannot invoke manager tools unless its definition explicitly includes them — the standard `unknown_tool` block applies otherwise.
+- **Narrowing on transfer, never widening.** If the specialist needs the caller's verified identity, project it through `narrowIdentity` / `assertIdentityPropagation` ([Agent identity](agent-identity.md)) so scopes and tenant cannot widen across the swap. For delegation the same discipline is built in (`narrowIdentity`, AND-composed policies); for A2A the exact-origin client plus per-operation authorization is the boundary.
+- **Manager-generated task plans are untrusted model output.** Manager plan outputs are validated against the typed schema via `ArtifactValidator` before being persisted to workflow state or dispatched to `fan_out`. Malformed or invalid plans trigger the artifact repair loop or fail closed before any specialist is invoked.
+- **Redaction of carried context.** Handoff carries the raw transcript by design — same rows a human replay would read. Apply the session egress seams on the way out: `redactSessionEntry` / `redactMessage` with a host field policy (see [Data classification](data-classification.md)) and `AgentConfig.redactor`; for durable replay across tenants reuse the redacted transcript seam discipline used by ACP `sessions.transcript` ([ACP interop](acp.md)).
+- **Telemetry attribution.** Which agent produced which turn is not stored on message entries; the host knows (it performed the swap or aggregated fan-out results) and should pin it per run via `RunOptions.identity` (principal kind `agent`) so `identityTelemetryAttributes` (`prism.identity.*`) carries redacted attribution on telemetry, or via observability metadata. Supervisor runs emit dedicated `delegation_*` events; adapter-owned delegation timelines emit `delegated_agent_step` through `createDelegatedAgentStep` (see [Agent events](agent-events.md)) — an in-process definition swap has no session seam to emit it, which is why the swap records attribution host-side.
+- **Performance.** The swap performs zero provider calls; it costs one registry resolution plus one session open (~sub-millisecond in the example fixture). The transferred turn costs what any tool round costs.
+
+## Extension and configuration notes
+
+- Handoff targets may be code-defined `AgentDefinition` objects or `<configRoot>/agents/<name>/AGENT.md` bundles resolved via `resolveAgentBundle` — the allow-list maps names to either.
+- Hosts wanting the pattern behind a UI timeline can emit their own step events from the swap; `delegated_agent_step` remains reserved for adapter-driven delegation loops (`@arnilo/prism-antigravity-agent`).
+- A reusable in-session handoff helper was evaluated and **not** shipped in 0.3.x: the unavoidable boilerplate is a ~20-line allow-list tool plus one `createAgentSession` call. Revisit only if multiple hosts show materially different swap semantics.
+- Hierarchical crew patterns compose entirely on existing `@arnilo/prism-workflows` and `@arnilo/prism` primitives (`agentNode`, `fanOutNode`, `joinNode`, `conditionalNode`, `ArtifactValidator`, `resolveAgentDefinition`); no separate helper package is needed.
+
+## Related APIs
+
+- [Workflows](workflows.md): `defineWorkflow`, `fanOutNode`, `joinNode`, `conditionalNode`, `runWorkflow`.
+- [Structured output](structured-output.md): `ArtifactParser`, `ArtifactValidator`, `generateValidateReviseLoop`.
+- [Agent definitions](agent-definitions.md): `resolveAgentDefinition` and fail-closed capability activation — the swap seam itself.
+- [Supervisor delegation](supervisors.md): same-process subtasks with budgets, hooks, and durable nested approvals.
+- [A2A interoperability](a2a.md): the cross-service protocol boundary.
+- [Agent identity](agent-identity.md): verified identity propagation and narrowing (`narrowIdentity`, `assertIdentityPropagation`).
+- [Agent events](agent-events.md): `delegated_agent_step` and delegation event surfaces for timelines.
+- [Policy and audit](policy-and-audit.md): decision ledger, approval gates, and signed audit export.
+- [Observability](observability.md): OpenTelemetry agent/provider/tool hierarchy and metrics.
+- [Middleware hooks](middleware-hooks.md): context bridging and redaction without permission grants.

package/docs/multimodal-content.md

@@ -136,7 +136,7 @@ try {
 - Supplying `fetch` is a trusted compatibility/custom-transport escape hatch: Prism still checks URL literals and host allow-lists, but the host-provided fetch owns DNS resolution, rebinding protection, redirects, proxies, TLS, auth, and logging.
 - `resourceUri` resolution requires a caller-provided `ResourceLoader` and optional `ResourceLoadContext.permission` check.
 - Local filesystem paths should use trust policies such as `createPathTrustPolicy()` before exposing URIs to loaders.
-- Provider upload/create/delete lifecycles are provider-package-local. `@arnilo/prism-provider-openai` inlines files under 4 MiB as `data:<mediaType>;base64,...` `file_data`, otherwise uses a bounded per-run upload cache and best-effort `DELETE /v1/files` cleanup after each stream.
+- Provider upload/create/delete lifecycles are provider-package-local. `@arnilo/prism-providers/openai` inlines files under 4 MiB as `data:<mediaType>;base64,...` `file_data`, otherwise uses a bounded per-run upload cache and best-effort `DELETE /v1/files` cleanup after each stream.
 - Shared wire helpers live in `@arnilo/prism/providers/media` (`resolveProviderMediaMessages`, `serializeOpenAIResponsesInputFile`, `serializePdfDocumentWireBlock`, `createBoundedUploadCache`). OpenAI Responses, Kimi, and OpenCode Go Anthropic routes resolve their complete media collection once before serialization or upload.
 - OpenAI Realtime audio is a bidirectional `RealtimeSession` stream, not a `ContentBlock`: provide host-captured `Uint8Array` chunks with `sendAudio()` and consume untrusted `audio_delta` / transcript events. It has a fixed 256 events/s, 1 MiB/s, and 600 s default ceiling.
 

package/docs/obscura.md

@@ -1,6 +1,6 @@
 # Obscura browser engine
 
-Optional `@arnilo/prism-obscura` support for a host-installed
+Optional `@arnilo/prism-web-tools/obscura` support for a host-installed
 [Obscura](https://github.com/h4ckf0r0day/obscura) headless browser. Obscura is never
 bundled — install the binary (or use the `h4ckf0r0day/obscura` Docker image) and point
 the package at it.
@@ -11,7 +11,7 @@ the package at it.
 ## Install
 
 ```bash
-npm install @arnilo/prism-obscura
+npm install @arnilo/prism-web-tools @arnilo/prism-mcp
 ```
 
 ## Process lifecycle (`spawnObscuraProcess`)
@@ -23,7 +23,7 @@ environment (`PATH`, `HOME`), and insecure flags (`--allow-private-network`,
 is set explicitly.
 
 ```ts
-import { spawnObscuraProcess } from "@arnilo/prism-obscura";
+import { spawnObscuraProcess } from "@arnilo/prism-web-tools/obscura";
 
 const obscura = spawnObscuraProcess({
   command: "/usr/local/bin/obscura",
@@ -53,7 +53,7 @@ Connects to `obscura mcp` (stdio or Streamable HTTP) through
 allow-list, so future Obscura tools keep flowing through.
 
 ```ts
-import { createObscuraMcpTools } from "@arnilo/prism-obscura";
+import { createObscuraMcpTools } from "@arnilo/prism-web-tools/obscura";
 
 const obscura = await createObscuraMcpTools({
   transport: { type: "stdio", command: "/usr/local/bin/obscura", args: ["mcp"] },
@@ -68,7 +68,7 @@ await obscura.close();
 - Effects: read/diagnostic/waiter/capture tools are effect-free; navigation,
   interaction, evaluation, cookie/storage writes, tabs, and any unknown future tool
   are exclusive, serialized external mutations (Obscura keeps one live page).
-- Naming: default `obscura_` prefix coexists with `@arnilo/prism-browser`;
+- Naming: default `obscura_` prefix coexists with the `browser` subpath;
   `namePrefix: ""` preserves native Obscura names.
 - Transports: stdio configs are validated with the same fail-closed command policy;
   Streamable HTTP endpoints outside loopback require explicit `allowRemoteHttp` and
@@ -82,8 +82,8 @@ host's Playwright via `chromium.connectOverCDP`. `connect()` and browser launch
 never used; Prism never launches browsers.
 
 ```ts
-import { connectObscuraCdp } from "@arnilo/prism-obscura";
-import { createBrowserTools } from "@arnilo/prism-browser";
+import { connectObscuraCdp } from "@arnilo/prism-web-tools/obscura";
+import { createBrowserTools } from "@arnilo/prism-web-tools/browser";
 
 const session = await connectObscuraCdp({
   command: "/usr/local/bin/obscura",
@@ -107,7 +107,7 @@ await session.close(); // browser first, then the owned process
   APIs (`browser.newBrowserCDPSession()`, `context.newCDPSession(page)`); the package
   adds no CDP command allow-list.
 - Concurrency limit: pages served by one Obscura worker share one V8 isolate —
-  CPU-bound page JavaScript can delay sibling pages. Keep `@arnilo/prism-browser`
+  CPU-bound page JavaScript can delay sibling pages. Keep the `browser` subpath
   limits authoritative; size Obscura's `--workers` for the host.
 - Screenshots/PDF require a render-enabled Obscura build and still obey the browser
   package's artifact/byte policy.
@@ -119,7 +119,7 @@ child processes. Returns standard Prism `web_search`/`web_fetch` tools plus expl
 `obscura_fetch`/`obscura_scrape` (disable with `nativeTools: false`).
 
 ```ts
-import { createObscuraWebTools } from "@arnilo/prism-obscura";
+import { createObscuraWebTools } from "@arnilo/prism-web-tools/obscura";
 
 const web = createObscuraWebTools({ command: "/usr/local/bin/obscura" });
 agent.tools = [...agent.tools, ...web.tools];
@@ -149,7 +149,7 @@ agent.tools = [...agent.tools, ...web.tools];
 - Docker-style invocations work through `argsBefore` (e.g.
   `["run", "--rm", "-i", "h4ckf0r0day/obscura"]`).
 - An opt-in live smoke test runs against a real installed binary with
-  `npm run test:live -w @arnilo/prism-obscura` plus `PRISM_LIVE_OBSCURA=1` and
+  `npm run test:live -w @arnilo/prism-web-tools` plus `PRISM_LIVE_OBSCURA=1` and
   `PRISM_OBSCURA_BIN=/path/to/obscura`.
 
 ## Host conformance (one generic integration)

package/docs/openapi-tools.md

@@ -53,4 +53,4 @@ Defaults and hard caps (frozen in `scripts/phase11-freeze-manifest.json`): `maxD
 - [Tools](tools.md): registry, dispatch, validation
 - [Recoverable tool effects](tool-effects.md): approval + idempotency contracts
 - [Host security guide](host-security.md): permission, trust, validation checklist
-- Package README: [`@arnilo/prism-openapi-tools`](../packages/prism-openapi-tools/README.md)
+- Package README: [`@arnilo/prism-coding-tools`](../packages/prism-coding-tools/README.md)

package/docs/performance.md

@@ -65,6 +65,26 @@ serialized provider event at the exact response-byte cap succeeds; one byte belo
 fails closed, including multibyte Unicode deltas. Context-budget omission order and
 newest-history preservation remain covered by the root context-budget tests.
 
+## Tool progressive disclosure (plan 041)
+
+`node scripts/benchmark.mjs --scenario tool-search` is network-free (mock assembly, in-memory, no credentials). It builds a 128-tool fixture registry and assembles the provider input once per mode through `assembleProviderInput`: `toolsDisclosure "all"` (default, full tool set) vs `"search"` (top-k 16 plus the generated `search_tools` tool), then asserts provider-request tool-definition bytes shrink ≥ 60% and the index+score pass stays well under a turn. Frozen caps live in `scripts/budgets.json#toolSearch` (reduction floor 0.6, index+score ceiling 50 ms, disclosed-count ceiling 33 — sanity bounds, machine-dependent). Schema/caps/network-free gating in `npm test`: `scripts/benchmark-tool-search.test.mjs`.
+
+```bash
+node scripts/benchmark.mjs --scenario tool-search --out /tmp/prism-tool-search.json
+```
+
+Recorded 2026-08-30, Node v24.19.0 / Linux x64: tool bytes 31,923 → 4,329 (**86.4% reduction**, floor 60%), index+score 1.9–2.5 ms across three runs, disclosed 17 tools (top-k 16 + `search_tools`). Tool-accuracy fixtures (mock provider picking by name among 64/128 distractors, scripted scanner reading only the disclosed list) show search mode at full-exposure pick accuracy in both sizes — the conformance floor `search ≥ all` holds (`src/__tests__/tool-search.test.ts`).
+
+## Workflow loop refinement (plan 045)
+
+`node scripts/benchmark.mjs --scenario workflow-loop` is network-free: five serial `loopNode` iterations each run one refinement through a mock provider and an in-memory checkpoint adapter. The frozen budget in `scripts/budgets.json#workflowLoop` allows 50 ms p95 per node execution, or 250 ms across all five iterations. The scenario also checks five provider calls, five finished iteration records, peak provider concurrency of one, and zero active work after completion.
+
+Recorded 2026-08-31 on Node v24.19.0 / Linux x64: 5 warmups + 20 measured runs, p50 **2.356 ms**, p95 **6.443 ms** (**1.289 ms/iteration**), 352.88 runs/s. `maxNodes` remains the declared-node count; `maxIterations` is the independent runtime budget and stays hard-capped at 64. These timings are local evidence, not portable SLOs.
+
+```bash
+node scripts/benchmark.mjs --scenario workflow-loop --out /tmp/prism-workflow-loop.json
+```
+
 ## Current-line root artifact diet
 
 `npm pack --dry-run --json` on `@arnilo/prism` is gated by `scripts/budget-gate.test.mjs` against `scripts/budgets.json#root` (±5%). Repository-only history stays out of the tarball: `docs/_evidence/**`, `docs/release-*-evidence.md`, `docs/api-page-template.md`, `dist/__tests__`, and `*.map`. Every page linked from shipped `docs/index.md` must be in the pack. Recorded 2026-08-27: **923,045 packed / 3,149,665 unpacked / 375 files** (226 `dist` js+d.ts, 124 index-linked docs, 25 other). 0.1.0 freeze 713,454 / 293 stays historical.
@@ -365,7 +385,7 @@ Structured Git/check/handoff defaults/hard caps: paths 1,000/10,000; refs 1 KiB/
 
 Durable coding plan/checkpoint defaults/hard caps: plan Markdown 256 KiB/1 MiB; todos 1,000/10,000 with 512 B/4 KiB text; checkpoint metadata 64 KiB/512 KiB; artifact references 16/64 at 256 MiB/2 GiB each; check summaries 1 KiB/8 KiB. Checkpoints store URI/hash/summaries/fingerprints only; resume revalidates workspace root, base branch, plan hash, and tool/policy/image fingerprints before import.
 
-Browser automation defaults/hard caps from `@arnilo/prism-browser`: pages 4/16; actions 100/256; queued actions 16/64; snapshot refs 2,000/10,000; depth 30/100; snapshot bytes 256 KiB/2 MiB; navigation 30 s/120 s; action 10 s/60 s; wait 30 s/120 s; run wall 20 min/30 min; popups 4/16; dialogs 16/64; listeners 64/256; action input 64 KiB/256 KiB; close grace 5 s/30 s; network requests 1,000/10,000 with 10/32 redirects per request and 8/32 WebSockets; screenshots 16/64 with 16/64 megapixels and 10 MiB/32 MiB encoded; uploads 8/32 files, 16 MiB/64 MiB each, 64 MiB/256 MiB aggregate; downloads 8/32 files, 32 MiB/256 MiB each, 64 MiB/512 MiB aggregate. Caps charge before context/page/action/queue/snapshot/network/artifact retention. Host supplies Playwright and egress proxy attestation; package import launches nothing.
+Browser automation defaults/hard caps from the `browser` subpath: pages 4/16; actions 100/256; queued actions 16/64; snapshot refs 2,000/10,000; depth 30/100; snapshot bytes 256 KiB/2 MiB; navigation 30 s/120 s; action 10 s/60 s; wait 30 s/120 s; run wall 20 min/30 min; popups 4/16; dialogs 16/64; listeners 64/256; action input 64 KiB/256 KiB; close grace 5 s/30 s; network requests 1,000/10,000 with 10/32 redirects per request and 8/32 WebSockets; screenshots 16/64 with 16/64 megapixels and 10 MiB/32 MiB encoded; uploads 8/32 files, 16 MiB/64 MiB each, 64 MiB/256 MiB aggregate; downloads 8/32 files, 32 MiB/256 MiB each, 64 MiB/512 MiB aggregate. Caps charge before context/page/action/queue/snapshot/network/artifact retention. Host supplies Playwright and egress proxy attestation; package import launches nothing.
 
 0.0.14 co-work defaults/hard caps (frozen in [Phase 9 evidence](_evidence/review-coverage-2026-07-25-phase-9.md)): conversation thread list pages 50/200, active branches per thread 16/64, replay/export page 100/500 events; artifact revisions per artifact 32/128, artifacts per thread 64/256, metadata record 8/64 KiB, preview 16/64 KiB, citations 32/128 (2/8 KiB each), delivery-link TTL 5 min/24 h, delivery token 4/16 KiB, compare exactly 2 revisions; memory retention batch 500/5000; proactive capability TTL 24 h/31 d, capability token record 16 KiB; browser checkpoint URL 8 KiB/16 KiB, domain-state hash 256 B/1 KiB, host-data ref 2 KiB/8 KiB, 16/64 checkpoints per run; device stream chunk 1 MiB/8 MiB, concurrent device sessions per identity 1/4 (device wall/turns/tool calls consume shared `RunLimits`). All caps charge before persist/emit and fail closed on overflow. Benchmark placeholder: `node scripts/benchmark-0.0.14.mjs` (release Task 12) reports conversation replay, memory injection/consent, artifact revision/delivery, AG-UI co-work mapping, and connector refresh overhead against these budgets.
 
@@ -595,7 +615,7 @@ Experiment concurrency is capped at 32 workers and defaults to 1. Scorers operat
 
 ### 0.0.5 Phase 6 verification (2026-07-15)
 
-Optional `@arnilo/prism-provider-ai-sdk` adapts AI SDK `LanguageModelV4` streams to Prism without adding an AI SDK dependency to core.
+Optional `@arnilo/prism-providers/ai-sdk` adapts AI SDK `LanguageModelV4` streams to Prism without adding an AI SDK dependency to core.
 
 | Surface | Result |
 | --- | --- |
@@ -751,7 +771,7 @@ Offline behavior tests (identity propagation, policy export, router deny paths,
 
 ### 0.3.x Phase 39 Obscura browser-engine envelopes (2026-08-29)
 
-`@arnilo/prism-obscura` binary-backed legs, network-free, driven by a deterministic fake CLI: `node scripts/benchmark-obscura.mjs` (3 runs, medians vs reviewed ceilings; artifact `scripts/benchmark-obscura.json`). Startup leg probes SIG-0 liveness after spawn — a real host waits on its readiness endpoint inside the same bound.
+`obscura` binary-backed legs, network-free, driven by a deterministic fake CLI: `node scripts/benchmark-obscura.mjs` (3 runs, medians vs reviewed ceilings; artifact `scripts/benchmark-obscura.json`). Startup leg probes SIG-0 liveness after spawn — a real host waits on its readiness endpoint inside the same bound.
 
 | Leg | Median (3 runs) | Ceiling | Notes |
 | --- | --- | --- | --- |

package/docs/persistence-credentials-multimodality-primitives.md

@@ -70,7 +70,7 @@ Static review of `src/contracts.ts`, `src/session-stores.ts`, `src/credentials.t
 | `refreshOAuthCredential` | `src/credentials.ts` | Calls `OAuthProvider.refresh`; optional `OAuthCredentialStore.set` |
 | `OAuthCredentialStore` | `src/contracts.ts` | `set(provider, credentials)` only — no `get`/`delete` in core contract |
 | `OAuthProvider` / `OAuthCredentials` | `src/contracts.ts` | `login`, optional `refresh`, optional `getCredential` |
-| Device-code OAuth | `packages/provider-openai` | Bounded polling; abort via `OAuthLoginCallbacks.signal` |
+| Device-code OAuth | `packages/prism-providers/src/openai` | Bounded polling; abort via `OAuthLoginCallbacks.signal` |
 | Redaction | `src/redaction.ts` | Exact known-secret replacement; not secret detection |
 
 **Gaps (C-011):** No encrypted file store, no system keychain adapter, no versioned credential envelope, no `OAuthCredentialStore` `get`/`delete`/`list` in core (Task 4 package may extend store interface locally while integrating `refreshOAuthCredential`).

package/docs/policy-and-audit.md

@@ -203,4 +203,4 @@ await evaluateAndAppend(request, { store: state.policy, evaluator, id: crypto.ra
 - [Workflows](workflows.md): proactive schedule capability enable/revoke events bridge here via `onCapability`.
 - [Host security](host-security.md)
 - [Enterprise PostgreSQL state](enterprise-postgres-state.md): durable policy/evaluation/work/router composition.
-- Package README: [`@arnilo/prism-policy`](../packages/policy/README.md)
+- Package README: [`@arnilo/prism-core`](../packages/prism-core/README.md)

package/docs/ponytail.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-ponytail` is an optional package that wires [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) into Prism contribution contracts.
+`@arnilo/prism-coding-tools/ponytail` is an optional package that wires [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) into Prism contribution contracts.
 
 It registers upstream skills and commands, injects active mode instructions via upstream `getPonytailInstructions` / `filterSkillBodyForMode`, and persists mode as session custom `ponytail-mode` entries. Import is inert; missing upstream fails closed at `setup` with a bounded redacted error.
 
@@ -66,7 +66,7 @@ Deactivation: exact phrases `stop ponytail` and `normal mode`.
 ## Implementation example
 
 ```ts
-import { createPonytailExtension } from "@arnilo/prism-ponytail";
+import { createPonytailExtension } from "@arnilo/prism-coding-tools/ponytail";
 import {
   createExtensionKernel,
   createLoadSkillTool,

package/docs/prompt-registry.md

@@ -0,0 +1,106 @@
+# Versioned prompt registry
+
+## What it does
+
+The optional `@arnilo/prism-prompts` package stores prompt assets as immutable, content-hashed versions. It provides a memory store plus SQLite and PostgreSQL adapters. The registry returns prompt data; it does not compose system-prompt layers, evaluate prompt quality, discover files, or activate text.
+
+## Inputs / request
+
+```ts
+import { createMemoryPromptStore } from "@arnilo/prism-prompts";
+
+const store = createMemoryPromptStore();
+const version = await store.put({
+  tenantId: "tenant-1",
+  name: "support-agent",
+  body: "Answer support questions briefly.",
+  labels: ["production"],
+  metadata: { owner: "support" },
+});
+```
+
+`put` always appends the next version for one ownership/name scope. It computes `hash` as `sha256:<64 lowercase hex>` over exact UTF-8 body bytes. Records, labels, and JSON metadata are frozen before return.
+
+Ownership fields (`tenantId`, optional `accountId` and `userId`) are direct fields on every operation. Omitted ownership is a separate local scope, never a wildcard over tenant-owned rows.
+
+## Outputs / response / events
+
+```ts
+const latest = await store.resolve({ tenantId: "tenant-1", name: "support-agent" });
+const production = await store.resolve({ tenantId: "tenant-1", name: "support-agent", label: "production" });
+const exact = await store.resolve({ tenantId: "tenant-1", name: "support-agent", version: 1 });
+
+for (let page = await store.list({ tenantId: "tenant-1", name: "support-agent", limit: 50 });; ) {
+  consume(page.items);
+  if (!page.nextCursor) break;
+  page = await store.list({ tenantId: "tenant-1", name: "support-agent", cursor: page.nextCursor, limit: 50 });
+}
+
+const diff = await store.diff({ tenantId: "tenant-1", name: "support-agent", fromVersion: 1, toVersion: 2 });
+```
+
+`resolve` returns the latest version by default, or the latest version carrying `label`; exact `version` can be combined with a label. `list` uses bounded keyset cursors ordered by name/version. `diff` returns bounded `context`/`add`/`remove` lines plus `added`, `removed`, and `truncated` counts. The host decides how a resolved body enters the existing `composeSystemPrompt` layers.
+
+## Run provenance
+
+Pass the resolved version's identity to a run so every ledger record answers "which prompt version produced this output":
+
+```ts
+const resolved = await store.resolve({ tenantId, name: "support-agent" });
+await session.run(input, {
+  promptVersion: { name: resolved.name, version: resolved.version, hash: resolved.hash },
+});
+```
+
+The ref is opaque identity — name, version number, and the store's SHA-256 body hash — never prompt content. It rides on the start/finish `RunRecord`s, round-trips through first-party SQLite/PostgreSQL run rows (`prompt_version` column, schema migration `009_run_prompt_version`), and stays subject to the existing ledger redaction and field-policy boundaries. See [Runs and usage](runs-and-usage.md#prompt-provenance).
+
+## Durable adapters
+
+```ts
+import { createSqlitePromptStore } from "@arnilo/prism-prompts";
+const sqlite = createSqlitePromptStore({ filename: "./prompts.db" });
+
+import { createPostgresPromptStore } from "@arnilo/prism-prompts";
+const postgres = await createPostgresPromptStore({
+  connectionString: process.env.DATABASE_URL,
+  schema: "prism",
+});
+```
+
+SQLite uses `better-sqlite3`; PostgreSQL uses a caller-supplied or adapter-owned `pg` pool. Both adapters use the package-owned `prism_prompts` and `prism_prompt_labels` tables, exact ownership predicates, bound values, and an indexed label lookup. Startup applies checked `001_init` migration history and refuses checksum drift. SQLite exposes `applySqlitePromptMigrations` for managed setup tests; PostgreSQL migration setup is guarded by `pg_advisory_xact_lock`.
+
+## Eval-gated promotion
+
+`assertPromptPromotion` composes [evaluations](evaluations.md) with the store to answer one question — should this candidate version replace the baseline? It resolves both versions (read-only), runs them head-to-head over a dataset through `runComparison`, and returns a typed verdict. It never promotes anything, writes nothing, and never touches a live agent:
+
+```ts
+import { assertPromptPromotion } from "@arnilo/prism-prompts";
+
+const v = await assertPromptPromotion({
+  store,
+  name: "support-agent",
+  candidate: { label: "candidate" },   // or an exact version
+  baseline: { label: "production" },   // must resolve to a different version
+  dataset,
+  scorers,
+  run: (prompt) => hostRunnerFactory(prompt.body), // host bridge: body → candidate
+  minimumWinRate: 0.8,                 // optional; default gate is a strict win majority
+  thresholds: { maximumFailures: 0 },  // optional; forwarded to assertEvaluationThreshold
+});
+if (v.verdict === "promote") await store.put({ ...hostInput, body: v.candidate.body, labels: ["production"] });
+```
+
+The verdict carries `promote`/`hold`, per-scorer `wins/losses/ties/failures`, `winRate`, the raw `ComparisonReport`, a redacted bounded `reportJson` (`serializeEvaluationReport`), and `reasons` on hold. The default gate holds unless the candidate wins strictly more scored comparisons than the baseline; `minimumWinRate` and `thresholds` add stricter gates, and threshold equality passes. Requires the optional peer `@arnilo/prism-evals` (install it or the helper fails closed with `ERR_PRISM_PROMPT_EVALS_PEER`). Promotion itself stays a host decision: applying the verdict means `put`-ing a new version with labels — the helper never does.
+
+## Limits and security
+
+Names, bodies, labels, metadata, cursors, pages, and diffs have finite defaults and hard caps. Prompt bodies are data: no evaluation, template execution, file discovery, or implicit layer injection occurs. Store body hashes are integrity checks; a durable row whose hash no longer matches its body fails closed. Never put credentials or provider clients in prompt metadata.
+
+Threat model: the registry is **host-trusted data**. Anyone who can write versions into the store is inside the trust boundary — `put`, label management, and `assertPromptPromotion` verdicts are host operations, never agent-reachable surfaces. Untrusted prompt-injection defense stays at Prism's existing untrusted-content boundaries (tool results, attachments, and provider output), which the store neither bypasses nor weakens: a resolved body enters the system-prompt layer exactly like a host-authored constant. The optional `@arnilo/prism-evals` peer is only loaded by `assertPromptPromotion` and never makes the store itself depend on evaluation infrastructure.
+
+## Related APIs
+
+- [System prompts](system-prompts.md): existing explicit layering and file adapters.
+- [Input and prompt assembly](input-and-prompt-assembly.md): host-controlled message/context assembly.
+- [Evaluations](evaluations.md): bounded evaluation primitives; `assertPromptPromotion` composes `runComparison` + `assertEvaluationThreshold`.
+- [Database persistence](database-persistence.md): persistence and ownership conventions.