@arnilo/prism 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,3 +1,35 @@
+## [0.5.0] - 2026-09-06 (plans 055-065)
+
+### Changed
+- **Thinking/reasoning effort is now model-aware, declared, and snapped across all first-party providers (plan 065):** core gains `applyThinkingLevelForModel(base, level, model)` (family resolution + snap + merge in one call), `parseThinkingLevel` (known portable level → canonical; other non-empty string → opaque passthrough; empty/non-string → `undefined`, fail closed), `isSupportedThinkingLevel`, `thinkingLevelsForModel`, and `snapThinkingLevel` (nearest declared by ladder distance, ties break up, below-minimum snaps up; provider-documented tables remain wire authority). `ModelCapabilities` gains `thinkingLevels?: readonly string[]`; family inference is stamp-first via the new `compat.thinkingFamily` stamp set by every first-party catalog. Two new core compat families: `google` (`{ thinkingLevel }` → `generationConfig.thinkingConfig`) and `output_config_effort` (`{ output_config: { effort } }` → Anthropic Messages / DeepSeek anthropic-format). Per-provider: OpenAI catalogs declare per-family effort tables (gpt-5.1 `none/low/medium/high` default `none`; gpt-5.2 `none`–`xhigh` default `medium`) with Responses-side clamping; Google stamps per-model thinkingLevel sets (3.x) and budget ranges (2.5, `none` → range minimum); Anthropic emits generation-aware thinking (`adaptive` on 4.6+, legacy 4.5 budget default 10000) with per-model effort declarations; Azure/Vertex/Bedrock forward sanitized thinking compat through `buildBodyExtra` (previously silently dropped); Kimi K3, Z.AI GLM-5.2/5.3, and DeepSeek declare documented snap tables; xAI now sends `reasoning_effort` (grok-4.6 `low`–`xhigh`, grok-4.5 `low/medium/high`, grok-4.3 `none`–`high`) instead of dropping it; OpenRouter derives declared levels from the models API (`reasoning.supported_efforts`); Hyper snaps instead of dropping out-of-set efforts and derives levels from the live `effort_levels` list; ClinePass declares levels by inverting its slot maps; the shared Anthropic-Messages route gained `thinking`/`effort` hook slots (hyper/commandcode bind resolvers; opencode-go deleted its private serializer copy for the shared route); commandcode/opencode-go carry provenance-commented level tables; Alibaba/Qwen maps the `thinking_type` family onto `enable_thinking` with thinking-only models never disabled; Ollama/NeuralWatt declare + snap `reasoning_effort`. `@arnilo/prism-memory` workers (LLM compaction, observational memory) now use the single model-aware adapter. Conformance: a cross-catalog walk (`thinking-conformance.test.ts`) machine-checks all 133 reasoning-capable catalog models (declarations + legal wire fields + no verbatim leakage), generated evidence matrix `docs/_evidence/thinking-coverage-2026-09-05.md`, and env-gated live probes pin the riskiest wire changes (Anthropic `output_config.effort` + legacy-field outcome, Google `thinkingLevel`, xAI/Kimi/Z.AI `reasoning_effort`, GLM-5.3 `thinking.type: disabled` rejection gate, Azure `reasoning_effort`). Breaking wire moves + new exports in `docs/migrate-to-0.5.md`; contract rewrite in `docs/thinking-and-reasoning.md`; per-provider pages document declared levels, wire fields, and snapping.
+
+
+### Changed
+- **CLI real-provider support (plan 064 Task 5):** `prism --provider <id>` now runs real providers, not just the built-in mock — provider ids resolve through the init provider catalog (`templates/init/providers.json`, single source shared with `prism init` scaffolding via new `factoryModule`/`factoryExport` fields): the CLI dynamically imports the provider factory from the installed `@arnilo/prism-providers/*` package and reads the catalog's credential env var. `--mode print|json|rpc` all honor it; RPC's session factory became async-capable (`AgentSession | Promise<AgentSession>`) to support the dynamic import. Without `--provider` the CLI still fails with a usage error (unchanged contract). Covered by the new packed-install live journey `scripts/e2e-cli-live.test.mjs` (scaffold + `providers add` + print/json/rpc over the real wire + full-transcript secret scan; matrix entry `cli/journey`).
+- **`@arnilo/prism-mcp` completes the MCP 2026-07-28 adoption (plan 063):** modular TypeScript SDK v2 (`@modelcontextprotocol/client` + `@modelcontextprotocol/server` 2.0.0 exact pins) replaces the monolithic `@modelcontextprotocol/sdk` 1.30.0; modern client negotiation (`legacy`/`auto`/`{pin}` with one bounded discovery probe), negotiated-era exposure, SDK-managed routing headers with `Mcp-Param-*` mirroring (SEP-2243), SDK subscriptions + explicit-cursor lists + `callTool({toolDefinition})`, SEP-2549 list-cache hints (private per principal by default), elicitation via SDK MRTR auto-fulfilment with `maxMrtrRounds` (roots/sampling callbacks `@deprecated` per SEP-2577), dual-era HTTP/stdio serving through `createMcpHandler`/`serveStdio` with host/origin gates in front, and 2026-07-28-conformant OAuth (issuer-keyed storage, CIMD preferred, RFC 9207 `iss` validation, explicit insufficient-scope policy). Tasks (`io.modelcontextprotocol/tasks`) intentionally not advertised; draft-era task vocabulary fails closed. Conformance: official suite (latest published spec version 2025-11-25 — no 2026-07-28 scenarios upstream yet) 20/20 expressible scenarios green against the dual-era serving fixture with the remaining 14 scenarios recorded as documented Prism boundaries in `scripts/mcp-conformance-2026-baseline.yaml`; two real defects found and fixed by the matrix (no-argument prompts rejected `undefined` args; tool inputSchema lost `$schema`/`$defs`/`$ref`/`additionalProperties` through the zod round-trip). Full migration table + legacy-session timeline in `docs/migration.md`; canonical API in `docs/mcp-tools.md`.
+
+
+### Changed
+- **pdf-parse 1.1 → 2.4 migration (plan 062, parser CVE class):** `@arnilo/prism-coding-tools` document-reader moves `pdf-parse` `^1.1.1` → `^2.4.5` (optional peer) and the two optional peers (`pdf-parse`, `mammoth`) become explicit devDependencies so the fixture suites actually run in this repo (previously they self-skipped via `PEERS_OK`). v2 replaced the v1 `pdf(buffer) → {numpages, text}` function with a `PDFParse` class: adapter now constructs `new PDFParse({ data, isEvalSupported: false })`, calls `getText({ pageJoiner: "" })`, and `destroy()`s in `finally`; page count reads `result.total` instead of `numpages`. `isEvalSupported: false` hard-disables pdf.js `eval` of PDF functions — the reader contract forbids embedded script execution (v1 did not disable it). Engine constraints for hosts: v2 parses in a worker thread (the `data` TypedArray is transferred, so the caller must not reuse the buffer — the adapter passes a fresh view per extract), requires Node ≥ 20.16 (repo already `engines.node >=20`), and ships CJS + ESM builds with a browser bundle; bundlers must resolve the `import`/`require` conditions of the new exports map. Golden deltas: extracted text for the committed fixtures is byte-identical to v1 modulo trailing `\n` (page-boundary markers suppressed via `pageJoiner: ""`); the 1000-page budget fixture parses in ~223ms (ceiling 2000ms, v1 baseline ~162ms — no regression). New fuzz smoke: a `%PDF-`-magic 256KiB garbage buffer rejects within the budget ceiling instead of hanging. Full coding-tools suite 646 pass / 0 fail; workspace typecheck green; root suite green.
+- **better-sqlite3 12 → 13 migration (plan 062):** `@arnilo/prism-core` moves `better-sqlite3` `^12.11.1` → `^13.0.3` (optional peer) with `@types/better-sqlite3` `^7.6.13` → `^9.6.0`. Upstream 13 is an N-API rewrite (`node-addon-api`): no removed or changed APIs — only additions (`db.explain()`, `statement.toString()`) and a `SqliteError` cross-realm fix. Packaging change for hosts: 13 removes the deprecated `prebuild-install` and bundles prebuilt N-API binaries for supported platforms directly in the package (one binary across Node versions — no per-Node rebuild); unsupported platform/arch compiles from source during install as before (`npm rebuild better-sqlite3` after a toolchain change). No SQL construction or prepared-statement layout changed in the adapter (statements remain hoisted `db.prepare` consts); all sqlite session/enterprise/prompt suites green (34 pass / 1 env-gated skip), packed-tarball fresh-install native-load + round-trip smoke green, benchmark gate medians green.
+- **Keyring 2 migration (plan 062, credential-storage boundary):** `@arnilo/prism-core` moves `@napi-rs/keyring` `^1.3.0` → `^2.0.0`. Upstream 2.0 changes error reporting, not success paths: reads (`getPassword`/`getSecret`) and deletes (`deleteCredential`) now reject on locked/inaccessible stores instead of silently resolving `undefined`/`false`; a missing credential still resolves `undefined`, and `false` from a delete now guarantees absence. The keychain adapter (`packages/prism-core/src/credentials/node/keychain-store.ts`) already routes every native call through `runKeychainOperation` → typed-error mapping (`CredentialStoreLockedError`/`CredentialStoreUnavailableError`/`CredentialStoreTimeoutError`), so host-visible behavior is unchanged in shape and strictly safer in semantics: a locked keychain now surfaces as a typed locked-store error instead of masquerading as an empty vault (which under 1.x could lead a `set()` to overwrite the real vault). Async signatures (`signal` parameters, binary `getSecret`, `AsyncEntry`) unchanged. Evidence: full credential-node suite 75/75 green; live Secret Service round-trip (`PRISM_TEST_KEYCHAIN=1`, credential + OAuth set/get/delete) green on Linux keyring 2.0.0; macOS/Windows legs are not exercisable in CI (all legs ubuntu) — the round-trip test ships gated per platform via `PRISM_TEST_KEYCHAIN=1`.
+
+### Removed
+- **Dead-export removal wave (plan 058 task 3, breaking):** all 27 unused public exports classified `deprecate`/`remove` in `docs/_evidence/dead-export-verification-2026-09-03.md` are deleted in one coordinated 0.5.0 cut (deprecated at 0.5.0-precursor in the same cycle). Per package — `@arnilo/prism`: `statusFromState`, `isInitProvider`, `isInitTemplate`, `parseContextFile`, `parseToolFile`, `defaultUserSettingsPath`, `resolveProviderMediaBlock`, `ProviderSecretLeakConformanceOptions`, `runToolEffectStoreConformance`; `@arnilo/prism-core`: `OidcIdentityVerifierResult`, `assertDiffLines`, `ResolvedPromptLimits`, `encodeMetadata`, `parseListOffsetCursor`, `nodeKindOf`; `@arnilo/prism-memory`: `DEFAULT_MAX_PROMPT_CHARS`, `GRAFT_RESOLVE_ERROR_CODE`, `LinterOptions`, `ResolvedGraftExtension`, `WikiCategory`; `@arnilo/prism-coding-tools`: `codingSha256Hex`, `DEFAULT_MAX_REVIEW_DELTA_ENTRIES`, `HARD_MAX_REVIEW_DELTA_ENTRIES`, `indexErrorCode`, `PONYTAIL_PEER_RANGE`, `CavemanSkillName`; `@arnilo/prism-providers`: `withOpenRouterCacheMarker`. All had zero in-repo references (test-only false positives were reclassified keep by the verification sweep; security guards are keep-classified and untouched). Compat baselines regenerated at the cut; intentional breaks recorded in `docs/migration.md`; removal table + replacements in `docs/migrate-to-0.5.md`. `scripts/unused-report.json` deadExports → 0 (the scan now counts test/example/script/template usage and suppresses keep-classified zero-ref exports). All manifests bump 0.4.x → 0.5.0 lockstep; internal ranges `^0.4.0` → `^0.5.0`. Security keeper surface (ownership/checkpoint guards, `secureCompare`, `zeroBuffer`, sandbox path-escape guard, RAG scope guard, MCP content-bounds guard, secret-leak conformance assert) unchanged.
+- Removed `@arnilo/prism-antigravity-agent` workspace, package surface, active documentation, release wiring, and host-conformance branch. Delegated CLI execution belongs to hosts and composes through generic process, tool, MCP, supervisor, or A2A contracts.
+
+### Changed
+- Updated `@nanonets/graft` peer support to `^0.16.0`, AG-UI packages to `0.0.59`, `@ai-sdk/provider` to `4.0.10`, Office Open packages to `0.13.1`, Biome to `2.5.11`, and `fast-xml-parser` to `5.11.1`.
+- Refreshed lockfile transitive dependencies; `npm audit` reports zero vulnerabilities.
+
+### Deprecated
+- **Type-level deprecation wave (plan 058, task 2):** 27 unused public exports now carry `@deprecated` JSDoc naming "no replacement" and the 0.5.0 removal plan; runtime behavior is unchanged (no warnings). Per package — `@arnilo/prism`: `statusFromState`, `isInitProvider`, `isInitTemplate`, `parseContextFile`, `parseToolFile`, `defaultUserSettingsPath`, `resolveProviderMediaBlock`, `ProviderSecretLeakConformanceOptions`, `runToolEffectStoreConformance`; `@arnilo/prism-core`: `OidcIdentityVerifierResult`, `assertDiffLines`, `encodeMetadata`, `parseListOffsetCursor`, `nodeKindOf`, `ResolvedPromptLimits` (marked for removal); `@arnilo/prism-memory`: `DEFAULT_MAX_PROMPT_CHARS`, `GRAFT_RESOLVE_ERROR_CODE`, `LinterOptions`, `ResolvedGraftExtension` (marked for removal), `WikiCategory` (marked for removal); `@arnilo/prism-coding-tools`: `codingSha256Hex`, `DEFAULT_MAX_REVIEW_DELTA_ENTRIES`, `HARD_MAX_REVIEW_DELTA_ENTRIES`, `indexErrorCode`, `PONYTAIL_PEER_RANGE`, `CavemanSkillName` (marked for removal); `@arnilo/prism-providers`: `withOpenRouterCacheMarker`. All are removed in the 0.5.0 cut above (plan 058 task 3, `docs/migrate-to-0.5.md`).
+
+## [0.4.1] - 2026-09-02 (plan 055)
+
+### Changed
+- **Two new first-class provider adapters (plan 055):** `@arnilo/prism-providers` (0.4.0 → 0.4.1, Decision B changed-package cut) gains `./hyper` (Charm Hyper — dual-route `/v1/chat/completions` + `/v1/messages` adapter with cache_control on Anthropic-shaped models and Hypercredit cost telemetry) and `./commandcode` (Command Code Provider API — dual-route `/provider/v1/chat/completions` + `/provider/v1/messages` adapter with cache_control on Claude tiers and optional ZDR). Both keep zero network at setup, caller-gated model discovery, provider-owned header enforcement, secret redaction, and offline conformance suites; live probes are operator-gated behind `PRISM_LIVE_PROVIDER_TESTS=1` + provider key. Public symbols and trust boundaries unchanged except the two new subpaths; peer `@arnilo/prism@^0.4.0` unchanged; no root package change (docs only).
+
 ## [0.4.0] - 2026-09-01 (plan 054)
 
 ### Changed
