@arnilo/prism 0.0.3 → 0.0.5

package/docs/agent-session-runtime.md

@@ -7,8 +7,9 @@ The agent/session runtime adds the minimal shared SDK surface for running provid
 - `createAgent(config)`
 - `createAgentSession(config)`
 - `agent.createSession(config)`
-- `session.run(input, options)`
-- `session.prompt(input, options)`
+- `session.run(input, options)` → `AgentRunResult`
+- `session.prompt(input, options)` → `AgentRunResult`
+- `session.stream(input, options)` → owned-run `AsyncIterable<AgentEvent>`
 - `session.compact(options?)`
 - `session.subscribe(options?)`
 - `session.abort()`
@@ -46,7 +47,11 @@ string | Message | readonly Message[]
 
 ## Outputs / response / events
 
-`session.subscribe(options?)` returns a live `AsyncIterable<AgentEvent>`. Subscribe before `run()` to observe that run's events. The consumer loop and `session.run()` must run concurrently (e.g. start the `for await` consumer, then `await Promise.all([consumer, session.run("Hi")])`): events are only emitted during a live run, so awaiting the subscribe loop before calling `run()` deadlocks. `SubscribeOptions.maxQueuedEvents` defaults to `1024` (minimum `1`) and caps events queued while the consumer is not awaiting `next()`. `SubscribeOptions.overflow` defaults to `"close"`; it clears queued payload events, delivers one `event_subscriber_overflow` notice to that subscriber, then closes it. `"drop_oldest"` keeps newest events; `"drop_newest"` ignores new events while full.
+`session.run()` / `session.prompt()` resolve to an `AgentRunResult` with `sessionId`, `runId`, `status`, `text`, `content`, optional `message`/`usage`/`leafId`, and terminal `error`/`abortReason` when applicable. Callers may ignore the return value. Failed and aborted runs still emit their terminal events, then reject with `AgentRunError` whose `.result` carries the same shape.
+
+`session.stream(input, options?)` subscribes first, starts exactly one run, yields only that run's events, and terminates when the run succeeds, fails, or aborts. Early consumer return aborts the owned run and releases the session. `SubscribeOptions.maxQueuedEvents` / `overflow` may be passed alongside `RunOptions`.
+
+`session.subscribe(options?)` remains available for hosts that want a long-lived subscriber across runs. Subscribe before `run()` to observe that run's events. The consumer loop and `session.run()` must run concurrently (e.g. start the `for await` consumer, then `await Promise.all([consumer, session.run("Hi")])`): events are only emitted during a live run, so awaiting the subscribe loop before calling `run()` deadlocks. Prefer `session.stream()` when you only need one run's events. `SubscribeOptions.maxQueuedEvents` defaults to `1024` (minimum `1`) and caps events queued while the consumer is not awaiting `next()`. `SubscribeOptions.overflow` defaults to `"close"`; it clears queued payload events, delivers one `event_subscriber_overflow` notice to that subscriber, then closes it. `"drop_oldest"` keeps newest events; `"drop_newest"` ignores new events while full.
 
 For a text-only provider turn, the runtime emits:
 
@@ -101,29 +106,22 @@ const agent = createAgent({
 });
 
 const session = agent.createSession({ id: "s1" });
-const reader = (async () => {
-  for await (const event of session.subscribe()) console.log(event.type);
-})();
+const result = await session.run("Hi", { maxToolRounds: 1, compaction: { thresholdEntries: 20, keepRecentEntries: 6 }, retry: { maxAttempts: 3, baseDelayMs: 50 } });
+console.log(result.text, result.usage?.totalTokens);
+
+for await (const event of session.stream("Follow up")) console.log(event.type);
 
-await session.run("Hi", { maxToolRounds: 1, compaction: { thresholdEntries: 20, keepRecentEntries: 6 }, retry: { maxAttempts: 3, baseDelayMs: 50 } });
 await session.compact({ keepRecentEntries: 4 });
 const branch = await session.entries();
 await session.checkout(branch.at(-1)?.id);
 const clone = await session.clone({ id: "s2" });
