@arnilo/prism 0.0.2 → 0.0.4

package/docs/index.md

@@ -3,16 +3,17 @@
 Prism is a TypeScript/Node.js agent harness. Host apps and extension packages own providers, tools, resources, credentials, storage, UI, and business behavior. Prism supplies contracts, registries, streaming events, and replaceable runtime primitives.
 
 ## Public contracts
-- [Public contracts](public-contracts.md): type shapes for messages, content, agents, sessions, providers, tools, context, skills, extensions, stores, resources, settings, credentials, and events.
+- [Public contracts](public-contracts.md): type shapes for messages, agents, tools, stores, generic `CheckpointStore`, atomic `LeaseStore`, bounded `EventMultiplexer`, resources, credentials, and events.
 
 ## Agent/session runtime
 - [Agent/session runtime](agent-session-runtime.md): create agents and sessions, run prompts, subscribe to normalized events, and see which `AgentConfig` fields are runtime-consumed vs host-owned metadata. Covers tool-call loop transcript shape and prior-reasoning preservation across turns.
 - [Agent definitions](agent-definitions.md): resolve declarative `AgentDefinition` values via `resolveAgentDefinition`, and turn app-config `<configRoot>/agents/<name>/AGENT.md` bundles into runnable agents via `discoverAgentBundles` / `resolveAgentBundle` (explicit tool/skill activation by name, fail-closed omitted capabilities, migration-only `activateAllCapabilities`, strict duplicate scope checks, configurable prompt layers, no auto-discovery).
 - [Agent loops](agent-loops.md): replaceable per-run control loops — `singleShotLoop` default and `generate-validate-revise` with host-supplied `validator`/`parser`/`repairer` callbacks.
-- [Agent events](agent-events.md): the `AgentEvent` stream — agent/turn/message (including live `tool_call_delta` fragments), tool execution, queue/subscriber overflow, compaction/retry, artifact validation/refinement, and error variants, redacted via `redactAgentEvent`.
+- [Agent events](agent-events.md): the `AgentEvent` stream — agent/turn/message (including live `tool_call_delta` fragments), provider turn timing, tool execution, queue/subscriber overflow, compaction/retry, artifact validation/refinement, and error variants, redacted via `redactAgentEvent`.
+- [Observability](observability.md): metadata-only `provider_turn_*` events, `ToolExecutionMetadata`, core helpers, and optional `@arnilo/prism-observability-opentelemetry` adapter.
 - [Runs and usage ledger](runs-and-usage.md): `RunLedger` adapter for durable run, event, tool-call, usage persistence, cache diagnostics, ownership/idempotency, and redaction guidance.
 - [Performance limits](performance.md): bounded live subscriber queues, branch-read pagination expectations, JSONL/dev-store limits, and production sizing assumptions.
-- [Structured output](structured-output.md): the `Artifact*` seam (parser/validator/repairer, host-defined `T`) — the only typed-output path from a loop, with a Synapta-style schema→`ArtifactValidation` mapping example and an end-to-end third-party integration walkthrough.
+- [Structured output](structured-output.md): the `Artifact*` seam plus provider-native `StructuredOutputOptions` / `structuredOutputMode` for capable models.
 
 ## Compaction/session memory
 - [Compaction and retry policies](compaction-and-retry.md): summarize branch history and retry transient provider failures with host-replaceable policies.
@@ -20,11 +21,15 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 - [Observational memory compaction package](compaction-observational-memory.md): optional source-backed memory, owned runtime append callback, provider-valid worker transcripts, fast compaction, recall tool, and status/view command package.
 - [Session stores](session-stores.md): `SessionStore` contract, `SessionAppendOptions`, `SessionAppendConflictError`, branch handles, `readBranchPath`, and dev-vs-production branch reads — start here for session persistence.
 - [Session stores and branching](session-stores-and-branching.md): detailed branch semantics and helper reference (kept for compatibility; links back to the canonical atomic append / branch-handle sections).
