@arnilo/prism 0.5.0 → 0.5.2

package/docs/public-contracts.md

@@ -522,4 +522,4 @@ with 0.0.28 (no migration) and the `0.0.17 → 0.1.0` upgrade matrix in
 - `@arnilo/prism/providers/transport`: bounded SSE/event parsing, bounded HTTP error-body reads, and JSON-object tool-argument parsing for provider packages.
 - `@arnilo/prism/providers/openai`: OpenAI Chat Completions message/tool serialization, usage mapping, and indexed message validation helpers.
 
-Phase 10 public helpers include `createStaticSettingsProvider`, `createChainedSettingsProvider`, `createMemoryCredentialStore`, `createChainedCredentialResolver`, `createStaticTrustPolicy`, `assertTrusted`, `createStaticPermissionPolicy`, `assertPermission`, and `createSecretRedactor`. Phase 11 auth/request/prompt helpers include `createExplicitCredentialResolver`, `createEnvCredentialResolver`, `refreshOAuthCredential`, `createProviderRequestPolicyChain`, `createSessionCachePolicy`, `mergeProviderRequestOptions`, `composeSystemPrompt`, and `mergeSystemPromptConfig`; 0.0.16 adds `resolveRedactor(redactor?, secrets?)`, which resolves the active redactor from an explicit redactor plus known secret values (the single survivor of the former per-package copies). They do not read env vars, persist OAuth tokens, create cache stores, discover prompt files, or load packages unless the host supplies that behavior. `@arnilo/prism/testing/provider-conformance` exports network-free provider assertion helpers. Node subpaths `@arnilo/prism/node/settings` and `@arnilo/prism/node/trust` are explicit filesystem/path helpers.
+Phase 10 public helpers include `createStaticSettingsProvider`, `createChainedSettingsProvider`, `createMemoryCredentialStore`, `createChainedCredentialResolver`, `createStaticTrustPolicy`, `assertTrusted`, `createStaticPermissionPolicy`, `assertPermission`, and `createSecretRedactor`. Phase 11 auth/request/prompt helpers include `createExplicitCredentialResolver`, `createEnvCredentialResolver`, `refreshOAuthCredential`, `createProviderRequestPolicyChain`, `createSessionCachePolicy`, `applyDefaultProviderRequestOptions`, `ProviderRequirementError`, `mergeProviderRequestOptions`, `composeSystemPrompt`, and `mergeSystemPromptConfig`; 0.0.16 adds `resolveRedactor(redactor?, secrets?)`, which resolves the active redactor from an explicit redactor plus known secret values (the single survivor of the former per-package copies). They do not read env vars, persist OAuth tokens, create cache stores, discover prompt files, or load packages unless the host supplies that behavior. `@arnilo/prism/testing/provider-conformance` exports network-free provider assertion helpers. Node subpaths `@arnilo/prism/node/settings` and `@arnilo/prism/node/trust` are explicit filesystem/path helpers.