-await reader;
 ```
 
 ## Extension and configuration notes
 
 The runtime calls `assembleProviderInput()` on every turn and uses only runtime-consumed values supplied on `AgentConfig`: `instructions`, `systemPrompt`, `inputBuilder`, `promptBuilder`, `inputLayout`, `context`, selected `skills`, active `tools`, `middleware`, `resourceLoader`, metadata, `compaction`, `retry`, and `RunOptions.model`/`systemPrompt`/`inputLayout`/`compaction`/`retry`. Contributions remain inert until a host passes selected values into the agent config.
 
-`AgentConfig` fields that are host-owned metadata, not runtime work:
-
-| Field | Runtime behavior |
-| --- | --- |
-| `extensions` | Preserved on `agent.config` only. `createAgent()` / `session.run()` do not call `setup()`, load packages, or auto-register contributions. Load extensions with `createExtensionKernel()` before building config. |
-| `settings` | Preserved on `agent.config` only. The runtime does not call `settings.get()`; hosts or provider packages read settings before passing concrete runtime options. |
-| `credentials` | Preserved on `agent.config` only. The runtime does not call `credentials.resolve()`; provider adapters/request policies resolve credentials at the provider edge and pass exact secret values to redaction when needed. |
+`AgentConfig` no longer accepts inert `extensions`, `settings`, or `credentials` fields. Load extensions with `createExtensionKernel()` before building config; read settings in the host before passing concrete runtime options; resolve credentials at the provider edge and pass exact secret values to redaction when needed.
 
 The runtime calls `middleware.run("compaction", { context, result })` after a compaction strategy returns and before appending the standard compaction entry. Middleware can adjust the result summary/data, but the runtime still owns store append ordering and branch parent ids.
 
@@ -131,7 +129,7 @@ Provider request policy application is one ordered in-memory pass per provider t
 
 The runtime calls `middleware.run("retry", { context, decision })` after the retry policy decision and before emitting `retry_scheduled`. Middleware can stop retrying or adjust the delay. Retry wraps only the current provider turn, reuses the same assembled request, and never retries after assistant output has been emitted.
 
-`createAgent()` is a thin wrapper over explicit config. It does not load `AgentConfig.extensions`, scan packages, resolve credentials, read settings, call `Extension.setup()`, or consult hidden registries. External `AgentDefinition` implementations can call it from their own `create()` method:
+`createAgent()` is a thin wrapper over explicit config. It does not scan packages, resolve credentials, read settings, call `Extension.setup()`, or consult hidden registries. External `AgentDefinition` implementations can call it from their own `create()` method:
 
 ```ts
 import { createAgent, createContributionRegistries } from "@arnilo/prism";
@@ -173,6 +171,7 @@ await agent.createSession().run("Hi", { model: overrideModel });
 - [Tools](tools.md): host-owned tool harness used by the bounded runtime tool loop.
 - [Middleware hooks](middleware-hooks.md): hooks that configured assembly/runtime can run.
 - [CLI/RPC](cli-rpc.md): terminal and JSONL adapters over this runtime.
+- [Workflows](workflows.md): optional DAG orchestration that calls `AgentSession.run()` for agent nodes.
 
 `AgentConfig.loop` and `RunOptions.loop` select a replaceable per-run control loop (`singleShotLoop` default, or `generate-validate-revise` with host callbacks); see [Agent loops](agent-loops.md). `RunOptions.loop` wins over `AgentConfig.loop`. Built-in loops emit the same normal turn/message envelope around provider turns, and both add the first run input to live history once after the first provider turn so later turns see the same transcript shape.
 

package/docs/cli-rpc.md

@@ -2,23 +2,41 @@
 
 ## What it does
 
-The `prism` bin is a thin adapter over `AgentSession`:
+The `prism` bin is a thin adapter over `AgentSession` plus a tiny project scaffold:
 
 - `prism -p "prompt"`: print assistant text deltas.
 - `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.
 
-It does not add a TUI, app tools, provider globals, extension discovery, resource discovery, or credential storage.
+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.
 
 ## When to use it
 
-Use the CLI for terminal smoke tests, scriptable JSON event streams, and simple non-Node clients that can speak newline-delimited JSON.
+Use the CLI for terminal smoke tests, scriptable JSON event streams, simple non-Node clients that can speak newline-delimited JSON, and bootstrapping a tiny host project with `prism init`.
 
 Use the SDK directly when an app needs custom providers, tools, resources, credentials, trust prompts, or UI behavior.
 
 ## Inputs / request
 
-CLI flags:
+### `prism init`
+
+```bash
+prism init <dir> [--provider <name>] [--with-workflows] [--with-evals] [--force]
+```
+
+| Flag / arg | Purpose |
+| --- | --- |
+| `<dir>` | Destination directory (created if missing). |
+| `--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.
+
+### Run/RPC CLI flags
 
 | Flag | Purpose |
 | --- | --- |
@@ -127,6 +145,11 @@ Events streamed during a run keep the original prompt request id, even when an `
 prism --provider mock --model demo -p "Hi"
 prism --provider mock --mode json -p "Hi"
 printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' | prism --provider mock --mode rpc
+
+prism init my-agent
+prism init my-agent --provider openai
+prism init my-agent --provider openrouter --with-workflows --with-evals
+cd my-agent && npm install && npm test
 ```
 
 Programmatic hosts should use the public runtime directly:
@@ -147,6 +170,10 @@ CLI/RPC are adapters over `AgentSession`. They do not scan packages, import exte
 
 RPC `command` executes only explicitly registered `CommandDefinition` values. `setModel` stores a model override for later prompt/follow-up calls. `compact`, `switchSession`, `forkSession`, `cloneSession`, and `checkout` call the existing session APIs.
 
