@arnilo/prism 0.4.0 → 0.5.0

package/dist/thinking.d.ts

@@ -9,8 +9,16 @@ export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
  * Compat mapping families used by ≥2 packages, or explicit no-op for host-owned adapters.
  * Provider packages keep unique escape hatches (budgets, keep/all, tool_stream) local.
  */
-export type ThinkingCompatFamily = "openai_reasoning" | "reasoning_effort" | "thinking_type" | "noop";
+export type ThinkingCompatFamily = "openai_reasoning" | "reasoning_effort" | "thinking_type" | "google" | "output_config_effort" | "noop";
 export declare function isThinkingLevel(value: unknown): value is ThinkingLevel;
+/**
+ * Parse a host thinking-level value without guessing: known levels canonicalize to
+ * `ThinkingLevel`, unknown non-empty strings pass through as opaque `{ opaque }`
+ * (forward-compat passthrough), invalid/empty/non-string input fails closed.
+ */
+export declare function parseThinkingLevel(value: unknown): ThinkingLevel | {
+    readonly opaque: string;
+} | undefined;
 /**
  * Normalize a host thinkingLevel string. Known levels are lowercased; other non-empty
  * strings pass through as opaque effort values for forward-compatible provider fields.
@@ -26,17 +34,48 @@ export declare function thinkingCompatFor(family: ThinkingCompatFamily, level: T
  * Per-turn patches win over prior compat via {@link mergeProviderRequestOptions}.
  */
 export declare function applyThinkingLevel(options: ProviderRequestOptions | undefined, level: ThinkingLevel | string, family?: ThinkingCompatFamily): ProviderRequestOptions;
+/**
+ * Declared portable thinking levels for a model, if any (ascending ladder order).
+ * `undefined` means the provider declares no subset — forward-compat passthrough.
+ */
+export declare function thinkingLevelsForModel(model: Pick<ModelConfig, "provider" | "compat" | "capabilities">): readonly string[] | undefined;
+/**
+ * Strict declared-set membership (hosts fail closed on unknown levels).
+ * A model that declares no levels supports any value (forward-compat passthrough).
+ */
+export declare function isSupportedThinkingLevel(model: Pick<ModelConfig, "provider" | "compat" | "capabilities">, level: unknown): boolean;
+/**
+ * Snap a portable level to a model's declared set (design record §2):
+ * in-set → unchanged; below the declared minimum → up to the minimum
+ * (never silently disable what cannot be disabled); otherwise nearest declared
+ * level by ladder distance with ties breaking up; undeclared levels and
+ * undeclared sets pass through. Provider-documented snap tables
+ * (deepseek, Z.AI GLM-5.2, clinepass slots) override this generic fallback
+ * inside their own resolvers.
+ */
+export declare function snapThinkingLevel(model: Pick<ModelConfig, "provider" | "compat" | "capabilities">, level: ThinkingLevel | string): ThinkingLevel | string;
+/**
+ * Model-aware thinking-level application (design record §5). Resolves the family
+ * stamp-first (`compat.thinkingFamily` → inference → `capabilities.reasoning`),
+ * snaps the level to the model's declared set, and merges the compat patch
+ * per-turn-wins. Returns options unchanged for non-reasoning models — never
+ * invents a field where the model declares no thinking support.
+ */
+export declare function applyThinkingLevelForModel(options: ProviderRequestOptions | undefined, level: ThinkingLevel | string, model: Pick<ModelConfig, "provider" | "compat" | "capabilities">): ProviderRequestOptions;
 /**
  * Best-effort family inference from model metadata without a second options tree.
- * Prefer an explicit family in hosts/use-case workers when the provider is known.
+ * Prefer an explicit `compat.thinkingFamily` stamp in host/use-case workers when
+ * the provider is known; inference is the fallback (stamp-first).
  *
  * Heuristics (ordered):
- * 1. Existing `compat.thinking` object → `thinking_type`
- * 2. Existing `compat.reasoning` → `openai_reasoning`
- * 3. Existing `compat.reasoning_effort` → `reasoning_effort`
- * 4. Provider id starting with `openai` → `openai_reasoning`
- * 5. Provider id `neuralwatt` → `reasoning_effort`
- * 6. `capabilities.reasoning` → `reasoning_effort` (portable string field)
- * 7. Else `noop`
+ * 1. `compat.thinkingFamily` stamp → itself
+ * 2. Existing `compat.thinking` object → `thinking_type`
+ * 3. Existing `compat.thinkingConfig` object/boolean → `google`
+ * 4. Existing `compat.reasoning` → `openai_reasoning`
+ * 5. Existing `compat.reasoning_effort` → `reasoning_effort`
+ * 6. Provider id starting with `openai` → `openai_reasoning`
+ * 7. Provider id `neuralwatt` → `reasoning_effort`
+ * 8. `capabilities.reasoning` → `reasoning_effort` (portable string field)
+ * 9. Else `noop`
  */
 export declare function thinkingFamilyForModel(model: Pick<ModelConfig, "provider" | "compat" | "capabilities">): ThinkingCompatFamily;

package/dist/thinking.js