package/docs/release-and-install.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-Prism's current **0.5.x** line has **10 publishable manifests**: the root `@arnilo/prism` core package plus **9 workspace packages** — **19 provider adapters** (19 provider adapter subpaths inside the `@arnilo/prism-providers` family), 3 `prism-*` family/profile packages, and 6 capability packages. (Generated by `node scripts/package-truth.mjs` → `scripts/package-truth.json` — the manifest-derived single source for counts, provider membership, umbrella closures, and profile closures.) The last lockstep cut was 0.3.0; Decision B now publishes changed packages independently inside `^0.3.0` — the plan 039 changed-package cut moved root `@arnilo/prism` and every plan-035+ changed package to **0.3.1**, and the plan 050 changed-package cut moved root plus four changed packages to **0.3.2**; the plan 041-044 changed-package cut moves root to **0.3.3** with `@arnilo/prism-memory@0.3.2` (composite recall scoring), `@arnilo/prism-evals@0.3.1` (trace-to-dataset curation), the three session-store packages at **0.3.1** (run-ledger `promptVersion` provenance), and the initial `@arnilo/prism-prompts@0.0.1` (independent opt-in, outside `prism-all`); plan 054 consolidation then folded `@arnilo/prism-browser` and `@arnilo/prism-obscura` into the `@arnilo/prism-web-tools` family as `/browser` and `/obscura` subpaths, folded `@arnilo/prism-rag`, both compaction strategies, `@arnilo/prism-graft`, and `@arnilo/prism-wiki` into the `@arnilo/prism-memory` family as `/rag`, `/compaction/llm`, `/compaction/observational-memory`, `/graft`, and `/wiki` subpaths (deleting the `@arnilo/prism-compaction` profile), and folded all 17 `@arnilo/prism-provider-*` packages into the `@arnilo/prism-providers` family as `/<adapter>` subpaths (Azure/Bedrock/Vertex stop being special all-only manifests); independent publication continues inside `^0.3.0` ranges (which satisfy 0.3.1, 0.3.2, and 0.3.3). This page describes how they are packed, what each tarball contains, how to install them, the required non-optional **caret** `@arnilo/prism@^0.5.0` peer range, the release workflow, and the offline test budget. The measurable 1.0 readiness gates (command-per-gate) live in [`0.1.0-readiness.md`](./0.1.0-readiness.md).
+Prism's current **0.5.x** line has **10 publishable manifests**: the root `@arnilo/prism` core package plus **9 workspace packages** — **19 provider adapters** (19 provider adapter subpaths inside the `@arnilo/prism-providers` family), 3 `prism-*` family/profile packages, and 6 capability packages. (Generated by `node scripts/package-truth.mjs` → `scripts/package-truth.json` — the manifest-derived single source for counts, provider membership, umbrella closures, and profile closures.) The last lockstep cut was 0.3.0; Decision B now publishes changed packages independently inside `^0.3.0` — the plan 039 changed-package cut moved root `@arnilo/prism` and every plan-035+ changed package to **0.3.1**, and the plan 050 changed-package cut moved root plus four changed packages to **0.3.2**; the plan 041-044 changed-package cut moves root to **0.3.3** with `@arnilo/prism-memory@0.3.2` (composite recall scoring), `@arnilo/prism-evals@0.3.1` (trace-to-dataset curation), the three session-store packages at **0.3.1** (run-ledger `promptVersion` provenance), and the initial `@arnilo/prism-prompts@0.0.1` (independent opt-in, outside `prism-all`); plan 054 consolidation then folded `@arnilo/prism-browser` and `@arnilo/prism-obscura` into the `@arnilo/prism-web-tools` family as `/browser` and `/obscura` subpaths, folded `@arnilo/prism-rag`, both compaction strategies, `@arnilo/prism-graft`, and `@arnilo/prism-wiki` into the `@arnilo/prism-memory` family as `/rag`, `/compaction/llm`, `/compaction/observational-memory`, `/graft`, and `/wiki` subpaths (deleting the `@arnilo/prism-compaction` profile), and folded all 17 `@arnilo/prism-provider-*` packages into the `@arnilo/prism-providers` family as `/<adapter>` subpaths (Azure/Bedrock/Vertex stop being special all-only manifests); independent publication continues inside `^0.3.0` ranges (which satisfy 0.3.1, 0.3.2, and 0.3.3). This page describes how they are packed, what each tarball contains, how to install them, the required non-optional **caret** `@arnilo/prism@^0.5.2` peer range, the release workflow, and the offline test budget. The measurable 1.0 readiness gates (command-per-gate) live in [`0.1.0-readiness.md`](./0.1.0-readiness.md).
 
 Core `@arnilo/prism` ships runtime, CLI, templates, and docs. Every code package has a required `@arnilo/prism` peer inside the Decision B window — the caret current spec is `@arnilo/prism@^0.3.3` and every declared window peer satisfies it: packages republishing in the plan 050 cut carry `^0.3.2`; the plan 039 set keeps `^0.3.1`; unchanged packages keep their `^0.3.0` peer; profiles are pure manifests. The plan 050 republished set declares the required `@arnilo/prism@^0.3.2` peer; the plan 041-044 republished set keeps its existing `^0.3.0` window peer; unchanged packages keep their prior window. Installation activates no provider, listener, database, browser, credential, or tool capability.
 
