@arnilo/prism 0.0.4 → 0.0.6

package/docs/server.md

@@ -0,0 +1,139 @@
+# Web-standard server handler
+
+## What it does
+
+`@arnilo/prism-server` exposes explicitly selected agents and workflows through one framework-free `(Request) => Promise<Response>` handler. It supports direct agent results, bounded agent/workflow SSE, durable workflow start/enqueue/status/cancel/resume/replay, ownership-scoped schedules, host authorization, ownership propagation, redaction, and resource ceilings.
+
+No listener starts on import. Empty `agents`/`workflows` maps expose nothing. Authentication, authorization, route selection, durable stores, TLS, rate limiting, and framework/serverless adaptation remain host-owned.
+
+## When to use it
+
+Use it when a Node 20, serverless, worker, or framework host already speaks Web `Request`/`Response` and needs a small Prism API boundary. Wrap it in the platform's native adapter rather than adding Express, Fastify, Hono, Koa, Nest, or Next to Prism.
+
+Use `AgentSession` or workflow APIs directly for in-process applications. Do not treat this package as an auth provider, user database, firewall, durable agent-result store, or public listener.
+
+## Inputs / request
+
+```ts
+const handler = createPrismHandler({
+  agents?: Record<string, Agent | PrismAgentExposure>,
+  workflows?: Record<string, PrismWorkflowExposure>,
+  schedules?: WorkflowSchedules | ((authorization, signal) => WorkflowSchedules),
+  authorize: async ({ request, operation, capabilityId }) => false | {
+    ownership: { tenantId?: string; accountId?: string; userId?: string },
+    metadata?: Record<string, unknown>,
+  },
+  basePath?: "/prism",
+  allowedHosts?: string[],
+  allowedOrigins?: string[],
+  redactor?: SecretRedactor,
+  limits?: PrismServerLimits,
+  disconnectAborts?: boolean,
+});
+```
+
+At least one non-empty ownership field must come from `authorize()`. Request JSON never chooses ownership.
+
+| Method and route | Authorization operation | Body |
+| --- | --- | --- |
+| `POST /prism/agents/:id/runs` | `agent.run` | `{ "input": string | Message | Message[] }` |
+| `POST /prism/agents/:id/stream` | `agent.stream` | same; SSE response |
+| `POST /prism/workflows/:id/runs` | `workflow.run` | `{ "input": unknown, "runId"?: string }` |
+| `POST /prism/workflows/:id/stream` | `workflow.stream` | same; SSE response |
+| `POST /prism/workflows/:id/enqueue` | `workflow.enqueue` | `{ "input": unknown, "runId"?: string }`; returns `202` queued handle |
+| `GET /prism/workflows/:id/runs/:runId` | `workflow.status` | none |
+| `DELETE /prism/workflows/:id/runs/:runId` | `workflow.cancel` | none |
+| `POST /prism/workflows/:id/runs/:runId/resume` | `workflow.resume` | `{ "decision": "approve" | "deny", "input"?: unknown, "expectedVersion": number }` |
+| `POST /prism/workflows/:id/runs/:runId/replay` | `workflow.replay` | `{ "fromNodeId": string, "runId"?: string }` |
+| `POST /prism/schedules/:id` | `schedule.create` | `{ "workflowId", "nextRunAt", "input"?, "intervalMs"?, "calculatorId"?, "paused"?, "metadata"? }` |
+| `GET /prism/schedules?status=&cursor=&limit=` | `schedule.list` | none |
+| `POST /prism/schedules/:id/pause` | `schedule.pause` | `{}` |
+| `POST /prism/schedules/:id/resume` | `schedule.resume` | `{ "nextRunAt"?: string }` |
+| `POST /prism/schedules/:id/trigger` | `schedule.trigger` | `{ "idempotencyKey": string }` |
+| `DELETE /prism/schedules/:id` | `schedule.delete` | none |
+
+POST routes require `Content-Type: application/json`. Capability/run IDs are bounded URL-safe identifiers. A custom `PrismAgentExposure.sessionFactory` can build sessions from authorized host context; otherwise an `Agent` creates a fresh session.
+
+## Outputs / response / events
+
+Direct routes return bounded JSON. Stream routes return `text/event-stream`; every event is one `data: <AgentEvent|WorkflowEvent>` frame. Status returns the ownership-scoped durable checkpoint record. Resume uses Phase 8 expected-version CAS. Cancel aborts active work or marks eligible durable checkpoints aborted.
+
+Errors use `{ "error": { "code", "message" } }`. Unknown routes/capabilities are `404`, authorization/policy denial `403`, malformed input `400`, unsupported content type `415`, body overflow `413`, concurrency overflow `429`, and result overflow `507`. Unexpected errors are generic and never include stacks.
+
+## Request/response example
+
+```json
+{
+  "request": { "method": "POST", "path": "/prism/agents/support/runs", "body": { "input": "Summarize this" } },
+  "response": { "status": "succeeded", "sessionId": "...", "runId": "...", "text": "Summary" }
+}
+```
+
+## Implementation example
+
+```ts
+import { createAgent, createMockProvider, providerDone, providerTextDelta } from "@arnilo/prism";
+import { createPrismHandler } from "@arnilo/prism-server";
+
+const agent = createAgent({
+  model: { provider: "mock", model: "offline" },
+  provider: createMockProvider([providerTextDelta("ready"), providerDone()]),
+});
+
+const handler = createPrismHandler({
+  agents: { support: agent },
+  authorize: async ({ request }) => request.headers.get("authorization") === "Bearer host-validated"
+    ? { ownership: { tenantId: "tenant-1", userId: "user-1" } }
+    : false,
+  allowedHosts: ["api.example.test"],
+  allowedOrigins: ["https://app.example.test"],
+});
+
+// Cloudflare/Bun/Deno-style: export { handler as fetch }.
+// Node/framework hosts adapt their request to Web Request and return Web Response.
+```
+
+## Extension and configuration notes
+
+- `basePath` defaults to `/prism`; URL root exposure is rejected.
+- Agent maps and workflow maps are immutable host selections. No registry/package discovery runs.
+- Workflow exposure requires its existing `WorkflowCheckpointAdapter`; no server-owned database exists.
+- Schedule exposure is optional and may be one service or an authorization-selected resolver. Returned service ownership must exactly match authorized tenant/account/user scope; otherwise request is forbidden.
+- `PrismWorkflowExposure.runOptions` can supply agent/tool/policy/resume-validator wiring. Server-owned ownership, signal, checkpoint, redactor, run ID, and event bus fields cannot be overridden.
+- Host/origin checks and CORS headers activate only when their allow-lists are configured. Hosts still own reverse-proxy trust and canonical host handling.
+
+Default/hard ceilings:
+
+| Limit | Default | Hard cap |
+| --- | ---: | ---: |
+| JSON request | 64 KiB | 1 MiB |
+| direct response | 1 MiB | 8 MiB |
+| SSE event | 64 KiB | 1 MiB |
+| SSE total | 10 MiB | 64 MiB |
+| SSE event count | 10,000 | 100,000 |
+| concurrent runs | 16 | 256 |
+| subscriber queue | 128 | 4,096 |
+| request/run timeout | 120 s | 30 min |
+
+## Security and performance notes
+
+- `authorize()` is required and runs for every matched operation before capability lookup or body execution. Return `false` on missing/invalid credentials. Do not trust caller ownership fields.
+- Use authorization metadata only for non-secret audit context. Never put credentials in metadata, input, route IDs, run IDs, checkpoints, events, or responses.
+- Configure `SecretRedactor` before runs. Redaction matches known secrets; it is not DLP.
+- Agent tools and workflow tool nodes still need their own `PermissionPolicy`, `ToolValidator`, and `ExecutionPolicy`. HTTP authorization does not replace side-effect policy.
+- Host and origin allow-lists are exact string matches. Configure reverse-proxy normalization, TLS, rate limiting, IP policy, CSRF/cookie policy, and authentication outside Prism.
+- SSE uses bounded upstream subscriber queues. Consumer cancellation aborts owned work by default and releases concurrency; set `disconnectAborts: false` only when the host deliberately owns background completion.
+- Source inputs/resource URLs remain host responsibilities and use existing resource/media SSRF policies. Server package does not fetch URLs.
+- Schedule routes never accept ownership from JSON. Services carry mandatory ownership and explicit workflow/calculator registries; route authorization cannot broaden either. Replay applies workflow ownership/hash/approval checks.
+- No agent status/reconnect store is invented. Durable reconnect/status/resume is the workflow path; persistent agent run querying remains a host persistence API.
+
+A2A routes are not added to `createPrismHandler()`. Install `@arnilo/prism-supervisor` and explicitly mount `createA2AHandler()` when protocol interoperability is required; this keeps cards and remote invoke absent from ordinary Prism servers.
+
+## Related APIs
+
+- [Agent/session runtime](agent-session-runtime.md): direct result and event stream semantics.
+- [Workflows](workflows.md): durable checkpoints, status, cancellation, and exact-once resume.
+- [MCP client and server exposure](mcp-tools.md): selected MCP capabilities and web-standard MCP transport.
+- [Host security guide](host-security.md): remote-boundary checklist.
+- [A2A interoperability](a2a.md): separately mounted A2A 1.0 handler/client.
+- [Release and install](release-and-install.md): optional package installation and profiles.

