@arnilo/prism 0.0.3 → 0.0.5

package/docs/mcp-tools.md

@@ -0,0 +1,184 @@
+# MCP client bridge and server exposure
+
+## What it does
+
+`@arnilo/prism-mcp` has two explicit directions. Its client bridge connects hosts to remote [Model Context Protocol](https://modelcontextprotocol.io) servers and maps discovered tools to ordinary `ToolDefinition`s. Its server API registers selected Prism `ToolDefinition` and `CommandDefinition` values on the official SDK `McpServer`, with required authorization and a bounded optional Web-standard Streamable HTTP handler. The package wraps `@modelcontextprotocol/sdk` v1.29+ and adds no MCP branch to core Prism.
+
+Primary API:
+
+```ts
+import { connectMcpTools } from "@arnilo/prism-mcp";
+
+const bridge = await connectMcpTools({
+  serverId: "fs",
+  transport: { type: "stdio", command: "node", args: ["server.js"] },
+});
+
+// bridge.tools are ToolDefinition[] — register with createToolRegistry / createAgent
+await bridge.refresh(); // re-list after notifications or TTL expiry
+await bridge.close();   // close client + transport
+```
+
+Advanced hosts that manage their own `Client` + `Transport` can call `attachMcpToolBridge(client, transport, options)` after `client.connect(transport)`.
+
+Server direction:
+
+```ts
+import { createPrismMcpServer, createPrismMcpWebHandler } from "@arnilo/prism-mcp";
+
+const server = createPrismMcpServer({
+  tools: [approvedTool],
+  commands: [approvedWorkflowStatusCommand],
+  authorize: async ({ authInfo, kind, name }) => hostPolicy(authInfo, kind, name)
+    ? { allowed: true, ownership: { tenantId: "tenant-1" } }
+    : false,
+  validate,
+  permission,
+  redactor,
+});
+
+const handleMcp = await createPrismMcpWebHandler(server, {
+  resolveAuthInfo: authenticateRequest,
+  allowedHosts: ["api.example.test"],
+  allowedOrigins: ["https://app.example.test"],
+});
+```
+
+`McpServer.connect(transport)` remains available for SDK stdio or in-memory transports. The helper uses SDK `WebStandardStreamableHTTPServerTransport` in bounded stateless JSON-response mode; it does not start a listener.
+
+## When to use it
+
+- **Integrate external MCP tool servers** (filesystem, databases, SaaS adapters) without reimplementing JSON-RPC transports in your app.
+- **Keep core dispatch gates** — register returned tools and let `dispatchToolCall` enforce permission, JSON Schema validation (`ToolValidator`), middleware, abort, and parallel execution (Plan 055 Tasks 1–2).
+- **Explicit lifecycle** — connect, refresh on `notifications/tools/list_changed`, and `close()` when the session ends.
+- **Expose selected capabilities** — register a reviewed tool/command allow-list for MCP clients without a custom JSON-RPC server.
+
+Do **not** use this package as a sandbox, permission engine, or auto-discovery loader. Hosts must trust configured commands/URLs and gate registration.
+
+## Inputs / request
+
+`connectMcpTools()` requires a stable `serverId` plus an explicit stdio or Streamable HTTP transport. Optional bounds control list caching, call timeout, result bytes, name prefix, and abort behavior; defaults are listed below.
+
+## Outputs / response / events
+
+The resolved `McpToolBridge` exposes `tools`, `refresh()`, and `close()`. Each discovered MCP tool becomes a normal Prism `ToolDefinition`; calls return `ToolResult`, with remote `isError` mapped to `ToolResult.error`. List-change notifications invalidate the cache but register nothing automatically.
+
+`createPrismMcpServer()` returns the SDK `McpServer`. It lists only passed tools/commands; JSON Schema parameters are converted through installed Zod v4 for SDK validation, then Prism tool calls still pass through `dispatchToolCall` permission/validator/redactor gates. Command definitions support explicitly selected direct/background/replay workflow operations and optional ownership-scoped schedule operations from `createWorkflowCommands()`; none are registered unless the host passes those command definitions. Calls return bounded MCP text content and `isError` on denial/failure. `createPrismMcpWebHandler()` returns `(Request) => Promise<Response>`.
+
+## Request/response example
+
+```json
+{
+  "request": { "serverId": "docs", "transport": { "type": "stdio", "command": "node", "args": ["server.js"] } },
+  "mappedTool": { "name": "mcp:docs:search", "parameters": { "type": "object" } }
+}
+```
+
+## Implementation example
+
+```ts
+import { createToolRegistry } from "@arnilo/prism";
+import { connectMcpTools } from "@arnilo/prism-mcp";
+
+const bridge = await connectMcpTools({
+  serverId: "docs",
+  transport: { type: "stdio", command: "node", args: ["server.js"] },
+  callTimeoutMs: 30_000,
+});
+const registry = createToolRegistry({ duplicate: "error" });
+for (const tool of bridge.tools) registry.register(tool);
+```
+
+## Tool naming and mapping
+
+| MCP | Prism |
+| --- | --- |
+| `tools/list` `inputSchema` | `ToolDefinition.parameters` |
+| `tools/call` arguments | Parsed `ToolCallContent.arguments` |
+| `tools/call` content blocks | `ToolResult.content` (`text`, `image`; resource/audio/link → descriptive `text`) |
+| Tool `name` | Prefixed `mcp:<serverId>:<name>` (override with `namePrefix`) |
+| `isError` results | `ToolResult.error` with summarized text |
+| `structuredContent` | `ToolResult.value` / metadata |
+
+Duplicate prefixed names throw `McpToolNameCollisionError` at refresh time.
+
+## Extension and configuration notes
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `serverId` | required | Stable identifier used in default name prefix |
+| `transport` | required | `stdio` or `streamable-http` config |
+| `namePrefix` | `mcp:<serverId>:` | Registry namespace for remote tools |
+| `listCacheTtlMs` | `30000` | Skip re-listing until TTL expires (invalidated on list-changed) |
+| `callTimeoutMs` | `60000` | Per-call MCP request timeout |
+| `maxResultBytes` | `10000000` | Bound mapped result content |
+| `signal` | none | Abort connect and trigger close on abort |
+
+### Stdio transport
+
+```ts
+{
+  type: "stdio",
+  command: "node",
+  args: ["path/to/server.js"],
+  env?: Record<string, string>,
+  cwd?: string,
+  stderr?: "inherit" | "pipe" | "ignore" | "overlapped",
+}
+```
+
+The host explicitly chooses the executable, arguments, environment, and working directory. Prism does not search `PATH` for unknown servers or inject credentials.
+
+### Streamable HTTP transport
+
+```ts
+{
+  type: "streamable-http",
+  url: "https://mcp.example.com/mcp",
+  requestInit?: RequestInit,
+  sessionId?: string,
+}
+```
+
+Only `http:` and `https:` URLs are accepted. Authentication (Bearer tokens, cookies) is supplied through `requestInit.headers` by the host.
+
+### MCP server options
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `tools` / `commands` | empty | Explicit allow-list; zero default exposure |
+| `authorize` | required | Per-call host authz using SDK auth/session metadata |
+| `permission` / `validate` / `redactor` | none | Core tool-dispatch gates and known-secret redaction |
+| `maxResultBytes` | 1 MiB (8 MiB hard) | Bound mapped MCP call output |
+| `maxConcurrentCalls` | 16 (256 hard) | Bound active tool/command execution |
+| `callTimeoutMs` | 60 s (30 min hard) | Abort and return timed-out calls |
+
+Web handler defaults: 1 MiB request (8 MiB hard), 2 MiB response (16 MiB hard), 32 concurrent requests (512 hard), and 60 s timeout (30 min hard). It parses bounded JSON before passing `parsedBody` to the SDK transport. `allowedHosts`/`allowedOrigins` activate SDK DNS-rebinding checks only when explicitly configured. Authentication data comes only from host `resolveAuthInfo()`.
+
+## Security and performance notes
+
+| Risk | Mitigation |
+| --- | --- |
+| Untrusted subprocess (stdio) | Explicit `command` / `args` / `env` / `cwd`; review before deploy |
+| SSRF / open redirects (HTTP) | Host URL allow-lists, network policy, no implicit discovery |
+| Tool-name shadowing | Prefixed names + `createToolRegistry({ duplicate: "error" })` |
+| Oversized server output | `maxResultBytes` on content mapping |
+| Unvalidated arguments | Register tools with `createJsonSchemaToolArgumentValidator()` at dispatch |
+| Missing permission gate | Client direction: `PermissionPolicy` on `tool:mcp:<serverId>:<name>:execute`; server direction: required MCP `authorize` plus optional core `PermissionPolicy` |
+| Accidental server exposure | Empty default arrays, duplicate-name rejection, explicit tools/commands only |
+| Unbounded MCP HTTP | Bounded pre-parsed JSON, response bytes, concurrent requests, call timeout, SDK web-standard transport |
+| Cross-tenant operation | Authorizer derives ownership from validated auth and passes it to tool dispatch/selected workflow commands; never trust arguments as identity |
+
+MCP output is untrusted. Apply `SecretRedactor` and host logging policy to `ToolResult` before persisting or displaying. MCP server authorization does not replace tool `PermissionPolicy`, argument validation, coding `ExecutionPolicy`, workflow ownership checks, TLS, rate limiting, or sandboxing. A timed-out tool must cooperate with `AbortSignal` to stop side effects; the response is bounded even when untrusted code ignores abort.
+
+## Related APIs
+
+- [Tools](tools.md): registry, dispatch, validation
+- [Tool execution primitives](tool-execution-primitives.md): Plan 055 design and conformance matrix
+- [Host security guide](host-security.md): permission, trust, validation checklist
+- [Web-standard server handler](server.md): agent/workflow HTTP routes and shared remote-boundary rules
+- Package README: [`@arnilo/prism-mcp`](../packages/mcp/README.md)
+
+## Testing
+
+Package tests use in-memory MCP transports (no network). Hosts should integration-test their configured stdio commands and HTTP endpoints in staging before production registration.

package/docs/middleware-hooks.md

@@ -101,6 +101,7 @@ export const extension: Extension = {
 - `retry` middleware may stop retrying or adjust delay, but runtime still owns retry event emission, abort-aware waiting, and provider-turn boundaries.
 - The registry does not discover packages, read manifests, load config, call providers, execute tools, read resources, or start sessions.
 - Hosts may pass a middleware registry into `createExtensionKernel({ middleware })` to share it with direct host code.
+- For OpenTelemetry export, prefer `session.subscribe()` + `@arnilo/prism-observability-opentelemetry` (see [Observability](observability.md)) rather than adding a parallel event bus. Middleware hooks remain for transforming payloads at named boundaries.
 
 ## Security and performance notes
 
@@ -118,6 +119,7 @@ export const extension: Extension = {
 - [Input and prompt assembly](input-and-prompt-assembly.md): `input_assembly` and `prompt_build` helper call sites.
 - [Compaction and retry policies](compaction-and-retry.md): compaction/retry middleware payloads and runtime timing.
 - [Context and skills](context-and-skills.md): `context` helper call site.
+- [Observability](observability.md): optional OpenTelemetry adapter over `AgentEvent` streams.
 - [Public contracts](public-contracts.md): provider, tool, context, session, and extension contracts that runtimes can pass through hooks.
 
 Permission checks for tools, extensions, and resources are hard guards; middleware can transform payloads but cannot bypass a denied `PermissionPolicy`.

package/docs/migration.md

@@ -2,12 +2,33 @@
 
 ## What it does
 
-This page is the single navigation entry for the two cross-cutting migrations external apps hit when moving from Prism's development defaults to its production persistence and explicit-capability surfaces:
+Prism 0.0.5 preserves documented 0.0.3 agent construction except for two intentional Phase 3 public-API cleanups:
 
-1. **In-memory / JSONL → database-backed persistence** — swap the single-process development `SessionStore` for a host-implemented `ProductionPersistenceStore` / `SessionStore` adapter, and optionally attach a durable `RunLedger`.
-2. **Permissive capability defaults → explicit capability activation** — move from "omitted tool/skill lists activate everything in scope" (pre-Phase 38 behavior) to named, fail-closed tool/skill activation.
+1. **`session.run()` / `session.prompt()` return `AgentRunResult`** and `session.stream()` starts one owned run after subscribing. Callers that ignored the previous `Promise<void>` keep working; failed/aborted runs reject with `AgentRunError` (`.result` attached).
+2. **`AgentConfig.extensions` / `settings` / `credentials` are removed.** Wire extensions through `createExtensionKernel()`, read settings in the host, and pass credential resolvers to the provider edge.
 
-It is a thin, link-first guide: it states before/after shapes and points at the detailed pages for schema, indexes, redaction, branch handles, capability semantics, and security.
+Phase 4 adds optional `@arnilo/prism-evals` for deterministic scorers/datasets/experiments. It is not a core dependency; install it directly or through `@arnilo/prism-all`.
+
+Phase 5 adds `prism init <dir>` to the existing CLI. It scaffolds a tiny TypeScript project with one selected provider and an offline mock test. Optional `--with-workflows` / `--with-evals` flags add only those packages; storage and telemetry stay opt-in elsewhere.
+
+Phase 6 adds optional `@arnilo/prism-provider-ai-sdk` for AI SDK `LanguageModelV4` interoperability. Install it with `@ai-sdk/provider@^4`, through `@arnilo/prism-providers`, or through `@arnilo/prism-all`; it is not a core dependency.
+
+Phase 7 adds optional `@arnilo/prism-memory` for schema/template-backed working memory and embedding-based semantic recall. Install it directly or through `@arnilo/prism-all`; in-memory adapters are default, and PostgreSQL/pgvector is opt-in. It is not a core dependency.
+
+Phase 8 extends `@arnilo/prism-workflows` compatibly. Nodes may return `suspend()`, and opted-in tool nodes may declare `approval`. Resuming a suspended run requires `{ decision, input?, expectedVersion }`; ordinary failed/aborted recovery resume remains unchanged. `WorkflowRunStatus` adds `suspended` and terminal `denied`. Suspension/resume records remain bounded checkpoint JSON, so SQLite/PostgreSQL require no migration.
+
+Phase 9 adds optional `@arnilo/prism-rag` for bounded plain-text/Markdown chunking, Phase 7 vector indexing/retrieval, stable citations, and explicit context injection. Existing agents and memory stores are unchanged; install and attach its context provider explicitly. No database migration is required.
+
+Phase 10 adds optional `@arnilo/prism-server` and extends `@arnilo/prism-mcp` with server-direction APIs. Existing agent/workflow/MCP client behavior is unchanged. Install the server package explicitly, pass selected capability maps plus required host authorization, and adapt its Web handler in the deployment host. MCP servers likewise register only passed tools/commands and require authorization. No listener, route, credential source, profile package, or database migration activates automatically.
+
+Phase 11 compatibly extends `@arnilo/prism-workflows` with `workflowNode`, shared state fields/context updates, replay lineage, explicit background enqueue, and ownership-scoped schedules. Existing workflow definitions and direct runs remain valid; `WorkflowRunResult` now always includes `state`. State schemas require a host `validateState` callback. Schedules reuse generic checkpoint/lease stores, so SQLite/PostgreSQL need no migration and no scheduler starts automatically.
+
+This page also covers two optional adoption paths:
+
+1. **In-memory / JSONL → database-backed persistence** — replace the single-process development `SessionStore` with `@arnilo/prism-session-store-sqlite`, `@arnilo/prism-session-store-postgres`, or a host implementation, and optionally attach its durable `RunLedger`.
+2. **Legacy permissive capability configuration → explicit activation** — name tools/skills and keep omitted capabilities fail-closed.
+
+It states before/after shapes and links detailed schema, redaction, branch, capability, and security guidance.
 
 ## When to use it
 
@@ -15,7 +36,7 @@ Read this page when:
 
 - you are taking an app from the `createMemorySessionStore()` / `createJsonlSessionStore()` path to a multi-process, multi-tenant, or durable database backend;
 - you are hardening an agent that previously relied on "every scoped tool/skill is active" and need to name capabilities explicitly;
-- you are adopting the Phase 34–40 production surfaces (atomic append, branch handles, run/event/tool/usage ledger, security boundary hardening) for the first time.
+- you are adopting 0.0.5 persistence, checkpoints/leases, workflows, structured output, multimodality, or explicit tool safety for the first time.
 
 If you are new to Prism, start at [Session stores](session-stores.md) and [Agent/session runtime](agent-session-runtime.md) instead.
 
@@ -26,6 +47,8 @@ There is no runtime import for this page. The migrations below use these surface
 | Surface | Where | Migration role |
 | --- | --- | --- |
 | `SessionStore` | `@arnilo/prism` | Runtime seam swapped from memory/JSONL to DB. |
+| `createSqlitePersistence` | `@arnilo/prism-session-store-sqlite` | Local durable session, ledger, query, checkpoint, and lease adapter. |
+| `createPostgresPersistence` | `@arnilo/prism-session-store-postgres` | Multi-process pooled persistence with advisory-lock migrations. |
 | `ProductionPersistenceStore` | `@arnilo/prism` | Adapter-facing contract for paginated, multi-tenant reads (`query*`, optional `readBranchPath`). |
 | `RunLedger` / `RunLedgerRecord` | `@arnilo/prism` | Durable run/event/tool-call/usage ledger attached via `AgentConfig.runLedger` / `RunOptions.runLedger`. |
 | `SessionAppendOptions` / `SessionAppendConflictError` / `SessionBranchHandle` | `@arnilo/prism` | Atomic append, retry dedup, durable branch handles. |
@@ -77,34 +100,23 @@ Capability migration (before/after):
 
 ### Migration 1 — in-memory / JSONL → database-backed persistence
 
-A complete, network-free reference adapter that implements these contracts against in-memory tables (and wires a `RunLedger`, branch-handle checkout, fork, and prior-run timeline resume) lives at [`examples/external-app-db-backed.ts`](../examples/external-app-db-backed.ts). The steps below mirror its structure.
+Runnable references: [`examples/workflow-sqlite-resume.ts`](../examples/workflow-sqlite-resume.ts), credential-gated [`examples/workflow-postgres-resume.ts`](../examples/workflow-postgres-resume.ts), and the network-free custom-adapter example [`examples/external-app-db-backed.ts`](../examples/external-app-db-backed.ts).
 
-Step 1: implement a `SessionStore` (or the richer `ProductionPersistenceStore`) against your database. The runtime only requires `append(entry, options?)`, `list(sessionId)`, and optional `get(id)` / `readBranchPath(query)`.
+Step 1: replace the development store with a first-party adapter. Use PostgreSQL instead when multiple processes or sustained concurrent writers matter.
 
 ```ts
 // Before: development store, single process.
 import { createJsonlSessionStore } from "@arnilo/prism/node/session-store-jsonl";
-const store = createJsonlSessionStore("./sessions.jsonl");
-
-// After: host-implemented database adapter implementing the documented contract, no real DB needed to satisfy the contract.
-import type { SessionStore, SessionEntry, SessionAppendOptions, PersistencePage, SessionBranchRead } from "@arnilo/prism";
-
-const store: SessionStore = {
-  async append(entry: SessionEntry, options?: SessionAppendOptions) {
-    // 1. idempotency dedup: insert (session_id, expected_parent_id, idempotency_key, entry_id)
-    //    into prism_session_append_idempotency; unique hit => SessionAppendConflictError { idempotencyDuplicate: true }
-    // 2. expectedParentId existence check => SessionAppendConflictError { expectedParentId } if missing
-    // 3. insert prism_session_entries row; duplicate id fails the transaction
-    // 4. optionally compare-and-swap prism_branches.leaf_entry_id
-  },
-  async list(sessionId: string) { /* O(n) development fallback only */ return []; },
-  async readBranchPath(query: SessionBranchRead): Promise<PersistencePage<SessionEntry>> {
-    // one recursive CTE / ancestor query — do NOT list(sessionId)+in-memory walk for long sessions
-    return { items: [] };
-  },
-};
+const oldStore = createJsonlSessionStore("./sessions.jsonl");
+
+// After: local durable adapter. The same object implements SessionStore,
+// RunLedger, ProductionPersistenceStore, checkpoints, and leases.
+import { createSqlitePersistence } from "@arnilo/prism-session-store-sqlite";
+const store = createSqlitePersistence({ filename: "./prism.db" });
 ```
 
+Custom adapters remain supported through `SessionStore` / `ProductionPersistenceStore`; implement indexed `readBranchPath()` rather than full-session scans.
+
 Step 2: optionally attach a durable run/event/tool/usage ledger and ownership scope so a process exit leaves enough to resume and bill:
 
 ```ts
@@ -134,6 +146,8 @@ What you leave behind and why:
 - `createMemorySessionStore()` — process-local maps; lost on restart, no cross-process locking. Keep for tests.
 - `createJsonlSessionStore()` — single-process file adapter; reads are linear in file size, no cross-process lock, no durable idempotency table, two writers to the same file can race. Keep for local/dev only.
 
+Prism 0.0.5 persistence adapters automatically apply additive schema step `002_usage_scope`, then `003_run_feedback`. Migration 003 creates immutable owned run/trace feedback with a run FK, cascade deletion, JSON tag/scorer/evaluation ID lists, and owner/run/trace cursor indexes. Existing rows are unchanged. Custom adapters may omit optional `ProductionPersistenceStore.feedback`; adopters implement `RunFeedbackStore` append/query/delete semantics and must verify exact linked-run ownership before insert.
+
 See [Database persistence](database-persistence.md) for the full reference schema, indexes, conditional-append transaction pattern, retention, and NoSQL mapping; [Session stores](session-stores.md) for the `SessionStore` contract and branch helpers; [Session stores and branching](session-stores-and-branching.md) for branch semantics; [Runs and usage ledger](runs-and-usage.md) for the `RunLedger` record shapes and ordering rules.
 
 ### Migration 2 — permissive capability defaults → explicit capability activation
@@ -174,7 +188,7 @@ Runtime skill activation remains explicit: `RunOptions.activeSkills` narrows per
 
 ## Extension and configuration notes
 
-- **Persistence is host-owned.** Prism ships no database adapter, no DDL, no migration runner. Hosts own connection pools, transactions, cursor encoding, retention jobs, and tenant isolation. The runtime only talks to `SessionStore` (+ optional `readBranchPath`) and `RunLedger`.
+- **Persistence remains host-configured.** Optional SQLite/PostgreSQL packages ship adapters and versioned setup, but hosts choose connection paths/pools, TLS, credentials, retention, tenant policy, and lifecycle. Core only consumes `SessionStore`, `RunLedger`, feedback, checkpoint, and lease contracts.
 - **`RunLedger` is not a `SessionStore` replacement.** Messages, branches, and session entries still flow through `SessionStore.append()`; the ledger records run/event/tool/usage facts. See [Runs and usage ledger](runs-and-usage.md).
 - **Capability activation is config over code.** Every seam lives on `AgentDefinition` / `AgentDefinitionResolutionContext` / `RunOptions`; no auto-activation, no privilege grant. A declaration cannot grant permissions or bypass `toolNames`.
 - **Migration order is decoupled.** You can adopt database persistence without changing capability activation, and vice versa. Both migrations are independent config swaps.
@@ -190,7 +204,16 @@ Runtime skill activation remains explicit: `RunOptions.activeSkills` narrows per
 
 ## Related APIs
 
-- [Database persistence](database-persistence.md): production persistence contracts, reference schema, indexes, conditional append, retention, migrations, NoSQL mapping.
+- [Evaluations](evaluations.md): optional `@arnilo/prism-evals` scorers/datasets/experiments over `AgentRunResult`.
+- [AI SDK provider adapter](providers/ai-sdk.md): optional `@arnilo/prism-provider-ai-sdk` `LanguageModelV4` bridge.
+- [Working and semantic memory](working-and-semantic-memory.md): optional `@arnilo/prism-memory` working/semantic recall primitives.
+- [Retrieval-augmented generation](rag.md): optional text/Markdown chunk, index, retrieval, and citation helpers.
+- [Web-standard server handler](server.md): optional authorized agent/workflow HTTP routes.
+- [Supervisor delegation](supervisors.md) and [A2A interoperability](a2a.md): optional install only; core agent/workflow behavior is unchanged. Child factories now receive package-derived memory IDs and narrowing permission, while remote endpoints require exact HTTPS origin allow-lists.
+- [MCP client/server exposure](mcp-tools.md): selected MCP tools/commands and bounded Web transport.
+- [Database persistence](database-persistence.md): production contracts, reference schema, indexes, conditional append, retention, migrations, and custom adapters.
+- [SQLite persistence](sqlite-persistence.md): local durable first-party adapter and writer ceiling.
+- [PostgreSQL persistence](postgres-persistence.md): pooled multi-process adapter, TLS/pool ownership, and live gate.
 - [Session stores](session-stores.md): `SessionStore` contract, `SessionAppendOptions`, `SessionAppendConflictError`, branch handles, `readBranchPath`.
 - [Session stores and branching](session-stores-and-branching.md): detailed branch semantics and helper reference.
 - [Runs and usage ledger](runs-and-usage.md): `RunLedger` record shapes, redaction, and event/usage ordering.

package/docs/model-registry.md

@@ -36,7 +36,7 @@ import { createModelRegistry, type ModelConfig } from "@arnilo/prism";
 | --- | --- |
 | `provider` / `model` | Required registry key. |
 | `displayName` | Human-readable label. |
-| `capabilities` | Input/output modes plus reasoning/tools/streaming booleans. |
+| `capabilities` | Input/output modes (`text`, `image`, `audio`, `file`, `document`) plus reasoning/tools/streaming booleans and optional `structuredOutput` (`true` or `"json_schema"`) for native JSON-schema requests. |
 | `limits` | Context and output-token limits. |
 | `cost` | Input/output/cache read/cache write pricing. |
 | `cache` | Generic `ModelCacheCapabilities`. |
@@ -74,7 +74,7 @@ The registry emits no events and performs no I/O.
   "model": {
     "provider": "demo",
     "model": "demo-large",
-    "capabilities": { "input": ["text"], "tools": true, "streaming": true },
+    "capabilities": { "input": ["text", "image", "audio", "file", "document"], "tools": true, "streaming": true },
     "limits": { "contextWindow": 128000, "maxOutputTokens": 8192 },
     "cost": { "input": 10, "output": 30, "cacheRead": 2, "currency": "USD", "unit": "1M tokens" },
     "cache": { "kind": "cache_control", "maxBreakpoints": 4, "longRetention": true }
@@ -91,7 +91,7 @@ const model: ModelConfig = {
   provider: "demo",
   model: "demo-large",
   displayName: "Demo Large",
-  capabilities: { input: ["text"], output: ["text"], tools: true, streaming: true },
+  capabilities: { input: ["text", "document"], output: ["text"], tools: true, streaming: true },
   limits: { contextWindow: 128_000, maxOutputTokens: 8_192 },
   cost: { input: 10, output: 30, cacheRead: 2, cacheWrite: 12, currency: "USD", unit: "1M tokens" },
   cache: { kind: "cache_control", maxBreakpoints: 4, minCacheableTokens: 1024, longRetention: true },
@@ -110,12 +110,14 @@ Provider packages register models through `ProviderPackageAPI.registerModel(mode
 ## Security and performance notes
 
 - Model metadata must not contain credentials or secrets.
+- Declare truthful `capabilities.input` tags. Prism core rejects undeclared modalities in `assembleProviderInput()` when the list is present.
 - Registration is in-memory and O(1) by provider/model key.
 - `ModelConfig.cache` is declarative capability info only; it does not grant permissions, select tools, or bypass auth.
 - Provider-specific behavior belongs in provider packages, not Prism core.
 
 ## Related APIs
 
+- [Multimodal content](multimodal-content.md): `audio`/`file`/`document` blocks and `MODEL_INPUT_CAPABILITIES`.
 - [Provider layer](provider-layer.md): provider/model registry overview.
 - [Provider caching](provider-caching.md): `ModelCacheCapabilities` and cache helpers.
 - [Provider packages](provider-packages.md): package registration of model metadata.

package/docs/multimodal-content.md

@@ -0,0 +1,156 @@
+# Multimodal content
+
+## What it does
+
+Prism core ships generic `audio`, `file`, and `document` `ContentBlock` types plus bounded media resolution helpers. Blocks carry MIME type, optional name, and exactly one source: inline base64 `data`, remote `url`, or host `resourceUri`. Optional `transcript` metadata can accompany audio/document blocks.
+
+`assembleProviderInput()` calls `assertMessagesSupportModelCapabilities()` so declared `ModelCapabilities.input` tags are enforced before provider calls. First-party provider packages map supported blocks locally; unsupported combinations fail closed with `UnsupportedModalityError` or an explicit provider error.
+
+## When to use it
+
+- **Host apps** attaching PDFs, audio clips, or generic files to user messages before a provider turn.
+- **Resource loaders** returning binary payloads for `resourceUri` references under trust/permission policy.
+- **Provider authors** reading truthful `ModelCapabilities.input` tags (`text`, `image`, `audio`, `file`, `document`) before mapping wire formats.
+
+Do not embed provider upload IDs, tenant-scoped remote file IDs, or API-specific handles in core content blocks.
+
+## Inputs / request
+
+```ts
+import {
+  resolveMediaContentBlock,
+  resolveMediaContentBlocks,
+  assertSsrfAllowedUrl,
+  type AudioContent,
+  type FileContent,
+  type DocumentContent,
+} from "@arnilo/prism";
+
+const file: FileContent = {
+  type: "file",
+  mediaType: "application/pdf",
+  name: "report.pdf",
+  data: base64Pdf,
+};
+
+const audio: AudioContent = {
+  type: "audio",
+  mediaType: "audio/wav",
+  resourceUri: "package://demo/sample.wav",
+  durationMs: 12_000,
+};
+
+await resolveMediaContentBlock(file, { bounds: { maxItemBytes: 10_000_000 } });
+```
+
+`ResolveMediaContentOptions` also exposes `ssrf`, `fetch`, `resolveHostname`, `requestUrl`, `loader`, `loadContext`, and `signal`. `MediaHostnameResolver`, `MediaHostAddress`, `MediaUrlRequester`, and `MediaUrlRequest` are exported for typed custom/test transports; ordinary callers need none of them.
+
+Known `ModelCapabilities.input` tags are exported as `MODEL_INPUT_CAPABILITIES`:
+
+| Tag | Block type | First-party mapping (declared capability required) |
+| --- | --- | --- |
+| `text` | `text` (default) | All providers |
+| `image` | `image` | OpenAI Responses, OpenRouter, OpenCode Go Anthropic route, Kimi, NeuralWatt |
+| `audio` | `audio` | OpenAI Responses (`input_audio`) |
+| `file` | `file` | OpenAI Responses (`input_file`); Anthropic routes map PDF only |
+| `document` | `document` | OpenAI Responses (`input_file`); OpenCode Go Anthropic route; Kimi |
+
+## Outputs / response / events
+
+- `resolveMediaContentBlock()` resolves one item and returns `{ mediaType, bytes, name?, durationMs?, transcript?, metadata? }`.
+- `resolveMediaContentBlocks()` is the complete-request path: it rejects item count/inline estimates before I/O, resolves each item within its bound, then enforces exact aggregate decoded bytes.
+- `assertModelSupportsContentBlocks()` / `assertMessagesSupportModelCapabilities()` throw `UnsupportedModalityError` when a declared capability list omits the block modality.
+- `assertMediaBlocksWithinBounds()` enforces per-item bytes, total request bytes, item count, and audio duration ceilings.
+- `assertSsrfAllowedUrl()` rejects loopback, private, link-local, unspecified, multicast, IPv4-mapped private, and metadata literals/hosts unless explicitly allow-listed.
+- Default URL resolution performs one bounded `dns.lookup(..., { all: true })`, rejects the whole hostname if any answer is non-public, then pins the selected public address into `http.request()`/`https.request()` so a second DNS lookup cannot rebind the connection.
+- `sniffMediaMimeType()` / `assertDeclaredMediaTypeMatches()` compare declared MIME types to magic bytes.
+- No events are emitted and no provider calls occur in these helpers.
+
+Default ceilings:
+
+| Constant | Value |
+| --- | --- |
+| `DEFAULT_MAX_MEDIA_ITEM_BYTES` | 10 MB |
+| `DEFAULT_MAX_MEDIA_REQUEST_BYTES` | 32 MiB |
+| `DEFAULT_MAX_AUDIO_DURATION_MS` | 5 minutes |
+| `DEFAULT_MEDIA_FETCH_TIMEOUT_MS` | 30 seconds |
+| `DEFAULT_MAX_MEDIA_ITEMS_PER_REQUEST` | 32 items |
+
+## Request/response example
+
+```json
+{
+  "block": {
+    "type": "file",
+    "mediaType": "application/pdf",
+    "name": "report.pdf",
+    "resourceUri": "package://demo/report.pdf"
+  },
+  "resolved": {
+    "mediaType": "application/pdf",
+    "bytes": "<Uint8Array>",
+    "name": "report.pdf"
+  }
+}
+```
+
+## Implementation example
+
+```ts
+import {
+  assembleProviderInput,
+  loadBinaryResource,
+  resolveMediaContentBlock,
+  UnsupportedModalityError,
+} from "@arnilo/prism";
+
+const loader = {
+  async load(uri) {
+    return { uri, mediaType: "application/pdf", data: pdfBytes };
+  },
+};
+
+const bytes = await loadBinaryResource(loader, "package://demo/report.pdf");
+const resolved = await resolveMediaContentBlock(
+  { type: "document", mediaType: "application/pdf", resourceUri: "package://demo/report.pdf" },
+  { loader },
+);
+
+try {
+  await assembleProviderInput({
+    model: { provider: "demo", model: "text-only", capabilities: { input: ["text"] } },
+    input: [{ role: "user", content: [{ type: "file", mediaType: "application/pdf", data: "..." }] }],
+  });
+} catch (error) {
+  if (error instanceof UnsupportedModalityError) {
+    // Host-visible reject before provider HTTP.
+  }
+}
+```
+
+## Extension and configuration notes
+
+- URL fetches use the DNS-classifying, address-pinned Node transport by default. `resolveHostname` and `requestUrl` are paired test/custom seams; `requestUrl` must connect to the supplied validated address while preserving the original URL hostname for HTTP Host/TLS verification.
+- Supplying `fetch` is a trusted compatibility/custom-transport escape hatch: Prism still checks URL literals and host allow-lists, but the host-provided fetch owns DNS resolution, rebinding protection, redirects, proxies, TLS, auth, and logging.
+- `resourceUri` resolution requires a caller-provided `ResourceLoader` and optional `ResourceLoadContext.permission` check.
+- Local filesystem paths should use trust policies such as `createPathTrustPolicy()` before exposing URIs to loaders.
+- Provider upload/create/delete lifecycles are provider-package-local. `@arnilo/prism-provider-openai` inlines files under 4 MiB as `data:<mediaType>;base64,...` `file_data`, otherwise uses a bounded per-run upload cache and best-effort `DELETE /v1/files` cleanup after each stream.
+- Shared wire helpers live in `@arnilo/prism/providers/media` (`resolveProviderMediaMessages`, `serializeOpenAIResponsesInputFile`, `serializePdfDocumentWireBlock`, `createBoundedUploadCache`). OpenAI Responses, Kimi, and OpenCode Go Anthropic routes resolve their complete media collection once before serialization or upload.
+
+## Security and performance notes
+
+- SSRF deny-by-default blocks IPv4/IPv6 loopback, private/unique-local, link-local, unspecified, multicast, IPv4-mapped private, and cloud metadata targets. DNS answers are all classified before one public address is pinned; mixed public/private answers fail closed.
+- `allowedHostnames` is an explicit trust override and may permit a private destination. `denyPrivateHosts: false` is broader and should be reserved for hosts that intentionally own private-network access.
+- DNS lookup, connection, and body streaming share `fetchTimeoutMs` and caller abort; more than 32 resolved addresses, redirects, and oversized response bodies are rejected.
+- MIME validation rejects common magic-byte spoofing; extensions alone are never trusted.
+- Byte budgets use base64 size estimates before decode and re-check decoded bytes after every read/fetch. Complete-request resolution keeps at most the configured request budget plus one bounded item in memory and performs no provider upload/request until validation succeeds.
+- Media errors omit raw bytes/base64 payloads from messages.
+- Fetch readers are cancelled promptly after bound violations or abort signals.
+
+## Related APIs
+
+- [Input and prompt assembly](input-and-prompt-assembly.md): attachments and `assembleProviderInput()` capability checks.
+- [Resource loading](resource-loading.md): `loadBinaryResource()` and text/JSON helpers.
+- [Model registry](model-registry.md): `ModelCapabilities.input` metadata.
+- [Provider conformance](provider-conformance.md): serialized request coverage for content blocks.
+- [Persistence, credentials, and multimodality primitives](persistence-credentials-multimodality-primitives.md): Plan 056 inventory and threat model.