@@ -11,16 +11,16 @@ Core `@arnilo/prism` ships runtime, CLI, templates, and docs. Every code package
 
 | package | version | notes |
 | --- | --- | --- |
-| `@arnilo/prism` | 0.5.0 | core — runtime, CLI/RPC, templates, docs |
-| `@arnilo/prism-coding-tools` | 0.5.0 | family — /agent, /security, /document-reader, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
-| `@arnilo/prism-core` | 0.5.0 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /work, /validation subpaths |
-| `@arnilo/prism-providers` | 0.5.0 | family — all provider adapters as `/<adapter>` subpaths |
-| `@arnilo/prism-acp-agent` | 0.5.0 | capability — ACP adapter |
-| `@arnilo/prism-ag-ui` | 0.5.0 | capability — AG-UI/A2A/A2UI adapter |
-| `@arnilo/prism-mcp` | 0.5.0 | capability — MCP client/server/OAuth interop |
-| `@arnilo/prism-memory` | 0.5.0 | capability — memory plus /rag, /compaction/*, /graft, /wiki subpaths |
-| `@arnilo/prism-office` | 0.5.0 | capability — /documents, /sheets, /diagrams subpaths |
-| `@arnilo/prism-web-tools` | 0.5.0 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
+| `@arnilo/prism` | 0.5.2 | core — runtime, CLI/RPC, templates, docs |
+| `@arnilo/prism-coding-tools` | 0.5.2 | family — /agent, /security, /document-reader, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
+| `@arnilo/prism-core` | 0.5.2 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /work, /validation subpaths |
+| `@arnilo/prism-providers` | 0.5.2 | family — all provider adapters as `/<adapter>` subpaths |
+| `@arnilo/prism-acp-agent` | 0.5.2 | capability — ACP adapter |
+| `@arnilo/prism-ag-ui` | 0.5.2 | capability — AG-UI/A2A/A2UI adapter |
+| `@arnilo/prism-mcp` | 0.5.2 | capability — MCP client/server/OAuth interop |
+| `@arnilo/prism-memory` | 0.5.2 | capability — memory plus /rag, /compaction/*, /graft, /wiki subpaths |
+| `@arnilo/prism-office` | 0.5.2 | capability — /documents, /sheets, /diagrams subpaths |
+| `@arnilo/prism-web-tools` | 0.5.2 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
 <!-- generated:package-truth:inventory end -->
 
 
@@ -29,26 +29,26 @@ Core `@arnilo/prism` ships runtime, CLI, templates, and docs. Every code package
 
 | adapter package | version |
 | --- | --- |
-| `@arnilo/prism-providers/ai-sdk` | 0.5.0 |
-| `@arnilo/prism-providers/alibaba` | 0.5.0 |
-| `@arnilo/prism-providers/anthropic` | 0.5.0 |
-| `@arnilo/prism-providers/azure` | 0.5.0 |
-| `@arnilo/prism-providers/bedrock` | 0.5.0 |
-| `@arnilo/prism-providers/clinepass` | 0.5.0 |
-| `@arnilo/prism-providers/commandcode` | 0.5.0 |
-| `@arnilo/prism-providers/deepseek` | 0.5.0 |
-| `@arnilo/prism-providers/google` | 0.5.0 |
-| `@arnilo/prism-providers/hyper` | 0.5.0 |
-| `@arnilo/prism-providers/kimi` | 0.5.0 |
-| `@arnilo/prism-providers/model-discovery` | 0.5.0 |
-| `@arnilo/prism-providers/neuralwatt` | 0.5.0 |
-| `@arnilo/prism-providers/ollama` | 0.5.0 |
-| `@arnilo/prism-providers/openai` | 0.5.0 |
-| `@arnilo/prism-providers/opencode-go` | 0.5.0 |
-| `@arnilo/prism-providers/openrouter` | 0.5.0 |
-| `@arnilo/prism-providers/vertex` | 0.5.0 |
-| `@arnilo/prism-providers/xai` | 0.5.0 |
-| `@arnilo/prism-providers/zai` | 0.5.0 |
+| `@arnilo/prism-providers/ai-sdk` | 0.5.2 |
+| `@arnilo/prism-providers/alibaba` | 0.5.2 |
+| `@arnilo/prism-providers/anthropic` | 0.5.2 |
+| `@arnilo/prism-providers/azure` | 0.5.2 |
+| `@arnilo/prism-providers/bedrock` | 0.5.2 |
+| `@arnilo/prism-providers/clinepass` | 0.5.2 |
+| `@arnilo/prism-providers/commandcode` | 0.5.2 |
+| `@arnilo/prism-providers/deepseek` | 0.5.2 |
+| `@arnilo/prism-providers/google` | 0.5.2 |
+| `@arnilo/prism-providers/hyper` | 0.5.2 |
+| `@arnilo/prism-providers/kimi` | 0.5.2 |
+| `@arnilo/prism-providers/model-discovery` | 0.5.2 |
+| `@arnilo/prism-providers/neuralwatt` | 0.5.2 |
+| `@arnilo/prism-providers/ollama` | 0.5.2 |
+| `@arnilo/prism-providers/openai` | 0.5.2 |
+| `@arnilo/prism-providers/opencode-go` | 0.5.2 |
+| `@arnilo/prism-providers/openrouter` | 0.5.2 |
+| `@arnilo/prism-providers/vertex` | 0.5.2 |
+| `@arnilo/prism-providers/xai` | 0.5.2 |
+| `@arnilo/prism-providers/zai` | 0.5.2 |
 <!-- generated:package-truth:providers end -->
 
 
@@ -137,7 +137,7 @@ A packed tarball contains only public compiled output and release files:
 - Code packages ship `README.md`, `LICENSE`, and `CHANGELOG.md`; family/profile packages ship `README.md` and `CHANGELOG.md`.
 - The core tarball additionally ships the full `docs/` directory (the docs hub), `templates/init/`, and the `templates/` gallery (e.g. `deep-research`) used by `prism init`.
 - `dist/cli.js` and the `bin` link in core.
-- **Tarball filenames.** npm strips the `@scope/` prefix, so the core package `@arnilo/prism` produces a tarball named `arnilo-prism-0.5.0.tgz`; family packages produce `arnilo-prism-core-0.5.0.tgz`, `arnilo-prism-coding-tools-0.5.0.tgz`, `arnilo-prism-providers-0.5.0.tgz` (all 19 adapters inside), `arnilo-prism-memory-0.5.0.tgz`, `arnilo-prism-web-tools-0.5.0.tgz`, and `arnilo-prism-office-0.5.0.tgz`; capability packages like `arnilo-prism-mcp-0.5.0.tgz` carry their own package version. Independent-package tags carry their own version. The CLI bin name `prism` is unaffected by the package name (`npx prism` still works; npm allows the bin field to differ from the package name).
+- **Tarball filenames.** npm strips the `@scope/` prefix, so the core package `@arnilo/prism` produces a tarball named `arnilo-prism-0.5.2.tgz`; family packages produce `arnilo-prism-core-0.5.2.tgz`, `arnilo-prism-coding-tools-0.5.2.tgz`, `arnilo-prism-providers-0.5.2.tgz` (all 19 adapters inside), `arnilo-prism-memory-0.5.2.tgz`, `arnilo-prism-web-tools-0.5.2.tgz`, and `arnilo-prism-office-0.5.2.tgz`; capability packages like `arnilo-prism-mcp-0.5.2.tgz` carry their own package version. Independent-package tags carry their own version. The CLI bin name `prism` is unaffected by the package name (`npx prism` still works; npm allows the bin field to differ from the package name).
 
 Excluded from every tarball by `files` negation:
 
@@ -157,9 +157,9 @@ Excluded from every tarball by `files` negation:
   "name": "host-app",
   "type": "module",
   "dependencies": {
-    "@arnilo/prism": "^0.5.0",
-    "@arnilo/prism-core": "^0.5.0",
-    "@arnilo/prism-providers/openai": "^0.5.0"
+    "@arnilo/prism": "^0.5.1",
+    "@arnilo/prism-core": "^0.5.1",
+    "@arnilo/prism-providers/openai": "^0.5.1"
   }
 }
 ```
@@ -169,7 +169,7 @@ Installing the provider/compaction packages without `@arnilo/prism` present prod
 ```text
 npm error code ERESOLVE
 npm error Could not resolve dependency:
-npm error peer @arnilo/prism@"^0.5.0" from @arnilo/prism-providers/openai@0.5.0
+npm error peer @arnilo/prism@"^0.5.1" from @arnilo/prism-providers/openai@0.5.1
 ```
 
 ## Implementation example
@@ -1042,7 +1042,7 @@ Audit fixes, dependency updates, and security patches land only for the supporte
 
 ## Security and performance notes
 
-- **Export-count budget.** `scripts/budget-gate.test.mjs` counts each publishable package's public exports (same name classes as `scripts/dead-exports.mjs`) and fails CI when any exceed the `exportCounts` ceilings in `scripts/budgets.json` (plan 058 post-0.5.0-cut baselines); the failure names the package and the exact delta. Growth requires removing exports or rebaselining with a recorded reason.
+- **Export-count budget.** `scripts/budget-gate.test.mjs` counts each publishable package's public exports (same name classes as `scripts/dead-exports.mjs`) and fails CI when any exceed the `exportCounts` ceilings in `scripts/budgets.json` (plan 066 post-0.5.1-cut baselines); the failure names the package and the exact delta. Growth requires removing exports or rebaselining with a recorded reason.
 - **No secrets or fixtures in tarballs.** Tests, fixtures, `src/`, `plans/`, `.agents/`, `roadmap.md`, and `tsconfig` files are excluded. The `docs avoid real-looking secret examples` docs check and the packaging guard's deny list prevent secret-bearing fixtures from shipping.
 - **Live tests stay opt-in.** The default `npm test` is network-free by construction and never sets these vars. Provider/compaction live gates stay credential-gated and are not set by default or during `sdk:ready`. The PostgreSQL adapter live matrix is the exception that runs in CI via the dedicated `postgres-integration` job (still skipped in the default suite).
   - `PRISM_LIVE_PROVIDER_TESTS=1` — gates the eight provider packages' `src/__tests__/live.test.ts` (`@arnilo/prism-providers/anthropic`, `provider-google`, `provider-openai`, `provider-opencode-go`, `provider-openrouter`, `provider-zai`, `provider-kimi`, `provider-neuralwatt`). Each provider live test also requires its own API key env var and skips safely when it is missing:

package/docs/thinking-and-reasoning.md

@@ -2,12 +2,13 @@
 
 ## What it does
 
-Prism gives hosts one portable way to set thinking/reasoning effort per model and per turn, and guarantees the level actually reaches the wire on every provider Prism ships. The single entry point is **`applyThinkingLevelForModel`**: it resolves the model's compat family, snaps the requested level to the model's **declared levels** (`capabilities.thinkingLevels`), and merges the family's compat patch into your base options. Every first-party provider catalog stamps the family and declares the per-model level set; provider resolvers translate the patch into official wire fields. Model defaults live on `ModelConfig.compat`; per-turn overrides live on `ProviderRequestOptions.compat` and win through the existing `mergeProviderRequestOptions` merge.
+Prism gives hosts one portable way to set thinking/reasoning effort per model and per turn, and guarantees the level actually reaches the wire on every provider Prism ships. **Session entry point:** `AgentConfig.thinkingLevel` / `RunOptions.thinkingLevel` (run overrides agent). The kernel passes that string through **`applyThinkingLevelForModel`**, which resolves the model's compat family, snaps the requested level to the model's **declared levels** (`capabilities.thinkingLevels`), and merges the family's compat patch into already-merged host `providerOptions`. Use `applyThinkingLevelForModel` directly only on custom `provider.generate` sites. Every first-party provider catalog stamps the family and declares the per-model level set; provider resolvers translate the patch into official wire fields. Model defaults live on `ModelConfig.compat`; per-turn overrides live on `ProviderRequestOptions.compat` and win through the existing `mergeProviderRequestOptions` merge. Omitted `thinkingLevel` invents no compat on non-reasoning / `noop` models.
 
 ## When to use it
 
-- Session runs: pass `providerOptions` from `applyThinkingLevelForModel` on `RunOptions` — one call, no per-provider branching.
+- Session runs: `createAgent({ thinkingLevel: "low" })` or `session.run(input, { thinkingLevel: "high" })` — no per-provider branching, no hand-merged `providerOptions.compat`.
 - Use-case workers (LLM compaction, observational memory): pass `thinkingLevel`; workers call `applyThinkingLevelForModel` with the bound model.
+- Custom generate sites: wrap with `applyDefaultProviderRequestOptions(request, { sessionId, thinkingLevel })` or call `applyThinkingLevelForModel` yourself.
 - Hosts building UI: read `model.capabilities.thinkingLevels` (when declared) to render a legal level picker; `isSupportedThinkingLevel` tells you whether a value is declared before sending.
 - Provider authors: read official wire fields from the compat patches below; keep unique knobs package-local.
 
@@ -32,12 +33,15 @@ Returns the merged `ProviderRequestOptions` (a new object when a patch applies;
 ## Implementation example
 
 ```ts
-import { applyThinkingLevelForModel } from "@arnilo/prism";
+import { applyThinkingLevelForModel, createAgent } from "@arnilo/prism";
 
-// Per-turn override on a session run
-await session.run(input, {
-  providerOptions: applyThinkingLevelForModel(base, "high", model),
-});
+const agent = createAgent({ model, provider, thinkingLevel: "low" });
+const session = agent.createSession();
+await session.run(input); // low
+await session.run(input, { thinkingLevel: "high" }); // high this run
+
+// Custom generate sites still use the helper
+const options = applyThinkingLevelForModel(base, "high", model);
 
 // Declared-level-aware UI
 const levels = model.capabilities?.thinkingLevels; // e.g. ["low","medium","high","xhigh","max"]
@@ -47,7 +51,8 @@ const levels = model.capabilities?.thinkingLevels; // e.g. ["low","medium","high
 
 | Layer | Surface |
 | --- | --- |
-| Adapter (use this) | `applyThinkingLevelForModel(base, level, model)` — family resolution + snap + merge in one call |
+| Session (use this) | `AgentConfig.thinkingLevel` / `RunOptions.thinkingLevel` — kernel snaps via `applyThinkingLevelForModel` |
+| Adapter (custom generate) | `applyThinkingLevelForModel(base, level, model)` — family resolution + snap + merge in one call |
 | Model default | `ModelConfig.compat` (+ `capabilities.reasoning`, `capabilities.thinkingLevels` when declared) |
 | Per-turn override | `ProviderRequestOptions.compat` (request wins over model via merge) |
 | Portable level | `ThinkingLevel`: `none` \| `minimal` \| `low` \| `medium` \| `high` \| `xhigh` \| `max` |

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

@@ -2,7 +2,7 @@
 
 ## 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.
+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. Observational-memory workers stamp derived `om:{session.id}`; LLM compaction reuses the agent `sessionId` so summarization can hit the same prompt cache.
 
 ## When to use it
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Agent harness for AI providers, agents, sessions, and tools.",
   "type": "module",
   "main": "./dist/index.js",