@arnilo/prism 0.3.2 → 0.4.0

package/docs/coding-tools.md

@@ -0,0 +1,82 @@
+# Coding Tools, Sandboxing, and Personas (@arnilo/prism-coding-tools)
+
+The `@arnilo/prism-coding-tools` family package unifies Prism's coding agent tools, security sandboxing, document reading, OpenAPI integration, Linux desktop automation, Dev inspector, and persona extensions into explicit, import-isolated subpaths.
+
+## Installation
+
+```bash
+npm install @arnilo/prism @arnilo/prism-coding-tools
+```
+
+For document reading or specialized persona integrations, install the optional peer dependencies as needed:
+
+```bash
+# PDF and DOCX document extraction
+npm install pdf-parse mammoth
+
+# Ponytail upstream integration
+npm install @dietrichgebert/ponytail
+```
+
+## Subpaths Map
+
+| Subpath | Description | Optional Peers |
+|---|---|---|
+| `@arnilo/prism-coding-tools/agent` | Core coding tools (read, write, edit, search, bash, git, diagnostics, check, ast-grep, lsp) | — |
+| `@arnilo/prism-coding-tools/security` | Sandbox execution adapters (Docker/OCI, native disposable sandbox, approval policies, egress proxy) | — |
+| `@arnilo/prism-coding-tools/document-reader` | Bounded PDF/DOCX literal-text extraction adapter with fail-closed loading | `pdf-parse`, `mammoth` |
+| `@arnilo/prism-coding-tools/openapi` | OpenAPI 3.x tool generator and executor with SSRF protection and parameter validation | — |
+| `@arnilo/prism-coding-tools/computer-use-linux` | Linux desktop observation and targeting tool bridge | — |
+| `@arnilo/prism-coding-tools/dev` | Loopback-only developer inspector, event timeline visualizer, and local replay server | — |
+| `@arnilo/prism-coding-tools/dev/cli` | Command-line entrypoint for `prism dev` | — |
+| `@arnilo/prism-coding-tools/caveman` | Caveman ultra-terse engineering persona extension | — |
+| `@arnilo/prism-coding-tools/ponytail` | Ponytail multi-agent planning and delegation persona extension | `@dietrichgebert/ponytail` |
+| `@arnilo/prism-coding-tools/impeccable` | Impeccable high-precision frontend engineering persona extension | — |
+
+## CLI
+
+```bash
+# Start the loopback dev inspector
+npx prism-dev --port 4311
+```
+
+## Usage Examples
+
+### Creating Coding Tools
+```ts
+import { createCodingTools } from "@arnilo/prism-coding-tools/agent";
+
+const tools = createCodingTools({
+  workspaceRoot: process.cwd(),
+});
+```
+
+### Sandboxed Execution
+```ts
+import { createDockerSandbox, createSandboxCodingComposition } from "@arnilo/prism-coding-tools/security";
+
+const composition = createSandboxCodingComposition({
+  workspaceMode: "sandbox",
+  sandbox: createDockerSandbox({
+    image: "node:20-alpine@sha256:...",
+    workspaceRoot: process.cwd(),
+  }),
+});
+```
+
+### Persona Extensions
+```ts
+import { createCavemanExtension } from "@arnilo/prism-coding-tools/caveman";
+import { createPonytailExtension } from "@arnilo/prism-coding-tools/ponytail";
+import { createImpeccableExtension } from "@arnilo/prism-coding-tools/impeccable";
+
+const caveman = createCavemanExtension();
+const ponytail = createPonytailExtension();
+const impeccable = createImpeccableExtension();
+```
+
+## Security & Import Isolation
+
+- Importing `@arnilo/prism-coding-tools/agent` never loads Docker sandbox adapters, desktop MCP bridges, document parser peers, or Dev inspector modules.
+- Document parser peers (`pdf-parse`, `mammoth`) and Ponytail optional peer fail closed when absent.
+- Persona extensions are pure prompt and behavior modifiers and never gain implicit host privileges.

package/docs/compaction-and-retry.md

@@ -149,11 +149,11 @@ await session.compact({ keepRecentEntries: 4 });
 
 ## Extension and configuration notes
 