@@ -62,7 +94,7 @@
 
 ### Added
 - `@arnilo/prism-obscura` (new workspace package, 0.3.0): optional Obscura headless-browser engine over a **host-installed** binary — fail-closed `spawnObscuraProcess` lifecycle (absolute shell-free command, Docker argv, bounded readiness, group close), `createObscuraMcpTools` bridging the complete advertised MCP surface (reads effect-free; mutations and unknown future tools exclusive/serialized; `obscura_` prefix; loopback-default HTTP), `connectObscuraCdp` managed/external CDP + Playwright `connectOverCDP` composition, and `createObscuraWebTools` (standard `web_search`/`web_fetch` through one replaceable HTML search profile plus native `obscura_fetch`/`obscura_scrape`; public-HTTP(S)-only URL validation, byte/count/timeout caps, `allowEval`-gated custom expressions, untrusted-content labeling). Deliberately omitted from `prism-all`/`prism-base`/`prism-sdk` umbrella profiles — installation does not supply the binary/image; consumers install it explicitly.
-- Cross-host conformance (`scripts/obscura-host-conformance.test.mjs`, wired into `npm test`): the same Obscura `ToolDefinition[]` executes through core agent sessions, the Prism MCP server, the server handler, AG-UI, ACP, workflow nodes, supervisor children, and Antigravity delegated exposure — no host branch; host authorization/selection deny before execution; abort kills owned children.
+- Cross-host conformance (`scripts/obscura-host-conformance.test.mjs`, wired into `npm test`): the same Obscura `ToolDefinition[]` executes through core agent sessions, the Prism MCP server, the server handler, AG-UI, ACP, workflow nodes and supervisor children — no host branch; host authorization/selection deny before execution; abort kills owned children.
 - New required peers: `@arnilo/prism-obscura` peers `@arnilo/prism` and `@arnilo/prism-web-tools` (reused citation/normalized shapes; `WebProvider` widened with `"obscura"`); `@arnilo/prism-obscura` also peers `@arnilo/prism-mcp`, `@arnilo/prism-browser`, and optional `playwright-core@1.61.0`.
 
 ## [0.3.1] - 2026-08-26