@@ -7,6 +7,40 @@ export const THINKING_LEVELS = ["none", "minimal", "low", "medium", "high", "xhi
 export function isThinkingLevel(value) {
     return typeof value === "string" && THINKING_LEVELS.includes(value);
 }
+const LEVEL_RANK = {
+    none: 0,
+    minimal: 1,
+    low: 2,
+    medium: 3,
+    high: 4,
+    xhigh: 5,
+    max: 6,
+};
+function isThinkingFamily(value) {
+    return (typeof value === "string" &&
+        (value === "openai_reasoning" ||
+            value === "reasoning_effort" ||
+            value === "thinking_type" ||
+            value === "google" ||
+            value === "output_config_effort" ||
+            value === "noop"));
+}
+function thinkingLevelRank(level) {
+    return isThinkingLevel(level) ? LEVEL_RANK[level] : undefined;
+}
+/**
+ * Parse a host thinking-level value without guessing: known levels canonicalize to
+ * `ThinkingLevel`, unknown non-empty strings pass through as opaque `{ opaque }`
+ * (forward-compat passthrough), invalid/empty/non-string input fails closed.
+ */
+export function parseThinkingLevel(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = normalizeThinkingLevel(value);
+    if (!normalized)
+        return undefined;
+    return isThinkingLevel(normalized) ? normalized : { opaque: normalized };
+}
 /**
  * Normalize a host thinkingLevel string. Known levels are lowercased; other non-empty
  * strings pass through as opaque effort values for forward-compatible provider fields.
@@ -32,6 +66,10 @@ export function thinkingCompatFor(family, level) {
             return { reasoning_effort: normalized };
         case "thinking_type":
             return { thinking: { type: normalized === "none" ? "disabled" : "enabled" } };
+        case "google":
+            return { thinkingLevel: normalized };
+        case "output_config_effort":
+            return { output_config: { effort: normalized } };
         default: {
             const _exhaustive = family;
             return _exhaustive;
@@ -62,23 +100,111 @@ export function applyThinkingLevel(options, level, family = "reasoning_effort")
     }
     return mergeProviderRequestOptions(options, { compat: patch });
 }
+/**
+ * Declared portable thinking levels for a model, if any (ascending ladder order).
+ * `undefined` means the provider declares no subset — forward-compat passthrough.
+ */
+export function thinkingLevelsForModel(model) {
+    return model.capabilities?.thinkingLevels;
+}
+/**
+ * Strict declared-set membership (hosts fail closed on unknown levels).
+ * A model that declares no levels supports any value (forward-compat passthrough).
+ */
+export function isSupportedThinkingLevel(model, level) {
+    const parsed = parseThinkingLevel(level);
+    if (!parsed)
+        return false;
+    const declared = thinkingLevelsForModel(model);
+    if (!declared || declared.length === 0)
+        return true;
+    const value = typeof parsed === "string" ? parsed : parsed.opaque;
+    return declared.includes(value);
+}
+/**
+ * Snap a portable level to a model's declared set (design record §2):
+ * in-set → unchanged; below the declared minimum → up to the minimum
+ * (never silently disable what cannot be disabled); otherwise nearest declared
+ * level by ladder distance with ties breaking up; undeclared levels and
+ * undeclared sets pass through. Provider-documented snap tables
+ * (deepseek, Z.AI GLM-5.2, clinepass slots) override this generic fallback
+ * inside their own resolvers.
+ */
+export function snapThinkingLevel(model, level) {
+    const normalized = normalizeThinkingLevel(String(level));
+    if (!normalized)
+        return String(level);
+    const declared = thinkingLevelsForModel(model);
+    if (!declared || declared.length === 0)
+        return normalized;
+    if (declared.includes(normalized))
+        return normalized;
+    const rank = thinkingLevelRank(normalized);
+    const ranked = declared
+        .map((entry) => ({ entry, rank: thinkingLevelRank(entry) }))
+        .filter((entry) => entry.rank != null);
+    if (rank == null || ranked.length === 0)
+        return normalized;
+    const minRank = Math.min(...ranked.map(({ rank: r }) => r));
+    if (rank < minRank)
+        return ranked.find(({ rank: r }) => r === minRank).entry;
+    let best = ranked[0].entry;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    let bestRank = Number.NEGATIVE_INFINITY;
+    for (const { entry, rank: candidateRank } of ranked) {
+        const distance = Math.abs(candidateRank - rank);
+        if (distance < bestDistance || (distance === bestDistance && candidateRank > bestRank)) {
+            best = entry;
+            bestDistance = distance;
+            bestRank = candidateRank;
+        }
+    }
+    return best;
+}
+/**
+ * Model-aware thinking-level application (design record §5). Resolves the family
+ * stamp-first (`compat.thinkingFamily` → inference → `capabilities.reasoning`),
+ * snaps the level to the model's declared set, and merges the compat patch
+ * per-turn-wins. Returns options unchanged for non-reasoning models — never
+ * invents a field where the model declares no thinking support.
+ */
+export function applyThinkingLevelForModel(options, level, model) {
+    const normalized = normalizeThinkingLevel(String(level));
+    if (!normalized)
+        return options ?? {};
+    const family = model.compat?.thinkingFamily != null && isThinkingFamily(model.compat.thinkingFamily)
+        ? model.compat.thinkingFamily
+        : thinkingFamilyForModel(model);
+    if (family === "noop")
+        return options ?? {};
+    return applyThinkingLevel(options, snapThinkingLevel(model, normalized), family);
+}
 /**
  * Best-effort family inference from model metadata without a second options tree.
- * Prefer an explicit family in hosts/use-case workers when the provider is known.
+ * Prefer an explicit `compat.thinkingFamily` stamp in host/use-case workers when
+ * the provider is known; inference is the fallback (stamp-first).
  *
  * Heuristics (ordered):
- * 1. Existing `compat.thinking` object → `thinking_type`
- * 2. Existing `compat.reasoning` → `openai_reasoning`
- * 3. Existing `compat.reasoning_effort` → `reasoning_effort`
- * 4. Provider id starting with `openai` → `openai_reasoning`
- * 5. Provider id `neuralwatt` → `reasoning_effort`
- * 6. `capabilities.reasoning` → `reasoning_effort` (portable string field)
- * 7. Else `noop`
+ * 1. `compat.thinkingFamily` stamp → itself
+ * 2. Existing `compat.thinking` object → `thinking_type`
+ * 3. Existing `compat.thinkingConfig` object/boolean → `google`
+ * 4. Existing `compat.reasoning` → `openai_reasoning`
+ * 5. Existing `compat.reasoning_effort` → `reasoning_effort`
+ * 6. Provider id starting with `openai` → `openai_reasoning`
+ * 7. Provider id `neuralwatt` → `reasoning_effort`
+ * 8. `capabilities.reasoning` → `reasoning_effort` (portable string field)
+ * 9. Else `noop`
  */
 export function thinkingFamilyForModel(model) {
+    const stamp = model.compat?.thinkingFamily;
+    if (isThinkingFamily(stamp))
+        return stamp;
     const compat = model.compat ?? {};
     if (compat.thinking != null && typeof compat.thinking === "object")
         return "thinking_type";
+    if (compat.thinkingConfig != null && (typeof compat.thinkingConfig === "object" || typeof compat.thinkingConfig === "boolean")) {
+        return "google";
+    }
     if (compat.reasoning != null)
         return "openai_reasoning";
     if (compat.reasoning_effort != null)

package/docs/0.1.0-readiness.md

@@ -1,6 +1,6 @@
 # 0.1.0 / 1.0 Readiness Gates
 
-Status: **0.4.0** is the current release line (plan 054 package consolidation: 11 active packages, family subpaths, `^0.4.0` peers); **0.3.3** was the terminal 0.3.x cut; **0.1.7** was the terminal 0.1.x baseline; **1.0** readiness remains operator-gated, not automatic.
+Status: **0.5.0** is the current release line (dead-export removal cut: 10 active packages, family subpaths, `^0.5.0` peers); **0.3.3** was the terminal 0.3.x cut; **0.1.7** was the terminal 0.1.x baseline; **1.0** readiness remains operator-gated, not automatic.
 
 This page distills runnable readiness gates into one command-per-gate table.
 The **Last evidence** column records the 0.1.0-tree snapshot (plan 012 Tasks
@@ -20,7 +20,7 @@ Historical release lines (0.0.16 floor → 0.0.27 Phase 10 ACP interop → 0.1.0
 keep their per-phase evidence in the pages above; this page records the 0.2.6
 snapshot (plan 026) with the 0.1.x tables below as the historical record.
 
-## Current line (0.4.0)
+## Current line (0.5.0)
 
 | Item | Status |
 |---|---|
@@ -66,7 +66,7 @@ snapshot (plan 026) with the 0.1.x tables below as the historical record.
 | Publish order + tarball validation | `node scripts/release.mjs publish --version 0.1.0 --dry-run --allow-dirty --allow-untagged` | 49/49 packages `dry-run` twice with byte-identical reports, deterministic dependency order, no failures (Task 7) | Operator (dry-run), CI |
 | Node 20 compatibility | CI `node20-compat` (build + public-import smoke) | all 21 root exports import cleanly on Node 20.20.2 | CI |
 | PostgreSQL suite | `PRISM_TEST_POSTGRES_URL="$DATABASE_URL" npm run test:postgres` | 0.1.0: Phase 7 conformance + Phase 12 restart-recovery + 74 workspace checks green against PostgreSQL 16 (Task 4 recording, re-run green at 0.1.0 on 2026-08-09); operator-gated | Operator |
-| Keychain suite | `PRISM_TEST_KEYCHAIN=1 npm test --workspace @arnilo/prism-credentials-node` (protected) | 28/28 green incl. native keychain round-trip against the OS secret-service backend (gnome-keyring, 2026-08-09) | Operator host |
+| Keychain suite | `PRISM_TEST_KEYCHAIN=1 npm test --workspace @arnilo/prism-core/credentials/node` (protected) | 28/28 green incl. native keychain round-trip against the OS secret-service backend (gnome-keyring, 2026-08-09) | Operator host |
 | Live-provider suites | `npm run test:live` (protected) | **operator-gated** (requires credentials; `live-canaries.yml` blocked gate, `canary-report.json` retained) | Operator |
 | SAST | GitHub CodeQL | **operator-gated** (runs in CI workflow) | CI |
 | Signed, provenance publication | `npm run release:publish` (clean tagged tree, OIDC) | **operator-gated** (see "Remaining for 1.0") | Operator |

package/docs/a2a.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-supervisor` implements bounded A2A 1.0 over the JSON-RPC/HTTPS binding. Supported operations: `SendMessage`, `SendStreamingMessage`, `GetTask`, `ListTasks`, `CancelTask`, `SubscribeToTask`, push-notification-config create/get/list/delete, and `GetExtendedAgentCard`. `client.streamMessage()` additionally exposes verified rich task/message events for frontend adapters while legacy `stream()` remains text-compatible. Agent Cards retain explicit ES256 verification. gRPC, HTTP+JSON, discovery registries, automatic JWK/OAuth fetching, and an internal task worker/store are absent.
+`@arnilo/prism-core/runtime/supervisor` implements bounded A2A 1.0 over the JSON-RPC/HTTPS binding. Supported operations: `SendMessage`, `SendStreamingMessage`, `GetTask`, `ListTasks`, `CancelTask`, `SubscribeToTask`, push-notification-config create/get/list/delete, and `GetExtendedAgentCard`. `client.streamMessage()` additionally exposes verified rich task/message events for frontend adapters while legacy `stream()` remains text-compatible. Agent Cards retain explicit ES256 verification. gRPC, HTTP+JSON, discovery registries, automatic JWK/OAuth fetching, and an internal task worker/store are absent.
 
 ## When to use it
 
@@ -41,7 +41,7 @@ Parts, messages, artifacts, histories, metadata, and aggregate responses are unt
 
 ## AG-UI server-side exposure (Task 13, 0.0.26)
 
-`createAgUiA2AServer()` in `@arnilo/prism-ag-ui` fronts one host-selected **local AG-UI agent** as an A2A 1.0 server, the reverse direction of `createAgUiA2AAdapter()`: remote A2A clients start and stream local runs through the same AG-UI input allow-list and event mapper as the AG-UI SSE path (same projection, redaction, and byte caps). It reuses this package's `createA2AHandler` transport/lifecycle; it creates no second runtime, task store, or worker. Requires the optional `@arnilo/prism-supervisor` peer (imported lazily; plain `@arnilo/prism-ag-ui` imports keep working without it).
+`createAgUiA2AServer()` in `@arnilo/prism-ag-ui` fronts one host-selected **local AG-UI agent** as an A2A 1.0 server, the reverse direction of `createAgUiA2AAdapter()`: remote A2A clients start and stream local runs through the same AG-UI input allow-list and event mapper as the AG-UI SSE path (same projection, redaction, and byte caps). It reuses this package's `createA2AHandler` transport/lifecycle; it creates no second runtime, task store, or worker. Requires the optional `@arnilo/prism-core/runtime/supervisor` peer (imported lazily; plain `@arnilo/prism-ag-ui` imports keep working without it).
 
 ```ts
 import { createAgentEventSourceAgUiReplay, createAgUiA2AServer } from "@arnilo/prism-ag-ui";

package/docs/acp.md

@@ -112,7 +112,7 @@ const agent = createPrismAcpAgent({
 
 - **Seam = capability.** Wiring `sessions.load` advertises `loadSession`; removing it withdraws the method. There is no separate capability flag to keep in sync — the freeze manifest's advertise-when matrix is enforced by construction and asserted by `scripts/phase10-conformance.test.mjs`.
 - **Transcript replay (F2).** When `sessions.transcript` is wired, `session/load` and `session/resume` replay `user_message_chunk`/`agent_message_chunk` text chunks (from `SessionEntry`s with `kind: "message"` and a user/assistant role, text blocks only) before returning `sessionState`. Each chunk passes the shared redactor and is truncated at `maxTextBytes`; replay stops at `maxReplayEvents` chunks and counts against the stream event/byte caps (an oversized transcript fails the load/resume request closed). Absent seam = no replay, behavior unchanged.
-- **Client fs/terminal are adapters, not a second implementation.** `AcpClientFilesystem` / `AcpClientTerminals` wrap the client's `fs/*` and `terminal/*` methods behind the Phase 9 `ProcessSession`-flavored interfaces; the agent pre-generates the session id so terminal requests can carry it. `createAcpFilesystemOperations` from `@arnilo/prism-coding-agent` maps that filesystem seam onto the coding tools' `read`/`write`/`edit` operations. This editor-buffer mode is intentionally hybrid: `repo_list`, `repo_search`, `glob`, `delete`, and `move` remain disk-backed unless the host supplies separate operations; binary/image/document handling never falls back to local disk. Host repo operations remain default when the client fs is absent.
+- **Client fs/terminal are adapters, not a second implementation.** `AcpClientFilesystem` / `AcpClientTerminals` wrap the client's `fs/*` and `terminal/*` methods behind the Phase 9 `ProcessSession`-flavored interfaces; the agent pre-generates the session id so terminal requests can carry it. `createAcpFilesystemOperations` from `@arnilo/prism-coding-tools/agent` maps that filesystem seam onto the coding tools' `read`/`write`/`edit` operations. This editor-buffer mode is intentionally hybrid: `repo_list`, `repo_search`, `glob`, `delete`, and `move` remain disk-backed unless the host supplies separate operations; binary/image/document handling never falls back to local disk. Host repo operations remain default when the client fs is absent.
 - **Spawnable ACP coding registry (Task 6).** `@arnilo/prism-acp-agent` wires `createAcpClientFilesystem` and creates a separate coding tool registry per ACP session when the client advertises `fs/read_text_file` or `fs/write_text_file`. That session's `read`/`write`/`edit` operations use editor buffers; without fs advertisement, the existing disk registry is used. `shell`, repository search/list/glob, `delete`, and `move` remain disk-backed in this hybrid mode. Durable approvals resolve the same per-session agent, so one session cannot resume through another session's buffer adapter.
 - **Modes and config options are a pure host overlay.** The agent stores only a thin per-session registry; `apply`/`onChange` hooks narrow the host's own behavior. Mode switches can narrow or host-authorized widen — never a parallel policy evaluator, never a client-enabled tool.
 - **Lifecycle wiring.** Pass your `createCodingLifecycleEmitter()` as `coding.lifecycle`; `file_changed` etc. then flow to streaming sessions. `configuration_changed` broadcasts `config_option_update` (agent-message fallback if the SDK rejects the kind).
@@ -152,14 +152,14 @@ const agent = createPrismAcpAgent({
 - **Deny-closed by default.** Unknown mode ids, unadvertised methods, unprojected lifecycle events, oversize diffs/locations/media, thrown projection hooks, and failed elicitation all fail closed. Raw tool arguments/results are never sent unless a projection allow-list says otherwise.
 - **Slash commands (F9).** `commands.list` is a host-owned slash-command list (not derived from the tool registry). The agent emits `available_commands_update` on session start (`session/new`, `session/load`, `session/resume`). Mid-session refresh is not in this release — re-list by starting a session. Names, descriptions, and input hints pass the shared redactor; the list is sliced at `acpCommandsPerUpdate`. Absent seam or a thrown list ⇒ no update.
 - **Projected images (F8).** `AgUiProjection.toolResult` may return `{ type: "image", data, mimeType }` (return-type widening — existing string returns stay valid). The mapper emits `{ type: "content", content: { type: "image", data, mimeType } }` (SDK v1 `ToolCallContent` has no top-level image variant). `data` is the host-supplied base64; it is not redacted and not truncated — payloads over `acpImageBytes` are dropped. Default (no hook / non-image return) emits no image.
-- **Coding-tool projection (F7).** `createCodingToolProjection({ maxDiffBytes? })` is an opt-in `AgUiProjection` for first-party `@arnilo/prism-coding-agent` results: `edit` → `toolDiff` (`path` + unified `patch` as `newText`) and `toolLocations` (`path` + `firstChangedLine`); `write` and `delete` → `toolLocations` (`path` only); `move` → destination `toolLocations` (`metadata.to`, with `from` fallback). No delete/move diff is fabricated. Pass as `projection: createCodingToolProjection()` on the agent/mapper. Mapper still redacts and enforces `acpDiffBytes` / `acpLocationsPerUpdate`; optional `maxDiffBytes` pre-truncates the patch so a slightly-oversize edit is shortened instead of dropped. Without the factory, behavior is unchanged (deny-by-default).
+- **Coding-tool projection (F7).** `createCodingToolProjection({ maxDiffBytes? })` is an opt-in `AgUiProjection` for first-party `@arnilo/prism-coding-tools/agent` results: `edit` → `toolDiff` (`path` + unified `patch` as `newText`) and `toolLocations` (`path` + `firstChangedLine`); `write` and `delete` → `toolLocations` (`path` only); `move` → destination `toolLocations` (`metadata.to`, with `from` fallback). No delete/move diff is fabricated. Pass as `projection: createCodingToolProjection()` on the agent/mapper. Mapper still redacts and enforces `acpDiffBytes` / `acpLocationsPerUpdate`; optional `maxDiffBytes` pre-truncates the patch so a slightly-oversize edit is shortened instead of dropped. Without the factory, behavior is unchanged (deny-by-default).
 - **No secrets.** Updates carry no raw file bodies, terminal output is capped by the Phase 9 chunk budget, and the shared redactor is applied before anything leaves the host. `permission_denied` never includes raw args.
 - **Performance.** The adapter is O(1) per update with no unbounded buffering; p95 targets (fs round trip 250 ms, mode switch 250 ms, terminal chunk ack 1000 ms, prompt first update 2000 ms, prompt end 30 s) are recorded by `scripts/benchmark-0.0.27.mjs` and gated in `scripts/budgets.json` `phase10`.
 
 ## Related APIs
 
 - [AG-UI](ag-ui.md): sibling frontend protocol; shared projection/redaction/caps and the same pending-decision model. This page is the full ACP reference.
-- [Coding agent tools](coding-agent-tools.md): the `CodingLifecycleEvent` source mapped here; `@arnilo/prism-coding-agent` `process.outputChunkBytes` caps terminal chunks.
+- [Coding agent tools](coding-agent-tools.md): the `CodingLifecycleEvent` source mapped here; `@arnilo/prism-coding-tools/agent` `process.outputChunkBytes` caps terminal chunks.
 - [Agent events](agent-events.md): the durable `AgentEventSource`/replay story behind `session/load` and `session/resume`.
 - [Host security guide](host-security.md): fail-closed checklist rows for ACP boundaries (authorize, ownership, redaction, untrusted MCP).
 - [Migration guide](migration.md): 0.0.26 → 0.0.27 advertise/surface changes for hosts that parsed the old `initialize`.

package/docs/ag-ui-adoption.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-This page records Prism's compatibility review against official AG-UI `@ag-ui/core` **0.0.57** and the official repository at commit [`a40b5c0`](https://github.com/ag-ui-protocol/ag-ui/commit/a40b5c0824564eb2f9ab9edf2be43f355f42a3b8). It separates shipped transport/replay support from remaining work needed to claim full AG-UI support, including AG-UI fronting MCP and A2A agents.
+This page records Prism's compatibility review against official AG-UI `@ag-ui/core` **0.0.59** and the official repository at commit [`a40b5c0`](https://github.com/ag-ui-protocol/ag-ui/commit/a40b5c0824564eb2f9ab9edf2be43f355f42a3b8). It separates shipped transport/replay support from remaining work needed to claim full AG-UI support, including AG-UI fronting MCP and A2A agents.
 
 Official material reviewed:
 

package/docs/ag-ui.md

@@ -4,7 +4,7 @@
 
 `@arnilo/prism-ag-ui` is an optional, framework-free protocol adapter over Prism's existing redacted `AgentEvent`, session, durable-run, and persistence seams.
 
-- Root export maps Prism events to AG-UI `@ag-ui/core` **0.0.57** events and offers `createAgUiHandler()` (`Request` → SSE `Response`), compatible `createPersistenceAgUiReplay()` pages, distributed `createAgentEventSourceAgUiReplay()` follow, and explicit `createAgUiMcpAdapter()` / `createAgUiMcpAppHandler()` / `createAgUiA2AAdapter()` protocol handshakes.
+- Root export maps Prism events to AG-UI `@ag-ui/core` **0.0.59** events and offers `createAgUiHandler()` (`Request` → SSE `Response`), compatible `createPersistenceAgUiReplay()` pages, distributed `createAgentEventSourceAgUiReplay()` follow, and explicit `createAgUiMcpAdapter()` / `createAgUiMcpAppHandler()` / `createAgUiA2AAdapter()` protocol handshakes.
 - `@arnilo/prism-ag-ui/acp` is the stable ACP **v1** sibling: `createAcpEventMapper()` and `createPrismAcpAgent()` over `@agentclientprotocol/sdk` **1.3.0** root exports. ACP is a protocol adapter — sessions, modes, MCP, fs/terminal, lifecycle mapping, and caps live on the host seams. See [ACP coding-host interop](acp.md) for the full reference; this page covers AG-UI only.
 - Core remains protocol-free. `resumeAgentRunStream()` / `AgentRunLifecycle.resumeStream()` are generic durable-resume streams shared by adapters.
 
@@ -225,5 +225,4 @@ Defaults / hard caps: request 64 KiB / 1 MiB; input 128 / 1024 messages, 32 / 25
 - [MCP bridge/server](mcp-tools.md): `mcpApps` negotiation, bounded resources, and remote tool trust.
 - [A2A interoperability](a2a.md): verified rich task client and remote task lifecycle.
 - [Host security guide](host-security.md): authorization, ownership, redaction, and credential boundaries.
-- [Antigravity delegated agent](antigravity-agent.md): delegated Antigravity CLI execution with timeline step projection.
 - [Work artifacts and review](work-artifacts-and-review.md): durable artifact service that produces the co-work approval/progress/download-link events projected here.

package/docs/agent-definitions.md

@@ -224,7 +224,7 @@ Use `activateAllCapabilities: true` only while migrating old configs. It intenti
 - `ExtensionAPI.registerAgent(agent)` contributes an inert `AgentDefinition` programmatically; its `create()` (if present) is only invoked when the host runs it through `resolveAgentDefinition`. See [Extensions](extensions.md).
 - Bundle resolution is config over code: every seam lives on `AgentDefinition`, `AgentDefinitionResolutionContext`, or `ResolveAgentBundleOptions`. `systemPrompt` and `loop` are passed via `context.overrides` / `create()` rather than frontmatter.
 - Migration note: before Phase 38, a definition that omitted `tools` but had a tool scope could receive every scoped tool. Now omitted `tools`/`skills` activates none. Add explicit names to `tools` / `skills`; use `activateAllCapabilities: true` only while migrating old configs.
-- `parseAgentFile(text, path)` (re-exported from `@arnilo/prism`) is the stdlib-only frontmatter parser for `AGENT.md`. `parseContextFile` and `parseToolFile` parse colocated `CONTEXT.md` / tool descriptors inside the Node subpath.
+- `parseAgentFile(text, path)` (re-exported from `@arnilo/prism`) is the stdlib-only frontmatter parser for `AGENT.md`. Colocated `CONTEXT.md` / tool-descriptor parsing is host-owned (the thin `parseContextFile`/`parseToolFile` helpers were removed in 0.5.0 — see `docs/migrate-to-0.5.md`).
 - Repo contributions (`<workspaceRoot>/.agents/{skills,tools}/`) are scanned by `discoverContributions` and passed via `repoContributions`. Repo `.agents/` is preserved as a shared contribution surface across every agent that operates on the same repository; multiple agents from different apps can work the same repo, and all share its repo-level skills.
 
 ## Security and performance notes

package/docs/agent-events.md

@@ -24,10 +24,10 @@ Event records preserve emission order within a run because the runtime drains pe
 
 ### Placement (FR-7 answer, 0.0.26)
 
-The durable `AgentEventSource` **stays in `@arnilo/prism-session-store-postgres`** for the 0.0.26 line and is importable from the package root (FR-6):
+The durable `AgentEventSource` **stays in `@arnilo/prism-core/sessions/postgres`** for the 0.0.26 line and is importable from the package root (FR-6):
 
 ```ts
-import { createPostgresAgentEventSource } from "@arnilo/prism-session-store-postgres";
+import { createPostgresAgentEventSource } from "@arnilo/prism-core/sessions/postgres";
 const source = createPostgresAgentEventSource({ pool, schema: "prism", cursorSecret });
 ```
 
@@ -35,11 +35,11 @@ PostgreSQL `LISTEN`/`NOTIFY` remains the **reference durable implementation**; `
 
 ### NATS JetStream adapter (FR-5)
 
-`@arnilo/prism-session-store-nats` ships a sibling durable `AgentEventSource` over NATS JetStream for JetStream backbones (Postgres remains the reference implementation):
+`@arnilo/prism-core/sessions/nats` ships a sibling durable `AgentEventSource` over NATS JetStream for JetStream backbones (Postgres remains the reference implementation):
 
 ```ts
 import { connect } from "@nats-io/transport-node";
-import { createNatsAgentEventSource, createNatsJetStream } from "@arnilo/prism-session-store-nats";
+import { createNatsAgentEventSource, createNatsJetStream } from "@arnilo/prism-core/sessions/nats";
 
 const nc = await connect({ servers: process.env.NATS_URL });
 const source = createNatsAgentEventSource({ connection: await createNatsJetStream(nc), stream: "prism_agent_events" });
@@ -249,4 +249,4 @@ for await (const event of session.stream("draft", { loop: { strategy: "generate-
 - [Observability](observability.md): `ProviderTurnMetadata`; optional adapter builds one parented GenAI span tree from metadata-only lifecycle events and ignores message/progress deltas.
 - [Tools](tools.md): `tool_execution_*` variants.
 - [Compaction and retry policies](compaction-and-retry.md): `compaction_*` and `retry_scheduled` variants.
-- [Frontend interoperability (AG-UI and ACP)](ag-ui.md): optional redacted mapping of this stream; durable replay is ledger-backed and at-least-once, never a live-subscriber substitute. [ACP coding-host interop](acp.md) additionally maps `CodingLifecycleEvent`s from `@arnilo/prism-coding-agent` (`file_changed`, `worktree_changed`, `permission_denied`, `configuration_changed`, `plan_changed`, `plan_removed`; process events reuse `CodingProcessEvent`) into ACP session updates — locations/diff blocks only through projection allow-lists, terminal chunks under `process.outputChunkBytes`, plan updates only to clients that advertised the UNSTABLE `plan` capability.
+- [Frontend interoperability (AG-UI and ACP)](ag-ui.md): optional redacted mapping of this stream; durable replay is ledger-backed and at-least-once, never a live-subscriber substitute. [ACP coding-host interop](acp.md) additionally maps `CodingLifecycleEvent`s from `@arnilo/prism-coding-tools/agent` (`file_changed`, `worktree_changed`, `permission_denied`, `configuration_changed`, `plan_changed`, `plan_removed`; process events reuse `CodingProcessEvent`) into ACP session updates — locations/diff blocks only through projection allow-lists, terminal chunks under `process.outputChunkBytes`, plan updates only to clients that advertised the UNSTABLE `plan` capability.

package/docs/agent-identity.md

@@ -87,7 +87,7 @@ await agent.createSession().run("Summarize inbox", {
 
 Server / MCP / A2A authorize callbacks may include the same `identity` beside `ownership`. Handlers assert activity and ownership match before admitting work.
 
-## OIDC/JWKS verifier adapter (`@arnilo/prism-credentials-node/oidc`)
+## OIDC/JWKS verifier adapter (`@arnilo/prism-core/credentials/node/oidc`)
 
 Optional `createOidcIdentityVerifier` turns a pinned issuer/audience and pinned JWKS URL into a core `IdentityVerifier` — one bounded reference adapter for hosts that already authenticate callers with OIDC JWTs (Entra, Keycloak, Auth0, …). Native `fetch` + WebCrypto only; no JOSE dependency.
 
@@ -102,7 +102,7 @@ Optional `createOidcIdentityVerifier` turns a pinned issuer/audience and pinned
 | `limits` | Bounded JWKS/claims knobs; `identity` reuses core identity caps |
 
 ```ts
-import { createOidcIdentityVerifier } from "@arnilo/prism-credentials-node/oidc";
+import { createOidcIdentityVerifier } from "@arnilo/prism-core/credentials/node/oidc";
 
 const verifier = createOidcIdentityVerifier({
   issuer: "https://id.example.com/tenant",
@@ -132,6 +132,17 @@ Identity is optional. Hosts that only set `ownership` keep prior behavior. When
 - Checks are O(fields) and network-free in core; remote auth stays in the host verifier.
 - Raising hard caps requires updating `docs/_evidence/review-coverage-2026-07-23-phase-8.md`, tests, and docs.
 
+## Live probe (plans/064 Task 9)
+
+The OIDC/JWKS identity verifier has an operator-gated live probe against a real issuer:
+
+```bash
+PRISM_TEST_OIDC_ISSUER=https://id.example.com/tenant PRISM_TEST_OIDC_AUDIENCE=prism-api \
+PRISM_TEST_OIDC_TOKEN=<real bearer token> npm test -w @arnilo/prism-core -- oidc-live
+```
+
+Set `PRISM_TEST_OIDC_JWKS_URL` to pin a non-default JWKS URL (default `<issuer>/.well-known/jwks.json`). Probes: a valid token verifies against the live JWKS (1 fetch), a tampered token fails closed with `ERR_PRISM_OIDC_SIGNATURE` (error text never echoes the token), and a garbage token fails closed without JWKS traffic. Bounded to 1 real request. Registered in `scripts/live-matrix.json` as `core/oidc-live`.
+
 ## Related APIs
 
 - [Policy and audit](policy-and-audit.md)

package/docs/audit-export.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-policy` exports tenant-scoped audit records as signed, hash-chained
+`@arnilo/prism-core/governance/policy` exports tenant-scoped audit records as signed, hash-chained
 batches: each record envelope is canonicalized (RFC 8785 semantics), hashed with
 SHA-256 including the prior digest, so records form a tamper-evident chain. A
 batch of chained records is wrapped in a manifest that a host-provided
@@ -69,7 +69,7 @@ canonical `record` payload. `verifyAuditBatch` returns `{ ok, errors, batch }`.
 ## Request/response example
 
 ```ts
-import { createAuditExporter, createMemoryAuditCursorStore } from "@arnilo/prism-policy";
+import { createAuditExporter, createMemoryAuditCursorStore } from "@arnilo/prism-core/governance/policy";
 
 const exporter = createAuditExporter({
   source,                                 // host: tenant-scoped record pages
@@ -87,7 +87,7 @@ const result = await exporter.exportNext({ tenantId: "acme", maxRecords: 1000 })
 
 ```ts
 import { readFileSync } from "node:fs";
-import { verifyAuditBatch } from "@arnilo/prism-policy";
+import { verifyAuditBatch } from "@arnilo/prism-core/governance/policy";
 
 const artifactBytes = new Uint8Array(readFileSync("./acme-000001.json"));
 const verified = verifyAuditBatch({

package/docs/batch-jobs.md

@@ -0,0 +1,120 @@
+# Batch jobs
+
+## What it does
+
+`BatchJobsProvider` is the provider-neutral async batch contract (plan 061
+Task 7): `submit` (requests + metadata → opaque job id), `status`, `cancel`, and
+paged `results`, with a typed job-state union and a `pollBatch` backoff utility
+exported standalone — core never loops or awaits completion for you. The
+first-party adapter is [`createOpenAIBatchJobsProvider`](providers/openai.md)
+(Files API JSONL upload + `/v1/batches` lifecycle). Offline conformance runs via
+`runBatchJobsConformance` from `@arnilo/prism/testing/provider-conformance`.
+
+## When to use it
+
+Use it for large asynchronous workloads that tolerate 24-hour completion
+windows — offline scoring, backfills, bulk classification. Do not use it as a
+scheduler or an orchestration saga: the contract is standalone by decision
+(integration with the workflows saga is deferred — see plan 061 Further
+Actions). Interactive low-latency requests belong on the normal provider path.
+
+## Inputs / request
+
+| Call | Inputs | Meaning |
+| --- | --- | --- |
+| `submit` | `{ model, requests, metadata? }` | `requests` are provider-native `{ customId?, body: JsonObject }` items; bodies are opaque to the contract and inherit provider caps. |
+| `status` | opaque job id | Current `BatchJob` snapshot (state union + provider counts + `raw`). |
+| `cancel` | opaque job id | Best-effort cancellation; returns the transitioning job (`cancelling`). |
+| `results` | job id + `{ cursor?, pageSize? }` | Page of per-request outcomes; cursor is an opaque continuation token. |
+| `pollBatch` | provider + job id + `{ intervalMs?, backoffMultiplier?, maxIntervalMs?, maxAttempts? }` | Utility only — resolves on `completed`, throws typed on `failed`/`cancelled`/`expired`. |
+
+Adapter options: `apiKey` (`CredentialValueSource` — resolved per call,
+redacted from errors), `baseUrl`, `fetch` (fake transport for offline tests),
+`headers`, `endpoint` (defaults to `/v1/chat/completions`),
+`completionWindow` (defaults `24h`).
+
+## Outputs / response / events
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `job.state` | `"queued" \| "running" \| "cancelling" \| "completed" \| "failed" \| "cancelled" \| "expired"` | Neutral union; adapters map provider states (OpenAI `validating`→`queued`, `in_progress`/`finalizing`→`running`, …). `isBatchJobTerminal` classifies. |
+| `job.id` | `string` | Opaque provider id — the contract never parses or scopes it. |
+| `job.requestCounts` | `{ total, completed, failed }?` | Provider progress counts. |
+| `job.raw` | `JsonObject?` | Provider-native job fields, unmodified, for audits. |
+| `result.items[n]` | `{ customId, response?, error?, raw? }` | Per-request outcome; per-item failures ride alongside a `completed` job. |
+
+Failures throw `BatchJobsError` with a stable `code`: `empty_requests`,
+`too_many_requests` (adapter cap `OPENAI_BATCH_MAX_REQUESTS` = 50,000, OpenAI's
+documented limit), `unsupported_model` (via `assertBatchJobsSupported` when the
+host checks `ModelCapabilities.batchJobs`), `job_not_found`, `invalid_cursor`,
+`request_failed` (non-2xx, secret-redacted), `response_malformed`, and — from
+`pollBatch` on terminal states — `job_failed`, `job_cancelled`, `job_expired`.
+
+## Request/response example
+
+```json
+{ "input_file_id": "file-X123", "endpoint": "/v1/chat/completions", "completion_window": "24h" }
+```
+
+## Implementation example
+
+```ts
+import { createOpenAIBatchJobsProvider } from "@arnilo/prism-providers/openai";
+import { pollBatch, runBatchJobsConformance } from "@arnilo/prism";
+import { runBatchJobsConformance } from "@arnilo/prism/testing/provider-conformance";
+
+const batch = createOpenAIBatchJobsProvider({ apiKey: process.env.OPENAI_API_KEY });
+const job = await batch.submit({
+  model: "gpt-4o-mini",
+  requests: [{ customId: "doc-1", body: { messages: [{ role: "user", content: "summarize" }] } }],
+});
+// pollBatch is a plain utility — host owns scheduling and persistence:
+const done = await pollBatch(batch, job.id, { intervalMs: 30_000, backoffMultiplier: 1.5, maxIntervalMs: 300_000 });
+let cursor: string | null | undefined = null;
+do {
+  const page = await batch.results(done.id, { cursor });
+  for (const item of page.items) { /* host owns per-item handling */ }
+  cursor = page.nextCursor ?? null;
+} while (cursor !== null);
+
+// Offline conformance (fake transport, no network):
+await runBatchJobsConformance({
+  provider: createOpenAIBatchJobsProvider({ apiKey: "sk-test", fetch: fakeFetch }),
+  maxRequests: 50_000,
+  sample: { model: "gpt-4o-mini", requests: [{ body: { messages: [] } }] },
+});
+```
+
+## Extension and configuration notes
+
+- Implement `BatchJobsProvider` for other vendors; the contract is structural —
+  no base class, no registry. Map your provider's states onto the neutral union
+  and surface your raw job payload on `job.raw`.
+- Models declare support with `capabilities.batchJobs`; hosts gate with
+  `modelSupportsBatchJobs` / `assertBatchJobsSupported`, mirroring the
+  embeddings/speech/image/video/moderation guard pattern.
+- Workflow-saga integration (auto-submission from run failure recovery) is
+  intentionally out of scope for v1 — see plan 061 Further Actions.
+
+## Security and performance notes
+
+- Job ids are opaque strings; results cursors are opaque continuation tokens
+  (adapter: line offsets — never parsed as authorization).
+- API keys resolve through the existing `CredentialValueSource` seam and are
+  redacted from every thrown error; no new secret paths.
+- All responses read through the bounded readers
+  (`OPENAI_BATCH_MAX_RESPONSE_BYTES`, 256 MiB for JSONL downloads — batches are
+  large by design); oversized payloads reject instead of buffering.
+- One provider request per call; paging is client-side over the downloaded
+  output/error file — no network per page boundary.
+- Inputs, payloads, and raw files are never logged by core; error messages
+  carry status and a redacted body only.
+
+## Related APIs
+
+- [Provider conformance](provider-conformance.md): `runBatchJobsConformance`
+  and the offline conformance matrix.
+- [Provider packages](provider-packages.md): subpath import rules for
+  `@arnilo/prism-providers/openai`.
+- [Multimodal content](multimodal-content.md): sibling one-shot modality
+  contracts sharing the same capability-flag and guard pattern.