@arnilo/prism 0.3.1 → 0.4.0

package/docs/migrate-to-0.4.md

@@ -0,0 +1,312 @@
+# Migrate legacy 0.3 packages to Prism 0.4
+
+> **Status: 0.4 release draft.** Follow this guide only after the 0.4 packages are published.
+> Until then, stay on your current 0.3.x package set. This page is the permanent destination of
+> npm's legacy-package warnings.
+
+## What changes
+
+Prism 0.4 replaces 62 separate 0.3 package manifests with 11 active packages and explicit
+subpaths. The code and behavior move; this is not a database/data migration. It is a **package
+name and import-specifier migration**.
+
+- Existing applications pinned to 0.3.x continue to work.
+- Retired packages are not unpublished. Their final release remains on npm with its `latest`
+  tag and gains a `legacy` tag plus an install-time deprecation warning.
+- `npm install` cannot automatically replace one package name with another. Upgrade each package
+  dependency and its imports together.
+- There are no 0.4 compatibility wrappers. New packages never import old package names, so the
+  package graph cannot form a wrapper cycle.
+- `@arnilo/prism` stays small and dependency-free. Runtime, sessions, governance, and optional
+  drivers live in `@arnilo/prism-core`, not root-package subpaths.
+
+## Before you start
+
+1. Commit or lock your working 0.3.x application.
+2. Record installed Prism packages and direct imports:
+
+   ```bash
+   npm ls --all @arnilo/prism @arnilo/prism-*
+   rg -n 'from "@arnilo/prism|import\("@arnilo/prism' src test
+   ```
+
+3. Classify each package using the tables below. Leave unchanged interop packages in place.
+4. Upgrade package dependencies and imports in one pull request; then run your normal typecheck,
+   tests, and packed-install smoke test.
+5. Add optional peers only for subpaths you use. Do not add a database, browser, parser, or host
+   binary merely because a family package is installed.
+
+## Active 0.4 packages
+
+| Package | Use it for |
+|---|---|
+| `@arnilo/prism` | Contracts, agent APIs, CLI, root `node/*` and `testing/*` exports. |
+| `@arnilo/prism-core` | Runtime, sessions, governance, credentials, persistence, work integration, JSON Schema validation. |
+| `@arnilo/prism-providers` | All first-party provider adapters as explicit subpaths. |
+| `@arnilo/prism-coding-tools` | Coding agent/security, document reader, OpenAPI, desktop control, Dev inspector, Caveman, Ponytail, Impeccable. |
+| `@arnilo/prism-web-tools` | Generic web tools plus browser and Obscura subpaths. |
+| `@arnilo/prism-memory` | Memory, RAG, compaction, Graft, Wiki. |
+| `@arnilo/prism-office` | Documents, sheets, and diagrams. |
+| `@arnilo/prism-mcp` | MCP interop. |
+| `@arnilo/prism-acp-agent` | ACP interop. |
+| `@arnilo/prism-ag-ui` | AG-UI/A2A/A2UI interop. |
+| `@arnilo/prism-antigravity-agent` | Antigravity interop. |
+
+## Package and import mapping
+
+Replace the package name in `package.json` and every corresponding source import. The tables map
+root package entrypoints. Any documented non-root entrypoint keeps its feature suffix under the
+new family path; the 0.4 API page for that family is authoritative for exact nested exports.
+
+### Providers
+
+Install `@arnilo/prism-providers` once, then import only the provider subpath used by the host.
+
+| Legacy 0.3 package | 0.4 import |
+|---|---|
+| `@arnilo/prism-provider-ai-sdk` | `@arnilo/prism-providers/ai-sdk` |
+| `@arnilo/prism-provider-alibaba` | `@arnilo/prism-providers/alibaba` |
+| `@arnilo/prism-provider-anthropic` | `@arnilo/prism-providers/anthropic` |
+| `@arnilo/prism-provider-azure` | `@arnilo/prism-providers/azure` |
+| `@arnilo/prism-provider-bedrock` | `@arnilo/prism-providers/bedrock` |
+| `@arnilo/prism-provider-clinepass` | `@arnilo/prism-providers/clinepass` |
+| `@arnilo/prism-provider-deepseek` | `@arnilo/prism-providers/deepseek` |
+| `@arnilo/prism-provider-google` | `@arnilo/prism-providers/google` |
+| `@arnilo/prism-provider-kimi` | `@arnilo/prism-providers/kimi` |
+| `@arnilo/prism-provider-neuralwatt` | `@arnilo/prism-providers/neuralwatt` |
+| `@arnilo/prism-provider-ollama` | `@arnilo/prism-providers/ollama` |
+| `@arnilo/prism-provider-openai` | `@arnilo/prism-providers/openai` |
+| `@arnilo/prism-provider-opencode-go` | `@arnilo/prism-providers/opencode-go` |
+| `@arnilo/prism-provider-openrouter` | `@arnilo/prism-providers/openrouter` |
+| `@arnilo/prism-provider-vertex` | `@arnilo/prism-providers/vertex` |
+| `@arnilo/prism-provider-xai` | `@arnilo/prism-providers/xai` |
+| `@arnilo/prism-provider-zai` | `@arnilo/prism-providers/zai` |
+
+```ts
+// Before
+import * as openai from "@arnilo/prism-provider-openai";
+
+// After
+import * as openai from "@arnilo/prism-providers/openai";
+```
+
+### Runtime, sessions, governance, and work integration
+
+Install `@arnilo/prism-core`, then choose the specific subpath. This family does not add
+optional drivers to your host automatically.
+
+| Legacy 0.3 package | 0.4 import |
+|---|---|
+| `@arnilo/prism-server` | `@arnilo/prism-core/runtime/server` |
+| `@arnilo/prism-supervisor` | `@arnilo/prism-core/runtime/supervisor` |
+| `@arnilo/prism-workflows` | `@arnilo/prism-core/runtime/workflows` |
+| `@arnilo/prism-session-store-codecs` | `@arnilo/prism-core/sessions/codecs` |
+| `@arnilo/prism-session-store-nats` | `@arnilo/prism-core/sessions/nats` |
+| `@arnilo/prism-session-store-postgres` | `@arnilo/prism-core/sessions/postgres` |
+| `@arnilo/prism-session-store-sqlite` | `@arnilo/prism-core/sessions/sqlite` |
+| `@arnilo/prism-policy` | `@arnilo/prism-core/governance/policy` |
+| `@arnilo/prism-evals` | `@arnilo/prism-core/governance/evals` |
+| `@arnilo/prism-prompts` | `@arnilo/prism-core/governance/prompts` |
+| `@arnilo/prism-model-router` | `@arnilo/prism-core/governance/model-router` |
+| `@arnilo/prism-observability-opentelemetry` | `@arnilo/prism-core/governance/observability` |
+| `@arnilo/prism-credentials-node` | `@arnilo/prism-core/credentials/node` |
+| `@arnilo/prism-enterprise-postgres` | `@arnilo/prism-core/enterprise/postgres` |
+| `@arnilo/prism-work-tools` | `@arnilo/prism-core/integrations/work` |
+| `@arnilo/prism-tool-validator-json-schema` | `@arnilo/prism-core/validation/json-schema` |
+
+`work-tools` belongs to core because enterprise Postgres composes its work-idempotency store.
+It is not part of coding tools.
+
+### Coding tools and personas
+
+Install `@arnilo/prism-coding-tools`; import the smallest needed subpath. The `prism-dev` binary
+continues to be named `prism-dev` after migration.
+
+| Legacy 0.3 package | 0.4 import |
+|---|---|
+| `@arnilo/prism-coding-agent` | `@arnilo/prism-coding-tools/agent` |
+| `@arnilo/prism-coding-security` | `@arnilo/prism-coding-tools/security` |
+| `@arnilo/prism-document-reader` | `@arnilo/prism-coding-tools/document-reader` |
+| `@arnilo/prism-openapi-tools` | `@arnilo/prism-coding-tools/openapi` |
+| `@arnilo/prism-computer-use-linux` | `@arnilo/prism-coding-tools/computer-use-linux` |
+| `@arnilo/prism-dev` | `@arnilo/prism-coding-tools/dev` |
+| `@arnilo/prism-caveman` | `@arnilo/prism-coding-tools/caveman` |
+| `@arnilo/prism-ponytail` | `@arnilo/prism-coding-tools/ponytail` |
+| `@arnilo/prism-impeccable` | `@arnilo/prism-coding-tools/impeccable` |
+
+### Web, browser, and Obscura
+
+`@arnilo/prism-web-tools` keeps its root entrypoint for generic research tools. Browser and
+Obscura become explicit subpaths; neither activates a browser or process on import.
+
+| Legacy 0.3 package | 0.4 import |
+|---|---|
+| `@arnilo/prism-browser` | `@arnilo/prism-web-tools/browser` |
+| `@arnilo/prism-obscura` | `@arnilo/prism-web-tools/obscura` |
+
+### Memory, RAG, compaction, and context
+
+`@arnilo/prism-memory` retains its root memory entrypoint and gains explicit subpaths. The
+`prism-wiki` binary remains named `prism-wiki` and continues to ship Wiki skills.
+
+| Legacy 0.3 package | 0.4 import or install |
+|---|---|
+| `@arnilo/prism-rag` | `@arnilo/prism-memory/rag` |
+| `@arnilo/prism-compaction-llm` | `@arnilo/prism-memory/compaction/llm` |
+| `@arnilo/prism-compaction-observational-memory` | `@arnilo/prism-memory/compaction/observational-memory` |
+| `@arnilo/prism-graft` | `@arnilo/prism-memory/graft` |
+| `@arnilo/prism-wiki` | `@arnilo/prism-memory/wiki` |
+| `@arnilo/prism-compaction` | Install `@arnilo/prism-memory`; choose one or both compaction subpaths. No direct import replacement: it was a profile-only manifest. |
+
+### Office suite
+
+Plans 051–053 drafted three separate packages. They were never published to npm.
+Install `@arnilo/prism-office` and import the subpath:
+
+| Draft 0.3 name | 0.4 import |
+|---|---|
+| `@arnilo/prism-documents` | `@arnilo/prism-office/documents` |
+| `@arnilo/prism-sheets` | `@arnilo/prism-office/sheets` |
+| `@arnilo/prism-diagrams` | `@arnilo/prism-office/diagrams` |
+
+```ts
+import { generateDocument } from "@arnilo/prism-office/documents";
+import { parseCsv } from "@arnilo/prism-office/sheets";
+```
+
+`@office-open/{docx,xlsx,pptx,xml}` are exact-pinned regular dependencies of the
+office tarball. The diagrams live-embed optionally peers `playwright-core`; XML
+canonicalization does not.
+
+### Removed profile packages
+
+Profiles were dependency lists, not runtime APIs. Choose the families your host uses; do not look
+for a 0.4 profile replacement package.
+
+| Legacy 0.3 profile | 0.4 starting recipe |
+|---|---|
+| `@arnilo/prism-base` | `npm i @arnilo/prism@^0.4.0 @arnilo/prism-core@^0.4.0 @arnilo/prism-memory@^0.4.0` |
+| `@arnilo/prism-code` | Base recipe + `@arnilo/prism-coding-tools@^0.4.0 @arnilo/prism-mcp@^0.4.0` |
+| `@arnilo/prism-sdk` | Base recipe + `@arnilo/prism-mcp@^0.4.0`; Core contains credentials, observability, and workflows. |
+| `@arnilo/prism-all` | Select required families explicitly. Begin with Core, Providers, Coding tools, Web tools, Memory, and required interop; add Office only if needed. |
+
+### Names that remain
+
+These package names remain valid. Review their imports if they now consume one of the new family
+subpaths, but do not rename the dependency merely because of 0.4.
+
+| Package | 0.4 status |
+|---|---|
+| `@arnilo/prism` | Unchanged root package; remains dependency-free. |
+| `@arnilo/prism-providers` | Same name, now code family; provider imports use `/provider-name`. |
+| `@arnilo/prism-web-tools` | Same name; root web tools unchanged, browser/Obscura use subpaths. |
+| `@arnilo/prism-memory` | Same name; RAG/compaction/Graft/Wiki use subpaths. |
+| `@arnilo/prism-mcp` | Unchanged interop package. |
+| `@arnilo/prism-acp-agent` | Unchanged interop package. |
+| `@arnilo/prism-ag-ui` | Unchanged interop package. |
+| `@arnilo/prism-antigravity-agent` | Unchanged interop package. |
+
+## Optional peers, host binaries, and trust boundaries
+
+Installing a family does not install or activate its optional capabilities. Add the peer only for
+the subpath you use and preserve its existing host policy.
+
+| Feature | Required host dependency / action | Do not weaken |
+|---|---|---|
+| SQLite sessions or prompt store | Install `better-sqlite3`; use only the selected `prism-core` session/governance subpath. | Database ownership, migration checks, and file permissions. |
+| PostgreSQL sessions, prompts, or enterprise state | Install `pg`; use the selected `prism-core` subpath. | TLS, roles, checksummed migrations, and tenant boundaries. |
+| NATS sessions | Install/configure the NATS client required by the sessions NATS subpath. | Stream/consumer ownership and durable cursor isolation. |
+| Browser tools | Install `playwright-core` and provide the approved host browser/context. | Egress, upload/download, screenshot, and side-effect policies. |
+| Obscura | Install/configure `playwright-core`, `@arnilo/prism-mcp`, and an approved host Obscura binary. | Absolute shell-free command, SSRF controls, process limits, MCP authorization. |
+| Document reader | Install `mammoth` and/or `pdf-parse` for used formats. | Magic-byte format gating, input/page/text caps, and no embedded-content execution. |
+| Graft | Install/configure `@nanonets/graft` or approved host CLI. | Workspace confinement, output/time limits, and no implicit process start. |
+| Wiki | Provide the documented host `qmd`/Context7 setup when using Wiki commands. | Workspace path, process, and untrusted-content limits. |
+| Computer Use Linux | Provide the approved `computer-use-linux` MCP host binary. | Consent, sandbox, approval, serialized input, and redaction. |
+
+## Recommended upgrade sequence
+
+1. **Move root/version first.** Set `@arnilo/prism` to `^0.4.0`; retain the Node version required
+   by the release.
+2. **Replace retired dependency names.** Use the appropriate family package in `package.json`.
+3. **Replace imports.** Apply the tables above. Do not keep both old and new imports in the same
+   runtime path.
+4. **Add only needed peers.** Follow the previous table; subpath import failures should name the
+   missing peer rather than fall back to an unsafe implementation.
+5. **Recheck host wiring.** Re-register tools/providers/extensions explicitly. Package install
+   remains inert; it must not activate providers, listeners, database connections, browsers,
+   credentials, or tools.
+6. **Run verification.**
+
+   ```bash
+   npm run typecheck
+   npm test
+   npm pack --dry-run
+   ```
+
+   Run protected PostgreSQL, browser, Obscura, MCP, or host-binary checks separately when your
+   application uses those integrations.
+
+## Legacy warning and lifecycle
+
+Each retired package's final 0.3 release is marked with npm's `legacy` dist-tag and a deprecation
+warning like:
+
+```text
+npm warn deprecated @arnilo/prism-browser@0.3.x:
+Legacy 0.3 package. Prism 0.4+: @arnilo/prism-web-tools/browser.
+https://github.com/ashiqrniloy/prism/blob/main/docs/migrate-to-0.4.md#web-browser-and-obscura
+```
+
+The warning is informational: it does not delete the package or rewrite your dependency. `latest`
+continues to point at the final 0.3 release because npm dist-tags cannot redirect one package name
+to a different package. New 0.4 development must use the successor listed above.
+
+The markers are generated and applied from one reviewed registry plan — never hand-copied. Run
+`node scripts/phase54-legacy-registry.mjs --dry-run` to resolve every retired name's final
+published version, verify the anchors above exist in this guide, and print the exact
+`npm dist-tag add ... legacy` and `npm deprecate ..."<0.4.0"` commands without mutating the
+registry. After the 0.4 packages and this guide are public (Task 9 cutover),
+`node scripts/phase54-legacy-registry.mjs --apply --confirm` pre-flights every entry and fails
+closed — zero mutations — on any mismatch, then applies the tags and warnings idempotently:
+already-correct entries are skipped on resume, and per-entry status is written to
+`release-artifacts/legacy-registry-plan.json` for safe resume. Two retired names
+(`@arnilo/prism-prompts`, `@arnilo/prism-dev`) were never published; they are recorded in the
+plan with no registry action.
+
+## Rollback
+
+If the 0.4 migration fails before deployment:
+
+1. Restore the committed 0.3.x `package.json` and lockfile.
+2. Restore old imports from the mapping table.
+3. Reinstall with the lockfile (`npm ci`).
+4. Do not unpublish any package or remove the `legacy` marker; those are registry metadata, not a
+   runtime migration.
+
+The package reorganization itself does not change persisted store schemas. If the same deployment
+also adopted a separate database/session feature release, follow that feature's migration and
+rollback instructions; do not assume package rollback reverses a forward-only database migration.
+
+## FAQ
+
+**Can I install `@arnilo/prism-all` in 0.4?** No. It was a pure manifest and is retired. Install
+only the family packages your host needs.
+
+**Why is `@arnilo/prism-core` separate from `@arnilo/prism`?** Root Prism remains dependency-free.
+Database drivers, optional Node integrations, and governance/runtime modules must not become
+implicit root dependencies.
+
+**Why not keep old packages as wrappers?** Wrappers preserve 54 active manifests and create a
+cycle if a new family imports the old implementation while the old package re-exports the family.
+The direct migration is smaller and unambiguous.
+
+**Do unchanged interop packages need changes?** No package-name change. Keep MCP, ACP, AG-UI, or
+Antigravity installed only when your host uses that protocol; update imports only if their own 0.4
+API page says so.
+
+## Related APIs
+
+- [Release and install](release-and-install.md): package contents, peer rules, and publication.
+- [Migration guide](migration.md): migration history for prior releases.
+- [Provider packages](provider-packages.md): provider adapter behavior.
+- [Host security guide](host-security.md): preserve host trust boundaries while upgrading.

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)