@arnilo/prism 0.0.2 → 0.0.4

package/docs/coding-agent-tools.md

@@ -0,0 +1,242 @@
+# Coding agent tools (first-party package)
+
+## What it does
+
+`@arnilo/prism-coding-agent` is an optional first-party package that provides host shell/filesystem tools as Prism `ToolDefinition` objects. It ships four tools — `shell`, `read`, `write`, `edit` — plus aggregator factories. The tools are **inert** until a host imports them and registers them into a `ToolRegistry`. Behavior is a behavioral port of the pi coding agent's `bash`/`read`/`write`/`edit` tools, adapted to Prism's `ToolDefinition` / `ToolResult` contracts (no `@earendil-works/*` or `typebox` dependencies; only `diff` plus the Node standard library).
+
+| Export | Purpose |
+| --- | --- |
+| `createShellTool(cwd, options?)` | `shell` tool: run a shell command and return combined output + exit code. |
+| `createReadTool(cwd, options?)` | `read` tool: read a text or image file into `TextContent` / `ImageContent`. |
+| `createWriteTool(cwd, options?)` | `write` tool: create or overwrite a file, creating parent directories. |
+| `createEditTool(cwd, options?)` | `edit` tool: precise exact-then-fuzzy text replacement in an existing file. |
+| `createCodingTools(cwd, options?)` | All four tools (`shell`, `read`, `write`, `edit`). |
+| `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:
+
+```ts
+import { createToolRegistry } from "@arnilo/prism";
+import { createCodingTools } from "@arnilo/prism-coding-agent";
+
+const tools = createToolRegistry(createCodingTools(process.cwd()));
+```
+
+## When to use it
+
+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; 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
+
+| Prism (`@arnilo/prism-coding-agent`) | pi coding agent |
+| --- | --- |
+| `shell` | `bash` |
+| `read` | `read` |
+| `write` | `write` |
+| `edit` | `edit` |
+
+## Inputs / request
+
+### `shell`
+
+Run a shell command and return combined stdout+stderr.
+
+**Inputs:**
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `command` | `string` | Shell command to execute (required). |
+| `timeout` | `number` | Timeout in **seconds** (optional; no default). |
+
+**Outputs:** a `ToolResult` whose `content[0]` is a `TextContent` with the combined output. Non-zero exit is **not** a tool error: it is returned as a normal result with `[Command exited with code N]` appended to the content and `exitCode` in metadata. Timeout and abort are error results that still carry the partial output captured so far.
+
+`shell` result `metadata`:
+
+| Field | Present when | Purpose |
+| --- | --- | --- |
+| `exitCode` | always | Process exit code, or `null` when the process was killed by timeout/abort. |
+| `truncation` | always | `TruncationResult` from the bounded output accumulator. |
+| `fullOutputPath?` | truncated only | Path to the spilled temp file holding the full output. |
+
+Shell resolution honors `options.shellPath` → `SHELL` env → `/bin/bash` → `sh`, and the process group is killed on timeout/abort (`process.kill(-pid)` on Unix, `taskkill /F /T` on Windows).
+
+### `read`
+
+Read a text or image file.
+
+**Inputs:**
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `path` | `string` | Path to the file (relative or absolute; `~` and `file://` expanded). Required. |
+| `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**, 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, bytes }`. `resized` is `true` when `transformImage` ran. |
+
+> `autoResizeImages` is deprecated. It has no effect without `transformImage`; use `transformImage` for host-owned resizing.
+
+### `write`
+
+Create or overwrite a file, creating parent directories as needed.
+
+**Inputs:**
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `path` | `string` | Path to the file to write (relative or absolute). Required. |
+| `content` | `string` | Content to write (empty string creates an empty file). Required. |
+
+**Outputs:** a `TextContent` confirmation naming the **absolute path** with UTF-8 byte and line counts (e.g. `Successfully wrote 42 bytes (3 lines) to /abs/path.txt`). Write failures and abort are error results. Empty `content` is valid.
+
+`write` result `metadata`: `{ bytes, lines, path }` (absolute path). Concurrent writes to the same path serialize through `withFileMutationQueue`; writes to different paths run in parallel.
+
+### `edit`
+
+Precise text replacement in an existing file via exact-then-fuzzy matching.
+
+**Inputs:**
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `path` | `string` | Path to the file to edit. Required. |
+| `edits` | `Array<{ oldText: string, newText: string }>` | Targeted replacements, each matched against the **original** file (not incrementally). No overlapping/nested edits. Required, non-empty. |
+
+Each `edits[].oldText` must match a unique, non-overlapping region of the original file. Matching is exact first, then fuzzy (unicode normalization / whitespace collapse). A BOM is stripped before matching and re-prepended on write; original line endings are restored.
+
+**Outputs:** a `TextContent` confirmation (`Successfully replaced N block(s) in {path}.`) plus `metadata`. Any failure — missing/unreadable file, no match, duplicate (non-unique) match, overlap, empty `oldText`, no-op edit, or abort — is an error result, and the file is left **unchanged** (the match runs before the write).
+
+`edit` result `metadata`: `{ diff, patch, firstChangedLine }` — a display-oriented diff, a standard unified patch, and the first changed line in the new file. These are host-readable; the model only sees the short confirmation (keeps model context small).
+
+## Outputs / response / events
+
+Every tool returns a `ToolResult` with `toolCallId`, `name`, `content` (`readonly ContentBlock[]`), optional `error`, and optional `metadata`. Mutating tools (`shell` with same cwd, `write`, `edit`) serialize per realpath through `withFileMutationQueue` so concurrent calls targeting one file do not interleave. The package emits no events of its own; hosts observe tool execution through the normal Prism `AgentEvent` stream via `dispatchToolCall`.
+
+## Request/response example
+
+```json
+// edit request
+{ "path": "src/app.ts", "edits": [{ "oldText": "const x = 1;", "newText": "const x = 2;" }] }
+```
+
+```json
+// edit success result
+{
+  "toolCallId": "call_1",
+  "name": "edit",
+  "content": [{ "type": "text", "text": "Successfully replaced 1 block(s) in src/app.ts." }],
+  "metadata": { "diff": "...", "patch": "--- src/app.ts\n+++ src/app.ts\n...", "firstChangedLine": 3 }
+}
+```
+
+```json
+// edit no-match result (file unchanged)
+{
+  "toolCallId": "call_2",
+  "name": "edit",
+  "error": { "message": "Could not find edits[0] in src/app.ts. The oldText must match exactly including all whitespace and newlines." }
+}
+```
+
+## Implementation example
+
+Minimal drop-in for any Prism app:
+
+```ts
+import { createToolRegistry } from "@arnilo/prism";
+import { createCodingTools, createReadOnlyTools } from "@arnilo/prism-coding-agent";
+
+// Full coding set (shell + read + write + edit) against the project root:
+const tools = createToolRegistry(createCodingTools(process.cwd()));
+
+// Or a read-only set for inspection-only agents:
+const ro = createToolRegistry(createReadOnlyTools(process.cwd()));
+```
+
+Customizing a single tool (force bash, cap output, delegate writes to a remote backend):
+
+```ts
+import { createShellTool, createWriteTool } from "@arnilo/prism-coding-agent";
+
+const shell = createShellTool("/repo", {
+  shellPath: "/bin/bash",
+  commandPrefix: "set -euo pipefail",
+  maxLines: 500,
+});
+
+const remoteWrite = createWriteTool("/repo", {
+  operations: {
+    writeFile: async (abs, content) => { /* ship to remote */ },
+    mkdir: async (dir) => { /* mkdir -p remotely */ },
+  },
+});
+```
+
+## 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`, `executionPolicy`); `ReadToolOptions` (`operations`, `maxImageBytes`, `transformImage`, `maxLines`, `maxBytes`, `executionPolicy`; `autoResizeImages` deprecated); `WriteToolOptions` (`operations`, `executionPolicy`); `EditToolOptions` (`operations`, `executionPolicy`).
+- **Aggregator options.** `ToolsOptions` (`{ shell?, read?, write?, edit? }`) threads each sub-object to the matching tool.
+- **`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).
+- **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).
+- **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
+
+- [Tools](tools.md): the host-owned tool harness — `createToolRegistry`, `dispatchToolCall`, filtering, and the `ToolDefinition` contract these factories satisfy.
+- [Public contracts](public-contracts.md): `ToolDefinition`, `ToolResult`, `ToolExecutionContext`, `ContentBlock`, and `JsonObject` shapes.
+- [Host security guide](host-security.md): fail-closed checklist for permission policies, tool validation, and trust boundaries that must gate these tools.
+- [Tool conformance](tool-conformance.md): assertions for the tool-dispatch blocked-reason matrix these tools participate in.

package/docs/coding-security.md

@@ -0,0 +1,84 @@
+# 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. |
+
+## 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` 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()` or per tool. `SandboxAdapter` is replaceable and host-owned; approval policy and sandboxing are separate layers. Use run-scoped approval caching unless a wider host identity/lifecycle is explicit.
+
+## 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. 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/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

@@ -113,6 +113,7 @@ console.log(error.message);
 - `AgentConfig.credentials` is not eagerly resolved, serialized into provider requests/events/stores, or passed to loops/compaction by the core runtime.
 - `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).