+Optional workflow control (from `@arnilo/prism-workflows`) registers `workflow.start`, `workflow.enqueue`, `workflow.replay`, `workflow.status`, `workflow.list`, `workflow.cancel`, and `workflow.resume` via `createWorkflowCommands({ workflows, checkpoints, runOptions? })`. Supplying an ownership-scoped `schedules` service additionally registers `schedule.create`, `schedule.list`, `schedule.pause`, `schedule.resume`, `schedule.trigger`, and `schedule.delete`. Pass the returned `CommandDefinition[]` into `runRpcServer({ commands })` the same way as observational-memory commands. Cancel aborts in-process runs through the package active-run registry; orphaned durable checkpoints still marked `running` are fail-closed to `aborted`.
+
+Suspended workflow resume parameters are `{ workflowId, runId, decision: "approve" | "deny", input?, expectedVersion, ownership? }`. Read `expectedVersion` from `workflow.status`/`workflow.list`; stale or duplicate decisions fail checkpoint CAS before node execution. Ordinary recovery resume for failed/aborted runs remains backward-compatible without decision fields.
+
 `forkSession` creates another handle for the same `sessionId` and selected `leafId`; it no longer overwrites the parent handle in the RPC map. Keep the returned `handleId` when a UI needs to switch among sibling branches. `switchSession` accepts `handleId` (preferred), `sessionId`, or `id`; with multiple branch handles, use `handleId` to avoid ambiguity. `checkout` requires `params.leafId`, calls `AgentSession.checkout(leafId)`, and keeps the active handle id unchanged while moving that handle to the existing leaf. `messages` returns entries for the active branch path.
 
 ## Security and performance notes
@@ -155,7 +182,10 @@ RPC `command` executes only explicitly registered `CommandDefinition` values. `s
 - No hidden provider, credential, extension, resource, config, settings, or tool globals are created.
 - No full TUI or sandbox is provided or implied.
 - JSONL is processed line by line with Node stdlib; no parser dependency, worker, watcher, or queue is added.
-- Unknown or malformed CLI/RPC input fails closed.
+- Unknown or malformed CLI/RPC input fails closed. Workflow resume validates decision and positive `expectedVersion`; ownership remains host-selected and checkpoint-enforced.
+- `prism init` refuses non-empty destinations without `--force`, keeps writes inside the destination root, and never executes downloaded code beyond the user's later `npm install`.
+- Generated `.env.example` values are placeholders only; `.gitignore` excludes `.env` and local store files.
+- Default generated install stays small (~27 MB with TypeScript tooling in a clean consumer install versus Mastra's measured 439 MB scaffold); unselected storage/telemetry/eval/workflow packages are omitted.
 - Branch handles (`handleId`, `sessionId`, `leafId`) are identifiers only; do not encode credentials, tokens, provider objects, or secrets into them.
 - Do not put resolved credential values, tokens, headers, or secrets in prompts, CLI flags, config, events, or docs examples.
 
@@ -169,6 +199,7 @@ RPC `command` executes only explicitly registered `CommandDefinition` values. `s
 - [Resource loading](resource-loading.md): explicit resource loading primitives.
 - [Credentials and redaction](credentials-and-redaction.md): secret redaction helpers and credential boundaries.
 - [Observational memory compaction package](compaction-observational-memory.md): optional `om:status` and `om:view` command factories for explicitly wired hosts.
+- [Workflows](workflows.md): optional `createWorkflowCommands()` for direct/background/replay/status/cancel/resume and selected schedule control over the same RPC `command` seam.
 
 The CLI records flags but does not auto-load project-local resources, extensions, tools, or config. The two system/project prompt files are the exception: in print/json modes the CLI auto-loads `<workspaceRoot>/AGENTS.md` (trust-gated) and an app-supplied `SYSTEM.md` layer as `AgentConfig.systemPrompt` layers composed with `--system` (base); `--no-agents-md` / `--no-system-md` skip them and `--agents-md-file` / `--system-md-file` override the paths. The CLI does not default `globalRoot` to the user's home directory — pass it from a host adapter or use `--agents-config <path>` for the app-config bundle layout. RPC mode does not auto-read these files (the host owns the session factory). Hosts must make explicit trust and permission decisions before wiring any other local loading.
 

package/docs/coding-agent-tools.md

@@ -14,6 +14,8 @@
 | `createReadOnlyTools(cwd, options?)` | Read-only subset: `read` only. |
 | `createAllTools(cwd, options?)` | Every tool the package provides (currently identical to `createCodingTools`). |
 | `detectSupportedImageMimeType(buf)` / `detectSupportedImageMimeTypeFromFile(path)` | Magic-byte image MIME detection (PNG/JPEG/GIF/WebP/BMP) used by `read`. |
+| `DEFAULT_MAX_IMAGE_BYTES` | Default `read` image size ceiling (10 MB). |
+| `TransformImage` / `TransformImageInput` | Types for the optional `read` `transformImage` callback. |
 | `withFileMutationQueue(path, fn)` | Per-path serialization primitive re-exported for hosts. |
 
 Each factory returns a plain `ToolDefinition` (no auto-registration). Register what you need:
@@ -29,7 +31,19 @@ const tools = createToolRegistry(createCodingTools(process.cwd()));
 
 Use this package when a host wants ready-made coding tools for an agent, session, or run, registered explicitly into a `ToolRegistry` and dispatched through the normal Prism tool harness. The tools perform **real** shell and filesystem operations on the host — they are not mocked or sandboxed. Use the individual factories when you need per-tool options or custom operation backends; use the aggregators when you want the default set.
 