package/docs/settings-auth-trust-security.md

@@ -18,7 +18,7 @@ Use these APIs when a host wants one explicit place to compose settings, resolve
 - Node-only subpaths: `@arnilo/prism/node/settings` for caller-named JSON settings files and `@arnilo/prism/node/trust` for explicit trusted path roots with symlink-aware realpath checks.
 
 ## Outputs / response / events
-Settings and credential helpers return existing `SettingsProvider` and `CredentialResolver` contracts. `AgentConfig.settings` and `AgentConfig.credentials` are host-owned metadata for compatibility; `createAgent()` / `session.run()` do not call `settings.get()` or `credentials.resolve()`. Permission denial blocks tool execution, extension setup, and resource loader calls before side effects. A configured `AgentConfig.redactor` or `RunOptions.redactor` redacts provider requests, emitted `AgentEvent` payloads, stored `SessionEntry` values, and runtime `InstructionContext` input/history seen by instruction injectors.
+Settings and credential helpers return existing `SettingsProvider` and `CredentialResolver` contracts. These seams are host-owned outside `AgentConfig`; `createAgent()` / `session.run()` do not call `settings.get()` or `credentials.resolve()`. Permission denial blocks tool execution, extension setup, and resource loader calls before side effects. A configured `AgentConfig.redactor` or `RunOptions.redactor` redacts provider requests, emitted `AgentEvent` payloads, stored `SessionEntry` values, and runtime `InstructionContext` input/history seen by instruction injectors.
 
 ## Request/response example
 ```ts
@@ -47,17 +47,17 @@ const apiKey = await resolveCredentialValue(credentials, { name: "api", provider
 
 const agent = createAgent({
   model: { provider: "demo", model: "model" },
-  // host-owned metadata; runtime does not read/resolve these fields
-  settings,
-  credentials,
+  // Resolve credentials at the provider edge; register known secrets for redaction.
   redactor: apiKey ? createSecretRedactor([apiKey]) : undefined,
 });
+void settings;
+void credentials;
 void trust;
 void agent;
 ```
 
 ## Extension and configuration notes