-- [Database persistence](database-persistence.md): production persistence contracts, conditional append transaction pattern, idempotency indexes, `readBranchPath`, reference relational schema, retention, migrations, and NoSQL mapping.
-- [Migration guide](migration.md): the two cross-cutting app migrations in one place — in-memory/JSONL → database-backed `ProductionPersistenceStore` persistence (+ `RunLedger`) and permissive capability defaults → Phase 38 explicit `tools`/`skills` activation, with before/after shapes and links to the detailed pages.
+- [Database persistence](database-persistence.md): production persistence contracts, shared schema/migration primitives (`@arnilo/prism/testing/persistence-schema`), conditional append transaction pattern, idempotency indexes, `readBranchPath`, reference relational schema, retention, migrations, and NoSQL mapping.
+- [SQLite persistence](sqlite-persistence.md): optional `@arnilo/prism-session-store-sqlite` adapter — `SessionStore`, `RunLedger`, `ProductionPersistenceStore`, and generic durable checkpoints and atomic leases over `better-sqlite3`.
+- [PostgreSQL persistence](postgres-persistence.md): optional pooled adapter — session/run/query persistence plus generic durable checkpoints and atomic leases over `pg`, with advisory-lock migrations and opt-in live conformance.
+- [Migration guide](migration.md): 0.0.3 compatibility and optional 0.0.4 adoption — first-party/custom database persistence plus explicit fail-closed tool/skill activation.
 - [Node JSONL session store](node-jsonl-session-store.md): development-only JSONL file adapter for single-process Node hosts; no cross-process safety.
+- [Persistence, credentials, and multimodality primitives](persistence-credentials-multimodality-primitives.md): Plan 056 inventory — session/run-ledger/persistence contracts, credential/OAuth seams, content/resource/model capabilities, package dependency matrix, conformance matrix, and threat model for production adapters.
 
 ## Provider and model connection
+- [Provider primitives](provider-primitives.md): shared bounded transport and OpenAI serialization helpers — migrated across first-party providers; native structured-output and observability contracts.
 - [Provider layer](provider-layer.md): register and resolve host-owned providers/models, choose replace-or-error duplicate policy, create provider events, stream/reconstruct tool-call deltas, use generic provider request options, and test with the mock provider; deprecated provider-level timeout/retry hints point to runtime abort/retry.
 - [Model registry](model-registry.md): register and resolve `ModelConfig` records with capabilities, limits, cost, cache support metadata, compat data, and duplicate policy.
 - [Provider caching](provider-caching.md): use `PromptCacheHints`, `PromptCacheBreakpoint`, `ModelCacheCapabilities`, cache-aware stable-prefix guidance, and shared cache diagnostics helpers; includes a per-provider explicit/implicit cache matrix for OpenAI, OpenRouter, OpenCode Go, Z.AI, Kimi, and NeuralWatt; cache hints are best-effort and cache keys are never secrets.
@@ -35,16 +40,22 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 
 ## Input, prompt, and context assembly
 - [SDK customization guide](customization.md): map provider resolution, middleware, context, builders, injectors, loops, compaction, retry, stores, and skills to explicit host-wired APIs.