-Do not use this package as a sandbox, permission policy, secret store, or provider loop. Prism gates tool dispatch with `PermissionPolicy` / `ToolValidator` / trust policies; the package performs no gating of its own. Do not register these tools for an untrusted provider.
+Do not use this package as a sandbox, permission policy, secret store, or provider loop. Prism gates tool dispatch with `PermissionPolicy` / `ToolValidator` / trust policies; pass an optional `ExecutionPolicy` (for example from `@arnilo/prism-coding-security`) for path/command approval before side effects. Do not register these tools for an untrusted provider.
+
+```ts
+import { createCodingTools } from "@arnilo/prism-coding-agent";
+import { createCodingApprovalPolicy } from "@arnilo/prism-coding-security";
+
+const tools = createCodingTools(workspaceRoot, {
+  executionPolicy: createCodingApprovalPolicy({
+    roots: [workspaceRoot],
+    approve: async ({ action }) => host.confirm(action),
+  }),
+});
+```
 
 ### pi name mapping
 
@@ -40,7 +54,7 @@ Do not use this package as a sandbox, permission policy, secret store, or provid
 | `write` | `write` |
 | `edit` | `edit` |
 
-## Tools
+## Inputs / request
 
 ### `shell`
 
@@ -77,16 +91,36 @@ Read a text or image file.
 | `offset` | `number` | Line to start reading from (1-indexed). |
 | `limit` | `number` | Maximum number of lines to read. |
 
-**Outputs:** text files become a single `TextContent`, truncated to `maxLines`/`maxBytes` (defaults 2000 lines / 50 KB) with a `Use offset=N to continue` footer when more remains. Image files (PNG/JPEG/GIF/WebP/BMP by magic bytes) become `[TextContent note, ImageContent]` with base64 `data` and `mimeType`. Read failures (missing file, offset beyond end, abort) are error results.
+**Outputs:** text files become a single `TextContent`, truncated to `maxLines`/`maxBytes` (defaults 2000 lines / 50 KB) with a `Use offset=N to continue` footer when more remains. Image files (PNG/JPEG/GIF/WebP/BMP by **magic bytes**, not extension) become `[TextContent note, ImageContent]` with base64 `data` and `mimeType`. Oversize images are rejected by `stat` (when available) or `buffer.length` against `maxImageBytes` (default 10 MB) before base64 encoding. An optional `transformImage` callback lets hosts resize or re-encode images without adding image-processing dependencies to the base package. Read failures (missing file, offset beyond end, oversize image, abort) are error results.
+
+`read` tool options (via `createReadTool(cwd, options)` or `ToolsOptions.read`):
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `maxImageBytes` | `DEFAULT_MAX_IMAGE_BYTES` (10 MB) | Reject image reads larger than this many bytes. |
+| `transformImage` | — | Host callback `( { buffer, mimeType } ) => Promise<Buffer>` run after read, before base64. |
+| `autoResizeImages` | — | **Deprecated.** Ignored unless `transformImage` is also set (use `transformImage` instead). |
+| `maxLines` / `maxBytes` | 2000 / 50 KB | Text head truncation limits. |
+| `operations` | local fs | Pluggable `ReadOperations` backend. |
+| `executionPolicy` | — | Structured pre-execution policy (see [Coding security](coding-security.md)). |
+
+```ts
+import { createReadTool, DEFAULT_MAX_IMAGE_BYTES } from "@arnilo/prism-coding-agent";
+
+const read = createReadTool(cwd, {
+  maxImageBytes: DEFAULT_MAX_IMAGE_BYTES,
+  transformImage: async ({ buffer, mimeType }) => host.resizeImage(buffer, mimeType),
+});
+```
 
 `read` result `metadata`:
 
 | Field | Present when | Purpose |
 | --- | --- | --- |
 | `truncation` | text reads | `TruncationResult`. |
-| `image` | image reads | `{ mimeType, resized: false }`. |
+| `image` | image reads | `{ mimeType, resized, bytes }`. `resized` is `true` when `transformImage` ran. |
 
-> `autoResizeImages` is accepted but is currently a documented no-op (deferred); images are returned at their original size with `image.resized = false`.
+> `autoResizeImages` is deprecated. It has no effect without `transformImage`; use `transformImage` for host-owned resizing.
 
 ### `write`
 