-Root imports stay filesystem-free. Node settings files are caller-named and read once; optional missing files are skipped. Trust storage, prompts, approval UI, OAuth token storage, environment-variable selection, and persistent credentials belong in the host or an extension package. For Node.js hosts, [`@arnilo/prism-credentials-node`](credential-storage.md) provides encrypted-file and system-keychain backends. Passing `settings` / `credentials` on `AgentConfig` does not wire hidden runtime reads; hosts pass concrete values or resolvers to the provider/request edge that needs them.
+Root imports stay filesystem-free. Node settings files are caller-named and read once; optional missing files are skipped. Trust storage, prompts, approval UI, OAuth token storage, environment-variable selection, and persistent credentials belong in the host or an extension package. For Node.js hosts, [`@arnilo/prism-credentials-node`](credential-storage.md) provides encrypted-file and system-keychain backends. Pass concrete settings values or credential resolvers to the provider/request edge that needs them; do not place them on `AgentConfig`.
 
 ## Security and performance notes
 Prism does not sandbox host tools or extensions. Prism does not read environment variables, keychains, user config files, package manifests, resources, settings providers, credential resolvers, or project-local extensions unless the host explicitly wires those operations. Redaction is exact known-secret replacement only; it is not secret detection. Permission and trust checks are one operation per guarded call and add no workers, watchers, retries, network, or filesystem scans.

package/docs/sqlite-persistence.md

@@ -37,6 +37,7 @@ import { createSqlitePersistence } from "@arnilo/prism-session-store-sqlite";
 | `filename` | `string` | SQLite database path. Use `:memory:` for ephemeral tests. |
 | `wal` | `boolean` | Enable WAL journal mode. Defaults to `true`. |
 | `busyTimeoutMs` | `number` | SQLite `busy_timeout` in milliseconds. Defaults to `5000`. |
+| `feedbackRedactor` | `SecretRedactor` | Optional redaction for feedback comment/tags/metadata before insert. |
 | `fileMode` | `number` | Unix file mode for newly created database files. Defaults to `0o600`. |
 | `database` | `Database` | Advanced: supply an existing `better-sqlite3` handle (caller owns lifecycle). |
 
@@ -51,11 +52,11 @@ import { createSqlitePersistence } from "@arnilo/prism-session-store-sqlite";
 | `SessionStore.readBranchPath` | Recursive ancestor query from `leafId` (or latest leaf) in root→leaf order. |
 | `RunLedger.append*` | Inserts run/event/tool/usage rows; events receive monotonic per-run `sequence` values. |
 | `ProductionPersistenceStore.query*` | Parameterized cursor pagination on indexed columns. |
-| `checkpoints` | Generic versioned `CheckpointStore` backed by `prism_checkpoints`; ownership, CAS/fencing checks, and bounded pagination. |
+| `checkpoints` | Generic versioned `CheckpointStore` backed by `prism_checkpoints`; ownership, CAS/fencing checks, bounded pagination, and workflow suspended/denied/schedule/state/replay values without a schema migration. |
 | `leases` | Atomic `LeaseStore` backed by `prism_leases`; database-clock expiry, opaque renew/release token, monotonic takeover fence. |
 | `close()` | Closes the underlying database when the adapter opened it. |
 
-Migrations run automatically on open and are idempotent across reopen.
+Migrations run automatically on open and are idempotent across reopen. Under the SQLite migration transaction, startup checks ordered contract name/version/SHA-256 rows plus full schema-v3 PRAGMA/catalog shape (all required tables, columns/types/nullability/defaults, PK/unique/FK keys, and named indexes) before any runtime write. A complete legacy 0.0.5 history with all `checksum` values `NULL` is shape-verified then backfilled transactionally once. Unknown, duplicate, out-of-order, partial-legacy, checksum, or shape drift rejects open; restore or apply reviewed DDL rather than editing migration rows.
 
 ## Request/response example
 
@@ -98,7 +99,7 @@ For resume/timeline flows, use `queryRuns`, `queryEvents`, `queryToolCalls`, and
 - The package is optional and workspace-local; `@arnilo/prism` core has no SQLite dependency.
 - Hosts choose the database path and own backup, retention enforcement, and filesystem permissions.
 - `SessionAppendOptions` idempotency rows are durable in `prism_session_append_idempotency` and survive reopen.