-- [Input and prompt assembly](input-and-prompt-assembly.md): render tiny prompt templates and turn common host input, history, attachments, explicit resources, summaries, and tool results into messages with replaceable builders, provider-input assembly, legacy default order, and opt-in cache-aware ordering.
+- [Input and prompt assembly](input-and-prompt-assembly.md): render tiny prompt templates and turn common host input, history, attachments, explicit resources, summaries, and tool results into messages with replaceable builders, provider-input assembly, legacy default order, and opt-in cache-aware ordering. Audio/file/document `ContentBlock` types and capability checks are documented there.
+- [Multimodal content](multimodal-content.md): bounded `audio`, `file`, and `document` content blocks, media resolution helpers, SSRF/MIME policy, and `ModelCapabilities.input` tags.
 - [System prompts](system-prompts.md): compose explicit user/package/app/run system prompt layers, auto-load the standard `AGENTS.md` (workspace) / `SYSTEM.md` prompt files via the Node `loadSystemPromptFiles` loader (trust-gated for `AGENTS.md`), and append `SYSTEM.md` → per-agent `AGENT.md` body → repo `AGENTS.md` layers from a discovered agent bundle via `resolveAgentBundle`.
 - [Instruction injection](instruction-injection.md): register package injectors that layer redacted instructions/context blocks without granting tools, permissions, or resource escapes.
 - [Context and skills](context-and-skills.md): resolve ordered context providers and keep context/skill selection host-owned; omitted declarative skills stay inactive by default, `toolNames` fail closed before provider turns, and strict skill registries prevent silent shadowing.
 
 ## Tools
 - [Tools](tools.md): register host-owned active tools with replace-or-error duplicate policy, apply exact allow/deny filtering, and dispatch tool calls.
+- [Tool execution primitives](tool-execution-primitives.md): JSON Schema validation, exclusive-aware bounded parallel dispatch, MCP bridge mapping, coding execution policy, and image-read bounds.
+- [Tool validator JSON Schema package](../packages/tool-validator-json-schema/README.md): optional `@arnilo/prism-tool-validator-json-schema` adapter for `tool.parameters`.
+- [MCP client bridge](mcp-tools.md): optional `@arnilo/prism-mcp` package mapping remote MCP tools to `ToolDefinition`s.
+- [Coding agent tools](coding-agent-tools.md): optional first-party package `@arnilo/prism-coding-agent` providing `shell`, `read`, `write`, and `edit` tools (ported from pi) as `ToolDefinition`s a host registers; pluggable operation backends, per-path mutation serialization, optional `ExecutionPolicy`, bounded image reads (`maxImageBytes`, `transformImage`), and read-only/coding aggregators. Host shell/filesystem access — gate with permission/trust policies and `@arnilo/prism-coding-security` approval.
+- [Coding execution approval and sandboxing](coding-security.md): optional `@arnilo/prism-coding-security` package for path roots, command rules, approval caching, shell-turn exclusivity, and pluggable sandbox adapters for coding tools.
 
 ## Extensions/plugins
-- [Contribution discovery (workspace)](contribution-discovery.md): opt-in, realpath-contained directory scanner turning `SKILL.md`/`manifest.json` into inert `DiscoveredContribution` envelopes the host registers — no `import()`, no auto-activate, no provider scanning. (Per-agent `AGENT.md` bundles live under an app-controlled `configRoot`; see [Agent definitions](agent-definitions.md).)
+- [Contribution discovery (workspace)](contribution-discovery.md): opt-in, realpath-contained directory scanner turning `SKILL.md`/`manifest.json` into inert `DiscoveredContribution` envelopes the host registers — no `import()`, no auto-activate, no provider scanning. Per-agent bundles remain app-controlled and are documented under Agent/session runtime.
 - [Contribution registries](contribution-registries.md): explicit host-owned registries for extension/package contributions without hidden globals, with `duplicate: "error"` strict mode for provider/model/tool/skill shadowing prevention.
 - [Extension kernel and event bus](extensions.md): load host-provided extensions in order, register contributions, emit lifecycle events, and isolate extension errors.
 - [Extension authoring guide](extension-authoring.md): publish third-party extension packages that register inert contributions and show host-owned activation, trust, permissions, redaction, and no-sandbox boundaries.
@@ -53,25 +64,31 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 ## Configuration/manifests
 - [Configuration and manifests](configuration-and-manifests.md): merge in-memory JSON config layers and validate data-only package manifests with prototype-pollution key rejection.
 - [Node filesystem config loader](node-filesystem-config.md): explicitly read caller-named JSON config files in Node hosts.
