@arnilo/prism 0.3.2 → 0.5.0

package/docs/core.md

@@ -0,0 +1,85 @@
+# Core Runtime, Sessions, and Governance (@arnilo/prism-core)
+
+The `@arnilo/prism-core` family package unifies Prism's privileged runtime, sessions, governance, credentials, enterprise persistence, and work integrations into explicit, import-isolated subpaths.
+
+## Installation
+
+```bash
+npm install @arnilo/prism @arnilo/prism-core
+```
+
+For database persistence and distributed event streams, install the required optional peer dependencies:
+
+```bash
+# SQLite sessions & prompt storage
+npm install better-sqlite3
+
+# PostgreSQL sessions, enterprise persistence & prompt storage
+npm install pg
+
+# NATS JetStream distributed event source
+npm install @nats-io/jetstream @nats-io/transport-node
+```
+
+## Subpaths Map
+
+| Subpath | Description | Optional Peers |
+|---|---|---|
+| `@arnilo/prism-core/runtime/server` | HTTP server handler, SSE streaming, artifact delivery, replay, webhook delivery | — |
+| `@arnilo/prism-core/runtime/supervisor` | Agent-to-Agent (A2A) protocol server, client, event source, and multi-agent supervisor | — |
+| `@arnilo/prism-core/runtime/workflows` | Multi-step DAG workflow coordinator, saga recovery, checkpoints, and loop nodes | — |
+| `@arnilo/prism-core/sessions/codecs` | Checkpoint, cursor, feedback, and search serialization codecs | — |
+| `@arnilo/prism-core/sessions/sqlite` | SQLite session store, leases, lifecycle, and schema migrations | `better-sqlite3` |
+| `@arnilo/prism-core/sessions/postgres` | PostgreSQL session store, event source, and migrations | `pg` |
+| `@arnilo/prism-core/sessions/nats` | NATS JetStream distributed event source | `@nats-io/jetstream`, `@nats-io/transport-node` |
+| `@arnilo/prism-core/governance/policy` | Capability admission, tool execution approvals, audit log exporter, and OPA evaluator | — |
+| `@arnilo/prism-core/governance/evals` | Offline evaluation runs, scorers, judges, threshold assertions, and trace curation | — |
+| `@arnilo/prism-core/governance/prompts` | Versioned prompt registry, promotion gating, rollback, and storage | `better-sqlite3`, `pg` |
+| `@arnilo/prism-core/governance/model-router` | Cost- and latency-aware model routing, token reservations, and failover | — |
+| `@arnilo/prism-core/governance/observability` | OpenTelemetry instrumentation and event tracing | `@opentelemetry/api` |
+| `@arnilo/prism-core/credentials/node` | Keyring-backed encrypted credential store, scrypt envelope encryption, OAuth2 PKCE providers, and OIDC identity verification | `@napi-rs/keyring` (bundled) |
+| `@arnilo/prism-core/enterprise/postgres` | Unified multi-tenant enterprise PostgreSQL state (approvals, evaluations, model-router, policy, tool effects, work idempotency) | `pg` |
+| `@arnilo/prism-core/integrations/work` | Microsoft 365 and Google Workspace CLI tool adapters with approval gates and idempotency | — |
+| `@arnilo/prism-core/validation/json-schema` | Ajv-backed JSON Schema tool argument validation | `ajv` (bundled) |
+
+## Usage Examples
+
+### Workflow Runtime
+```ts
+import { createWorkflowCoordinator, defineWorkflow, functionNode } from "@arnilo/prism-core/runtime/workflows";
+
+const wf = defineWorkflow({
+  name: "order-processing",
+  initial: "validate",
+  nodes: {
+    validate: functionNode(async ({ input }) => ({ next: "process", output: input })),
+  },
+});
+```
+
+### Policy & Approvals
+```ts
+import { createMemoryApprovalStore, evaluateApproval } from "@arnilo/prism-core/governance/policy";
+
+const approvals = createMemoryApprovalStore();
+```
+
+### SQLite Sessions
+```ts
+import { createSqlitePersistence } from "@arnilo/prism-core/sessions/sqlite";
+
+const persistence = createSqlitePersistence({ filename: "./prism.db" });
+```
+
+### JSON Schema Validation
+```ts
+import { createJsonSchemaToolArgumentValidator } from "@arnilo/prism-core/validation/json-schema";
+
+const validator = createJsonSchemaToolArgumentValidator();
+```
+
+## Security & Import Isolation
+
+- Subpaths never load database drivers (`pg`, `better-sqlite3`) unless the specific database subpath is imported.
+- All database and network drivers fail closed with clear actionable error messages when peers are omitted.
+- Root `@arnilo/prism` remains dependency-free contracts and CLI runner.

package/docs/credential-storage.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-The optional `@arnilo/prism-credentials-node` package ships host-owned credential persistence for Node.js CLI and desktop apps:
+The optional `@arnilo/prism-core/credentials/node` package ships host-owned credential persistence for Node.js CLI and desktop apps:
 
 - **Encrypted file store** — AES-256-GCM envelope with scrypt KDF, atomic rename writes, versioned on-disk format
 - **System keychain store** — cross-platform secret service via `@napi-rs/keyring@^1.3.0`
@@ -17,7 +17,7 @@ Factories:
 - `createOAuthCredentialStoreAdapter(store)`
 - `rotateEncryptedCredentialStorePassphrase(options)`
 
-The `@arnilo/prism-credentials-node/oidc` subpath adds the optional OIDC/JWKS identity verifier (`createOidcIdentityVerifier`) — pinned issuer/audience/JWKS verification over native `fetch` + WebCrypto (see [Agent identity](agent-identity.md)).
+The `@arnilo/prism-core/credentials/node/oidc` subpath adds the optional OIDC/JWKS identity verifier (`createOidcIdentityVerifier`) — pinned issuer/audience/JWKS verification over native `fetch` + WebCrypto (see [Agent identity](agent-identity.md)).
 
 Core `@arnilo/prism` remains storage-free. Hosts choose a backend explicitly at startup; there is no global credential singleton and no silent fallback from keychain to plaintext file storage.
 