package/docs/database-persistence.md

@@ -4,7 +4,9 @@
 
 The production persistence contracts describe database-neutral types for durable, multi-tenant storage of Prism sessions, branch handles, session entries, runs, agent-event ledger rows, tool-call rows, usage rows, agent-definition versions, retention policies, and migration records. They also define cursor-paginated query shapes so hosts can implement SQL, NoSQL, or object-store adapters without changing Prism runtime internals.
 
-Prism itself does not ship a production database adapter. The built-in `SessionStore` contract (`append` / `list` / optional `get`) remains the runtime seam; `ProductionPersistenceStore` is the optional adapter-facing contract for hosts that need paginated reads, tenant isolation, audit tables, and retention.
+Prism itself does not ship a production database adapter. The built-in `SessionStore` contract (`append` / `list` / optional `get`) remains the runtime seam; `ProductionPersistenceStore` is the optional adapter-facing contract for hosts that need paginated reads, tenant isolation, audit tables, retention, and optional generic `CheckpointStore` / `LeaseStore` capabilities.
+
+Plan 056 Task 1 adds dialect-neutral shared primitives under `@arnilo/prism/testing/persistence-schema`, `@arnilo/prism/testing/session-store-conformance`, and `@arnilo/prism/testing/run-ledger-conformance`. Task 2 ships `@arnilo/prism-session-store-sqlite` (see [SQLite persistence](sqlite-persistence.md)); Task 3 ships `@arnilo/prism-session-store-postgres` (see [PostgreSQL persistence](postgres-persistence.md)). Both implement dialect-local SQL against the shared model; Prism core still ships no ORM, driver, or migration runner.
 
 ## When to use it
 