-- [Resource loading](resource-loading.md): decode text, JSON, and manifest resources through caller-provided loaders.
+- [Resource loading](resource-loading.md): decode text, JSON, binary, and manifest resources through caller-provided loaders with bounded byte limits.
 
 ## CLI/RPC
 - [CLI/RPC](cli-rpc.md): Run print/json modes and LF-delimited RPC over the public AgentSession runtime, including branch-handle results, fixed `forkSession`, and `checkout`.
+- [Workflows](workflows.md): optional `@arnilo/prism-workflows` typed bounded DAG orchestration — local execution plus SQLite/PostgreSQL multi-process coordination with enqueue, leases, heartbeats, fencing, durable cancel/resume, events, and optional RPC bindings. Interactive TUI (C-012) deferred.
+- [Workflow orchestration primitives](workflow-orchestration-primitives.md): architecture inventory — workflow adapters consume core `CheckpointStore`, `LeaseStore`, and bounded `EventMultiplexer`; run control and optional RPC commands stay package-local.
+- [Workflow/TUI scope](workflow-tui-primitives.md): records why 0.0.4 ships workflow APIs/RPC control but no interactive terminal UI.
 
 ## Security and credentials
 - [Host security guide](host-security.md): fail-closed checklist for credentials, settings, redaction, trust roots, permission policies, persistence, extension loading, and tool validation.
 - [Security/auth/trust](settings-auth-trust-security.md): settings providers, credential helpers, trust/permission policies, redaction controls, host-owned `AgentConfig.settings`/`credentials`, and security-boundary hardening summary.
 - [Credentials and redaction](credentials-and-redaction.md): compose explicit credential resolver order, use caller-supplied env objects/OAuth refresh helpers, avoid eager `AgentConfig.credentials` resolution, and redact known secret values.
+- [Credential storage](credential-storage.md): optional `@arnilo/prism-credentials-node` encrypted-file and system-keychain adapters for durable host-owned credentials.
 
 ## Testing and examples
-- [Provider layer](provider-layer.md): use `createMockProvider()` and provider event helpers for deterministic tests without timers, credentials, or network.
+- Provider test doubles: `createMockProvider()` and provider event helpers are documented on the canonical Provider layer page above.
 - [Provider conformance](provider-conformance.md): run network-free provider adapter assertions (stream order, abort, tool-call reconstruction, cache usage, content coverage, protected header ownership, secret leak) from `@arnilo/prism/testing/provider-conformance`.
 - [Session store conformance](session-store-conformance.md): assert any `SessionStore` adapter satisfies append/idempotency/conflict/branch invariants from `@arnilo/prism/testing/session-store-conformance`.
+- [Run ledger conformance](run-ledger-conformance.md): assert any `RunLedger` adapter satisfies durable run/event/tool/usage writes and reopen survival from `@arnilo/prism/testing/run-ledger-conformance`.
 - [Compaction conformance](compaction-conformance.md): assert any `CompactionStrategy` returns a non-empty redacted summary and observes abort from `@arnilo/prism/testing/compaction-conformance`.
 - [Tool conformance](tool-conformance.md): assert the tool-dispatch blocked-reason matrix (unknown/denied/invalid/permission/validator) and success path from `@arnilo/prism/testing/tool-conformance`.
 - [Extension conformance](extension-conformance.md): assert an `Extension` setup runs, contributions stay inert, and setup errors are redacted or rethrown from `@arnilo/prism/testing/extension-conformance`.
-- `examples/`: compile-checked typed examples and runnable mock demos (SDK basics, provider registration, auth, tools, cache-aware prompt assembly, NeuralWatt agent run, stores/branching, compaction, observational-memory recall, structured-output/artifact-loop, CLI, RPC).
+- `examples/`: compile-checked typed examples and runnable mock demos (SDK basics, provider registration, auth, tools, cache-aware prompt assembly, NeuralWatt agent run, stores/branching, compaction, observational-memory recall, structured-output/artifact-loop, CLI, RPC, workflow orchestration).
 
 ## Release and install