-- Schema version **1** (`001_init`) matches `@arnilo/prism/testing/persistence-schema` — PostgreSQL adapters share the same model with dialect-local DDL.
+- Schema version **3** applies `001_init`, additive `002_usage_scope`, and `003_run_feedback`. Migration 003 adds immutable `prism_run_feedback` rows with run FK/cascade deletion and owner/run/trace cursor indexes. `persistence.feedback` validates exact run ownership, bounds/redacts through optional `feedbackRedactor`, queries bounded pages, and deletes only exact-owned IDs. PostgreSQL shares the same model with dialect-local DDL.
 - Pass an existing `better-sqlite3` `Database` via `database` when your host already manages connections.
 
 ## Security and performance notes
@@ -108,7 +109,7 @@ For resume/timeline flows, use `queryRuns`, `queryEvents`, `queryToolCalls`, and
 - **No path interpolation.** The adapter opens exactly the caller-supplied `filename`; it does not expand environment variables or discover paths.
 - **Redaction upstream.** Event and tool-call payloads may contain secrets; redact before ledger writes. The adapter does not scan or rewrite row contents.
 - **WAL + busy timeout.** WAL is enabled by default; busy timeout defaults to 5 seconds. This meets the Plan 056 local workload target but SQLite still serializes writers — prefer PostgreSQL for high write concurrency.
-- **Indexed operations.** Append, parent validation, idempotency dedup, branch reads, and pagination use the indexes documented in [Database persistence](database-persistence.md); normal paths avoid whole-database scans.
+- **Indexed operations.** Append, parent validation, idempotency dedup, branch reads, and pagination use the indexes documented in [Database persistence](database-persistence.md); normal paths avoid whole-database scans. Startup validation reads SQLite catalog/PRAGMA metadata only, never application rows.
 - **Tenant isolation.** `tenant_id` / `account_id` / `user_id` columns on run and ownership tables participate in query filters; hosts must still scope writes correctly.
 
 ## Related APIs
@@ -118,5 +119,5 @@ For resume/timeline flows, use `queryRuns`, `queryEvents`, `queryToolCalls`, and
 - [Run ledger conformance](run-ledger-conformance.md): `assertRunLedgerConforms` / `runRunLedgerConformance`.
 - [Persistence, credentials, and multimodality primitives](persistence-credentials-multimodality-primitives.md): package matrix and threat model.
 - [Node JSONL session store](node-jsonl-session-store.md): dev-only single-process alternative.
-- [Workflows](workflows.md): adapt `persistence.checkpoints` and pass `persistence.leases` to `createWorkflowCoordinator()` for durable multi-process workflow execution.
+- [Workflows](workflows.md): adapt `persistence.checkpoints` and pass `persistence.leases` to `createWorkflowCoordinator()` and `createWorkflowSchedules()` for durable background execution and schedules.
 - [Migration guide](migration.md): moving from JSONL/in-memory to database-backed persistence.

package/docs/structured-output.md

@@ -234,7 +234,7 @@ Key cross-seam points:
 - The default parser treats assistant text as the value (`{ ok: true, value: text }`); supply a host parser whenever `T` is not `string`.
 - The default repairer builds a user message from `validation.errors[].message`; supply a host repairer for schema-specific guidance.
 - `maxRevisions` (default 3) bounds revision turns; budget exhaustion ends the loop and emits `artifact_failed` (it does not throw).
-- Tools are not dispatched in revision turns. Hosts needing tools in artifact turns use `singleShotLoop` or a custom loop.
+- Tools are inert in artifact turns unless `loop.toolCalls: "bounded"` is explicit. Bounded mode uses run-global `maxToolRounds`, dispatches calls sequentially through normal runtime guards, skips parser/validator for tool-calling responses, and permits at most `1 + maxRevisions + maxToolRounds` provider turns. An extra tool response yields terminal `artifact_failed` with `result.metadata.reason === "tool_round_limit"` and executes nothing.
 
 ## Security and performance notes
 

package/docs/supervisors.md