package/README.md

@@ -4,9 +4,8 @@
 bring their tools, providers, credentials, storage, and UI; Prism supplies the
 common contracts, registries, agent/session runtime, replaceable input/prompt
 and compaction strategies, CLI/RPC adapters, and first-party provider/compaction
-packages. The current 0.3.3 line contains 11 publishable manifests, including
-optional Linux desktop control, a versioned prompt registry, and independent
-package versioning after the final lockstep cut. Prism defines contracts, not apps.
+packages. The current 0.4 line publishes the generated package inventory (see
+[Packages](#packages)) with explicit family subpaths and independent package versioning. Prism defines contracts, not apps.
 
 ## Current scope
 
@@ -20,7 +19,7 @@ package versioning after the final lockstep cut. Prism defines contracts, not ap
   OpenAI/OpenRouter use best-effort explicit cache hints, NeuralWatt uses
   best-effort implicit prefix caching, and other providers have route/model-specific
   or no cache-control support; see [docs/provider-caching.md](docs/provider-caching.md).
-- **First-party packages**: seventeen provider adapter subpaths, two compaction strategies,
+- **First-party packages**: nineteen provider adapter subpaths, two compaction strategies,
   coding tools/security, JSON Schema validation, MCP, workflows, OpenTelemetry,
   encrypted credentials, SQLite/PostgreSQL persistence, Linux desktop control,
   and manifest-only install profiles.
@@ -55,13 +54,13 @@ a non-optional peer. Install atomic packages directly or choose a manifest-only
 family/profile; profiles install packages but expose no alias exports and activate nothing:
 
 ```bash
-npm install @arnilo/prism @arnilo/prism-providers            # core + all 17 provider adapters
+npm install @arnilo/prism @arnilo/prism-providers            # core + all provider adapters
 npm install @arnilo/prism @arnilo/prism-core @arnilo/prism-memory   # replaces prism-base
 npm install @arnilo/prism @arnilo/prism-coding-tools @arnilo/prism-mcp @arnilo/prism-providers  # replaces prism-code
 npm install @arnilo/prism @arnilo/prism-core @arnilo/prism-mcp @arnilo/prism-providers          # replaces prism-sdk
 npm install @arnilo/prism @arnilo/prism-core @arnilo/prism-providers  # pick families explicitly (no umbrella)
-npm install @arnilo/prism-server @arnilo/prism-workflows    # optional Web API boundary
-npm install @arnilo/prism-supervisor                         # optional local delegation + A2A 1.0
+npm install @arnilo/prism-core/runtime/server @arnilo/prism-core/runtime/workflows    # optional Web API boundary
+npm install @arnilo/prism-core/runtime/supervisor                         # optional local delegation + A2A 1.0
 npm install @arnilo/prism-web-tools                          # unified web tools family (root search + /browser + /obscura subpaths)
 ```
 
@@ -158,19 +157,22 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' \
 
 ## Packages
 
-| package | purpose |
-|---------|---------|
-| `@arnilo/prism` | core contracts, runtime, registries, CLI/RPC |
-| `@arnilo/prism-core` | runtime/sessions/governance/credentials/enterprise/work/validation family |
-| `@arnilo/prism-providers` | all 17 first-party adapters as `/<adapter>` subpaths (openai, anthropic, google, azure, bedrock, vertex, deepseek, xai, zai, alibaba, kimi, clinepass, neuralwatt, ollama, opencode-go, openrouter, ai-sdk) |
-| `@arnilo/prism-coding-tools` | `/agent`, `/security`, `/document-reader`, `/openapi`, `/computer-use-linux`, `/dev`, `/caveman`, `/ponytail`, `/impeccable` |
-| `@arnilo/prism-web-tools` | Brave/Exa/Firecrawl plus peer-gated `/browser` and `/obscura` |
-| `@arnilo/prism-memory` | memory plus `/rag`, `/compaction/{llm,observational-memory}`, `/graft`, `/wiki` |
-| `@arnilo/prism-mcp` | MCP client/server/OAuth interop |
-| `@arnilo/prism-acp-agent` | ACP adapter |
-| `@arnilo/prism-ag-ui` | AG-UI/A2A/A2UI adapter |
-| `@arnilo/prism-antigravity-agent` | Antigravity CLI adapter |
-| `@arnilo/prism-office` | `/documents`, `/sheets`, `/diagrams` |
+<!-- generated:package-truth:inventory begin -->
+**10 publishable manifests** — root `@arnilo/prism` plus 9 workspace packages (3 `prism-*` family packages, 6 capability packages). Generated by `node scripts/package-truth.mjs --emit-docs` — do not hand-edit.
+
+| 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 |
+<!-- generated:package-truth:inventory end -->
 
 ## Scripts
 
@@ -179,6 +181,7 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' \
 | `npm run build` | Compile TypeScript to `dist/` (core + workspaces) |
 | `npm run typecheck` | Type-check without emitting |
 | `npm test` | Build + run network-free tests |
+| `npm run test:live` | Run live suites whose credentials are present (skip the rest) |
 | `prism --help` | CLI help |
 
 ## Non-goals (v1)

package/dist/agent-run-state.d.ts

@@ -1,4 +1,4 @@
-import type { Agent, AgentRunInterruption, AgentRunRef, AgentRunState, AgentRunStateOptions, AgentRunStatusResult, CheckpointRecord, CheckpointStore, JsonValue, Message, ModelConfig, NestedRunRef, OwnershipScope, RunDecision, RunLimitCounters, StickyDecision, ToolCallContent } from "./contracts.js";
+import type { Agent, AgentRunInterruption, AgentRunRef, AgentRunState, AgentRunStateOptions, CheckpointRecord, CheckpointStore, JsonValue, Message, ModelConfig, NestedRunRef, OwnershipScope, RunDecision, RunLimitCounters, StickyDecision, ToolCallContent } from "./contracts.js";
 import type { SecretRedactor } from "./redaction.js";
 import { type LoadedSkillBodiesEntry } from "./skill-load.js";
 export declare const AGENT_RUN_STATE_NAMESPACE = "prism.agent-run";
@@ -75,7 +75,6 @@ export declare function saveAgentRunState(input: {
     readonly record: CheckpointRecord;
     readonly state: StoredAgentRunState;
 }>;
-export declare function statusFromState(state: StoredAgentRunState, version: number): AgentRunStatusResult;
 export declare function publicState(state: StoredAgentRunState): AgentRunState;
 export declare function initialAgentRunState(input: {
     readonly agent: Agent;

package/dist/agent-run-state.js

@@ -127,9 +127,6 @@ export async function saveAgentRunState(input) {
     });
     return { record, state: { ...bounded, version: record.version } };
 }
-export function statusFromState(state, version) {
-    return { state: publicState({ ...state, version }), version };
-}
 export function publicState(state) {
     const { input: _input, pending: _pending, pendingCalls: _pendingCalls, nestedRuns: _nestedRuns, interruptBeforeTool: _interruptBeforeTool, counters: _counters, deadlineAt: _deadlineAt, ...publicValue } = state;
     return publicValue;

package/dist/agent-session/session/assemble.d.ts

@@ -0,0 +1,6 @@
+/** Context-assembly + runInternal orchestrator (plan 059). */
+import type { ActiveDurableRun } from "../../agent-approval.js";
+import type { AgentRunResult, RunOptions } from "../../contracts.js";
+import type { AgentInput } from "../../input.js";
+import type { SessionHost } from "./types.js";
+export declare function executeRun(session: SessionHost, input: AgentInput, options: RunOptions, runId: string, resumed?: ActiveDurableRun): Promise<AgentRunResult>;

package/dist/agent-session/session/assemble.js

@@ -0,0 +1,391 @@
+/** Context-assembly + runInternal orchestrator (plan 059). */
+import { AgentRunSuspended } from "../../agent-approval.js";
+import { resolveLoop, resolveToolConcurrency } from "../../agent-loops.js";
+import { validateRunStateOptions } from "../../agent-run-state.js";
+import { activeTools } from "../../agent-tool-dispatch.js";
+import { AgentLoopStateError, AgentRunError, AgentRunStateError } from "../../contracts.js";
+import { assertGuardrailsAllowed, runGuardrails } from "../../guardrails.js";
+import { identityTelemetryAttributes, ownershipFromIdentity, resolveRunIdentity } from "../../identity.js";
+import { assembleProviderInput } from "../../input.js";
+import { errorToErrorInfo, redactRunLedgerRecord } from "../../redaction.js";
+import { RunLimitError, RunLimitTracker, resolveRunLimits } from "../../run-limits.js";
+import { createSessionEntry } from "../../session-stores.js";
+import { resolveSkillsDisclosure } from "../../skill-disclosure.js";
+import { applyRestoredSkillBodies } from "../../skill-load.js";
+import { assertStructuredOutputRequestSupported, resolveRunProviderOptions } from "../../structured-output.js";
+import { composeSystemPrompt, mergeSystemPromptConfig } from "../../system-prompts.js";
+import { resolveToolResultFold } from "../../tool-result-fold.js";
+import { createSearchToolsTool, createToolSearchState, resolveToolsDisclosure } from "../../tool-search.js";
+import { createToolRegistry } from "../../tools.js";
+import { bridgeAbort, createUsageAccumulator, inputToMessages, isDurableLoop, isSteerSoftInterrupt, mergeGuardrails, throwIfAborted, } from "../helpers.js";
+import { cleanupRun, persistDurable, persistSucceeded, suspendDurable } from "./persist.js";
+import { generateWithRetry, recordProviderUsage } from "./provider-round.js";
+import { bindChargeToolRound, bindDispatchToolCall, replayDurableNestedAndPending, runLoopUntilSettled, suspendGatedRound, } from "./tool-round.js";
+const PROMPT_VERSION_MAX_NAME_BYTES = 256;
+const PROMPT_VERSION_HASH_PATTERN = /^sha256:[0-9a-f]{64}$/;
+function assertPromptVersionRef(ref) {
+    if (ref === undefined)
+        return undefined;
+    if (typeof ref !== "object" || ref === null)
+        throw new TypeError("RunOptions.promptVersion must be a PromptVersionRef object");
+    const { name, version, hash } = ref;
+    if (typeof name !== "string" || name.length === 0 || Buffer.byteLength(name, "utf8") > PROMPT_VERSION_MAX_NAME_BYTES) {
+        throw new TypeError(`RunOptions.promptVersion.name must be 1-${PROMPT_VERSION_MAX_NAME_BYTES} UTF-8 bytes`);
+    }
+    if (!Number.isInteger(version) || version < 1 || version > 0x7fffffff) {
+        throw new TypeError("RunOptions.promptVersion.version must be an integer in [1, 2147483647]");
+    }
+    if (typeof hash !== "string" || !PROMPT_VERSION_HASH_PATTERN.test(hash)) {
+        throw new TypeError('RunOptions.promptVersion.hash must be "sha256:" plus 64 lowercase hex characters');
+    }
+    return ref;
+}
+async function assembleRoundContext(params) {
+    const { session, input, options, runId, resumed, controller, model, startedAt, promptVersion, metadata, limits, runUsage } = params;
+    session.resolveRunProvider(options);
+    throwIfAborted(controller.signal);
+    session.emit({ type: "agent_started", sessionId: session.id, runId });
+    if (resumed)
+        session.emit({ type: "agent_resumed", sessionId: session.id, runId, version: resumed.version });
+    const startRecord = {
+        id: runId,
+        sessionId: session.id,
+        branchId: session.currentLeafId,
+        model,
+        provider: model.provider,
+        idempotencyKey: session.activeIdempotencyKey,
+        status: "running",
+        startedAt,
+        ...(promptVersion ? { promptVersion } : {}),
+        ...session.activeOwnership,
+    };
+    await session.activeLedger?.appendRun(redactRunLedgerRecord(startRecord, session.activeRedactor));
+    await session.rebuildHistory();
+    const { registry: baseRegistry, tools: activeToolList } = activeTools(session.agent.config.tools);
+    const toolsDisclosure = resolveToolsDisclosure(options.toolsDisclosure, session.agent.config.toolsDisclosure);
+    const toolSearch = toolsDisclosure === "search" && activeToolList.length > 0
+        ? {
+            state: createToolSearchState({
+                tools: activeToolList,
+                activated: session.activatedTools,
+                search: session.agent.config.toolsSearch,
+            }),
+        }
+        : undefined;
+    const searchTool = toolSearch ? createSearchToolsTool(toolSearch.state) : undefined;
+    const registry = searchTool ? createToolRegistry([...activeToolList, searchTool]) : baseRegistry;
+    const tools = searchTool ? [...activeToolList, searchTool] : activeToolList;
+    const activeSkills = session.resolveRunSkills(options, tools);
+    session.activeRunSkills = activeSkills;
+    if (options.model && JSON.stringify(options.model) !== JSON.stringify(session.agent.config.model)) {
+        await session.appendEntry(createSessionEntry({
+            sessionId: session.id,
+            parentId: session.currentLeafId,
+            runId,
+            kind: "model_change",
+            previousModel: session.agent.config.model,
+            model: options.model,
+        }));
+    }
+    const inputMessages = inputToMessages(input).map((message) => session.redact(message));
+    const inputGuardrails = await runGuardrails({
+        stage: "input",
+        guardrails: session.activeGuardrails,
+        value: inputMessages,
+        context: { sessionId: session.id, runId, metadata, signal: controller.signal },
+        redactor: session.activeRedactor,
+        emit: (event) => session.emit(event),
+    });
+    const approvedByResume = resumed !== undefined && inputGuardrails.terminal?.action === "interrupt" && session.activeDurable !== undefined;
+    if (inputGuardrails.terminal?.action === "interrupt" && session.activeDurable && !approvedByResume) {
+        const interruption = { kind: "input_guardrail", reason: inputGuardrails.terminal.reason ?? "Input requires approval" };
+        throw new AgentRunSuspended(await suspendDurable(session, { runId, model, limits, interruption, messages: inputMessages }), interruption);
+    }
+    if (inputGuardrails.terminal && !approvedByResume)
+        assertGuardrailsAllowed(inputGuardrails);
+    for (const message of inputMessages)
+        await session.appendMessage(message, runId);
+    await session.autoCompact(runId, options, controller.signal, inputMessages);
+    const maxToolRounds = resolveRunLimits(session.agent.config.limits, options.limits).maxToolRounds;
+    const systemInstructions = composeSystemPrompt(mergeSystemPromptConfig(session.agent.config.systemPrompt, options.systemPrompt), {
+        base: session.agent.config.instructions,
+    });
+    const contextProviders = [...(session.agent.config.context ?? []), ...activeSkills.flatMap((skill) => skill.context ?? [])];
+    const providerOptions = resolveRunProviderOptions(options, session.agent.config);
+    assertStructuredOutputRequestSupported(options.model ?? session.agent.config.model, providerOptions);
+    const validate = options.validate ?? session.agent.config.validator;
+    const instructionInjectors = options.instructionInjectors ?? session.agent.config.instructionInjectors ?? [];
+    const inputLayout = options.inputLayout ?? session.agent.config.inputLayout;
+    const loop = resolveLoop(options, session.agent.config);
+    session.activeLoop = loop;
+    const toolConcurrency = resolveToolConcurrency(options, session.agent.config);
+    session.activeLoopTurn = 1;
+    const ctx = {
+        session,
+        input,
+        options,
+        runId,
+        resumed,
+        controller,
+        model,
+        metadata,
+        limits,
+        registry,
+        tools,
+        activeSkills,
+        inputMessages,
+        maxToolRounds,
+        systemInstructions,
+        contextProviders,
+        providerOptions,
+        validate,
+        instructionInjectors,
+        inputLayout,
+        loop,
+        toolConcurrency,
+        toolsDisclosure,
+        assembledTurn: false,
+        artifactFinished: false,
+        artifactFailedInfo: undefined,
+        runUsage,
+        loopCtx: undefined,
+    };
+    const loopCtx = {
+        sessionId: session.id,
+        runId,
+        metadata,
+        signal: controller.signal,
+        history: session.history,
+        input,
+        inputMessages,
+        maxToolRounds,
+        toolConcurrency,
+        restoredLoopState: resumed?.state?.loopState?.snapshot,
+        assemble: async (nextInput, toolResults, turn) => {
+            limits.charge("maxTurns");
+            const request = await assembleProviderInput({
+                model: options.model ?? session.agent.config.model,
+                input: nextInput,
+                history: session.history,
+                summaries: (await session.snapshot()).summaries,
+                toolResults: toolResults ?? [],
+                turn,
+                instructionInjectors,
+                inputLayout,
+                systemInstructions,
+                inputBuilder: session.agent.config.inputBuilder,
+                promptBuilder: session.agent.config.promptBuilder,
+                contextProviders,
+                skills: session.restoredSkillBodies.length ? applyRestoredSkillBodies(activeSkills, session.restoredSkillBodies) : activeSkills,
+                skillsDisclosure: resolveSkillsDisclosure(options.skillsDisclosure, session.agent.config.skillsDisclosure),
+                toolsDisclosure,
+                toolsSearch: session.agent.config.toolsSearch,
+                activatedTools: session.activatedTools,
+                toolResultFold: resolveToolResultFold(options.toolResultFold, session.agent.config.toolResultFold),
+                loadedSkills: session.loadedSkills,
+                tools,
+                resourceLoader: session.agent.config.resourceLoader,
+                permission: session.agent.config.permission,
+                trust: session.agent.config.trust,
+                providerOptions,
+                redactor: session.activeRedactor,
+                middleware: session.agent.config.middleware,
+                sessionId: session.id,
+                runId,
+                metadata,
+                signal: controller.signal,
+            });
+            ctx.assembledTurn = true;
+            return request;
+        },
+        chargeToolRound: bindChargeToolRound(ctx),
+        generate: async (request) => {
+            await suspendGatedRound(ctx);
+            if (!ctx.assembledTurn)
+                limits.charge("maxTurns");
+            ctx.assembledTurn = false;
+            const policyResult = await session.applyProviderRequestPolicies(request, runId, options, metadata, controller.signal);
+            const middlewareRequest = (await session.agent.config.middleware?.run("provider_request", policyResult.request)) ?? policyResult.request;
+            try {
+                return await generateWithRetry(session, session.redactProviderRequest(middlewareRequest), runId, options, controller.signal, policyResult.secrets, session.activeLoopTurn, (turnUsage, turn, attempt) => recordProviderUsage(ctx, turnUsage, turn, attempt));
+            }
+            catch (error) {
+                if (isSteerSoftInterrupt(error)) {
+                    return { content: [], calls: [], started: false, usage: undefined };
+                }
+                throw error;
+            }
+        },
+        isToolCallExclusive: (call) => registry.get(call.name)?.exclusive === true,
+        dispatchToolCall: bindDispatchToolCall(ctx),
+        appendMessage: (message) => session.appendMessage(message, runId),
+        hasPendingSteers: () => session.pendingSteers.length > 0,
+        applyPendingSteers: () => session.applyPendingSteers(runId, metadata, controller.signal),
+        emit: (event) => {
+            if (event.type === "turn_started")
+                session.activeLoopTurn = event.turn;
+            if (event.type === "artifact_finished")
+                ctx.artifactFinished = true;
+            if (event.type === "artifact_failed") {
+                const first = event.result.errors?.[0];
+                const reason = event.result.metadata?.reason;
+                ctx.artifactFailedInfo = {
+                    message: first?.message ?? "artifact failed",
+                    code: typeof reason === "string" || typeof reason === "number" ? reason : "artifact_failed",
+                };
+            }
+            session.emit(event);
+        },
+    };
+    ctx.loopCtx = loopCtx;
+    return ctx;
+}
+export async function executeRun(session, input, options, runId, resumed) {
+    const legacyMaxToolRounds = options.maxToolRounds;
+    if (legacyMaxToolRounds !== undefined) {
+        throw new TypeError("RunOptions.maxToolRounds was removed in 0.1.5; use RunOptions.limits.maxToolRounds instead");
+    }
+    const promptVersion = assertPromptVersionRef(options.promptVersion);
+    if (session.agent.config.secure &&
+        (options.redactor !== undefined ||
+            options.ownership !== undefined ||
+            options.validate !== undefined ||
+            options.effectStore !== undefined ||
+            options.runState !== undefined)) {
+        throw new AgentRunStateError("Secure agent defaults cannot be replaced per run");
+    }
+    const requestedLimits = options.limits;
+    const resolvedLimits = resolveRunLimits(session.agent.config.limits, requestedLimits);
+    const durableOptions = options.runState ?? session.agent.config.runState;
+    if (session.agent.config.runState && options.runState && session.agent.config.runState !== options.runState) {
+        throw new AgentRunStateError("RunOptions cannot replace agent durable run-state configuration");
+    }
+    if (durableOptions) {
+        validateRunStateOptions(durableOptions);
+        if (options.model || options.guardrails || options.loop || options.effectStore)
+            throw new AgentRunStateError("Durable runs require model, guardrails, loop, and effect store on AgentConfig for fingerprinting");
+        const configuredLoop = session.agent.config.loop;
+        if (configuredLoop && !isDurableLoop(configuredLoop)) {
+            throw new AgentLoopStateError("ERR_PRISM_LOOP_NOT_DURABLE", "Custom AgentLoopStrategy on a durable run requires snapshot and restore hooks");
+        }
+    }
+    if (session.activeRun) {
+        const error = new Error("Agent session already has an active run");
+        session.emit({ type: "error", sessionId: session.id, runId, error: errorToErrorInfo(error) });
+        throw error;
+    }
+    const controller = new AbortController();
+    const cleanupSignal = bridgeAbort(options.signal, controller);
+    session.activeRun = controller;
+    session.activeRunId = runId;
+    session.pendingSteers = [];
+    session.pendingSteerBytes = 0;
+    session.pendingSoftInterrupt = false;
+    session.activeRedactor = options.redactor ?? session.agent.config.redactor;
+    session.activeLedger = options.runLedger ?? session.agent.config.runLedger;
+    session.activeEffectStore = options.effectStore ?? session.agent.config.effectStore;
+    session.activeOwnership = options.ownership ?? session.agent.config.ownership;
+    session.activeIdentity = resolveRunIdentity(options.identity, session.agent.config.identity, session.activeOwnership);
+    if (session.activeIdentity && !session.activeOwnership)
+        session.activeOwnership = ownershipFromIdentity(session.activeIdentity);
+    session.activeIdempotencyKey = options.idempotencyKey ?? session.agent.config.idempotencyKey;
+    session.activeGuardrails = mergeGuardrails(session.agent.config.guardrails, options.guardrails);
+    session.activeDurable = resumed ?? (durableOptions ? { options: durableOptions, version: 0 } : undefined);
+    session.activeGatedRound = undefined;
+    if (resumed)
+        session.invalidateSnapshot();
+    const model = options.model ?? session.agent.config.model;
+    const startedAt = new Date().toISOString();
+    let runError;
+    let runStatus = "succeeded";
+    const runUsage = createUsageAccumulator();
+    let usage;
+    const metadata = {
+        ...session.agent.config.metadata,
+        ...session.metadata,
+        ...options.metadata,
+        ...(session.activeIdentity ? identityTelemetryAttributes(session.activeIdentity) : {}),
+    };
+    session.activeMetadata = metadata;
+    session.activePromptVersion = promptVersion;
+    const limits = new RunLimitTracker(resolvedLimits, {
+        onExceeded: (breach) => {
+            session.emit({ type: "run_limit_exceeded", sessionId: session.id, runId, breach });
+            controller.abort(new RunLimitError(breach));
+        },
+        snapshot: resumed?.state?.counters,
+        deadlineAt: resumed?.state?.deadlineAt,
+    });
+    session.activeLimits = limits;
+    session.activeLimitOutputBuffer = [session.agent.config.limits, requestedLimits].some((value) => value?.maxOutputTokens !== undefined || value?.maxTotalTokens !== undefined || value?.maxCost !== undefined);
+    try {
+        const ctx = await assembleRoundContext({
+            session,
+            input,
+            options,
+            runId,
+            resumed,
+            controller,
+            model,
+            startedAt,
+            promptVersion,
+            metadata,
+            limits,
+            runUsage,
+        });
+        await replayDurableNestedAndPending(ctx);
+        const resumedLoopState = resumed?.state?.loopState;
+        if (resumedLoopState) {
+            if (ctx.loop.name !== resumedLoopState.name || (ctx.loop.revision ?? "1") !== resumedLoopState.revision) {
+                throw new AgentLoopStateError("ERR_PRISM_LOOP_REVISION", `Loop ${resumedLoopState.name} revision ${resumedLoopState.revision} does not match the resumed durable run`);
+            }
+            ctx.loop.restore?.(resumedLoopState.snapshot);
+        }
+        const loopUsage = await runLoopUntilSettled(ctx);
+        if (ctx.loop.name === "generate-validate-revise" && !ctx.artifactFinished) {
+            throw Object.assign(new Error(ctx.artifactFailedInfo?.message ?? "artifact loop ended without a validated artifact"), {
+                name: "ArtifactFailed",
+                code: ctx.artifactFailedInfo?.code ?? "artifact_failed",
+            });
+        }
+        usage = runUsage.value() ?? loopUsage;
+        return await persistSucceeded(ctx, loopUsage);
+    }
+    catch (error) {
+        if (error instanceof AgentRunSuspended) {
+            runStatus = "suspended";
+            const version = error.state.version;
+            session.emit({ type: "agent_suspended", sessionId: session.id, runId, interruption: error.interruption, version });
+            return session.buildRunResult({ runId, status: "suspended", runState: error.state, interruption: error.interruption });
+        }
+        runError = errorToErrorInfo(error);
+        session.emit({ type: "error", sessionId: session.id, runId, error: runError });
+        const breach = error instanceof RunLimitError ? error.breach : limits.breach;
+        runStatus = breach ? "failed" : controller.signal.aborted ? "aborted" : "failed";
+        const runState = session.activeDurable?.state
+            ? await persistDurable(session, {
+                ...session.activeDurable.state,
+                status: runStatus,
+                interruption: undefined,
+                loopState: undefined,
+                pendingCalls: undefined,
+                nestedRuns: undefined,
+                stickyDecisions: undefined,
+            })
+            : undefined;
+        const result = session.buildRunResult({
+            runId,
+            status: runStatus,
+            usage: runUsage.value() ?? usage,
+            limit: breach,
+            error: runError,
+            abortReason: !breach && controller.signal.aborted ? String(controller.signal.reason) : undefined,
+            runState,
+        });
+        throw new AgentRunError(result, { cause: error });
+    }
+    finally {
+        await cleanupRun({ session, controller, cleanupSignal, runId, model, startedAt, runStatus, runError });
+    }
+}
+//# sourceMappingURL=assemble.js.map

package/dist/agent-session/session/persist.d.ts

@@ -0,0 +1,28 @@
+/** Finalize/persist phase of runInternal (plan 059). */
+import type { PendingToolCall, StoredAgentRunState } from "../../agent-run-state.js";
+import type { AgentRunResult, AgentRunState, ErrorInfo, Message, ModelConfig, NestedRunRef, Usage } from "../../contracts.js";
+import type { RunLimitTracker } from "../../run-limits.js";
+import type { RoundContext, SessionHost } from "./types.js";
+export declare function persistDurable(session: SessionHost, state: StoredAgentRunState): Promise<AgentRunState>;
+export declare function suspendDurable(session: SessionHost, input: {
+    readonly runId: string;
+    readonly model: ModelConfig;
+    readonly limits: RunLimitTracker;
+    readonly interruption: import("../../contracts.js").AgentRunInterruption;
+    readonly messages?: readonly Message[];
+    readonly pending?: StoredAgentRunState["pending"];
+    readonly pendingCalls?: readonly PendingToolCall[];
+    /** Full replacement when provided; otherwise the recorded nested runs are preserved. */
+    readonly nestedRuns?: readonly NestedRunRef[];
+}): Promise<AgentRunState>;
+export declare function persistSucceeded(ctx: RoundContext, loopUsage: Usage | undefined): Promise<AgentRunResult>;
+export declare function cleanupRun(input: {
+    session: SessionHost;
+    controller: AbortController;
+    cleanupSignal: () => void;
+    runId: string;
+    model: ModelConfig;
+    startedAt: string;
+    runStatus: AgentRunResult["status"];
+    runError: ErrorInfo | undefined;
+}): Promise<void>;