-- [Release and install](release-and-install.md): package layout, install specifiers, required `@arnilo/prism` peer, tarball contents and exclusions, the map-retention knob, the release workflow, and the offline test budget.
+- [Release and install](release-and-install.md): 24-package graph and profiles, install/tarball rules, deterministic resumable provenance publication, and offline test budget.
+- [Review coverage (2026-07-14)](review-coverage-2026-07-14.md): traceability matrix linking review findings and bug-report fixes to plan tasks, tests, and documentation for release 0.0.4.
 

package/docs/input-and-prompt-assembly.md

@@ -60,7 +60,7 @@ Useful exported types:
 - `DefaultInputBuilder`: the default `InputBuilder` with typed default context.
 - `InputAssemblyLayout`: `"legacy" | "cache_aware"`; legacy is default.
 - `DefaultInputBuildContext`: optional input layout, instructions, history, summaries, attachments, resource loader/URIs, tool results, middleware, ids, metadata, and abort signal.
-- `InputAttachment`: already-loaded text/content or an explicit URI loaded through a caller-provided `ResourceLoader`.
+- `InputAttachment`: already-loaded text/content blocks (including `audio`, `file`, and `document`) or an explicit URI loaded through a caller-provided `ResourceLoader`.
 - `PromptInstruction`: labeled system instruction text.
 - `DefaultPromptBuilder`: the default `PromptBuilder`.
 - `AssembleProviderInputOptions`: model, input, optional builders, context providers, selected skills, active tools, generic provider options, metadata, and signal.
@@ -82,10 +82,10 @@ The builder returns `readonly Message[]`.
 The default prompt builder still prepends context, selected skills, and tool declarations before those input messages. Cache-aware ordering gives cache-capable providers a stable prefix only while those stable inputs stay byte-stable; changing tools, context, resources, summaries, history, or attachments changes the prefix too.
 - History is prepended before current input.
 - Instructions and summaries are system messages; compacted branch summaries from `rebuildSessionContext()` use the same path.
-- Text attachments and explicit text resources are user messages.
+- Text attachments and explicit text resources are user messages; inline `audio`/`file`/`document` blocks pass through unchanged on attachments with `content`.
 - Tool results are tool messages containing `tool_result` content; the agent/session runtime uses this to feed dispatched tool results into the next provider turn, placing the assistant `tool_call` and the matching role `tool` `tool_result` before any final assistant content. Cache-aware layout keeps tool results before the current user suffix so it does not split tool transcripts.
 - Middleware runs only when `middleware` is supplied in the context.
-- `assembleProviderInput()` returns a `ProviderRequest` with the caller's model/tools/provider options/metadata/signal and composed messages/context.
+- `assembleProviderInput()` returns a `ProviderRequest` with the caller's model/tools/provider options/metadata/signal and composed messages/context. It also calls `assertMessagesSupportModelCapabilities()` so unsupported `audio`/`file`/`document`/`image` blocks fail with `UnsupportedModalityError` when the model declares `capabilities.input`.
 - `renderPromptTemplate()` replaces top-level `{{name}}` variables with caller-supplied JSON-compatible values. Strings are inserted directly; numbers, booleans, `null`, arrays, and objects are stringified deterministically with sorted object keys. Missing variables throw by default or stay unchanged with `{ missing: "preserve" }`.
 
 ## Request/response example