@@ -0,0 +1,71 @@
+# Supervisor delegation
+
+## What it does
+
+`@arnilo/prism-supervisor` adds optional runtime-selected delegation to an explicit local child allow-list. It returns normal `AgentRunResult` values and does not modify core `createAgent()` or deterministic workflows.
+
+## When to use it
+
+Use a supervisor when a host or agent must choose a child dynamically. Use `@arnilo/prism-workflows` for known DAGs, durable checkpoints, schedules, replay, or human suspension.
+
+## Inputs / request
+
+| API/field | Meaning |
+| --- | --- |
+| `createSupervisor({ ownership, children })` | Creates one ownership-scoped supervisor. |
+| `SupervisorChild.createAgent(context)` | Child-owned factory; receives derived resource/thread IDs, narrowed permission, abort signal, and nested `delegate`. |
+| `delegate({ childId, input, threadId?, limits?, signal? })` | Invokes one allow-listed child. Input is text and byte-bounded. |
+| `hooks.before` | May reject, modify redacted input, or narrow limits/policy. |
+| `hooks.after` | Observes redacted terminal summary; failures cannot alter settled result. |
+| `limits` | Depth 4/16, active children 4/32, input 64 KiB/1 MiB, steps 8/64, tools 32/256, tokens 20k/1m, timeout 60s/30m, event queue 128/4096 default/hard. |
+
+## Outputs / response / events
+
+`delegate()` returns the child's `AgentRunResult` or throws its `AgentRunError`/a supervisor denial or limit error. `subscribe()` emits bounded `delegation_started`, `delegation_finished`, `delegation_rejected`, and `delegation_error` metadata events.
+
+## Request/response example
+
+```json
+{"childId":"research","input":"Check primary sources","limits":{"maxTokens":4000}}
+```
+
+## Implementation example
+
+```ts
+import { createSupervisor } from "@arnilo/prism-supervisor";
+
+const supervisor = createSupervisor({
+  ownership: { tenantId: "tenant", userId: "user" },
+  permission: parentPolicy,
+  children: {
+    research: {
+      permission: readOnlyPolicy,
+      createAgent: ({ resourceId, threadId, permission, delegate }) =>
+        createResearchAgent({ resourceId, threadId, permission, delegate }),
+    },
+  },
+  hooks: { before: ({ input }) => ({ input, limits: { maxTokens: 4000 } }) },
+});
+
+const result = await supervisor.delegate({ childId: "research", input: "Check sources" });
+```
+
+## Extension and configuration notes
+
+Child factories resolve their own providers/credentials and construct context/memory using the supplied IDs. Parent, child, returned-agent, budget, and hook permission policies are AND-composed. Child/request/hook limits can only lower inherited limits. A nested factory can call the supplied `delegate()`; immutable path state rejects cycles and depth overflow.
+
+## Security and performance notes
+
+- Child IDs are explicit; no package/provider discovery occurs.
+- `resourceId` and `threadId` include supervisor/delegation/child identity. Do not replace them with parent memory IDs.
+- Tool budget is checked before side effects. Token usage is enforced on terminal aggregate usage and can exceed by at most one provider turn because providers report tokens after generation.
+- Abort and timeout cover hooks, child creation, nested delegation, and the run. Host child code must cooperate with `AbortSignal`.
+- Redaction applies before hook input, run metadata/results, completion hooks, and events. Child credentials are never supplied in delegation context.
+- Static workflows remain smaller and more reproducible for known graphs.
+
+## Related APIs
+
+- [A2A interoperability](a2a.md): remote protocol boundary.
+- [Workflows](workflows.md): preferred deterministic orchestration.
+- [Working and semantic memory](working-and-semantic-memory.md): child scope construction.
+- [Host security](host-security.md): permission and credential boundaries.

package/docs/thinking-and-reasoning.md