@@ -37,7 +37,7 @@ Do **not** use it when credentials should live in a remote vault, HSM, or cloud
 import {
   openEncryptedCredentialStore,
   createKeychainCredentialStore,
-} from "@arnilo/prism-credentials-node";
+} from "@arnilo/prism-core/credentials/node";
 ```
 
 ### Encrypted file
@@ -79,6 +79,10 @@ Encrypted file stores also expose:
 
 `encryptBytes()` and `decryptBytes()` are Promise-based because they use asynchronous `node:crypto.scrypt`.
 
+### MCP OAuth records (plan 063)
+
+When backing `McpClientAuthState` from `@arnilo/prism-mcp` with one of these stores, key OAuth rows by the validated authorization-server `issuer` the SDK stamps onto every `StoredOAuthTokens`/`StoredOAuthClientInformation` record (the credential methods receive it). Credentials must never cross issuers: a store that cannot partition by issuer stays single-slot-safe (the MCP provider re-validates the stamp), but partitioning is the preferred shape for hosts talking to more than one MCP server. Refresh tokens belong only in the encrypted file or keychain backends — never the plaintext memory store in production.
+
 Errors are explicit and fail closed:
 
 | Error | Code | When |
@@ -126,7 +130,7 @@ import {
   createOAuthCredentialStoreAdapter,
   createStoredCredentialResolver,
   openEncryptedCredentialStore,
-} from "@arnilo/prism-credentials-node";
+} from "@arnilo/prism-core/credentials/node";
 
 const store = await openEncryptedCredentialStore({
   path: "./credentials.vault",
@@ -157,7 +161,7 @@ import {
   createGoogleWorkspaceOAuthProvider,
   createOAuthWorkTokenProvider,
   createOAuthCredentialStoreAdapter,
-} from "@arnilo/prism-credentials-node";
+} from "@arnilo/prism-core/credentials/node";
 
 // Read-only mail/calendar (no mutation scopes requested).
 const m365 = createMicrosoft365OAuthProvider({ clientId: "<app-id>", capabilities: ["mail", "calendar"], access: "read" });
@@ -178,7 +182,7 @@ await revokeOAuthCredential({ provider: m365, credentials: creds, store: createO
 Passphrase rotation:
 
 ```ts