@@ -165,7 +165,7 @@ const request = await assembleProviderInput({
 - The builder is linear in supplied messages, attachments, resources, and tool results. Layout selection is one flattening branch over already-built groups.
 - Template expansion is dependency-free string replacement over `{{name}}` variables. It does not evaluate expressions, filters, loops, partials, JavaScript, globals, or prototype properties.
 - It performs no provider calls, tool execution, credential resolution, package discovery, filesystem scan, network access, timers, or watchers.
-- URI attachments/resources load only through the caller-provided `ResourceLoader`.
+- URI attachments/resources load only through the caller-provided `ResourceLoader`. Binary media uses `resolveMediaContentBlock()` / `loadBinaryResource()` with bounded bytes, SSRF checks for URLs, and MIME magic validation — see [Multimodal content](multimodal-content.md).
 - Do not place secrets in templates, variables, instructions, messages, attachments, tool results, metadata, middleware payloads, or docs examples.
 - Active tools are passed through from the host; prompt middleware cannot grant additional provider tools.
 - Skill selection is handled by the host/skill registry path; this builder only includes selected skills passed by the caller.
@@ -175,7 +175,8 @@ const request = await assembleProviderInput({
 - [SDK customization guide](customization.md): high-level map of replaceable provider resolution, middleware, context, builder, injector, loop, compaction, retry, store, and skill seams.
 - [Public contracts](public-contracts.md): `Message`, `ContentBlock`, `InputBuilder`, `InputBuildContext`, `ToolResult`, and `ResourceLoader` shapes.
 - [Context and skills](context-and-skills.md): ordered context resolution feeding prompt composition.
-- [Resource loading](resource-loading.md): `loadTextResource()` behavior used for explicit URI resources.
+- [Multimodal content](multimodal-content.md): `audio`/`file`/`document` blocks, bounded media resolution, and capability checks.
+- [Resource loading](resource-loading.md): `loadTextResource()` and `loadBinaryResource()` behavior used for explicit URI resources.
 - [Middleware hooks](middleware-hooks.md): ordered middleware registry and `input_assembly`, `context`, and `prompt_build` hooks.
 - [System prompts](system-prompts.md): compose layered package/app/user/run prompts before input assembly.
 - [Contribution registries](contribution-registries.md): inert input, prompt, context, and skill contributions.

package/docs/mcp-tools.md

@@ -0,0 +1,139 @@
+# MCP client bridge
+
+## What it does
+
+`@arnilo/prism-mcp` connects Prism hosts to remote [Model Context Protocol](https://modelcontextprotocol.io) servers and maps discovered tools to ordinary `ToolDefinition`s. Transports are stdio subprocesses and Streamable HTTP. The package wraps the official MCP TypeScript SDK (`@modelcontextprotocol/sdk` v1.29+) and does **not** add MCP-specific branches 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)`.
+
+## 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.
+
+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.
+
+## 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.
+
+## 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 | `PermissionPolicy` on `tool:mcp:<serverId>:<name>:execute` (or broader deny rules) |
+
+MCP output is untrusted. Apply `SecretRedactor` and host logging policy to `ToolResult` before persisting or displaying.
+
+## 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
+- 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,12 @@
 
 ## 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.4 is source-compatible with documented 0.0.3 agent construction; no mandatory code migration is required. New capabilities are additive and inactive until configured. This page covers two optional adoption paths:
 
-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. **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 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.
+It states before/after shapes and links detailed schema, redaction, branch, capability, and security guidance.
 
 ## When to use it
 
@@ -15,7 +15,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.4 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 +26,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 +79,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
@@ -174,7 +165,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`, 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 +181,9 @@ 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.
+- [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,148 @@
+# 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,
+  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 } });
+```
+
+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()` returns `{ mediaType, bytes, name?, durationMs?, transcript?, metadata? }`.
+- `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 private/link-local/metadata hosts unless explicitly allow-listed.
+- `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 injectable `fetch` for tests and custom transports; production hosts should supply TLS, auth, and logging policy outside Prism core.
+- `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` (`serializeOpenAIResponsesInputFile`, `serializePdfDocumentWireBlock`, `createBoundedUploadCache`).
+
+## Security and performance notes
+
+- SSRF deny-by-default blocks loopback, RFC1918, link-local, and cloud metadata hostnames unless `SsrfPolicy.allowedHostnames` is set.
+- MIME validation rejects common magic-byte spoofing; extensions alone are never trusted.
+- Byte budgets use base64 size estimates before decode and re-check decoded `buffer.length` after read/fetch.
+- 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.