@@ -0,0 +1,98 @@
+# Thinking and reasoning
+
+## What it does
+
+Prism keeps thinking/reasoning **provider-owned on the wire** while giving hosts one portable way to set effort per turn. Model defaults live on `ModelConfig.compat` (and `capabilities.reasoning` where declared). Per-turn overrides live on `ProviderRequestOptions.compat` and win through existing `mergeProviderRequestOptions`. Shared helpers map a portable `ThinkingLevel` into the official compat fields each family already reads — they do **not** invent a second options tree.
+
+## When to use it
+
+- Session runs: pass `providerOptions.compat` (or `applyThinkingLevel`) on `RunOptions`.
+- Use-case workers (LLM compaction, observational memory): pass `thinkingLevel`; packages map it into `compat` via the shared helpers.
+- Provider authors: keep reading official fields from `options.compat` / `model.compat`; add package-local escape hatches only when the official API has unique knobs.
+
+## Contract
+
+| Layer | Surface |
+| --- | --- |
+| Model default | `ModelConfig.compat` (+ `capabilities.reasoning` when the model can reason) |
+| Per-turn override | `ProviderRequestOptions.compat` (request wins over model via merge) |
+| Portable level | `ThinkingLevel`: `none` \| `minimal` \| `low` \| `medium` \| `high` \| `xhigh` \| `max` |
+| Helpers | `thinkingCompatFor`, `applyThinkingLevel`, `thinkingFamilyForModel`, `isThinkingLevel`, `normalizeThinkingLevel`, `THINKING_LEVELS` |
+| Not used | Inert `options.extra.thinkingLevel` — providers do not read `extra` for effort |
+
+```ts
+import { applyThinkingLevel, thinkingCompatFor, thinkingFamilyForModel } from "@arnilo/prism";
+
+// Per-turn override on a session run (OpenAI / OpenRouter family)
+await session.run(input, {
+  providerOptions: applyThinkingLevel(undefined, "low", "openai_reasoning"),
+});
+
+// Equivalent explicit compat
+await session.run(input, {
+  providerOptions: { compat: thinkingCompatFor("openai_reasoning", "low") },
+  // → { reasoning: { effort: "low" } }
+});
+
+// Use-case worker: family from model metadata (or pass an explicit family)
+const family = thinkingFamilyForModel(model);
+await runObserver({
+  ...,
+  providerOptions: applyThinkingLevel(base, "low", family === "noop" ? "reasoning_effort" : family),
+});
+```
+
+## Compat families
+
+Core maps only shapes shared by ≥2 packages (or an explicit no-op). Unique knobs stay package-local.
+
+| Family | Compat patch | Used by (official fields) |
+| --- | --- | --- |
+| `openai_reasoning` | `{ reasoning: { effort } }` | OpenAI Responses `reasoning.effort`; OpenRouter `reasoning.effort` |
+| `reasoning_effort` | `{ reasoning_effort }` | Z.AI `reasoning_effort`; NeuralWatt `reasoning_effort`; Kimi K3 `reasoning_effort` |
+| `thinking_type` | `{ thinking: { type: "enabled" \| "disabled" } }` | Z.AI `thinking.type`; Kimi K2.x `thinking.type` (`none` → `disabled`) |
+| `noop` | `{}` | AI SDK / host-owned adapters — effort is host-model settings |
+
+`applyThinkingLevel` defaults `family` to `reasoning_effort` when omitted. For `openai_reasoning`, an existing `compat.reasoning.summary` (or other reasoning keys) is preserved when merging `effort`.
+
+### Recommended family by first-party package
+
+| Package | Recommended family | Notes |
+| --- | --- | --- |
+| `@arnilo/prism-provider-openai` | `openai_reasoning` | First-class body `reasoning` from model + per-turn compat merge; `summary`/`mode`/`context` via compat |
+| `@arnilo/prism-provider-openrouter` | `openai_reasoning` | First-class `resolveOpenRouterReasoning` merge; prefer `reasoning` object over legacy `reasoning_effort` shorthand; `preserveThinking` replays as body `reasoning` |
+| `@arnilo/prism-provider-zai` | `reasoning_effort` (+ optional `thinking_type`) | Official `thinking` / `reasoning_effort` / `tool_stream` / `clear_thinking`; Preserved Thinking via `reasoning_content` |
+| `@arnilo/prism-provider-neuralwatt` | `reasoning_effort` | Budgets / `preserve_thinking` / `clear_thinking` / `chat_template_kwargs` stay package-local on `compat` |
+| `@arnilo/prism-provider-kimi` | K3: `reasoning_effort`; K2.x: `thinking_type` | K2.7-code thinking is always on; do not send conflicting `thinking` + `reasoning_effort` |
+| `@arnilo/prism-provider-opencode-go` | Anthropic route: thinking blocks (`thinking_type` family); OpenAI route: `reasoning_content` preserve + optional `thinking`/`reasoning_effort`/`reasoning` passthrough | Official dual endpoints; MiniMax/Qwen → Anthropic, others → OpenAI |
+| `@arnilo/prism-provider-ai-sdk` | `noop` | Host `LanguageModelV4` owns reasoning settings |
+
+`thinkingFamilyForModel` infers family from existing `compat` shape, then safe provider heuristics (`openai*` → `openai_reasoning`, `neuralwatt` → `reasoning_effort`), then `capabilities.reasoning` → `reasoning_effort`, else `noop`. Docs and packages may map other provider ids explicitly; core avoids provider-specific literals beyond those heuristics.
+
+## Merge order
+
+1. `ModelConfig.compat` / model defaults inside the provider
+2. `ProviderRequestOptions.compat` from agent / session policies
+3. Per-turn `RunOptions.providerOptions` or use-case `applyThinkingLevel` patch (wins)
+
+Providers already prefer `request.options.compat.*` over `request.model.compat.*`.
+
+## Use-case workers
+
+LLM compaction and observational memory accept `thinkingLevel?: string`. They call `applyThinkingLevel` into `compat` (not `extra.thinkingLevel`). When model inference returns `noop`, an explicit `thinkingLevel` still falls back to `reasoning_effort` so the host setting is never inert. Model selection for those workers (including session-model fallback) is documented in [Use-case model selection](use-case-model-selection.md).
+
+## Non-reasoning models
+
+- Helper with `noop`: returns options unchanged — no invented body fields.
+- Helper with a real family on a model that rejects the field: provider/API error — hosts should gate on `capabilities.reasoning` or package docs.
+- `thinking_type` + `none` sets `{ type: "disabled" }`; other levels set `{ type: "enabled" }` without encoding effort (compose with `reasoning_effort` when the API supports both).
+
+## Related pages
+
+- [Use-case model selection](use-case-model-selection.md) — session vs worker/summary model binding
+- [Provider packages](provider-packages.md) — package boundaries and discovery
+- [Provider caching](provider-caching.md) — cache retention can disable thinking on some providers (e.g. Z.AI when `cacheRetention: "none"`)
+- [Provider request policies](provider-request-policies.md) — `mergeProviderRequestOptions`
+- [Agent/session runtime](agent-session-runtime.md) — prior-reasoning preservation across turns
+- Per-provider pages under [docs/providers](providers/)
+- Evidence matrix: [Review coverage (2026-07-17 provider validation)](review-coverage-2026-07-17-provider-validation.md)

package/docs/tool-execution-primitives.md

@@ -123,8 +123,8 @@ Package performs **no** `PermissionPolicy`, `ToolValidator`, or trust checks of
 | --- | --- |
 | `ToolDefinition.parameters` | Stored and forwarded to providers; **not validated** by core |
 | `ToolValidator` | Host function hook; Phase 25 threads through agent runtime |