-Retry policies are ordinary `RetryPolicy` implementations and can be registered as `retryPolicy` contributions. Hosts must still pass the selected policy/config to `createAgent()` or `session.run()`. Retry middleware receives `{ context, decision }` before a retry is scheduled and can reduce delay or stop retrying. First-party providers emit `ErrorInfo.code` as the numeric HTTP status so the default policy's transient-code set (`429`/`500`/`502`/`503`) classifies retryability without provider-specific core branches; `@arnilo/prism-provider-neuralwatt` additionally exports `classifyNeuralWattError()` for hosts that want structured `Retry-After`/`retry_strategy` metadata.
+Retry policies are ordinary `RetryPolicy` implementations and can be registered as `retryPolicy` contributions. Hosts must still pass the selected policy/config to `createAgent()` or `session.run()`. Retry middleware receives `{ context, decision }` before a retry is scheduled and can reduce delay or stop retrying. First-party providers emit `ErrorInfo.code` as the numeric HTTP status so the default policy's transient-code set (`429`/`500`/`502`/`503`) classifies retryability without provider-specific core branches; `@arnilo/prism-providers/neuralwatt` additionally exports `classifyNeuralWattError()` for hosts that want structured `Retry-After`/`retry_strategy` metadata.
 
 Compaction strategies are ordinary `CompactionStrategy` implementations. Extensions can register strategies through the existing compaction strategy contribution registry, but registration is inert until a host explicitly selects and passes a strategy to runtime code. Extensions can also register `compaction` middleware; the runtime calls it only when the agent/session has that middleware registry configured.
 
-The default strategy does not call a provider. Hosts that need model-generated summaries can use the optional [`@arnilo/prism-compaction-llm` package](compaction-llm.md); its `maxOutputTokens`/`maxSummaryTokens` budget is passed through `model.parameters.maxTokens` and first-party providers serialize that to provider output-token fields. Coding sessions can select that package's `createCodingCompactionStrategy()` preset for paths, patch intent, checks, plans/todos, blockers, and next verification steps; it remains an ordinary `CompactionStrategy` and does not retain complete diffs or add a coding runtime. Hosts that need prepared source-backed memory without a compaction-time model call can use [`@arnilo/prism-compaction-observational-memory`](compaction-observational-memory.md).
+The default strategy does not call a provider. Hosts that need model-generated summaries can use the optional [`@arnilo/prism-memory/compaction/llm` subpath](compaction-llm.md); its `maxOutputTokens`/`maxSummaryTokens` budget is passed through `model.parameters.maxTokens` and first-party providers serialize that to provider output-token fields. Coding sessions can select that package's `createCodingCompactionStrategy()` preset for paths, patch intent, checks, plans/todos, blockers, and next verification steps; it remains an ordinary `CompactionStrategy` and does not retain complete diffs or add a coding runtime. Hosts that need prepared source-backed memory without a compaction-time model call can use [`@arnilo/prism-memory/compaction/observational-memory`](compaction-observational-memory.md).
 
 ## Security and performance notes
 

package/docs/compaction-llm.md

@@ -1,7 +1,7 @@
 # LLM compaction package
 
 ## What it does
-`@arnilo/prism-compaction-llm` is an optional provider-backed compaction package. It prepares branch history, calls an explicit summary provider/model, and returns a standard Prism `CompactionStrategy`. The core default compaction remains local and conservative.
+`@arnilo/prism-memory/compaction/llm` is an optional provider-backed compaction subpath. It prepares branch history, calls an explicit summary provider/model, and returns a standard Prism `CompactionStrategy`. The core default compaction remains local and conservative.
 
 ## When to use it
 Use it when a host wants model-generated summaries while preserving raw append-only session history. Do not use it as a core default, provider SDK loader, hidden credential discovery layer, vector memory, or store rewrite.
@@ -59,7 +59,7 @@ Provider `error` events, empty summaries, or abort signals throw before returnin
 
 ## Implementation example
 ```ts
-import { createLlmCompactionStrategy } from "@arnilo/prism-compaction-llm";
+import { createLlmCompactionStrategy } from "@arnilo/prism-memory/compaction/llm";
 
 const strategy = createLlmCompactionStrategy({
   provider: summaryProvider,
@@ -80,7 +80,7 @@ await session.compact({ strategy, secrets: [apiKey] });
 Coding-session example:
 
 ```ts