@@ -187,18 +221,18 @@ const remoteWrite = createWriteTool("/repo", {
 ## Extension and configuration notes
 
 - **Pluggable operation backends.** Every tool accepts an `operations` seam so a host can delegate to a remote system (e.g. SSH) while keeping the tool's matching/serialization behavior: `BashOperations` (`shell`), `ReadOperations` (`read`), `WriteOperations` (`write`), `EditOperations` (`edit`).
-- **Per-tool options.** `ShellToolOptions` (`shellPath`, `commandPrefix`, `maxLines`, `maxBytes`, `tempFilePrefix`, `operations`, `spawnHook`); `ReadToolOptions` (`operations`, `autoResizeImages`, `maxLines`, `maxBytes`); `WriteToolOptions` (`operations`); `EditToolOptions` (`operations`).
-- **Aggregator options.** `ToolsOptions` (`{ shell?, read?, write?, edit? }`) threads each sub-object to the matching tool.
+- **Per-tool options.** `ShellToolOptions` (`shellPath`, `commandPrefix`, `maxLines`, `maxBytes`, `tempFilePrefix`, `operations`, `spawnHook`, `executionPolicy`); `ReadToolOptions` (`operations`, `maxImageBytes`, `transformImage`, `maxLines`, `maxBytes`, `executionPolicy`; `autoResizeImages` deprecated); `WriteToolOptions` (`operations`, `executionPolicy`); `EditToolOptions` (`operations`, `executionPolicy`).
+- **Aggregator options.** `ToolsOptions` (`{ executionPolicy?, shell?, read?, write?, edit? }`) threads each sub-object to the matching tool. `createCodingTools()`, `createAllTools()`, and `createReadOnlyTools()` apply the shared policy unless that tool has an explicit per-tool override.
 - **`ToolsOptions`** and the per-tool option types are exported from the package barrel for host configuration.
 - No auto-discovery or manifest registration: import and register explicitly. This package registers no extensions and owns no globals (the mutation queue is a process-wide per-path map — see `ponytail:` note in the source).
 
 ## Security and performance notes
 
-- **Host shell/filesystem access.** These tools run real commands and read/write real files. They provide **no sandbox**. Gate them with Prism `PermissionPolicy` / `ToolValidator` / trust policies before registering them for any provider turn. See [Host security guide](host-security.md) and [Security/auth/trust](settings-auth-trust-security.md).
+- **Host shell/filesystem access.** These tools run real commands and read/write real files. They provide **no sandbox**. Gate them with Prism `PermissionPolicy` / `ToolValidator` / trust policies before registering them for any provider turn. Shared `executionPolicy` applies to both full and read-only aggregators before filesystem/process side effects. See [Host security guide](host-security.md) and [Security/auth/trust](settings-auth-trust-security.md).
 - **Non-zero exit is not an error.** A failing command is a normal `shell` result (exit code in metadata); only timeout/abort/spawn failures are error results. Do not assume `error == undefined` means the command succeeded.
 - **Bounded output.** `shell`/`read` accumulate output into a rolling tail bounded by `maxLines`/`maxBytes`; oversized output spills to a temp file (`fullOutputPath`), so memory use is bounded regardless of command output size.
 - **Per-path serialization.** Concurrent mutations to the same file serialize; concurrent mutations to different files do not block each other. The queue is a process-wide map — across sessions in one process, same-path writes still serialize (upgrade path: scope per registry if throughput matters).
-- **Single runtime dependency.** `diff` (for `edit` unified patch/diff generation) plus the Node standard library. No native modules; no image-processing native dependency (image auto-resize is deferred, so no `sharp`/WASM dependency).
+- **Bounded image reads.** `read` rejects images over `maxImageBytes` (default 10 MB) by `stat` before read when possible; MIME is detected from magic bytes only. Optional `transformImage` is host-owned — the base package has no image-processing dependency.
 
 ## Related APIs
 

package/docs/coding-security.md

@@ -0,0 +1,88 @@
+# Coding execution approval and sandboxing
+
+## What it does
+
+`@arnilo/prism-coding-security` is an optional package that supplies structured execution policy for `@arnilo/prism-coding-agent` tools. It complements name-based `PermissionPolicy` at dispatch time with path/command context checked **inside** each tool before side effects.
+
+| Export | Purpose |
+| --- | --- |
+| `createCodingApprovalPolicy(options)` | Returns an `ExecutionPolicy` with trusted roots, read-only mode, command allow/deny rules, approval caching, and timeout/abort-aware approval waits. |
+| `createSandboxBashOperations(adapter)` | Maps a host-owned `SandboxAdapter` to coding-agent `BashOperations` for delegated shell execution. |
+| `assertPathInsideRoots`, `isPathInsideReal` | Symlink-aware path containment helpers. |
+| `evaluateCommandRules`, `hasShellMetacharacters` | Command classification helpers. |
+
+Core contracts live in `@arnilo/prism`:
+
+```ts
+import type { ExecutionAction, ExecutionPolicy, ExecutionDecision } from "@arnilo/prism";
+```
+
+## When to use it
+
+Use this package when coding tools need path scoping, human approval, command rules, or a pluggable sandbox backend. Wire the returned policy through `createCodingTools(cwd, { executionPolicy })` or per-tool `executionPolicy` options.
+
+Prism does **not** claim OS-level isolation unless the host provides a sandbox adapter. Default policy denies shell/write/edit without an `approve` callback and rejects paths outside configured roots. Coding shell definitions are marked `exclusive: true`, matching the approval policy's shell decision, so a single-shot turn containing shell work runs sequentially even when `toolConcurrency > 1`. Non-shell turns retain configured parallelism.
+
+## Inputs / request
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `roots` | required | Realpath-contained filesystem roots. |
+| `readOnly` | `false` | Deny shell/write/edit actions. |
+| `commandRules` | `[]` | Ordered allow/deny/approval command classification. |
+| `approve` | none | Host callback for actions not statically allowed; omission fails closed. |
+| `approvalCacheScope` | `"none"` | Optional `run` or `session` decision cache scope. |
+| `approvalTimeoutMs` | `30000` | Bound approval wait; caller abort also cancels it. |
+
+`run` caching keys decisions by the tool execution context's `runId`; `session` uses `sessionId`. Coding tools pass both identities to the policy. A missing/empty identity disables caching for that check rather than creating a global bucket. Identical actions in different runs/sessions never share approvals or denials.
+
+## Outputs / response / events
+
+`createCodingApprovalPolicy()` returns an `ExecutionPolicy`. Allowed checks return `ExecutionDecision { allowed: true }`; denied checks include a stable reason; shell decisions set `exclusive: true`. Sandbox adapters return coding-agent-compatible `BashOperations`, receive `onData(Buffer)` for ordered stdout/stderr forwarding through the shell tool's existing bounded accumulator, and never grant policy approval themselves.
+
+## Request/response example
+
+```json
+{
+  "action": { "kind": "shell", "operation": "execute", "command": "npm test", "paths": [] },
+  "decision": { "allowed": true, "exclusive": true }
+}
+```
+
+## Implementation example
+
+```ts
+import { createCodingTools } from "@arnilo/prism-coding-agent";
+import { createCodingApprovalPolicy, createSandboxBashOperations } from "@arnilo/prism-coding-security";
+
+const policy = createCodingApprovalPolicy({
+  roots: [workspaceRoot],
+  approve: async ({ action, signal }) => ui.confirm(action, { signal }),
+  approvalCacheScope: "run",
+  approvalTimeoutMs: 60_000,
+});
+
+const tools = createCodingTools(workspaceRoot, {
+  executionPolicy: policy,
+  shell: {
+    operations: createSandboxBashOperations(mySandboxAdapter),
+  },
+});
+```
+
+## Extension and configuration notes
+
+Policies are ordinary host values: attach one globally through `createCodingTools()`/`createReadOnlyTools()` or per tool. A per-tool policy overrides the shared policy. `SandboxAdapter` is replaceable and host-owned; approval policy and sandboxing are separate layers.
+
+Callback approval remains process-local. For approval that must survive restart, wrap the action in an opted-in workflow `toolNode({ approval: { reason, data?, resumeSchema? } })`. The workflow persists `suspended` state before any tool side effect. After explicit approve, it recomputes the action and invokes this package's current `ExecutionPolicy`; durable approval never populates or bypasses the process-local approval cache. Adapters should emit chunks through `request.onData` as they arrive and honor `request.signal`/`request.timeout`; buffering is unnecessary. Default caching is `none`; use run-scoped caching only when repeated approval within one run is desired, and session scope only when that wider lifecycle is intentional.
+
+## Security and performance notes
+
+Containment resolves symlinks and rejects paths outside roots. Command rules are not a shell parser; shell metacharacters require approval. Approval waits and subprocess execution honor abort/timeouts. Durable workflow denial/cancellation is terminal and attributable; approved resume still fails if roots, command rules, read-only mode, or other policy changed while suspended. Cache keys are fixed-size SHA-256 digests of selected identity plus action shape; caches remain process-local, retain at most 1,000 decisions with oldest-entry eviction, and have no default/global mode. Path checks and cache lookup are local; sandbox latency belongs to the supplied adapter.
+
+## Related APIs
+
+- [Coding agent tools](coding-agent-tools.md)
+- [Host security guide](host-security.md)
+- [Tool execution primitives](tool-execution-primitives.md)
+- [Security/auth/trust](settings-auth-trust-security.md)

package/docs/compaction-observational-memory.md

@@ -6,6 +6,8 @@
 
 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.
 
+This package is distinct from `@arnilo/prism-memory` working/semantic memory: observational memory compresses and recalls source-backed observations/reflections; semantic memory retrieves embeddings; working memory stores the current structured profile/state. Hosts may compose both.
+
 ## When to use it
 
 Use it when a host wants to opt in to long-session memory that records observations/reflections as session custom entries, renders prepared memory during compaction, and supports exact-id recall.

package/docs/context-and-skills.md

@@ -179,6 +179,7 @@ Use `activateAllCapabilities: true` only as a temporary all-skills/all-tools com
 - [Agent/session runtime](agent-session-runtime.md): consumes host-selected context providers and skills from explicit agent config.
 - [Input and prompt assembly](input-and-prompt-assembly.md): default prompt builder and provider-input assembly helper.
 - [Instruction injection](instruction-injection.md): package injectors contribute `contextBlocks` that merge after host+skill provider blocks.
+- [Retrieval-augmented generation](rag.md): optional retrieved citations contribute through the same explicit inert context seam.
 - [Public contracts](public-contracts.md): `ContextProvider`, `ContextResolutionContext`, `ContextBlock`, `Skill`, `SkillRegistry`, `PromptBuilder`, and `PromptBuildRequest`.
 - [Middleware hooks](middleware-hooks.md): `context` and `prompt_build` hooks.
 - [Contribution registries](contribution-registries.md): inert context provider and skill contributions.

package/docs/credential-storage.md

@@ -0,0 +1,177 @@
+# Credential storage
+
+## What it does
+
+The optional `@arnilo/prism-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`
+- **Stored credential resolver** — `createStoredCredentialResolver(store)` for explicit resolver chains
+- **OAuth adapter** — extends the core `OAuthCredentialStore` seam with `get`/`delete` for refresh flows
+
+Factories:
+
+- `openEncryptedCredentialStore(options)` / `createEncryptedCredentialStore(options)`
+- `createKeychainCredentialStore(options)`
+- `createStoredCredentialResolver(store)`
+- `createOAuthCredentialStoreAdapter(store)`
+- `rotateEncryptedCredentialStorePassphrase(options)`
+
+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.
+
+## When to use it
+
+Use this package when a host needs durable credentials beyond `createMemoryCredentialStore()`:
+
+- local CLI tools storing API keys or OAuth tokens between runs
+- desktop hosts integrating with macOS Keychain, Windows Credential Manager, or Linux Secret Service
+- integration tests that need encrypted reopen semantics without a live keychain
+
+Do **not** use it when credentials should live in a remote vault, HSM, or cloud secret manager — implement `CredentialResolver` against that service instead.
+
+## Inputs / request
+
+```ts
+import {
+  openEncryptedCredentialStore,
+  createKeychainCredentialStore,
+} from "@arnilo/prism-credentials-node";
+```
+
+### Encrypted file
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `path` | `string` | Vault file path. Parent directories are created as needed. |
+| `getPassphrase` | `() => string \| Promise<string>` | Host-owned passphrase retrieval. Never logged by the adapter. |
+| `scrypt` | `{ N?, r?, p?, keyLength? }` | Optional KDF tuning. Defaults: `N=32768`, `r=8`, `p=1`, `keyLength=32`. Minimum `N=16384`. |
+| `fileMode` | `number` | Unix mode for newly written files. Defaults to `0o600`. |
+
+### System keychain
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `service` | `string` | Keychain service name (application identifier). |
+| `namespace` | `string` | Optional prefix separating environments or tenants within one service. |
+| `timeoutMs` | `number` | Operation timeout. Defaults to `5000`. |
+
+## Outputs / response / events
+
+Both backends implement `StoredCredentialStore`:
+
+| Method | Behavior |
+| --- | --- |
+| `set(record)` / `get(request)` / `delete(request)` | Namespaced by `(provider, name)` for API keys and bearer tokens. |
+| `setOAuth(provider, credentials, accountId?)` | Stores OAuth tokens per provider/account. |
+| `getOAuth(provider, accountId?)` / `deleteOAuth(...)` | Reads or removes OAuth rows. |
+| `resolve(request)` | `CredentialResolver` compatibility via `createStoredCredentialResolver`. |
+
+Encrypted file stores also expose:
+
+- `reload()` — re-read and decrypt from disk
+- `flush()` — force rewrite of the encrypted envelope
+
+Errors are explicit and fail closed:
+
+| Error | Code | When |
+| --- | --- | --- |
+| `CredentialDecryptError` | `credential_decrypt_failed` | Wrong passphrase or tampered ciphertext |
+| `CredentialStoreLockedError` | `credential_store_locked` | Keychain denied or locked |
+| `CredentialStoreUnavailableError` | `credential_store_unavailable` | No OS secret service |
+| `CredentialStoreTimeoutError` | `credential_store_timeout` | Keychain call exceeded `timeoutMs` |
+| `WeakKdfParametersError` | `weak_kdf_parameters` | scrypt work factor below minimum |
+
+## Request/response example
+
+```json
+{
+  "path": "./credentials.vault",
+  "fileMode": 384,
+  "keychain": {
+    "service": "my-app",
+    "namespace": "production",
+    "timeoutMs": 5000
+  }
+}
+```
+
+On-disk envelope (illustrative — ciphertext is base64, secrets are not plaintext):
+
+```json
+{
+  "version": 1,
+  "kdf": { "algorithm": "scrypt", "N": 32768, "r": 8, "p": 1, "salt": "...", "keyLength": 32 },
+  "cipher": { "algorithm": "aes-256-gcm", "iv": "..." },
+  "ciphertext": "..."
+}
+```
+
+## Implementation example
+
+```ts
+import {
+  createExplicitCredentialResolver,
+  refreshOAuthCredential,
+  resolveCredentialValue,
+} from "@arnilo/prism";
+import {
+  createOAuthCredentialStoreAdapter,
+  createStoredCredentialResolver,
+  openEncryptedCredentialStore,
+} from "@arnilo/prism-credentials-node";
+
+const store = await openEncryptedCredentialStore({
+  path: "./credentials.vault",
+  getPassphrase: () => process.env.MY_APP_CREDENTIAL_PASSPHRASE!,
+});
+
+const resolver = createExplicitCredentialResolver([
+  { name: "stored", resolver: createStoredCredentialResolver(store) },
+]);
+
+const apiKey = await resolveCredentialValue(resolver, { name: "apiKey", provider: "demo" });
+
+const oauthStore = createOAuthCredentialStoreAdapter(store);
+await refreshOAuthCredential({
+  provider: myOAuthProvider,
+  credentials: existing,
+  store: oauthStore,
+});
+```
+
+Passphrase rotation:
+
+```ts
+import { rotateEncryptedCredentialStorePassphrase } from "@arnilo/prism-credentials-node";
+
+await rotateEncryptedCredentialStorePassphrase({
+  path: "./credentials.vault",
+  getCurrentPassphrase: () => oldPassphrase,
+  getNewPassphrase: () => newPassphrase,
+});
+```
+
+## Extension and configuration notes
+
+- Passphrase retrieval, TLS, and OS permission prompts remain host-owned.
+- Use distinct `namespace` or vault paths per tenant/environment.
+- Keychain `list()` / `listOAuth()` are intentionally unsupported — enumerate credentials through host configuration instead of scanning the OS store.
+- Combine with `createExplicitCredentialResolver()` so runtime overrides still win over stored values.
+- Wire `createOAuthCredentialStoreAdapter(store)` into `refreshOAuthCredential()` so refreshed tokens persist durably.
+
+## Security and performance notes
+
+- Authenticated encryption uses Node built-in `aes-256-gcm` and `scrypt`; no extra crypto dependencies for the file backend.
+- Atomic writes use temp file + rename; partial writes cannot replace a valid vault.
+- Derived keys are zeroed after encrypt/decrypt operations where practical.
+- Default scrypt `N=32768` targets interactive CLI unlock; raise `N` for higher security at the cost of unlock latency.
+- Keychain operations honor `timeoutMs` and surface `CredentialStoreTimeoutError` instead of blocking indefinitely.
+- Never log passphrases, derived keys, or decrypted credential payloads. Error messages do not echo secret values.
+- Live keychain tests are opt-in (`PRISM_TEST_KEYCHAIN=1`); default `npm test` stays offline.
+
+## Related APIs
+
+- [Credentials and redaction](credentials-and-redaction.md): core resolver helpers and `refreshOAuthCredential()`
+- [Security/auth/trust](settings-auth-trust-security.md): host-owned settings/credentials boundaries
+- [Persistence, credentials, and multimodality primitives](persistence-credentials-multimodality-primitives.md): Plan 056 threat model and conformance matrix rows 7–10
+- `@arnilo/prism`: `CredentialResolver`, `OAuthCredentialStore`, `createMemoryCredentialStore()`

package/docs/credentials-and-redaction.md

@@ -95,7 +95,7 @@ console.log(error.message);
 ## Extension and configuration notes
 
 - Hosts and extension packages can implement `CredentialResolver` and pass it explicitly to code that needs credentials.
-- `AgentConfig.credentials` is host-owned metadata for compatibility; `createAgent()` / `session.run()` do not call `credentials.resolve()`. Provider adapters, compaction workers, or request policies should receive and resolve credentials at the provider edge.
+- Credentials stay host-owned outside `AgentConfig`. `createAgent()` / `session.run()` do not call `credentials.resolve()`. Provider adapters, compaction workers, or request policies should receive and resolve credentials at the provider edge.
 - Use `createExplicitCredentialResolver()` when documenting a fixed order such as runtime override, stored credential, caller-provided env object, then fallback resolver.
 - Use `createEnvCredentialResolver()` only with an object supplied by the host; Prism does not read `process.env` for you.
 - Provider adapters should resolve credentials as late as possible, per request.
@@ -110,9 +110,10 @@ console.log(error.message);
 - Cycle and non-JSON value handling: `redactSecrets()` is cycle-safe via a `WeakSet` visited-set. Self-referential or mutually referenced objects render `"[Circular]"` at the back-reference instead of throwing. `Date` and `RegExp` values are passed through unchanged; `ArrayBuffer` and typed arrays are passed through unchanged; `Map` is normalized to a plain object and `Set` to an array so the output stays JSON-compatible. `errorToErrorInfo()` tolerates a cyclic `error.cause` (rendered via `String()`).
 - Use placeholders in tests and docs. Never commit real tokens.
 - Live provider/worker tests are gated behind explicit environment variables and skipped by default: `PRISM_LIVE_PROVIDER_TESTS`, `PRISM_LIVE_COMPACTION_TESTS`, `PRISM_LIVE_OBSERVATIONAL_MEMORY_TESTS`. Default `npm test` is network-free; do not add ungated network calls to default tests.
-- `AgentConfig.credentials` is not eagerly resolved, serialized into provider requests/events/stores, or passed to loops/compaction by the core runtime.
+- Credentials are not eagerly resolved by the core runtime, serialized into provider requests/events/stores, or passed to loops/compaction.
 - `resolveCredentialValue()` and `createExplicitCredentialResolver()` do not cache values. Add host-side caching only if a real credential source needs it.
 - `refreshOAuthCredential()` only calls the supplied OAuth provider and optional store; it has no built-in persistence or retry loop.
+- OpenAI Codex device-code OAuth polls inside `createOpenAICodexOAuthProvider().login()` with bounded delays and abort support via `OAuthLoginCallbacks.signal`. Token-endpoint failures redact authorization codes, PKCE verifiers, device/user codes, and access/refresh tokens when those values are known.
 
 ## Related APIs
 
@@ -121,4 +122,4 @@ console.log(error.message);
 - [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. 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. 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. 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).