-import { rotateEncryptedCredentialStorePassphrase } from "@arnilo/prism-credentials-node";
+import { rotateEncryptedCredentialStorePassphrase } from "@arnilo/prism-core/credentials/node";
 
 await rotateEncryptedCredentialStorePassphrase({
   path: "./credentials.vault",
@@ -198,8 +202,8 @@ import {
 import {
   createKeychainCredentialStore,
   createStoredCredentialResolver,
-} from "@arnilo/prism-credentials-node";
-import { createOpenAIProviderPackage } from "@arnilo/prism-provider-openai";
+} from "@arnilo/prism-core/credentials/node";
+import { createOpenAIProviderPackage } from "@arnilo/prism-providers/openai";
 
 const keychain = createKeychainCredentialStore({
   service: "com.example.my-app",

package/docs/credentials-and-redaction.md

@@ -133,4 +133,4 @@ A future provider-local OAuth adapter needs published permission for third-party
 - [LLM compaction package](compaction-llm.md): resolves optional summary-provider credentials per compaction call and redacts exact known values.
 - [OpenAI-compatible provider](providers/openai-compatible.md): resolves API keys per request and redacts known values from adapter errors.
 
-Phase 10 added `createMemoryCredentialStore()`, `createChainedCredentialResolver()`, and `createSecretRedactor()` for opt-in in-memory auth and runtime redaction. By default the memory store serves a providerless record for a provider-scoped request of the same name — that record is then shared across every provider; pass `{ allowProviderFallback: false }` for exact-match-only resolution (strict provider scoping). Phase 11 adds OAuth/API-key contracts plus explicit resolver order helpers. Core still has no persistent secret store and does not read environment variables or files for credentials. For durable storage, use [`@arnilo/prism-credentials-node`](credential-storage.md) encrypted-file or keychain backends. See [Security/auth/trust](settings-auth-trust-security.md).
+Phase 10 added `createMemoryCredentialStore()`, `createChainedCredentialResolver()`, and `createSecretRedactor()` for opt-in in-memory auth and runtime redaction. By default the memory store serves a providerless record for a provider-scoped request of the same name — that record is then shared across every provider; pass `{ allowProviderFallback: false }` for exact-match-only resolution (strict provider scoping). Phase 11 adds OAuth/API-key contracts plus explicit resolver order helpers. Core still has no persistent secret store and does not read environment variables or files for credentials. For durable storage, use [`@arnilo/prism-core/credentials/node`](credential-storage.md) encrypted-file or keychain backends. See [Security/auth/trust](settings-auth-trust-security.md).

package/docs/data-classification.md

@@ -77,6 +77,6 @@ const redactor = createAuditFieldRedactor(fieldPolicy, { labelFor });
 
 - `redactMessage` / `redactProviderRequest` / `redactAgentEvent` / `redactSessionEntry` / `redactRunLedgerRecord` — the egress seams that take the optional policy (secret redaction first, then classification).
 - `createAuditFieldRedactor` → the audit-export `redact` hook; see [Signed, hash-chained audit export](audit-export.md).
-- `createOpenTelemetryInstrumentation` in `@arnilo/prism-observability-opentelemetry` — the telemetry `fieldPolicy` option.
+- `createOpenTelemetryInstrumentation` in `@arnilo/prism-core/governance/observability` — the telemetry `fieldPolicy` option.
 - `createProtectedFieldPolicy`, `ALLOW_FIELD_POLICY`, `FieldPolicyError`, `FIELD_POLICY_LIMITS` — the protected default and limits.
 - The ERP-T9 threat matrix (`src/__tests__/field-policy.test.ts`) and the boundary-drill scripts cover the enforcement evidence.

package/docs/database-persistence.md

@@ -6,9 +6,11 @@ The production persistence contracts describe database-neutral types for durable
 
 Prism itself does not ship a production database adapter. The built-in `SessionStore` contract (`append` / `list` / optional `get`) remains the runtime seam; `ProductionPersistenceStore` is the optional adapter-facing contract for hosts that need paginated reads, tenant isolation, audit tables, retention, and optional generic `CheckpointStore` / `LeaseStore` capabilities.
 
-Plan 056 Task 1 adds dialect-neutral shared primitives under `@arnilo/prism/testing/persistence-schema`, `@arnilo/prism/testing/session-store-conformance`, and `@arnilo/prism/testing/run-ledger-conformance`. Task 2 ships `@arnilo/prism-session-store-sqlite` (see [SQLite persistence](sqlite-persistence.md)); Task 3 ships `@arnilo/prism-session-store-postgres` (see [PostgreSQL persistence](postgres-persistence.md)). Both implement dialect-local SQL against the shared model; Prism core still ships no ORM, driver, or migration runner.
+Plan 056 Task 1 adds dialect-neutral shared primitives under `@arnilo/prism/testing/persistence-schema`, `@arnilo/prism/testing/session-store-conformance`, and `@arnilo/prism/testing/run-ledger-conformance`. Task 2 ships `@arnilo/prism-core/sessions/sqlite` (see [SQLite persistence](sqlite-persistence.md)); Task 3 ships `@arnilo/prism-core/sessions/postgres` (see [PostgreSQL persistence](postgres-persistence.md)). Both implement dialect-local SQL against the shared model; Prism core still ships no ORM, driver, or migration runner.
 
-Release 0.0.23 additionally ships [`@arnilo/prism-enterprise-postgres`](enterprise-postgres-state.md), a separate PostgreSQL composition for policy decisions, evaluations, work-mutation claims, and model-router state. It is not a `ProductionPersistenceStore` replacement and does not store sessions/runs. Its fixed `prism_enterprise_migrations` history is independent of `prism_migrations`; hosts may use both compositions against the same validated schema.
+Release 0.0.23 additionally ships [`@arnilo/prism-core/enterprise/postgres`](enterprise-postgres-state.md), a separate PostgreSQL composition for policy decisions, evaluations, work-mutation claims, and model-router state. It is not a `ProductionPersistenceStore` replacement and does not store sessions/runs. Its fixed `prism_enterprise_migrations` history is independent of `prism_migrations`; hosts may use both compositions against the same validated schema.
+
+The optional [`@arnilo/prism-core/governance/prompts`](prompt-registry.md) package is another independent persistence surface: its SQLite/PostgreSQL adapters own `prism_prompts`, `prism_prompt_labels`, and `prism_prompt_migrations`, apply a checked `001_init` history, and filter every read/write by exact prompt ownership. It does not extend the shared session schema or place prompt bodies in run/session metadata.
 
 ## When to use it
 
@@ -80,6 +82,8 @@ Metadata CAS (0.2.2): the write seam accepts an additive `expectedVersion` guard
 
 Artifact co-work review (0.0.14) reuses the generic `CheckpointStore` rather than adding a dedicated table: the [artifact service](work-artifacts-and-review.md) stores each artifact as a versioned checkpoint value (namespace `prism.artifact`, key `threadId:artifactId`, category `artifact`). The checkpoint `version` is the compare-and-swap counter that resolves concurrent reviewers; revision numbers, approvals, and `lastValidatedVersion` live inside the JSON value. SQLite/Postgres already persist checkpoints durably, so there is no separate artifact schema or migration, and records carry metadata/hashes/refs only — never file bodies.
 
+Run prompt provenance (plan 042): `RunRecord` gains an optional typed `promptVersion` ref (`{ name, version, hash }`) that the first-party adapters persist as a nullable `prompt_version` JSON column on run rows (schema migration `009_run_prompt_version`, shared schema version 9). Rows written before the migration stay `NULL` and read back without the field; a host that never sets `RunOptions.promptVersion` sees byte-identical rows. The ref is an opaque identity (`sha256:` body hash), never prompt content, and flows through the same ledger redaction as every other run field. Prompt bodies themselves live only in the separate [prompt registry tables](prompt-registry.md) — never in run rows or run metadata.
+
 ## Outputs / response / events
 
 Each `query*` method returns a `PersistencePage<T>`:
@@ -453,7 +457,7 @@ const dbStore: ProductionPersistenceStore = {
 - `SessionStore` (`append`/`list`/`get`/optional `readBranchPath`) can be implemented on top of `ProductionPersistenceStore` or kept separate.
 - **State-concurrency conformance (0.2.2):** durable adapters must pass `assertStateConcurrencyConforms` from `@arnilo/prism/testing/state-concurrency-conformance` against both the memory stores and their own implementation (approval determinism, checkpoint CAS, replay-cursor resume, idempotency retry, router reservation, conversation metadata CAS, unknown-outcome recovery). The harness uses deterministic barriers only — no timing-only sleeps — and runs the memory leg in the default `npm test` and the durable legs in `test:postgres`/`test:nats`; `scripts/phase22-conformance.test.mjs` asserts every store leg executed (missing protected environment records a named BLOCKED GATE, never a green skip).
 - Cursor values and idempotency keys are host-defined and opaque to Prism.
-- First-party SQLite/PostgreSQL adapters expose `persistence.checkpoints` and `persistence.leases`, backed by package-owned `prism_checkpoints` / `prism_leases` tables. `@arnilo/prism-workflows` consumes them for durable resume, human suspension, multi-process coordination, Phase 11 schedule records/fire leases, shared state, and replay lineage; workflow code owns no SQL table. `suspended`/`denied`, schedules, state history, and replay lineage remain namespaces/categories plus bounded checkpoint JSON values, so Phases 8 and 11 need no database migration.
+- First-party SQLite/PostgreSQL adapters expose `persistence.checkpoints` and `persistence.leases`, backed by package-owned `prism_checkpoints` / `prism_leases` tables. `@arnilo/prism-core/runtime/workflows` consumes them for durable resume, human suspension, multi-process coordination, Phase 11 schedule records/fire leases, shared state, and replay lineage; workflow code owns no SQL table. `suspended`/`denied`, schedules, state history, and replay lineage remain namespaces/categories plus bounded checkpoint JSON values, so Phases 8 and 11 need no database migration.
 
 Schema version **7** adds the exact-owner durable event retention index (`prism_agent_events_owner_timestamp_sequence_idx`). Distributed subscribe/LISTEN remains PostgreSQL-only via `persistence.events`.
 

package/docs/dev-inspector.md

@@ -0,0 +1,103 @@
+# Dev inspector
+
+## What it does
+
+`@arnilo/prism-coding-tools/dev` is a **loopback-only local dev inspector** over a host's already-configured Prism agent — the `prism dev` playground server (plan 040). It is a **composition-only consumer**: it adds zero core primitives and imports no core internals. Every capability is an existing public seam consumed verbatim:
+
+- `@arnilo/prism-core/runtime/server` `createPrismHandler` — direct `POST /prism/agents/:id/runs` and SSE `POST /prism/agents/:id/stream` agent routes, authorization, ownership propagation, and the durable `Last-Event-ID` event route when an exposure carries `events` + `resolveRun`.
+- Core durable `AgentEventSource` contract (`page`/`subscribe`) — replay and reconnect without re-execution.
+- `@arnilo/prism-ag-ui/renderer` — event projection for the served UI page (plan 040 Task 3).
+- Run-ledger records (`RunRecord`/`AgentEventRecord`/`ToolCallRecord`/`UsageRecord`) surfaced only through the seams above — the package never touches a ledger.
+- Pending-decision resume through the server's fail-closed decision validation (plan 040 Task 2) — the inspector adds none.
+
+## When to use it
+
+Use it when iterating on prompts in a local Prism host and you want a inspectable timeline (events, tool calls, usage, HITL decisions, run replay) instead of building your own trace viewer. Do not deploy it: it is a developer-time surface, deliberately excluded from production dependency use, and it must never be the production API boundary — that stays `@arnilo/prism-core/runtime/server` under host authorization.
+
+### Quickstart — `prism dev` (plan 040 Task 4)
+
+```bash
+npm install --save-dev @arnilo/prism-coding-tools/dev
+cd my-agent && npm run dev   # → prism dev → http://127.0.0.1:4311
+```
+
+`prism dev` (and the standalone `prism-dev` bin, plus the programmatic `runDevCli` from `@arnilo/prism-coding-tools/dev/cli`) boots the inspector over the current `prism init` scaffold: it imports `dist/agent.js` and calls its `createAppAgent()` export — the scaffold's own agent, with its own credentials. It defaults to `127.0.0.1:4311`, prints the loopback URL once listening (start-to-listen under 1s excluding provider network), and `Ctrl+C` drains and closes. A non-loopback `--host` is refused before binding (`ERR_PRISM_DEV_REMOTE_BIND`); the CLI never reads environment secrets itself. See `docs/cli-rpc.md` for the flag table.
+
+## Inputs / request
+
+`createPrismDevInspector(options)`:
+
+| Field | Purpose |
+| --- | --- |
+| `agent` | Required host-built `Agent` (mock or provider-backed). The inspector never constructs the agent or reads credentials. |
+| `eventSource` | Optional durable `AgentEventSource`; opts the server exposure into durable event routes, SSE reconnect, and the paged replay endpoint. Requires `resolveRun`. |
+| `resolveRun` | Required with `eventSource`: resolves a public run selector to exact internal session/run IDs. Refusing a selector (foreign/unknown run) fails closed with `404`. |
+| `checkpoints` | Optional host checkpoint store backing the agent's `runState`; wiring it enables the durable status/resume capability behind the decision endpoint. Host-owned — the inspector only composes the core lifecycle seam (`createAgentRunLifecycle`) over the host's own agent. |
+| `definitionRevision` | Definition revision declared for the lifecycle resolve; default `"1"`. |
+| `authorize` | Optional per-operation authorizer. Loopback default: single synthetic local user (`local`, ownership `tenantId`/`userId` both `local` so durable event scoping passes); request JSON can never widen ownership (server seam enforces). |
+| `host` | Bind host, default `127.0.0.1`. **Non-loopback fails closed** unless `remoteAuthorize` resolves `true` and a real `authorize` callback is supplied. |
+| `port` | Default `4311`; `0` picks an ephemeral port. |
+| `remoteAuthorize` | Explicit opt-in callback for a non-loopback bind, consulted by `listen()`. |
+| `redactor` | Host `SecretRedactor` passed through to the server handler and the replay pager; rendered tool args/results stay host-redacted on both the SSE and replay paths. |
+| `limits` / `basePath` | Server limits and route base path passthrough. |
+
+## Outputs / response / events
+
+The inspector exposes `handler` (the composed `PrismRequestHandler`), `listen()`, `close()`, and once listening `url`/`host`/`port`. Boot (create + bind, excluding host model calls) stays under the 1s envelope. Configuration refusals throw `DevInspectorError` (`ERR_PRISM_DEV_INSPECTOR`, or `ERR_PRISM_DEV_REMOTE_BIND` for bind-policy failures).
+
+Per-task surface (plan 040): Task 1 wires agent routes + bind policy; Task 2 (shipped) adds the data-defined inspector routes below; Task 3 serves the static UI page; Task 4 ships the `prism dev` CLI composition.
+
+## HTTP surface (plan 040 Task 2)
+
+Data-defined route table over the server seam — each route either rewrites the URL into the already conformance-tested `PrismRequestHandler` or pages the durable event source. Unmatched requests forward unchanged to the raw `/{basePath}/*` server surface on the same listener.
+
+| Route | Purpose | Adapts to |
+| --- | --- | --- |
+| `POST /prompt` | Runs the agent (direct run). | server handler direct agent run. |
+| `GET /events?runId=<id>` | Durable SSE stream of normalized events. `Last-Event-ID` header reconnect and `?cursor=` are honored by the server seam; missing `runId` → `400 ERR_PRISM_DEV_ROUTE`. |
+| `GET /runs/:id/replay?cursor=…` | Paged replay of a stored run from the durable `AgentEventSource` — **no session, no provider, no re-execution** (`createPrismAgentEventReplay` page). Returns `{ items, nextCursor?, terminal }`; unknown/foreign run ids → `404`. |
+| `POST /runs/:runId/decisions/:decisionId` | Resumes/denies one suspended approval. Body `{ outcome: "allow_once" \| "allow_always" \| "deny", expectedVersion? }` → forwarded as a single-entry core decision batch; unknown discriminants and stale versions fail closed (`400`) at the core boundary **before any state write**. |
+
+Reconnect semantics: every SSE frame carries `id: <cursor>`; a reconnecting client sends `Last-Event-ID: <cursor>` and receives exactly the post-cursor events — no duplicates, no loss (server conformance-tested). Replay pages are bounded by the deployment limits (`maxReplayEvents`, `maxReplayCursorBytes`) and ownership-scoped by the source seam itself.
+
+## UI walkthrough (plan 040 Task 3)
+
+Opening the inspector URL serves one static page (`GET /` → `page` + `GET /assets/inspector.js`; bootstrap via same-origin `GET /config` → `{ basePath, agentId }`). No external fetches — the bundle is offline-capable, served with a strict CSP (`default-src 'none'; script-src 'self'; connect-src 'self'`, `nosniff`, `no-store`), and every dynamic payload reaches the DOM through text nodes only (redacted strings render as-is, never parsed as markup).
+
+Panels:
+
+- **Prompt box** — `POST {basePath}/agents/{id}/stream` (server SSE seam); frames arrive as redacted `AgentEvent` JSON and fold into the timeline live.
+- **Event timeline** — message deltas merged into per-stream text items, thinking separately, turn boundaries as separators. Rows render incrementally through a **windowed list** (last `MAX_RENDERED_WINDOW` = 400 rows; older rows collapse into a counter line) so 1k+ event runs never lock the page. Tool calls are expandable `<details>`: streamed args, finished results, blocked/error state.
+- **Usage** — per-run totals summed from `provider_turn_finished.usage` and the terminal `agent_finished.usage` (input/output/total tokens, cost when the model reports it).
+- **Decisions** — `agent_suspended` renders one card per pending decision (`PendingDecision.approvalId`, tool name, redacted reason, `expectedVersion` from the event's run version). Buttons post `POST /runs/:runId/decisions/:approvalId` ({ outcome: `allow_once` | `allow_always` | `deny`, expectedVersion }); rejections show the seam's fail-closed error verbatim, and a remaining-multi-decision suspension re-renders from the response's `runState.interruption`.
+- **Run selector** — session runs (live + loaded) with status; a durable view of any past run loads via `GET {basePath}/events?runId=…` over `EventSource` — the seam's own `Last-Event-ID` reconnect applies. Without a durable event source wired, loading by runId surfaces that fact instead of pretending to replay.
+
+## Request/response example
+
+```json
+POST /prompt
+{ "input": "Summarize the release notes" }
+```
+
+Suspended approval surfaced by that response (`runState.interruption.pendingDecisions`) resumes via:
+
+```json
+POST /runs/<runId>/decisions/<approvalId>
+{ "outcome": "allow_once", "expectedVersion": 1 }
+```
+
+## Implementation example
+
+```ts
+import { createPrismDevInspector } from "@arnilo/prism-coding-tools/dev";
+
+const inspector = createPrismDevInspector({
+  agent, // host-built agent (mock or provider-backed)
+  eventSource, // optional durable AgentEventSource for replay
+  host: "127.0.0.1",
+  port: 4311,
+});
+await inspector.listen(); // http://127.0.0.1:4311 — loopback only
+```
+
+Loopback policy: default bind is `127.0.0.1:4311`; a non-loopback bind is refused unless an explicit `remoteAuthorize` callback opts in and a real `authorize` callback is supplied; loopback default authorization is one synthetic local user; the inspector stores no secrets and never reads `process.env` for credentials.

package/docs/device-adapters.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-Optional realtime voice and desktop OS / computer-control surface for Prism agents, shipped in 0.0.14 as a **contract + deny-by-default policy** in `@arnilo/prism` (`src/devices.ts`). The first vendor adapter, `@arnilo/prism-computer-use-linux`, wraps the host-owned `computer-use-linux` MCP binary without changing this generic contract. The contract composes over the existing `PermissionPolicy`, `RunLimits`, approval (`tool_approval`), and redactor seams; it adds no second approval runtime and no device framework.
+Optional realtime voice and desktop OS / computer-control surface for Prism agents, shipped in 0.0.14 as a **contract + deny-by-default policy** in `@arnilo/prism` (`src/devices.ts`). The first vendor adapter, `@arnilo/prism-coding-tools/computer-use-linux`, wraps the host-owned `computer-use-linux` MCP binary without changing this generic contract. The contract composes over the existing `PermissionPolicy`, `RunLimits`, approval (`tool_approval`), and redactor seams; it adds no second approval runtime and no device framework.
 
 ## When to use it
 
@@ -79,7 +79,7 @@ if (chunk.accepted) emit(redactDeviceTelemetry(createSecretRedactor([token]), fr
 
 - Frozen caps: audio/screenshot/stream chunk **1 MiB / 8 MiB**; concurrent device sessions per identity **1 / 4**. Device wall time / turns / tool calls consume the shared `RunLimits` (admission fails closed without run accounting).
 - `enabled` resolves to `true` only on an explicit `true`; any other value is disabled. `requireApproval` stays `true` unless the host explicitly sets `false` (it should not).
-- `@arnilo/prism-computer-use-linux` is the first vendor package. It remains optional, Linux-only, host-binary-owned, and outside umbrella profiles; this page stays generic so future voice or desktop vendors can satisfy the same contract via `runDevicePolicyConformance`.
+- `@arnilo/prism-coding-tools/computer-use-linux` is the first vendor package. It remains optional, Linux-only, host-binary-owned, and outside umbrella profiles; this page stays generic so future voice or desktop vendors can satisfy the same contract via `runDevicePolicyConformance`.
 
 ## Security and performance notes
 

package/docs/diagrams.md

@@ -0,0 +1,247 @@
+# Diagramming, draw.io embed client, and mxGraph XML validation (`@arnilo/prism-office/diagrams`)
+
+## What it does
+
+The `@arnilo/prism-office/diagrams` package provides an origin-enforced draw.io / diagrams.net iframe embed client, XXE-safe mxGraph XML validation, and byte-stable deterministic XML canonicalization for content hashing and visual artifact workflows in Prism applications and agent runtimes.
+
+### Core Capabilities
+
+- **Origin-Enforced Embed Client**: `createDrawioEmbed({ iframe, origin })` establishes a typed, secure postMessage bridge between host applications and embedded draw.io editor iframes adhering to the diagrams.net `proto=json` embed protocol.
+- **Dual Inbound Verification Boundary**: Inbound `message` events are verified against **both** the configured origin and `iframe.contentWindow` prior to JSON parsing. Foreign origins, rogue windows, and malformed frames are dropped immediately at the boundary.
+- **Strict Outbound Target Enforcement**: Prohibits wildcard `targetOrigin: "*"` on all outbound actions. Every postMessage transmits exclusively to the exact validated origin.
+- **No Public SaaS Default**: Construction requires an explicit, validated origin string (`https://` or `http://`). No default fallback to public SaaS endpoints (`embed.diagrams.net`) exists; self-hosting is the documented deployment.
+- **XXE & Billion-Laughs Defenses**: `validateDrawioXml` rejects DOCTYPE and ENTITY declarations up-front (`UNSAFE_XML_DECLARATION_PATTERN = /<!\s*(?:DOCTYPE|ENTITY)/i`) with `ERR_PRISM_DIAGRAMS_XXE`, and operates with XML parser entity and HTML entity expansion disabled under strict element, attribute, and byte caps.
+- **Deterministic XML Canonicalization**: `canonicalizeDrawioXml` sorts element attributes lexicographically (`a-z`), standardizes double quotes and entity escaping, and normalizes insignificant whitespace while preserving document sequence, producing byte-identical outputs for SHA-256 content hashing.
+- **Visio Format Exclusion (P12 Guard)**: Detects and rejects Microsoft Visio binary (`.vsd`) and OpenXML (`.vsdx`) inputs across all entrypoints with `ERR_PRISM_DIAGRAMS_UNSUPPORTED_FORMAT`.
+- **Dependency-Free Telemetry Seam (P15)**: Pluggable `DiagramsTelemetry` interface emits `diagrams.validate` and `diagrams.canonicalize` spans tracking byte sizes, element/cell counts, and durations without leaking diagram contents or node text.
+
+## When to use it
+
+Use `@arnilo/prism-office/diagrams` when applications, host workspaces, or autonomous agents need to:
+1. Embed an interactive, self-hosted draw.io / diagrams.net editor inside a web or Electron iframe with strictly enforced cross-origin security.
+2. Coordinate diagram editing lifecycles (`init` handshake, `load`, `save`, `autosave`, `merge`, and `export`).
+3. Execute save-with-preview workflows generating SVG (`xmlsvg`) or PNG (`xmlpng`) visual snapshots from the active editor session.
+4. Validate untrusted agent-generated or user-uploaded mxGraph XML models against structural and memory boundaries before persistence.
+5. Compute deterministic content hashes (`sha256(canonicalizeDrawioXml(xml))`) for version control, caching, and change detection.
+
+Do **not** use this package for:
+- Microsoft Visio format conversion (`.vsd` / `.vsdx` files are explicitly excluded and rejected per P12).
+- Server-side headless diagram rendering without an editor instance (use headless browser automation or containerized export services).
+
+## Inputs / request
+
+### Primary Functions
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `createDrawioEmbed` | `(options: DrawioEmbedOptions) => DrawioEmbed` | Creates an origin-enforced embed client bound to an iframe element or structural frame. |
+| `validateDrawioXml` | `(xml: string \| Uint8Array, options?: DrawioXmlOptions) => DrawioModelSummary` | Validates mxGraph XML well-formedness, caps, and structure, extracting page/cell/edge metrics. |
+| `canonicalizeDrawioXml` | `(xml: string \| Uint8Array, options?: DrawioCanonicalizeOptions) => string` | Produces byte-stable, attribute-sorted, whitespace-normalized XML for content hashing. |
+| `validateDiagramsOrigin` | `(origin: unknown) => string` | Validates that an origin string is a valid `https:` or `http:` URL origin without paths, queries, hashes, or wildcards. |
+| `assertNotVisio` | `(input: string \| Uint8Array) => void` | Asserts that input is not a Microsoft Visio file, throwing `DiagramsFormatError` if Visio signatures are detected. |
+
+### Message & Options Types
+
+```ts
+export interface DrawioEmbedOptions {
+  readonly iframe: DrawioEmbedFrame;
+  readonly origin: string;
+  readonly messageSource?: DrawioMessageSource;
+  readonly onProtocolError?: (error: DiagramsProtocolError) => void;
+  readonly defaultExportTimeoutMs?: number;
+}
+
+export interface DrawioLoadOptions {
+  readonly xml: string;
+  readonly autosave?: boolean;
+  readonly saveAndExit?: boolean;
+  readonly noSaveBtn?: boolean;
+  readonly noExitBtn?: boolean;
+  readonly title?: string;
+}
+
+export interface DrawioExportOptions {
+  readonly format: "xml" | "xmlsvg" | "xmlpng" | "json" | "png" | "svg";
+  readonly scale?: number;
+  readonly border?: number;
+  readonly xml?: string;
+  readonly embedImages?: boolean;
+  readonly timeoutMs?: number;
+}
+
+export interface DrawioXmlCaps {
+  readonly maxBytes?: number;
+  readonly maxElements?: number;
+  readonly maxAttributes?: number;
+}
+```
+
+### Capacity Limits and Defaults
+
+| Cap | Default | Hard Ceiling | Description |
+| --- | --- | --- | --- |
+| `maxBytes` | 32 MiB (`33,554,432`) | 512 MiB (`536,870,912`) | Maximum input XML string or byte length. |
+| `maxElements` | 100,000 | 500,000 | Maximum total XML element count in diagram tree. |
+| `maxAttributes` | 500,000 | 2,000,000 | Maximum total XML attribute count across elements. |
+| `defaultExportTimeoutMs` | 30,000 ms | Unlimited | Timeout waiting for editor export responses. |
+
+## Outputs / response / events
+
+### Error Hierarchy
+
+All error classes extend `DiagramsError` and carry structured `ERR_PRISM_DIAGRAMS_*` error codes:
+
+| Error Class | Code | Cause / Trigger |
+| --- | --- | --- |
+| `DiagramsOriginError` | `ERR_PRISM_DIAGRAMS_ORIGIN_INVALID` | Origin is empty, wildcard (`*`), malformed URL, or contains forbidden path/query/hash components. |
+| `DiagramsProtocolError` | `ERR_PRISM_DIAGRAMS_PROTOCOL` | Inbound message failed JSON parsing, missing event discriminator, or postMessage issued without contentWindow. |
+| `DiagramsXxeError` | `ERR_PRISM_DIAGRAMS_XXE` | XML input contains forbidden DOCTYPE or ENTITY declaration. |
+| `DiagramsCapError` | `ERR_PRISM_DIAGRAMS_XML_CAP` | XML input exceeds byte length, total element count, or total attribute count caps. |
+| `DiagramsXmlMalformedError` | `ERR_PRISM_DIAGRAMS_XML_MALFORMED` | XML input is truncated or violates XML well-formedness rules. |
+| `DiagramsModelInvalidError` | `ERR_PRISM_DIAGRAMS_XML_INVALID_MODEL` | XML root is neither `<mxfile>` nor `<mxGraphModel>`. |
+| `DiagramsFormatError` | `ERR_PRISM_DIAGRAMS_UNSUPPORTED_FORMAT` | Visio format (.vsd/.vsdx) detected in input (P12). |
+| `DiagramsTimeoutError` | `ERR_PRISM_DIAGRAMS_TIMEOUT` | Export operation timed out waiting for editor response. |
+
+### Output Types
+
+```ts
+export interface DrawioModelSummary {
+  readonly pages: number;
+  readonly cells: number;
+  readonly edges: number;
+  readonly width?: number;
+  readonly height?: number;
+  readonly compressed?: boolean;
+}
+
+export interface DrawioExportResult {
+  readonly format: string;
+  readonly data: string;
+  readonly xml?: string;
+  readonly bounds?: DrawioExportBounds;
+}
+```
+
+## Request/response example
+
+### Protocol Envelope (`proto=json`)
+
+Inbound editor-to-host `message` event:
+```json
+{
+  "event": "save",
+  "xml": "<mxfile host=\"drawio.internal\"><diagram id=\"1\">...</diagram></mxfile>",
+  "exit": false
+}
+```
+
+Outbound host-to-editor action postMessage:
+```json
+{
+  "action": "load",
+  "xml": "<mxfile host=\"drawio.internal\"><diagram id=\"1\">...</diagram></mxfile>",
+  "autosave": 1,
+  "title": "System Architecture"
+}
+```
+
+## Implementation example
+
+```ts
+import { createDrawioEmbed, validateDrawioXml, canonicalizeDrawioXml } from "@arnilo/prism-office/diagrams";
+
+// 1. Initialize embed client with strict origin binding
+const embed = createDrawioEmbed({
+  iframe: document.getElementById("drawio-frame") as HTMLIFrameElement,
+  origin: "https://drawio.internal.example",
+  onProtocolError(error) {
+    console.error("Protocol error:", error.message);
+  },
+});
+
+// 2. Register typed event listeners
+embed.on("init", () => {
+  const initialXml = `<mxfile host="drawio.internal"><diagram id="d1" name="Architecture"><mxGraphModel dx="800" dy="600"><root><mxCell id="0"/><mxCell id="1" parent="0"/><mxCell id="2" value="Core Agent" vertex="1" parent="1"><mxGeometry x="100" y="100" width="120" height="60" as="geometry"/></mxCell></root></mxGraphModel></diagram></mxfile>`;
+  embed.load({ xml: initialXml, autosave: true });
+});
+
+embed.on("save", async ({ xml, exit }) => {
+  // Validate model before persisting
+  const summary = validateDrawioXml(xml);
+  console.log(`Validated diagram with ${summary.cells} cells and ${summary.edges} edges`);
+
+  // Compute canonical hash for content-addressed storage
+  const canonical = canonicalizeDrawioXml(xml);
+  console.log("Canonical XML ready for persistence");
+
+  if (exit) {
+    console.log("Editor exit requested by user");
+  }
+});
+
+embed.on("autosave", ({ xml }) => {
+  console.log("Draft autosaved:", xml.length, "bytes");
+});
+
+// 3. Save-with-preview flow: export SVG snapshot
+const preview = await embed.export({ format: "xmlsvg" });
+console.log("Exported preview format:", preview.format, "data:", preview.data.slice(0, 40));
+```
+
+## Extension and configuration notes
+
+### Self-Hosted draw.io Deployment
+
+The recommended and supported deployment is a self-hosted instance of the Apache-2.0 `jgraph/drawio` container:
+
+```bash
+docker run -d -p 8080:8080 -e DRAWIO_SERVER_URL="http://localhost:8080" jgraph/drawio
+```
+
+Iframe embed URLs are formed with query parameters configuring json protocol mode:
+```text
+http://localhost:8080/?embed=1&proto=json&spin=1
+```
+
+### Decoupled Structural DOM Interface
+
+`DrawioEmbedFrame` is typed structurally:
+```ts
+export interface DrawioEmbedFrame {
+  readonly contentWindow: {
+    postMessage(message: unknown, targetOrigin: string): void;
+  } | null;
+}
+```
+This enables use with vanilla DOM elements, React/Svelte/Vue refs, Electron webviews, and headless test doubles without requiring browser globals or `@types/dom`.
+
+### OpenTelemetry Telemetry Seam
+
+Pass an optional `DiagramsTelemetry` implementation to record spans without runtime overhead:
+```ts
+const summary = validateDrawioXml(xml, {
+  telemetry: {
+    startSpan(name, attributes) {
+      // Maps to OTel tracer.startSpan("diagrams.validate", { attributes })
+      // Diagram text and labels are NEVER passed to spans.
+      return activeSpan;
+    },
+  },
+});
+```
+
+## Security and performance notes
+
+- **Trust Boundary Placement**: Origin and `event.source` checks execute inside the embed client before JSON parsing. Rogue cross-origin messages and foreign window messages are dropped without triggering listeners or error handlers.
+- **Wildcard Prohibition**: `targetOrigin: "*"` is blocked at construction and runtime. Outbound messages are posted exclusively to the verified origin.
+- **XXE Prevention**: DOCTYPE and ENTITY declarations are rejected up-front by regex pre-checks; `fast-xml-parser` is configured with entity expansion disabled.
+- **Memory Caps**: Progressive limits on byte size, element counts, and attribute counts prevent XML decompression bombs and heap exhaustion.
+- **Single-Pass Performance**: Canonicalization and validation process 1 MB XML models in under 10 ms.
+
+## Related APIs
+
+- [`@arnilo/prism-office/documents`](./documents.md): Specification-compliant OpenXML document generation and preview rendering for DOCX, XLSX, and PPTX.
+- [`@arnilo/prism-office/sheets`](./sheets.md): Spreadsheet and CSV parsing engine with strict financial decimal safety guarantees.
+- [`@arnilo/prism-web-tools/browser`](./browser-automation.md): Browser automation tools and quarantine lifecycle.
+- [`@arnilo/prism-ag-ui`](./ag-ui.md): Agent-User Interface projection and timeline components.
+- [`@arnilo/prism-core/governance/observability`](./observability.md): OpenTelemetry instrumentation and trace adapters.

package/docs/document-reader.md

@@ -1,4 +1,4 @@
-# Document reader (`@arnilo/prism-document-reader`)
+# Document reader (`@arnilo/prism-coding-tools/document-reader`)
 
 ## What it does
 
@@ -6,7 +6,7 @@ Optional bounded literal-text extraction for PDF and DOCX files, consumed by the
 
 ## When to use it
 
-Use when coding agents must read PDF/Office files (specs, requirements docs, reports) as literal text. Do **not** use it when embedded content execution, macro evaluation, or external resource fetching is required — this adapter never does any of those by construction, and the optional peer parsers (`pdf-parse`, `mammoth`) are the only parsing code involved. Docker-less hosts that need document reads pair this with the network-free native sandbox backend (`@arnilo/prism-coding-security` `createNativeSandbox`) for the surrounding tool execution.
+Use when coding agents must read PDF/Office files (specs, requirements docs, reports) as literal text. Do **not** use it when embedded content execution, macro evaluation, or external resource fetching is required — this adapter never does any of those by construction, and the optional peer parsers (`pdf-parse`, `mammoth`) are the only parsing code involved. Docker-less hosts that need document reads pair this with the network-free native sandbox backend (`@arnilo/prism-coding-tools/security` `createNativeSandbox`) for the surrounding tool execution.
 
 Activation is explicit: no file-extension sniffing anywhere enables parsing. Absent `documentReader` option = exactly the 0.1.5 read behavior.
 
@@ -33,8 +33,8 @@ Errors: `DocumentReaderError` with code `ERR_PRISM_DOCUMENT_READER` for missing
 ## Request/response example
 
 ```ts
-import { createReadTool } from "@arnilo/prism-coding-agent";
-import { createDocumentReader } from "@arnilo/prism-document-reader";
+import { createReadTool } from "@arnilo/prism-coding-tools/agent";
+import { createDocumentReader } from "@arnilo/prism-coding-tools/document-reader";
 
 const documentReader = await createDocumentReader({
   maxBytes: 32 * 1024 * 1024,
@@ -49,7 +49,7 @@ A `read` of `spec.pdf` yields text content extracted from the PDF (up to 2 MiB o
 ## Implementation example
 
 ```ts
-import { createDocumentReader, createPdfParser, type DocumentParser } from "@arnilo/prism-document-reader";
+import { createDocumentReader, createPdfParser, type DocumentParser } from "@arnilo/prism-coding-tools/document-reader";
 
 // Host-selected parser wiring: swap in a different PDF backend without touching bounds.
 const myPdfParser: DocumentParser = {
@@ -79,7 +79,7 @@ const reader = await createDocumentReader({ parsers: [myPdfParser, await createP
 
 ## Related APIs
 
-- `createReadTool` / `DocumentReader` / `DocumentReaderResult` (`@arnilo/prism-coding-agent`)
+- `createReadTool` / `DocumentReader` / `DocumentReaderResult` (`@arnilo/prism-coding-tools/agent`)
 - `SecretRedactor` (`@arnilo/prism` redaction)
 - `docs/_evidence/phase18-primitive-review.md` (doc-reader threat model D1–D8)
 - `docs/coding-security.md` (native sandbox backend for surrounding execution containment)