@arnilo/prism 0.3.1 → 0.4.0

package/docs/caveman.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-caveman` is an optional package that wires [juliusbrussee/caveman](https://github.com/juliusbrussee/caveman) into Prism contribution contracts.
+`@arnilo/prism-coding-tools/caveman` is an optional package that wires [juliusbrussee/caveman](https://github.com/juliusbrussee/caveman) into Prism contribution contracts.
 
 It registers upstream skills and commands, injects active level prompt slices via `InstructionInjector`, and persists level as session custom `caveman-level` entries. Import and extension `setup` without a resolvable upstream path fail closed with a bounded redacted error and register zero contributions.
 
@@ -66,7 +66,7 @@ Deactivation phrases `stop caveman` and `normal mode` clear active injection wit
 ## Implementation example
 
 ```ts
-import { createCavemanExtension } from "@arnilo/prism-caveman";
+import { createCavemanExtension } from "@arnilo/prism-coding-tools/caveman";
 import {
   createExtensionKernel,
   createLoadSkillTool,

package/docs/cli-rpc.md

@@ -8,6 +8,7 @@ The `prism` bin is a thin adapter over `AgentSession` plus a tiny project scaffo
 - `prism --mode json -p "prompt"`: write one normalized event envelope per line.
 - `prism --mode rpc`: read LF-delimited JSON requests from stdin and write correlated JSON responses/events to stdout.
 - `prism init <dir>`: create a minimal TypeScript project with one selected provider, `.env.example`, and one offline mock test.
+- `prism dev`: boot the loopback dev inspector over the scaffolded agent (delegates into `@arnilo/prism-dev` when resolvable; plan 040 Task 4).
 
 It does not add a TUI, app tools, provider globals, extension discovery, resource discovery, or credential storage. `init` uses Node standard-library filesystem APIs and checked-in templates only — no interactive prompts or template-engine dependency.
 
@@ -22,19 +23,22 @@ Use the SDK directly when an app needs custom providers, tools, resources, crede
 ### `prism init`
 
 ```bash
-prism init <dir> [--provider <name>] [--with-workflows] [--with-evals] [--force]
+prism init <dir> [--template <name>] [--list-templates] [--provider <name>] [--with-workflows] [--with-evals] [--force]
 ```
 
 | Flag / arg | Purpose |
 | --- | --- |
-| `<dir>` | Destination directory (created if missing). |
+| `<dir>` | Destination directory (created if missing). Required unless `--list-templates` is specified. |
+| `--template <name>` | Template starter name (`init` [default], `deep-research`). |
+| `--list-templates` | List available starter templates from the templates gallery. |
 | `--provider <name>` | `mock` (default), `openai`, `openrouter`, `kimi`, `zai`, `opencode-go`, or `neuralwatt`. |
 | `--with-workflows` | Add `@arnilo/prism-workflows` and `src/workflows-example.ts`. |
 | `--with-evals` | Add `@arnilo/prism-evals` and `src/evals-example.ts`. |
 | `--force` | Overwrite generated files when the destination already exists. |
 | `-h`, `--help` | Print init usage. |
 
-Default generation installs only `@arnilo/prism` (mock provider). Selecting a real provider adds exactly one `@arnilo/prism-provider-*` package. Storage, telemetry, memory, and server packages are never added unless a later phase introduces an explicit flag for them. Rerunning without `--force` refuses non-empty destinations and existing generated files. `.env.example` contains placeholders only; `.gitignore` excludes `.env` and local stores.
+Default generation (`init` template) installs only `@arnilo/prism` (mock provider). Selecting a real provider adds exactly one dependency: the `@arnilo/prism-providers` family package (the selected adapter imports from `@arnilo/prism-providers/<id>`). Specifying `--template deep-research` scaffolds a flagship deep research agent pipeline (`@arnilo/prism`, `@arnilo/prism-web-tools`, `@arnilo/prism-rag`, `@arnilo/prism-workflows`) with planning, attributable citations, bounded refine loops, and HITL decision clarification. Rerunning without `--force` refuses non-empty destinations and existing generated files. `.env.example` contains placeholders only; `.gitignore` excludes `.env` and local stores.
+
 
 ### `prism providers add` (0.1.7)
 
@@ -68,6 +72,22 @@ header ownership, secret-leak redaction, and serialized-content coverage
 against the base provider. Replace the starter model metadata and the docs
 stub with docs-verified values before publishing.
 
+### `prism dev` (0.3.2)
+
+```bash
+prism dev [--port <n>] [--host <addr>]
+```
+
+Runs the local dev inspector over the current `prism init` scaffold's agent. Delegation, not duplication: the subcommand resolves `@arnilo/prism-dev` from the project's own `node_modules` (falling back to the CLI's own installation) and hands over to its `runDevCli` entry; unresolvable → install hint, exit `2`.
+
+| Flag / arg | Purpose |
+| --- | --- |
+| `--port <n>` | Bind port. Default `4311`. |
+| `--host <addr>` | Bind host. Default `127.0.0.1`; any non-loopback value is refused before binding (`ERR_PRISM_DEV_REMOTE_BIND`) unless remote authorization is wired programmatically. |
+| `-h`, `--help` | Print dev usage. |
+
+Manifests of the negotiation are simple: the agent is loaded from the scaffold contract `dist/agent.js` exporting `createAppAgent()` (missing → "build the project first", exit `2`); the inspector binds loopback, prints `prism dev → http://127.0.0.1:<port>/…`, and `SIGINT` drains and closes (exit `0`). Credentials stay in the scaffold's agent config — the CLI never reads environment secrets itself. Scaffolded projects ship a matching `"dev": "prism dev"` npm script.
+
 ### Run/RPC CLI flags
 
 | Flag | Purpose |
@@ -178,7 +198,10 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' | prism --provi
 prism init my-agent
 prism init my-agent --provider openai
 prism init my-agent --provider openrouter --with-workflows --with-evals
+prism init my-research --template deep-research
+prism init --list-templates
 cd my-agent && npm install && npm test
+
 ```
 
 Programmatic hosts should use the public runtime directly:

package/docs/coding-agent-tools.md

@@ -417,6 +417,12 @@ Opt-in `ask_user_decision` for ambiguous, high-impact direction choices. Model m
 | Agent durable adapter | `validateAskUserDecisionAgentResume({ request, answer })` — same validation; **no** new `AgentRunInterruption` kinds in 0.0.11 |
 
 Custom-text caps match question defaults (2 KiB / hard 8 KiB). Options default max 6 (hard 16).
+`allowCustom` defaults to `false` on **both** paths when omitted — the tool
+path (`parseAllowCustom`) and the workflow suspend path
+(`toAskUserDecisionSuspendData`) normalize at accept time, so the persisted
+suspension always carries a boolean and survives JSON checkpoint round-trips;
+a non-boolean value throws `allowCustom must be a boolean` at accept time,
+never at resume time.
 
 ```ts
 import { createToolRegistry } from "@arnilo/prism";
@@ -440,7 +446,7 @@ return suspendAskUserDecision({
   question: "Ship sqlite or postgres?",
   options: [/* ≥2 with 3 pros + 3 cons each */],
   selectionMode: "single",
-  allowCustom: false,
+  // allowCustom optional — defaults to false (tool-path parity)
 });
 // resumeWorkflow(..., { validateResume: createAskUserDecisionResumeValidator() })
 ```

package/docs/coding-security.md

@@ -194,7 +194,7 @@ await sandbox.close({
 
 Policies are ordinary host values: attach one globally through `createCodingTools()`/`createReadOnlyTools()`/`createSandboxCodingComposition()` or per tool. A per-tool policy overrides the shared policy. `SandboxAdapter` / `DisposableSandbox` are replaceable and host-owned; approval policy and sandboxing are separate layers. Custom remote sandboxes can implement `DisposableSandbox` without using Docker.
 
-`createSandboxCodingComposition()` requires `workspaceMode`. Sandbox mode auto-wires FS/list/search through `DisposableSandbox.execFile` (or host-supplied custom operations) so mutations stay on the disposable tree until export. Host mode runs every coding tool against the host cwd and reports no isolation capability (`containmentClaim` deprecated false). Sandbox shell + host FS throws unless `allowMixedWorkspaceWiring: true` (warnings + all capabilities false). Opt-in structured Git tools (`createGitTools(composition.workspaceRoot, { execFile: sandbox.execFile, commitIdentity })`) share the same tree/cwd; Prism still never pushes or opens PRs. Optional `@arnilo/prism-browser` can share the same disposable boundary: use `assertBrowserSandboxNetwork()` before browse-ready custom networks, and `createSharedSandboxBrowserOptions({ workspaceRoot, downloadsRoot, containedProxyAttestation })` so uploads/downloads align with `/workspace` and `/downloads`. Close the browser context before disposing the sandbox.
+`createSandboxCodingComposition()` requires `workspaceMode`. Sandbox mode auto-wires FS/list/search through `DisposableSandbox.execFile` (or host-supplied custom operations) so mutations stay on the disposable tree until export. Host mode runs every coding tool against the host cwd and reports no isolation capability (`containmentClaim` deprecated false). Sandbox shell + host FS throws unless `allowMixedWorkspaceWiring: true` (warnings + all capabilities false). Opt-in structured Git tools (`createGitTools(composition.workspaceRoot, { execFile: sandbox.execFile, commitIdentity })`) share the same tree/cwd; Prism still never pushes or opens PRs. Optional `@arnilo/prism-web-tools/browser` can share the same disposable boundary: use `assertBrowserSandboxNetwork()` before browse-ready custom networks, and `createSharedSandboxBrowserOptions({ workspaceRoot, downloadsRoot, containedProxyAttestation })` so uploads/downloads align with `/workspace` and `/downloads`. Close the browser context before disposing the sandbox.
 
 The Docker reference adapter starts by recorded container ID/label, uses argument arrays only, mounts source read-only, populates a size-bounded tmpfs `/workspace`, drops all capabilities, enables `no-new-privileges`, runs with `--init`, and never exposes the Docker socket, privileged mode, or host PID/IPC namespaces. Image pull/build/update stays outside Prism. Protected real-Docker checks are opt-in via `PRISM_TEST_DOCKER_SANDBOX=1` with host-supplied `PRISM_TEST_DOCKER_BIN` and digest-pinned `PRISM_TEST_DOCKER_IMAGE`.
 

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

@@ -93,6 +93,8 @@ createDefaultRetryPolicy(options?: DefaultRetryPolicyOptions): RetryPolicy
 
 `session.compact(options?)` emits `compaction_started`, runs the strategy on the current branch, runs `middleware.run("compaction", { context, result })` when middleware is configured, appends one standard `kind: "compaction"` entry under the current leaf, emits `compaction_finished`, and returns the appended result. Manual compaction rejects while a run is active.
 
+> **Contract — compact at the task boundary.** `session.compact()` throws `Error("Agent session already has an active run")` while `run()`/`stream()` is in flight. Intended model: one `run()` per task, then compact. Do not design mid-run compaction. Auto-compaction (when `thresholdEntries` is set) already runs **before** provider input, not during the turn. Live demo: [`examples/autonomous-coding-loop.ts`](../examples/autonomous-coding-loop.ts) (`compact` node after execute/validate/gate).
+
 Auto-compaction checks at most once per `run()`, after input/model-change entries are appended and before provider input assembly. It runs only when `AgentConfig.compaction` or `RunOptions.compaction` supplies `thresholdEntries`, and it is skipped by `RunOptions.compaction: false`.
 
 `rebuildSessionContext()` detects the latest compaction entry on a branch. Its returned `entries` still contains the raw full branch, while `messages` contains only messages after the compaction boundary plus `keepEntryIds`, and `summaries` contains the compaction summary plus later summary entries.
@@ -147,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
 
@@ -170,6 +172,7 @@ The default strategy does not call a provider. Hosts that need model-generated s
 - [Session stores and branching](session-stores-and-branching.md): branch entries, compaction entries, and `rebuildSessionContext()` behavior.
 - [Input and prompt assembly](input-and-prompt-assembly.md): compacted summaries become default summary messages for provider input.
 - [Agent/session runtime](agent-session-runtime.md): `session.compact()`, opt-in auto-compaction, `RunOptions.retry`, and `retry_scheduled` runtime behavior.
+- Example: [`examples/autonomous-coding-loop.ts`](../examples/autonomous-coding-loop.ts) — task-boundary compact after each iteration.
 - [Middleware hooks](middleware-hooks.md): `compaction` and `retry` middleware payload timing.
 - [Contribution registries](contribution-registries.md): compaction strategy and retry policy contributions.
 - [Configuration and manifests](configuration-and-manifests.md): `compactionStrategy` and `retryPolicy` manifest contribution kinds.

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 },
@@ -166,6 +166,52 @@ The runtime requires host-supplied `session`, an `appendEntry` callback bound to
 
 `createObservationalMemoryExtension()` registers only inert contributions. It does not start workers, compact sessions, read settings, resolve credentials, call providers, or execute tools/commands during setup.
 
+## Cross-session / delegation-tree recall (opt-in pattern)
+
+Default is per-session: `attach()` + `appendEntry` bind one store/branch, and `recallObservationalMemory(entries, id)` / `createRecallMemoryTool({ getEntries })` see only the entries the host passes for that session. Supervisor children therefore produce observations the parent cannot recall. That is acceptable for v1 — the parent transcript already contains `delegate()` results, so parent OM covers milestones. There is no package primitive for a shared workspace scope (a namespaced multi-tenant store key is out of scope).
+
+Hosts that need parent recall of child *source* work compose it themselves: wrap the shared `SessionStore.append` so eligible child messages (`isEligibleObservationSourceEntry`) are copied onto a workspace (or parent) session with a **new entry id** and that session's `sessionId`/`parentId`. Parent OM then observes those copies and mints **new** observation ids. Child OM, if attached, stays on the child session with its own ids.
+
+```ts
+import { createId, type SessionStore } from "@arnilo/prism";
+import { isEligibleObservationSourceEntry } from "@arnilo/prism-memory/compaction/observational-memory";
+
+function funnelChildMessagesToWorkspace(store: SessionStore, workspaceSessionId: string): SessionStore {
+  return {
+    async append(entry, options) {
+      await store.append(entry, options);
+      if (entry.sessionId === workspaceSessionId) return;
+      if (!isEligibleObservationSourceEntry(entry)) return;
+      const leaf = (await store.list(workspaceSessionId)).at(-1);
+      await store.append({
+        ...entry,
+        id: createId("entry"),
+        sessionId: workspaceSessionId,
+        parentId: leaf?.id,
+      });
+    },
+    list: (sessionId) => store.list(sessionId),
+    get: (id) => store.get?.(id) ?? Promise.resolve(undefined),
+    searchSessions: (query) => store.searchSessions?.(query) ?? Promise.reject(new Error("searchSessions unsupported")),
+    readBranchPath: store.readBranchPath?.bind(store),
+  };
+}
+```
+
+Wire the wrapped store into both the parent session and each supervisor child factory (`createAgent({ store })`). Parent `attach({ appendEntry: (entry, options) => store.append(entry, options) })` and `createRecallMemoryTool({ getEntries: () => parentSession.entries() })` then see funneled child messages plus parent-minted observations. Recreate the parent session with the store `leafId` after a restart so the workspace branch is the one that received the copies. [`examples/autonomous-coding-loop.ts`](../examples/autonomous-coding-loop.ts) shows parent OM attach/compact/recall in the supervisor loop; it records child outcomes on the parent session (same recall, no extra store wrap).
+
+Rules that keep exact-id recall unambiguous:
+
+- Recall always takes **one** branch (`session.entries()` / `getEntries(sessionId)`). Never concatenate parent + child lists into one `recallObservationalMemory()` call.
+- Copies mint a new `entry.id`. `createMemorySessionStore` rejects duplicate ids globally; JSONL/DB adapters do too.
+- Do **not** rewrite the child's OM `appendEntry` onto the workspace session. After each memory append the runtime checks the entry is visible at the **child** leaf and fails closed on a session/store mismatch. Funnel messages; let parent OM observe them.
+- Do **not** copy `om.*` custom entries across. Their `sourceEntryIds` point at the origin session and would dangle on the workspace branch.
+- Serialize funnel copies if concurrent children share the workspace tip (the sketch's `list().at(-1)` is not a lock).
+
+Cost: the workspace branch grows with every funneled child message; parent `compactAfterTokens` / observation-pool caps still apply but fire sooner. Keep the per-session default unless parent recall of child sources is required.
+
+Ownership: funnel only within the `OwnershipScope` already on the parent agent/store. Child factories receive that ownership from the supervisor; do not share a store across tenants or identities. Observations never leave the store the host scoped.
+
 ## Security and performance notes
 
 - Recall is exact-id only; there is no semantic search, vector store, or transcript browser.
@@ -187,6 +233,7 @@ The runtime requires host-supplied `session`, an `appendEntry` callback bound to
 - [Compaction and retry policies](compaction-and-retry.md): replaceable compaction strategy boundary.
 - [LLM compaction package](compaction-llm.md): existing optional compaction-package pattern.
 - [Session stores and branching](session-stores-and-branching.md): branch entries that observational memory reads and appends to.
+- [Supervisor delegation](supervisors.md): child sessions whose messages this page's opt-in funnel can copy onto a workspace branch.
 - [Extensions](extensions.md): inert registration pattern for optional package contributions.
 - [Tools](tools.md): host activation and dispatch for optional recall tool contributions.
 - [CLI/RPC](cli-rpc.md): command contributions through explicitly wired RPC hosts.

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.