@@ -184,6 +186,42 @@ The `usage` JSONB stores the `Usage` shape: input/output/total/cache tokens, cos
 
 Prism does not run migrations; hosts own migration tooling and use this table to record applied changes.
 
+## Shared schema model and migration contract
+
+Adapter packages import the shared model instead of copying table names piecemeal:
+
+```ts
+import {
+  createPersistenceSchemaModel,
+  createPersistenceMigrationContract,
+  assertPersistenceSchemaModel,
+  assertAdapterSchemaMatchesModel,
+  assertPersistenceQueryPaginationConforms,
+  assertTenantScopedQueryIsolation,
+  getPersistencePaginationCursors,
+  PARAMETERIZED_QUERY_GUIDANCE,
+} from "@arnilo/prism/testing/persistence-schema";
+import { assertSessionStoreConforms, runSessionStoreConformance } from "@arnilo/prism/testing/session-store-conformance";
+import { assertRunLedgerConforms, runRunLedgerConformance } from "@arnilo/prism/testing/run-ledger-conformance";
+
+const model = createPersistenceSchemaModel();
+assertPersistenceSchemaModel(model);
+
+await runSessionStoreConformance(() => createStore(testDatabase), { exerciseReopen: true });
+await runRunLedgerConformance(() => createLedger(testDatabase), { exerciseReopen: true });
+```
+
+| Primitive | Purpose |
+| --- | --- |
+| `PersistenceSchemaModel` | Versioned table/column/index model covering sessions, entries, parent chain, idempotency side table, runs, events, tool calls, usage, tenant columns, and `prism_migrations` |
+| `createPersistenceMigrationContract()` | Strictly increasing migration steps, `prism_migrations` recording, advisory-lock guidance, and least-privilege migration/runtime role guidance |
+| `getPersistencePaginationCursors()` | Indexed `(session_id, timestamp, id)`, `(run_id, sequence)`, `(run_id, recorded_at, id)` cursor shapes that avoid offset scans |
+| `assertPersistenceQueryPaginationConforms()` | Generic cursor pagination fixture for `queryEntries` |
+| `assertTenantScopedQueryIsolation()` | Tenant-filtered reads must not leak rows or primary-id collisions across tenants |
+| `PARAMETERIZED_QUERY_GUIDANCE` | Values are always bound parameters; only validated identifiers may be quoted |
+
+Dialect-local SQL remains in optional adapter packages. The shared model is the contract both adapters must satisfy before release.
+
 ## Adapter readiness checklist
 
 Before using a host database adapter in production:
@@ -382,9 +420,12 @@ const dbStore: ProductionPersistenceStore = {
 ## Extension and configuration notes
 
 - `ProductionPersistenceStore` is an optional extension point. The runtime does not require it.
-- Hosts choose the database, schema, transaction, and indexing strategy. The contract only specifies query shapes.
+- `ProductionPersistenceStore.checkpoints?: CheckpointStore` exposes generic versioned save/load/bounded-list/delete with compare-and-swap and fencing tokens, without workflow vocabulary.
+- `ProductionPersistenceStore.leases?: LeaseStore` exposes atomic acquire/renew/release/get with opaque claim tokens, expiries, ownership scope, and monotonic fencing tokens.
+- Hosts choose the database, schema, transaction, and indexing strategy. The contracts specify query and checkpoint capability shapes.
 - `SessionStore` (`append`/`list`/`get`/optional `readBranchPath`) can be implemented on top of `ProductionPersistenceStore` or kept separate.
 - Cursor values and idempotency keys are host-defined and opaque to Prism.
+- First-party SQLite/PostgreSQL adapters expose `persistence.checkpoints` and `persistence.leases`, backed by package-owned `prism_checkpoints` / `prism_leases` tables. `@arnilo/prism-workflows` consumes them for durable resume and multi-process coordination; workflow code owns no SQL table.
 
 ## Security and performance notes
 
@@ -405,3 +446,4 @@ const dbStore: ProductionPersistenceStore = {
 - [Agent events](agent-events.md): `AgentEvent` variants and redaction.
 - [Tools](tools.md): `ToolResult`, `ToolCallContent`, and tool execution events.
 - [Public contracts](public-contracts.md): full public contract inventory.
+- [Workflows](workflows.md): package-local durable checkpoint adapters on shared SQLite/Postgres handles.

package/docs/host-security.md

@@ -25,6 +25,7 @@ Start from explicit host inputs. Do not let runtime code discover security state
 | Permission decisions | allow/deny rules or approval UI result | `createStaticPermissionPolicy`, `assertPermission()` |
 | Tool allow-list | active tools for this agent/session/run | `createToolRegistry`, `filterTools()`, `dispatchToolCall()` |
 | Tool argument rules | host validator | `AgentConfig.validator`, `RunOptions.validate`, `ToolValidator` |
+| Coding execution policy | path/command approval adapter | `ExecutionPolicy`, `@arnilo/prism-coding-security` |
 | Durable history | host database adapter | `SessionStore`, `assertSessionStoreConforms()` |
 | Durable audit | host ledger adapter | `RunLedger`, `redactRunLedgerRecord()` |
 | Extensions | explicit package imports only | `createExtensionKernel`, `ExtensionAPI` |
@@ -120,12 +121,25 @@ Wire those values where they matter: provider adapters receive the resolved cred
 - Prism does not sandbox host tools, extensions, provider adapters, credential resolvers, or custom middleware. Use OS/container/process isolation when code is untrusted.
 - Redaction is exact known-secret replacement only. It is not arbitrary secret detection, entropy scanning, or DLP.
 - Known secrets must be passed into redactors before data is emitted or persisted. Redact again in host adapters if they transform records after Prism redaction.
-- Tool `parameters` metadata is not validation. Add a `ToolValidator` or validate inside the tool before side effects.
+- Tool `parameters` metadata is not validated by default. Add a `ToolValidator`, use `createToolParameterValidator()` with a schema adapter, or install `@arnilo/prism-tool-validator-json-schema` before side effects.
+- MCP tools from `@arnilo/prism-mcp` are untrusted remote servers. Configure stdio commands and HTTP URLs explicitly; bound output with `maxResultBytes`; register prefixed tools only after trust review. See [MCP client bridge](mcp-tools.md).
+- Coding tools from `@arnilo/prism-coding-agent` accept an optional `ExecutionPolicy` checked inside each tool before side effects. Use `@arnilo/prism-coding-security` for path roots, command rules, and approval caching. Prism does not provide OS sandboxing unless the host supplies a sandbox adapter.
 - Permission checks happen before tool validation and before `tool.execute()`. Middleware cannot grant permission by renaming a tool.
 - Session stores and ledgers receive redacted values when a redactor is active, but durable storage remains host-owned. Enforce tenant/account/user ownership and retention in the database layer.
 - Provider-owned auth/content/session/cache/security headers win over caller headers in adapters that merge headers.
 - Security checks are bounded explicit calls on the active path. Prism adds no hidden global middleware, background workers, watchers, network calls, or filesystem scans.
 
+### 0.0.4 release security audit (2026-07-14)
+
+- `npm audit --audit-level=high`: 0 vulnerabilities at every severity.
+- Lockfile: 162 registry dependency records, all with `resolved` provenance URL and integrity hash; `npm ls --all` reports a clean graph.
+- License inventory: 160 locked third-party packages; all declare permissive MIT, ISC, BSD, Apache-2.0, or compatible dual licenses. No GPL, AGPL, SSPL, or missing lockfile license metadata.
+- Install scripts: only `better-sqlite3@12.11.1` runs an install script (`prebuild-install || node-gyp rebuild --release`), required by the explicitly installed SQLite adapter. Core and other optional packages add no install hook.
+- Secret scan: source, tests, docs, workflow files, package metadata, built tests, packed-install canary, and tarball deny-list checks found no private-key block or common live-token prefix. Runtime redaction fixtures cover requests, events, ledgers, stores, checkpoints, provider/OAuth errors, and credential ciphertext.
+- Threat suites pass for parameterized SQL/tenant isolation, HTTP URL/SSRF rejection, realpath/symlink containment, shell-metacharacter approval, schema prototype-pollution/remote-reference bounds, OAuth polling/abort/redaction, credential tamper/wrong-key/KDF floors, MCP result bounds/timeouts, and coding approval/path policy.
+
+PostgreSQL TLS/network policy, MCP endpoint allow-listing, provider base URLs, OS keychain availability, process sandboxing, workflow tenant identity, and ANSI/control-sequence sanitization in any host terminal renderer remain host boundaries. Prism 0.0.4 ships JSON-line RPC, not an interactive TUI; hosts must render untrusted model/tool text safely. Credential-gated PostgreSQL/provider/keychain tests are separate operator/CI gates, not silently replaced by mocks.
+
 ## Related APIs
 
 - [Settings, auth, trust, and security controls](settings-auth-trust-security.md): low-level helpers and boundary hardening table.