-| Standards-based schema validation | **Not shipped** — capability gap C-001 |
-| Schema compile cache | **None** — every dispatch would re-validate if host validator is naive |
+| Standards-based schema validation | Optional `@arnilo/prism-tool-validator-json-schema`; host wires it through `ToolValidator` |
+| Schema compile cache | Adapter-owned finite LRU; core never compiles schemas |
 
 ### MCP mapping (shipped — Task 3)
 
@@ -186,7 +186,7 @@ import { createJsonSchemaToolArgumentValidator } from "@arnilo/prism-tool-valida
 createAgent({ model, validator: createJsonSchemaToolArgumentValidator() });
 ```
 
-**Cache key:** stable `JSON.stringify(schema)` in adapter-owned `Map`. **Bounds:** configurable depth/properties/string/array limits before Ajv validation. **Security:** remote `$ref` rejected; prototype-pollution keys rejected in schemas and instances.
+**Cache key:** stable `JSON.stringify(schema)` in an adapter-owned 256-entry LRU (hard cap 1,024); eviction removes the matching Ajv schema. **Bounds:** schemas default to 256 KiB, depth 64, 10,000 properties/keywords, and 128 refs (hard 1 MiB/128/100,000/1,024); instance depth/properties/string/array limits remain configurable. Every limit rejects non-finite, unsafe, zero/negative, and above-hard values. **Security:** only fragment-local `$ref` is accepted; prototype-pollution keys, cycles, and non-finite schema numbers reject before Ajv compilation.
 
 ### Task 2 — Parallel tool execution — **shipped**
 

package/docs/tools.md

@@ -154,6 +154,10 @@ const agent = createAgent({ model, provider, tools: activeTools, permission, val
 
 Need different tools for one request? Build a short-lived agent/session with a narrower registry, or block extra calls with `PermissionPolicy` / `RunOptions.validate`. No extra per-run tool API exists yet; add one only when host apps need it.
 
+### Artifact-loop tools
+
+`generate-validate-revise` treats provider tools as inert by default. Set `loop.toolCalls: "bounded"` and `RunOptions.maxToolRounds` only when an artifact needs a host-owned lookup before its next candidate. Each response with one-or-more calls consumes one shared round, dispatches calls sequentially through this exact `dispatchToolCall()` path, persists assistant-call then result transcript rows, and skips artifact parsing/validation for that response. A post-limit call executes nothing; the loop emits `artifact_failed` with `metadata.reason: "tool_round_limit"`. Tools do not consume `maxRevisions`, and tool schemas/context never grant authority.
+
 ### Runtime-supplied validators
 
 `AgentConfig.validator?` and `RunOptions.validate?` expose the same `ToolValidator` seam that `DispatchToolCallOptions.validate` already uses. The runtime threads `validate: RunOptions.validate ?? AgentConfig.validator` into every `dispatchToolCall` it issues during the tool loop, so an app can supply argument validation without taking ownership of dispatch itself. `RunOptions.validate` overrides `AgentConfig.validator` on a per-run basis (RunOptions wins). When neither is set, dispatch runs unmodified.
@@ -229,6 +233,17 @@ await session.run(input, {
 - Contribution registration and registry/filter calls do not perform provider calls, credential resolution, resource loading, network, filesystem discovery, or tool execution.
 - Dispatch performs explicit in-memory checks and executes only the selected host-active tool; it adds no retries, queues, timers, or new dependencies.
 
+## JSON Schema validator limits
+
+Core stores `ToolDefinition.parameters` but does not compile schemas. Hosts that install `@arnilo/prism-tool-validator-json-schema` receive pre-Ajv schema limits: 256 KiB bytes, depth 64, 10,000 properties/keywords, 128 refs, and a 256-entry LRU compiled cache by default. All reject invalid values and have finite hard ceilings. Only fragment-local `$ref` values are accepted; non-local refs, cycles, forbidden keys, and non-finite schema numbers fail before tool execution.
+
+```ts
+createJsonSchemaToolArgumentValidator({
+  maxSchemaBytes: 256 * 1024,
+  maxCompiledSchemas: 256,
+});
+```
+
 ## Related APIs
 
 - [Agent/session runtime](agent-session-runtime.md): dispatches complete provider tool calls through the host-active tool harness and returns tool results on the next provider turn.

package/docs/use-case-model-selection.md

@@ -0,0 +1,109 @@
+# Use-case model selection
+
+## What it does
+
+Prism separates the **session chat model** (`AgentConfig.model` / `RunOptions.model`) from **use-case models** used by background or adjacent LLM jobs (observational memory workers, LLM compaction summarizers, declarative agents, supervisor children, evals). Hosts bind `{ model?, provider?, providerOptions?, thinkingLevel? }` per use case. When the use-case omits `model`, resolution falls back to the active session model. Workers never write `model_change` session entries for their own jobs.
+
+## When to use it
+
+- Observational memory should run a cheaper/faster model than the chat session (or inherit the session model when unset).
+- LLM compaction should summarize with an explicit `summaryModel`, falling back to a host-supplied session `model`.
+- Declarative agents, supervisor children, evals, and RPC/CLI runs already own their models — document them as use-case sites that stay separate from a parent session.
+- Memory/RAG `Embedder` selection is related but **not** a chat `ModelConfig` binding.
+
+## Contract
+
+| Layer | Surface |
+| --- | --- |
+| Binding | `UseCaseModelBinding`: `{ model?, provider?, providerOptions?, thinkingLevel?, requireExplicitModel? }` |
+| Resolver | `resolveUseCaseModel({ configured, sessionModel, requireExplicitModel?, … })` → `{ model, source }` or `undefined` |
+| Binding helper | `resolveUseCaseModelBinding(binding, sessionModel)` |
+| Credential id | `useCaseCredentialProviderId(resolved, binding?)` — always the **resolved** `model.provider` |
+| Escape hatch | `requireExplicitModel: true` skips session fallback (OM historical `missing_model`) |
+
+```ts
+import { resolveUseCaseModel, applyThinkingLevel, thinkingFamilyForModel } from "@arnilo/prism";
+
+// Prefer an explicit worker; otherwise inherit the session/agent model.
+const resolved = resolveUseCaseModel({
+  configured: settings.workerModel,       // optional use-case ModelConfig
+  sessionModel: agent.config.model,       // host-supplied; AgentSession does not expose agent
+  thinkingLevel: settings.thinkingLevel,
+});
+if (!resolved) {
+  // skip — neither configured nor session model (or requireExplicitModel)
+}
+
+const family = thinkingFamilyForModel(resolved.model);
+const providerOptions = resolved.thinkingLevel
+  ? applyThinkingLevel(resolved.providerOptions, resolved.thinkingLevel, family === "noop" ? "reasoning_effort" : family)
+  : resolved.providerOptions;
+```
+
+### Precedence
+
+1. `configured` / `binding.model` → `source: "configured"`
+2. Else `sessionModel` when `requireExplicitModel` is not set → `source: "session"`
+3. Else `undefined` (package skips or throws)
+
+Resolution is O(1) and network-free. It does not mutate session history.
+
+## Binding sites
+
+| Site | How hosts bind | Session fallback |
+| --- | --- | --- |
+| Observational memory | `workerModel` / settings `workerModel` + runtime `sessionModel` | Yes — pass `sessionModel: agent.config.model`; `requireExplicitModel` restores skip |
+| LLM compaction | `summaryModel` with `model` as fallback slot | Yes — `resolveUseCaseModel({ configured: summaryModel, sessionModel: model })` |
+| `RunOptions.model` | Per-run override on the **session** | N/A — this *is* the session/run model (writes `model_change`) |
+| Declarative `AgentDefinition` | Definition `model` / registry resolve | Definition-scoped (independent agent) |
+| Supervisor children | Child `createSession` / child `AgentConfig.model` | Independent child session |
+| Evals / workflows / RPC / CLI | Caller `runOptions.model` | Caller-owned |
+| Structured output | Reuses session/run model | Same as run |
+| Memory / RAG | Host `Embedder` | Not a chat model — see [Working and semantic memory](working-and-semantic-memory.md) |
+
+## Observational memory
+
+```ts
+createObservationalMemoryRuntime({
+  session,
+  appendEntry: (entry) => store.append(entry),
+  workerProvider,
+  sessionModel: agent.config.model, // enables fallback when workerModel unset
+  // workerModel: { provider: "neuralwatt", model: "glm-5.2-fast" }, // optional override
+  overrides: { thinkingLevel: "low", observeAfterTokens: 1 },
+});
+```
+
+- Default: no `workerModel` + `sessionModel` set → workers use the session model.
+- Explicit `workerModel` (or settings `workerModel`) always wins.
+- `requireExplicitModel: true` (runtime or settings) → `skipped: "missing_model"` when no worker model, even if `sessionModel` is set.
+- Neither worker nor session model → `skipped: "missing_model"`.
+- Default credential request uses the **resolved** model's `provider` id.
+
+## LLM compaction
+
+```ts
+createLlmCompactionStrategy({
+  provider: summaryProvider,
+  summaryModel: { provider: "example", model: "cheap-summary" }, // optional
+  model: agent.config.model, // session fallback when summaryModel omitted
+  thinkingLevel: "low",
+});
+```
+
+`summaryModel` wins; otherwise `model` is required. Thinking maps into `compat` via `applyThinkingLevel` ([Thinking and reasoning](thinking-and-reasoning.md)).
+
+## Security
+
+- Credential requests for worker calls must target the **resolved** model’s provider — not ambient session credentials for a different provider unless the host wires that explicitly.
+- Pass known secrets into worker/compaction options so prompts, ledger custom entries, and errors stay redacted.
+- Background workers must not append `model_change` entries or otherwise rewrite the chat session’s model timeline.
+
+## Related pages
+
+- [Thinking and reasoning](thinking-and-reasoning.md) — per-turn `thinkingLevel` → `compat`
+- [Observational memory compaction package](compaction-observational-memory.md)
+- [LLM compaction package](compaction-llm.md)
+- [Agent/session runtime](agent-session-runtime.md) — `RunOptions.model` / `model_change`
+- [Working and semantic memory](working-and-semantic-memory.md) — `Embedder` (non-chat)
+- Evidence matrix: [Review coverage (2026-07-17 provider validation)](review-coverage-2026-07-17-provider-validation.md)