-import { createCodingCompactionStrategy } from "@arnilo/prism-compaction-llm";
+import { createCodingCompactionStrategy } from "@arnilo/prism-memory/compaction/llm";
 
 const strategy = createCodingCompactionStrategy({
   provider: summaryProvider,
@@ -110,7 +110,7 @@ This package is inert until imported. Direct strategy use works with `session.co
 
 ```ts
 import { createAgent, createExtensionKernel } from "@arnilo/prism";
-import { createLlmCompactionExtension } from "@arnilo/prism-compaction-llm";
+import { createLlmCompactionExtension } from "@arnilo/prism-memory/compaction/llm";
 
 const kernel = createExtensionKernel();
 await kernel.load([createLlmCompactionExtension({ provider: summaryProvider, model: summaryModel })]);

package/docs/compaction-observational-memory.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-compaction-observational-memory` is an optional package for source-backed observational memory and fast compaction.
+`@arnilo/prism-memory/compaction/observational-memory` is an optional subpath for source-backed observational memory and fast compaction.
 
 Current status: ledger/projection/render/recall utilities, explicit worker runtime, fast compaction strategy, inert extension helper, recall tool, and status/view command factories are available.
 
@@ -107,7 +107,7 @@ import {
   createRecallMemoryTool,
   recallObservationalMemory,
   renderObservationalMemory,
-} from "@arnilo/prism-compaction-observational-memory";
+} from "@arnilo/prism-memory/compaction/observational-memory";
 
 const om = createObservationalMemory({
   observation: { provider: observerProvider, model: observerModel, messageTokens: 10_000 },
@@ -174,7 +174,7 @@ Hosts that need parent recall of child *source* work compose it themselves: wrap
 
 ```ts
 import { createId, type SessionStore } from "@arnilo/prism";
-import { isEligibleObservationSourceEntry } from "@arnilo/prism-compaction-observational-memory";
+import { isEligibleObservationSourceEntry } from "@arnilo/prism-memory/compaction/observational-memory";
 
 function funnelChildMessagesToWorkspace(store: SessionStore, workspaceSessionId: string): SessionStore {
   return {

package/docs/context-and-skills.md

@@ -158,6 +158,8 @@ Skill selection grants no tool access and cannot bypass permissions — a skill'
 
 ### Progressive skill disclosure
 
+Skills apply the same progressive-disclosure discipline as plan 041's [tool disclosure](tools.md) (toolsDisclosure "search") — one mechanism applied to skills (prompt text) and tools (provider tool arrays).
+
 `skillsDisclosure` on `AgentConfig` / `RunOptions` (`"progressive"` default, `"eager"` opt-in; run wins) controls how active skills render in provider input:
 
 | Mode | Provider view per active skill |

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

@@ -199,7 +199,7 @@ import {
   createKeychainCredentialStore,
   createStoredCredentialResolver,
 } from "@arnilo/prism-credentials-node";
-import { createOpenAIProviderPackage } from "@arnilo/prism-provider-openai";
+import { createOpenAIProviderPackage } from "@arnilo/prism-providers/openai";
 
 const keychain = createKeychainCredentialStore({
   service: "com.example.my-app",

package/docs/database-persistence.md

@@ -10,6 +10,8 @@ Plan 056 Task 1 adds dialect-neutral shared primitives under `@arnilo/prism/test
 
 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.
 
+The optional [`@arnilo/prism-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
 
 Use these contracts when you write a database-backed `SessionStore` or a separate persistence adapter that needs:
@@ -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>`:

package/docs/dev-inspector.md

@@ -0,0 +1,103 @@
+# Dev inspector
+
+## What it does
+
+`@arnilo/prism-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-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, intentionally omitted from `@arnilo/prism-all` and the profile packages, and it must never be the production API boundary — that stays `@arnilo/prism-server` under host authorization.
+
+### Quickstart — `prism dev` (plan 040 Task 4)
+
+```bash
+npm install --save-dev @arnilo/prism-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-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-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/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-observability-opentelemetry`](./observability.md): OpenTelemetry instrumentation and trace adapters.