@graphorin/agent 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,119 @@
 # @graphorin/agent
 
+## 0.6.1
+
+### Patch Changes
+
+- [#142](https://github.com/o-stepper/graphorin/pull/142) [`436d6ca`](https://github.com/o-stepper/graphorin/commit/436d6ca5ebbd16df094e915682d3915c279a8430) Thanks [@o-stepper](https://github.com/o-stepper)! - Version constants and version-bearing strings now derive from each package's manifest at build time (`VERSION = pkg.version`; writer ids, client/server info, OTLP framework attributes, build-info metrics interpolate it). No behavioral change at the current version: the rendered strings are byte-identical. A release bump no longer edits source; the new `check-version-consistency` gate fails any reintroduced hardcoded framework version.
+
+- Updated dependencies [[`826ee59`](https://github.com/o-stepper/graphorin/commit/826ee5933ad38693b0dd2f20a110abfecba7d23d), [`436d6ca`](https://github.com/o-stepper/graphorin/commit/436d6ca5ebbd16df094e915682d3915c279a8430)]:
+  - @graphorin/observability@0.6.1
+  - @graphorin/core@0.6.1
+  - @graphorin/memory@0.6.1
+  - @graphorin/provider@0.6.1
+  - @graphorin/security@0.6.1
+  - @graphorin/skills@0.6.1
+  - @graphorin/tools@0.6.1
+
+## 0.6.0
+
+### Minor Changes
+
+- [#136](https://github.com/o-stepper/graphorin/pull/136) [`17a2d30`](https://github.com/o-stepper/graphorin/commit/17a2d30564154ca2ab87473335cdef43a5089c84) Thanks [@o-stepper](https://github.com/o-stepper)! - Prompt-cache economics end-to-end (audit 2026-07-04 Wave C, cluster C1).
+
+  - `Usage` gains `cachedReadTokens` / `cacheWriteTokens` (subsets of `promptTokens`), mapped by the vercel adapter (v7 `inputTokenDetails`; reasoning split kept exclusive of `completionTokens`) and the OpenAI-compatible adapter (`prompt_tokens_details.cached_tokens`); the fields flow through step/run aggregation, `usageByModel`, run-state (de)serialization and `withCostTracking` (new `cachedReadPerMtok`/`cacheWritePerMtok` lookup rates, full-input-rate fallback).
+  - New opt-in `ProviderRequest.cachePolicy` / `AgentConfig.cachePolicy` (`{ breakpoints: 'auto', ttl? }`): the vercel adapter anchors Anthropic `cache_control` on the first and last conversation messages so the stable prefix is written once and read at the discounted rate every later step.
+  - `ModelPrice` gains `cacheWriteUsdPerToken`; `calculateCost` bills cache writes; the bundled pricing snapshot is regenerated (2026-07-04) with current Anthropic 4.x / OpenAI gpt-5 + gpt-4.1 + o3/o4-mini / Gemini 2.5 families (legacy ids retained), `lookupPrice` resolves dated ids via a date-suffix fallback, and a new snapshot-coverage release gate cross-checks the model-tier classifier against the snapshot with an explicit known-unpriced allowlist (post-cutoff models report null cost + WARN instead of invented numbers).
+  - Cache-friendly catalogue: handoff tools serialize BEFORE the growing promoted section (byte-stable prefix under `tool_search` promotions), and new `toolPromotion: 'run-boundary'` freezes the advertised catalogue for a whole run while still persisting discoveries.
+
+- [#136](https://github.com/o-stepper/graphorin/pull/136) [`17a2d30`](https://github.com/o-stepper/graphorin/commit/17a2d30564154ca2ab87473335cdef43a5089c84) Thanks [@o-stepper](https://github.com/o-stepper)! - Agent harness quality (audit 2026-07-04 Wave C, cluster C3).
+
+  - Recoverable error envelope: `ToolError` gains `recoverable` + `recoveryHint` (retry_later / check_input / try_alternative / report_to_user), stamped from the kind at the executor's completion funnel and rendered to the model as a bracketed recovery line under the familiar `Error: <message>`.
+  - Transparent bounded tool retry: `rate_limited` outcomes from pure/read-only tools (or tools with an `idempotencyKey`) silently re-execute with exponential backoff up to 3 total attempts (`ToolRateLimitError.retryAfterMs` wins); tune via executor `retry` / `AgentConfig.toolRetry`.
+  - Verifier seam: `AgentConfig.verifiers` run deterministic checks on every terminal response, emit `verifier.result` events, feed failures back as a user message and continue up to `maxVerifierRounds` (default 1); throwing verifiers count as passed. Deliberately no evidence-free self-reflection step.
+  - ACI: empty successful tool output renders as an explicit `(tool ran successfully with no output)` marker.
+  - Deterministic replay: opt-in `recordProviderResponses` journals each step's raw model response onto `RunState.steps[].providerResponse`; new `createReplayProvider(state)` re-drives a run offline and fails loudly on divergence.
+
+- [#136](https://github.com/o-stepper/graphorin/pull/136) [`17a2d30`](https://github.com/o-stepper/graphorin/commit/17a2d30564154ca2ab87473335cdef43a5089c84) Thanks [@o-stepper](https://github.com/o-stepper)! - Deterministic security adoptions (audit 2026-07-04 Wave C, cluster C6).
+
+  - Derived-taint propagation: opt-in `dataFlowPolicy.derivedTaint: 'strict'` fires the paraphrase-robust `derived-untrusted-to-sink` flow for every model-driven sink call once untrusted content entered the run (CaMeL-style control-flow integrity); the agent also records each tainted step's assistant text as `llm-derived` spans so model-echoed phrasing trips the verbatim probe.
+  - Taint into memory (cross-session MINJA leg): `ToolReturn` gains a widen-only `taint` override honoured through the executor record path; `fact_search` / `deep_recall` / `recall_episodes` attach it when any returned item is quarantined or foreign-provenance, re-arming the ledger at recall. `RunState.taintSummary` additionally carries one-way FNV-1a span-tile hashes (no plaintext), so a resumed run re-detects pre-suspend verbatim copies.
+  - MCP pinning completed: `toTools({ pinStore })` records fingerprints on first use and REJECTS drift by default when a store is present (rug-pull defense; `onPinMismatch: 'warn'` downgrades); tool-description injection hits at registration are counted (`mcp.tool-description.injection-flagged.total`).
+  - Signal-only heuristics + Unicode pre-pass: shared `normalizeForMatching` (NFKC + zero-width strip) applied in the guardrails injection catalogue and the memory quarantine heuristics; security.md repositions all pattern catalogues as best-effort signal, never a sole gate. `TaintLabel.sourceKind` widened to `string` for the new descriptive kinds.
+
+- [#136](https://github.com/o-stepper/graphorin/pull/136) [`17a2d30`](https://github.com/o-stepper/graphorin/commit/17a2d30564154ca2ab87473335cdef43a5089c84) Thanks [@o-stepper](https://github.com/o-stepper)! - Trace-tree observability (audit 2026-07-04 Wave C, cluster C7; pairs periphery-04).
+
+  The agent loop now emits the previously-declared `agent.run` span per run and `agent.step` spans per step (parented under the run); `tool.execute` parents under the current step via the new optional `RunContext.span`; a `withTracing`-wrapped provider parents under the step via the new `ProviderRequest.parentSpan` (a live handle like `signal`). Attributes align to the OTel GenAI semantic conventions (`gen_ai.operation.name`, `gen_ai.agent.id/name`, `gen_ai.tool.name`, `gen_ai.request.model`, `gen_ai.usage.input_tokens/output_tokens`), parent-based sampling finally has parents to follow, and observability.md documents the real tree plus the memory-tier-spans-not-yet-parented limitation.
+
+- [#137](https://github.com/o-stepper/graphorin/pull/137) [`ce06b47`](https://github.com/o-stepper/graphorin/commit/ce06b472af9e30ac5d0792f7a8b6f42170a94627) Thanks [@o-stepper](https://github.com/o-stepper)! - Sub-agent isolation & orchestration primitives (audit 2026-07-04 Wave D, cluster D2).
+
+  - Run-level `'read-only'` capability (single-writer constraint): `AgentConfig.capability` / `AgentCallOptions.capability` never advertise writer tools or handoffs and the executor deterministically blocks fabricated writer calls with the new `capability_blocked` `ToolErrorKind` (threaded through `executeBatch`/`executeOne`, HITL resume, and the code-mode bridge).
+  - `toTool({ contextFold })` returns a compact distilled child-run outcome instead of raw output; `toTool({ propagateTaint })` (default on) carries the child's coarse taint flags across the fold as a widen-only `ToolReturn.taint` override (`sourceKind: 'sub-agent'`) that re-arms the parent's data-flow ledger.
+
+- [#137](https://github.com/o-stepper/graphorin/pull/137) [`ce06b47`](https://github.com/o-stepper/graphorin/commit/ce06b472af9e30ac5d0792f7a8b6f42170a94627) Thanks [@o-stepper](https://github.com/o-stepper)! - Security hardening (audit 2026-07-04 Wave D, cluster D4) - architectural, deterministic layers.
+
+  - RFC-6962 Merkle transparency over the audit log (`@graphorin/security/audit`): tree head, inclusion + consistency proofs, and Ed25519-signed checkpoints, so anchoring a signed head out-of-band makes the trail tamper-resistant (a rewrite of a checkpointed prefix fails the consistency proof).
+  - Operator trust root for skills: `verifySkillSignature`/`installSkillFrom{Npm,Git}` gain `trustRoot` - a valid signature from a key absent from the root returns `valid: false` reason `'untrusted-key'`.
+  - Progent-style tool-argument policies + Rule-of-Two capability profiles (`@graphorin/security/policy`): `AgentConfig.toolPolicy` (forbid-before-allow, default-deny sensitive) + `ruleOfTwo` (drops a lethal-trifecta leg, forcing a read-only capability floor) enforced by a new `ExecutorOptions.argumentPolicy` hook (`capability_blocked`).
+  - Code-mode sandbox blocklist parity (`bridged-source.ts`) blocks the process-escape modules (child_process/vm/worker_threads/cluster/inspector) via the ESM resolve hook + a CJS `Module._load` patch.
+
+- [#137](https://github.com/o-stepper/graphorin/pull/137) [`ce06b47`](https://github.com/o-stepper/graphorin/commit/ce06b472af9e30ac5d0792f7a8b6f42170a94627) Thanks [@o-stepper](https://github.com/o-stepper)! - Context engineering trial (audit 2026-07-04 Wave D, cluster D6) - opt-in; tool surface unchanged by default.
+
+  - Structured plan tool (`update_plan`, TodoWrite-style full-replace checklist) journaled in the new `RunState.todos` (core `TodoItem`), surviving suspend/resume via the strict run-state (de)serializer.
+  - Attention recitation: the current plan is rendered into a compact `<plan>` block appended to each step's request copy - request-only and cache-layout-aware (rides the last prompt-cache anchor, never touches the shared buffer or persisted state).
+  - `AgentConfig.plan` opt-in. Progress files, resume-recap injection, and the degraded-mode ladder are documented as trial follow-ups.
+
+### Patch Changes
+
+- [#134](https://github.com/o-stepper/graphorin/pull/134) [`32f20c1`](https://github.com/o-stepper/graphorin/commit/32f20c110f184f8cef7eec85bf39f5f07c886cb6) Thanks [@o-stepper](https://github.com/o-stepper)! - Fix three context-assembly defects (context-engine-02/03/04). The default post-compaction hooks (persona block, project rules, pinned facts) now apply the same D2 privacy decision as `assemble()`, so `sensitivity:'secret'` content the assembly withholds can no longer leak to the provider via the post-compaction splice. `renderMessageText` renders assistant tool-call arguments and `adaptTokenCounter` preserves the native `count(messages)` path, so tool-call args (file writes, code_execute scripts) finally contribute to trigger/before/after token arithmetic. And the trigger, SOTA-4 reclaim floor, and anti-thrash guard now share one full-buffer basis: `shouldCompact` takes `compactableFromIndex` (the pinned prefix is no longer counted as reclaimable) and `compactNow` takes `prefixMessages` so the guard arms against prefix + body + essentials instead of the sliced body - previously any real system prompt defeated the guard and a summarizer LLM call re-fired every step at the context edge.
+
+- [#134](https://github.com/o-stepper/graphorin/pull/134) [`32f20c1`](https://github.com/o-stepper/graphorin/commit/32f20c110f184f8cef7eec85bf39f5f07c886cb6) Thanks [@o-stepper](https://github.com/o-stepper)! - Make durable HITL exactly-once and gate approvals on validated input (agent-02, tools-02, agent-07). With a `checkpointStore` wired, the resume now persists a write-ahead intent checkpoint before dispatching approved calls and the journaled post-dispatch state after - so a re-delivered resume from the latest checkpoint (or from `result.state` in the manual JSON flow) cannot double-fire a side effect; re-resuming a stale pre-execution snapshot stays bounded at one re-execution. The executor validates (and repairs) args BEFORE the approval flow, evaluates `needsApproval` on the validated input, and the approval record carries the post-repair args a human actually vets; the agent pre-screen mirrors this (schema-invalid gated calls fail fast as `invalid_input`, never reaching a human) and the resumed dispatch runs with repair disabled so nothing can rewrite an approved payload behind the grant. Partial approval directives now execute the granted calls and re-suspend with the remainder instead of silently discarding grants. The FAQ and agent-runtime guide are rewritten to state the real exactly-once contract.
+
+- [#134](https://github.com/o-stepper/graphorin/pull/134) [`32f20c1`](https://github.com/o-stepper/graphorin/commit/32f20c110f184f8cef7eec85bf39f5f07c886cb6) Thanks [@o-stepper](https://github.com/o-stepper)! - Enforce transcript well-formedness so no path emits provider-rejected message sequences (agent-01, tools-07, context-engine-01). The durable-HITL pre-screen now collects EVERY approval-gated call in a step (not just the first) and executes the non-gated remainder before suspending, so the persisted transcript never carries dangling `tool_use` ids; `executeBatch` synthesizes an `execution_failed` outcome instead of silently dropping a slot whose `executeOne` rejected (e.g. a throwing tracer); summarize-compaction snaps its boundary backward so the preserved window never starts with an orphan `tool` message. The agent mock-provider harness now asserts transcript well-formedness on every request by default.
+
+- [#134](https://github.com/o-stepper/graphorin/pull/134) [`32f20c1`](https://github.com/o-stepper/graphorin/commit/32f20c110f184f8cef7eec85bf39f5f07c886cb6) Thanks [@o-stepper](https://github.com/o-stepper)! - Fix critical tool-schema wire bug (tools-01): plain Zod schemas were never converted to JSON Schema, so OpenAI-shaped/Ollama/vercel providers received `{"_def":...}` internals as tool `parameters` and MCP tools serialized to `{}`. Adds a shared structural Zod v3/v4 to JSON Schema converter (`@graphorin/tools/schema`, no new dependencies) used by the agent's `toolToDefinition`, the code-mode signature projection, and `ToolSearchMatch`; MCP's `buildJsonSchemaValidator` now retains the source JSON Schema and exposes it via `toJSON()`. Unprojectable schemas degrade loudly (WARN + permissive `{}`) instead of shipping serialized validator internals.
+
+- [#135](https://github.com/o-stepper/graphorin/pull/135) [`4f850d9`](https://github.com/o-stepper/graphorin/commit/4f850d9bc0a05d6256c59c5117b010336fcb41d3) Thanks [@o-stepper](https://github.com/o-stepper)! - Spill-handle producer taint now survives executor and process boundaries (audit 2026-07-04 Wave B, cluster B2; tools-03 / security-02 / agent-08).
+
+  - The default spill writer persists a `<file>.meta.json` sidecar (mode 0600) recording `{producerTrustClass, source, sensitivity}` next to every artifact; `createFileResultReader` recovers it and reports the producer class (plus source/sensitivity) on the read outcome. An untrusted spill produced in one executor (code-mode's quiet executor) or a prior process can no longer launder to trusted through the `read_result` built-in: the executor re-applies the producer's sanitization policy and records dataflow provenance under the producer's class.
+  - Producer taint is resolved BEFORE truncation, so a re-spill of a handle read persists the original producer's taint into the new artifact's sidecar, and a secret-produced body keeps its secret tier through re-spill (stays off disk).
+  - The agent snapshots the coarse taint summary and the promoted-tool set on EVERY exit through the run finalizer, not just the approval suspend: aborted runs (resumable) and completed runs (re-entered as follow-ups) now rehydrate the enforce-mode sink gate and the discovered-tool catalogue.
+
+- [#135](https://github.com/o-stepper/graphorin/pull/135) [`4f850d9`](https://github.com/o-stepper/graphorin/commit/4f850d9bc0a05d6256c59c5117b010336fcb41d3) Thanks [@o-stepper](https://github.com/o-stepper)! - Compaction-seam hardening (audit 2026-07-04 Wave B, cluster B4).
+
+  - context-engine-05: the agent's pinned-prefix scan stops at the `<graphorin_compaction_summary>` marker, so a compaction summary resumed from a suspended run stays compactable instead of being absorbed into the uncompactable prefix (one extra pinned summary per compact-then-resume cycle).
+  - context-engine-06: hard context overflow gets a last-resort tier - on a `context-length` provider error the agent forces ONE aggressive compaction (`preserveRecentTurns: 2`) and retries the same provider before walking the fallback chain or failing. Thrown `ProviderHttpError`s now classify by their canonical `errorKind`, so a thrown 429 / overflow is treated like the structured-event equivalent.
+  - context-engine-07: the summarizer prompt's older-messages dump is capped (default 96k chars, `summarizerInputCharBudget` strategy option; oldest lines elided with a marker) so pointing `summarizerModel` at a smaller model no longer overflows its window and silently disables compaction.
+  - context-engine-09: `<<<older_messages>>>` / `<<</older_messages>>>` sequences inside message text are neutralized before entering the summarizer prompt's data-only envelope - a tool result carrying the closing marker can no longer inject instructions into the summarizer.
+  - context-engine-10: new integration test drives the REAL context engine through the agent loop with tool loops crossing the threshold; the mock provider's transcript invariant validates every post-compaction request.
+
+- [#136](https://github.com/o-stepper/graphorin/pull/136) [`17a2d30`](https://github.com/o-stepper/graphorin/commit/17a2d30564154ca2ab87473335cdef43a5089c84) Thanks [@o-stepper](https://github.com/o-stepper)! - Eval honesty (audit 2026-07-04 Wave C, cluster C8; pairs evals-01..07/09).
+
+  The LongMemEval runner drops the harness-side keyword fan-out booster (numbers now measure the real search path), gains `--retrieval default|multi-query|hyde|iterative|graph` + `--embedder none|fake` A/B switches that wire the real library config, stamps a `benchConfig` block into every report, grades with a dedicated `--judge-provider` (self-judged real runs WARN and refuse to seed `--json` baselines without `--allow-self-judge`), reports pass rate as mean +/- stddev under `--iterations N` plus an abstention-rate aggregate, caches the in-flight ingest PROMISE (no concurrent double-ingest), and ships a committed deterministic stub+fixture baseline exercised by a new offline plumbing-gate step in the dispatch workflow. New adaptive injected-task scenarios (verbatim / unicode-obfuscated / split / paraphrase) gate the dataflow-policy defense claims both ways in the agent test suite.
+
+- [#138](https://github.com/o-stepper/graphorin/pull/138) [`6293a25`](https://github.com/o-stepper/graphorin/commit/6293a2531c5c9265294da22fb365a08f2bdf445a) Thanks [@o-stepper](https://github.com/o-stepper)! - OTel GenAI alignment + honest eval statistics (audit 2026-07-04 Wave E, cluster E8).
+
+  - Span names follow the GenAI semconv `{operation} {target}` shape when attributes carry the target (`chat <model>`, `execute_tool <tool>`, `invoke_agent <agent>`); the operation-mapping table and `GenAIOperationName` gain `invoke_agent` to match what the runtime actually emits; `agent.step` spans carry `gen_ai.agent.name`; pricing's `listMissingModels` reads the current `gen_ai.provider.name` attribute first (deprecated `gen_ai.system` kept as fallback).
+  - New `@graphorin/evals` stats module: `mean`/`sampleStddev`, Wilson 95% interval, `passHatK` over `-iter-N` outcomes, and McNemar paired significance. `runEvals` summaries always carry `passRateCi` and (under `iterations > 1`) `passHatK`; `detectRegressions` annotates pass-rate-drop findings with the paired regressed/improved counts + p-value, and opt-in `requireSignificance` vetoes drops the paired test cannot distinguish from noise - the fixed tolerance alone was sample-size blind.
+
+- Updated dependencies [[`32f20c1`](https://github.com/o-stepper/graphorin/commit/32f20c110f184f8cef7eec85bf39f5f07c886cb6), [`32f20c1`](https://github.com/o-stepper/graphorin/commit/32f20c110f184f8cef7eec85bf39f5f07c886cb6), [`32f20c1`](https://github.com/o-stepper/graphorin/commit/32f20c110f184f8cef7eec85bf39f5f07c886cb6), [`32f20c1`](https://github.com/o-stepper/graphorin/commit/32f20c110f184f8cef7eec85bf39f5f07c886cb6), [`32f20c1`](https://github.com/o-stepper/graphorin/commit/32f20c110f184f8cef7eec85bf39f5f07c886cb6), [`32f20c1`](https://github.com/o-stepper/graphorin/commit/32f20c110f184f8cef7eec85bf39f5f07c886cb6), [`4f850d9`](https://github.com/o-stepper/graphorin/commit/4f850d9bc0a05d6256c59c5117b010336fcb41d3), [`4f850d9`](https://github.com/o-stepper/graphorin/commit/4f850d9bc0a05d6256c59c5117b010336fcb41d3), [`4f850d9`](https://github.com/o-stepper/graphorin/commit/4f850d9bc0a05d6256c59c5117b010336fcb41d3), [`4f850d9`](https://github.com/o-stepper/graphorin/commit/4f850d9bc0a05d6256c59c5117b010336fcb41d3), [`4f850d9`](https://github.com/o-stepper/graphorin/commit/4f850d9bc0a05d6256c59c5117b010336fcb41d3), [`4f850d9`](https://github.com/o-stepper/graphorin/commit/4f850d9bc0a05d6256c59c5117b010336fcb41d3), [`17a2d30`](https://github.com/o-stepper/graphorin/commit/17a2d30564154ca2ab87473335cdef43a5089c84), [`17a2d30`](https://github.com/o-stepper/graphorin/commit/17a2d30564154ca2ab87473335cdef43a5089c84), [`17a2d30`](https://github.com/o-stepper/graphorin/commit/17a2d30564154ca2ab87473335cdef43a5089c84), [`17a2d30`](https://github.com/o-stepper/graphorin/commit/17a2d30564154ca2ab87473335cdef43a5089c84), [`17a2d30`](https://github.com/o-stepper/graphorin/commit/17a2d30564154ca2ab87473335cdef43a5089c84), [`17a2d30`](https://github.com/o-stepper/graphorin/commit/17a2d30564154ca2ab87473335cdef43a5089c84), [`17a2d30`](https://github.com/o-stepper/graphorin/commit/17a2d30564154ca2ab87473335cdef43a5089c84), [`ce06b47`](https://github.com/o-stepper/graphorin/commit/ce06b472af9e30ac5d0792f7a8b6f42170a94627), [`ce06b47`](https://github.com/o-stepper/graphorin/commit/ce06b472af9e30ac5d0792f7a8b6f42170a94627), [`ce06b47`](https://github.com/o-stepper/graphorin/commit/ce06b472af9e30ac5d0792f7a8b6f42170a94627), [`ce06b47`](https://github.com/o-stepper/graphorin/commit/ce06b472af9e30ac5d0792f7a8b6f42170a94627), [`ce06b47`](https://github.com/o-stepper/graphorin/commit/ce06b472af9e30ac5d0792f7a8b6f42170a94627), [`ce06b47`](https://github.com/o-stepper/graphorin/commit/ce06b472af9e30ac5d0792f7a8b6f42170a94627), [`6293a25`](https://github.com/o-stepper/graphorin/commit/6293a2531c5c9265294da22fb365a08f2bdf445a), [`6293a25`](https://github.com/o-stepper/graphorin/commit/6293a2531c5c9265294da22fb365a08f2bdf445a), [`6293a25`](https://github.com/o-stepper/graphorin/commit/6293a2531c5c9265294da22fb365a08f2bdf445a)]:
+  - @graphorin/memory@0.6.0
+  - @graphorin/tools@0.6.0
+  - @graphorin/core@0.6.0
+  - @graphorin/skills@0.6.0
+  - @graphorin/provider@0.6.0
+  - @graphorin/security@0.6.0
+  - @graphorin/observability@0.6.0
+
+## 0.5.0
+
+First version published to the npm registry (with Sigstore build
+provenance). The 0.2.0, 0.3.0, and 0.4.0 versions were internal lockstep
+milestones and were never published. All `@graphorin/*` packages release
+lockstep at the same version; the full release notes for 0.2.0-0.5.0 live
+in the repository-level
+[CHANGELOG](https://github.com/o-stepper/graphorin/blob/main/CHANGELOG.md).
+
 ## 0.1.0
 
 Initial release. See the workspace root `CHANGELOG.md` for the full

package/README.md

@@ -10,29 +10,29 @@ preservation, agent-level model fallback, post-compaction hooks,
 per-tool model-tier hints, lateral-leak defenses).
 
 The package is **library-mode-first**: every primitive that can be
-useful from a script (`createAgent`, `RunState.toJSON / fromJSON`,
-the filter library, `evaluatorOptimizer`, `Agent.fanOut`,
-`agent.progress.write / read`) ships from the npm package without
-the optional standalone server.
+useful from a script (`createAgent`, `runStateToJSON` /
+`runStateFromJSON`, the filter library, `evaluatorOptimizer`,
+`Agent.fanOut`, `agent.progress.write / read`) ships from the npm
+package without the optional standalone server.
 
 ## Dependencies
 
-- `@graphorin/core` — typed contracts (`AgentEvent`, `RunState`,
+- `@graphorin/core` - typed contracts (`AgentEvent`, `RunState`,
   `RunContext`, `Provider`, `Tool`, `StopCondition`, `HandoffFilter`,
   `Sensitivity`, …).
-- `@graphorin/provider` — middleware composer assertion + token
+- `@graphorin/provider` - middleware composer assertion + token
   counter dispatcher + per-provider model-tier auto-classifier.
-- `@graphorin/tools` — `ToolRegistry` + `ToolExecutor` (parallel /
+- `@graphorin/tools` - `ToolRegistry` + `ToolExecutor` (parallel /
   sequential dispatch, approval flow, sandbox enforcement, inbound
   sanitization).
-- `@graphorin/skills` — skill metadata cards, lazy body loading.
-- `@graphorin/memory` — `Memory` facade + `ContextEngine` for
+- `@graphorin/skills` - skill metadata cards, lazy body loading.
+- `@graphorin/memory` - `Memory` facade + `ContextEngine` for
   per-step prompt assembly + auto-compaction trigger.
-- `@graphorin/sessions` — multi-agent attribution, handoff records,
+- `@graphorin/sessions` - multi-agent attribution, handoff records,
   `AgentRegistry`, audit trail.
-- `@graphorin/observability` — `Tracer`, span attributes, counter
+- `@graphorin/observability` - `Tracer`, span attributes, counter
   receivers.
-- `@graphorin/security` — `SecretsAccessScope` for sub-agent
+- `@graphorin/security` - `SecretsAccessScope` for sub-agent
   inheritance, audit chain, lateral-leak guard primitives.
 
 ## Quick start
@@ -63,23 +63,43 @@ for await (const event of agent.stream('Plan a trip to Mars')) {
   progress artifacts, lateral-leak detections, model fallback
   transitions, …). `assertNever(...)` exhaustiveness is verified at
   compile time.
-- **Durable HITL.** `RunState.toJSON()` /
-  `RunState.fromJSON(serialized, agent)` round-trip the full run
-  state through any storage the caller picks (file, SQLite, KV, S3).
-- **Multi-agent.** `Agent.toTool({ exposeTurns, inputFilter })`
+- **Durable HITL.** `runStateToJSON(state)` /
+  `runStateFromJSON(serialized)` round-trip the full run state
+  through any storage the caller picks (file, SQLite, KV, S3); with a
+  `checkpointStore` wired, resuming a granted approval executes the
+  approved tool exactly once.
+- **Multi-agent.** `Agent.toTool({ exposeTurns, inputFilter, capability, contextFold, propagateTaint })`
   wraps an agent as a tool the parent agent can call. The parent's
   abort signal, deps, and sessionId propagate into the sub-run;
   without an `inputFilter` the sub-agent sees only the input string
   (no parent conversation crosses the boundary), and there is no
-  secret-inheritance mechanism at this boundary at all — least
-  authority by construction.
+  secret-inheritance mechanism at this boundary at all - least
+  authority by construction. `capability: 'read-only'` blocks
+  side-effecting tools in the child, `contextFold` returns a
+  distilled outcome instead of the raw transcript tail, and taint
+  from the child's untrusted inputs propagates to the parent by
+  default.
+- **Prompt-cache economics.** Opt-in `cachePolicy: { breakpoints: 'auto' }`
+  anchors provider cache breakpoints on the stable prefix so long
+  conversations are written once and read at the discounted rate;
+  cache read/write token legs flow through `Usage` and cost
+  tracking.
+- **Verifiers + deterministic replay.** `verifiers` run deterministic
+  checks on every terminal response (`verifier.result` events, up to
+  `maxVerifierRounds` feedback rounds); opt-in
+  `recordProviderResponses` journals raw model responses onto
+  `RunState` so `createReplayProvider(state)` re-drives the run
+  offline and fails loudly on divergence.
+- **Structured planning.** `plan: true` gives the model an
+  `update_plan` tool and surfaces the live plan as
+  `RunState.todos`.
 - **Filter library.** `filters.lastN(n)`, `filters.lastUser`,
   `filters.summary({...})`, `filters.bySensitivity({...})`,
   `filters.stripReasoning()`, `filters.stripSensitiveOutputs()`,
   `filters.stripToolCalls()`, `filters.compose(...)`. Every filter
   returns a serializable `HandoffInputFilterDescriptor` so the
   JSONL session export can replay it byte-equal.
-- **Cancellation.** `agent.abort({ drain, onPendingApprovals })` —
+- **Cancellation.** `agent.abort({ drain, onPendingApprovals })` -
   the default hard-kills the in-flight provider stream mid-event;
   `drain: true` lets the current step's stream finish (reach its step
   boundary) before stopping. A mid-stream abort ends the run as
@@ -128,7 +148,7 @@ for await (const event of agent.stream('Plan a trip to Mars')) {
   (Agentic Reference Monitor pattern), `Agent.mergeGuard` (per-child
   trust scoring + bias detection on `'judge-merge'`; `detect-and-block`
   refuses the merge with `MergeBlockedError`), the protocol
-  injection guard (`guardOutboundContent` — an exported helper for
+  injection guard (`guardOutboundContent` - an exported helper for
   the server boundary, not an `AgentConfig` knob), and
   commentary-phase trace sanitization at the session-output
   boundary compose orthogonally with the other security layers
@@ -155,5 +175,5 @@ text.
 
 ---
 
-**Project Graphorin** · v0.5.0 · MIT License · © 2026 Oleksiy
+**Project Graphorin** · v0.6.1 · MIT License · © 2026 Oleksiy
 Stepurenko · <https://github.com/o-stepper/graphorin>

package/dist/errors/index.d.ts

@@ -87,7 +87,7 @@ declare class ToolNotFoundError extends AgentRuntimeError {
  * in flight on the same `Agent` instance (AG-11). The public surface
  * (`steer` / `followUp` / `abort` / `compact`) addresses "the run"
  * without a run handle, so overlapping runs would share the abort
- * controller, steer queue, and executor bridge — start the second run
+ * controller, steer queue, and executor bridge - start the second run
  * on its own `createAgent(...)` instance instead.
  *
  * @stable

package/dist/errors/index.js

@@ -89,7 +89,7 @@ var ToolNotFoundError = class extends AgentRuntimeError {
 * in flight on the same `Agent` instance (AG-11). The public surface
 * (`steer` / `followUp` / `abort` / `compact`) addresses "the run"
 * without a run handle, so overlapping runs would share the abort
-* controller, steer queue, and executor bridge — start the second run
+* controller, steer queue, and executor bridge - start the second run
 * on its own `createAgent(...)` instance instead.
 *
 * @stable

package/dist/errors/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/errors/index.ts"],"sourcesContent":["/**\n * Typed error surface for `@graphorin/agent`.\n *\n * Every error class extends the base {@link AgentRuntimeError} which is\n * a thin wrapper around `Error` with a stable `code` discriminator so\n * callers can `switch` on it without parsing messages.\n *\n * @packageDocumentation\n */\n\n/**\n * Stable code discriminator surfaced on every {@link AgentRuntimeError}.\n *\n * @stable\n */\nexport type AgentRuntimeErrorCode =\n  | 'invalid-config'\n  | 'invalid-preferred-model'\n  | 'invalid-fallback-policy'\n  | 'invalid-evaluator-optimizer-config'\n  | 'agent-resolution-failed'\n  | 'tool-not-found'\n  | 'handoff-target-not-found'\n  | 'multiple-handoffs-in-step'\n  | 'run-aborted'\n  | 'middleware-order-violation'\n  | 'progress-write-failed'\n  | 'merge-blocked'\n  | 'protocol-injection-rejected'\n  | 'run-state-version-unsupported'\n  | 'run-state-malformed'\n  | 'concurrent-run';\n\n/**\n * Base class for every error thrown from `@graphorin/agent`.\n *\n * @stable\n */\nexport class AgentRuntimeError extends Error {\n  readonly code: AgentRuntimeErrorCode;\n  constructor(code: AgentRuntimeErrorCode, message: string, name = 'AgentRuntimeError') {\n    super(message);\n    this.name = name;\n    this.code = code;\n  }\n}\n\n/**\n * Thrown by `createAgent({...})` when the supplied options fail\n * structural validation (missing `provider`, empty `name`, an\n * `outputType` of kind `'text'` carrying a `schema`, ...).\n *\n * @stable\n */\nexport class InvalidAgentConfigError extends AgentRuntimeError {\n  constructor(reason: string) {\n    super(\n      'invalid-config',\n      `Invalid createAgent({...}) options: ${reason}.`,\n      'InvalidAgentConfigError',\n    );\n  }\n}\n\n/**\n * Thrown by `createAgent({...})` when `preferredModel` carries an\n * unknown literal (any value outside the `'fast' | 'balanced' |\n * 'smart'` cost-tier vocabulary AND not a valid `ModelSpec`).\n *\n * @stable\n */\nexport class InvalidPreferredModelError extends AgentRuntimeError {\n  readonly value: unknown;\n  constructor(value: unknown) {\n    super(\n      'invalid-preferred-model',\n      `Invalid Agent.preferredModel: ${JSON.stringify(value)}. ` +\n        \"Expected 'fast' | 'balanced' | 'smart' | ModelSpec.\",\n      'InvalidPreferredModelError',\n    );\n    this.value = value;\n  }\n}\n\n/**\n * Thrown by `evaluatorOptimizer({...})` when `maxIterations < 1` at\n * construction time. The helper purposely surfaces the misuse early\n * rather than failing on the first run.\n *\n * @stable\n */\nexport class EvaluatorOptimizerConfigError extends AgentRuntimeError {\n  constructor(reason: string) {\n    super(\n      'invalid-evaluator-optimizer-config',\n      `Invalid evaluatorOptimizer({...}) options: ${reason}.`,\n      'EvaluatorOptimizerConfigError',\n    );\n  }\n}\n\n/**\n * Thrown by `runStateFromJSON(...)` when the agent name in the\n * serialized state cannot be resolved against the supplied agent\n * graph (renamed agent / removed handoff).\n *\n * @stable\n */\nexport class AgentResolutionError extends AgentRuntimeError {\n  readonly agentId: string;\n  constructor(agentId: string) {\n    super(\n      'agent-resolution-failed',\n      `runStateFromJSON: agent '${agentId}' is not registered in the supplied graph.`,\n      'AgentResolutionError',\n    );\n    this.agentId = agentId;\n  }\n}\n\n/**\n * Thrown by the agent loop when the model emits a tool call referring\n * to an unregistered tool (the model hallucinated a name).\n *\n * @stable\n */\nexport class ToolNotFoundError extends AgentRuntimeError {\n  readonly toolName: string;\n  constructor(toolName: string) {\n    super(\n      'tool-not-found',\n      `Tool '${toolName}' is not registered on this agent.`,\n      'ToolNotFoundError',\n    );\n    this.toolName = toolName;\n  }\n}\n\n/**\n * Thrown when the model invokes more than one handoff (`transfer_to_*`)\n * tool in a single response. Per the agent-loop documentation this is\n * an error rather than a silent drop.\n *\n * @stable\n */\n/**\n * Thrown when a second `run()` / `stream()` starts while another run is\n * in flight on the same `Agent` instance (AG-11). The public surface\n * (`steer` / `followUp` / `abort` / `compact`) addresses \"the run\"\n * without a run handle, so overlapping runs would share the abort\n * controller, steer queue, and executor bridge — start the second run\n * on its own `createAgent(...)` instance instead.\n *\n * @stable\n */\nexport class ConcurrentRunError extends AgentRuntimeError {\n  constructor() {\n    super(\n      'concurrent-run',\n      'This Agent instance already has a run in flight. One run per instance: await the active run (or abort it), or create a separate agent instance for parallel work.',\n      'ConcurrentRunError',\n    );\n  }\n}\n\nexport class MultipleHandoffsInStepError extends AgentRuntimeError {\n  readonly handoffNames: ReadonlyArray<string>;\n  constructor(handoffNames: ReadonlyArray<string>) {\n    super(\n      'multiple-handoffs-in-step',\n      `The model invoked multiple handoff tools in one step: ${handoffNames.join(', ')}.`,\n      'MultipleHandoffsInStepError',\n    );\n    this.handoffNames = handoffNames;\n  }\n}\n\n/**\n * Thrown by `runStateFromJSON(...)` when the version field in the\n * serialized state is from a future major version of the framework.\n *\n * @stable\n */\nexport class RunStateVersionUnsupportedError extends AgentRuntimeError {\n  readonly version: string;\n  readonly readerVersion: string;\n  constructor(version: string, readerVersion: string) {\n    super(\n      'run-state-version-unsupported',\n      `RunState version '${version}' is newer than reader '${readerVersion}'. ` +\n        'Upgrade @graphorin/agent to load this state.',\n      'RunStateVersionUnsupportedError',\n    );\n    this.version = version;\n    this.readerVersion = readerVersion;\n  }\n}\n\n/**\n * Thrown by `runStateFromJSON(...)` when the supplied JSON does not\n * shape-match the documented {@link SerializedRunState}.\n *\n * @stable\n */\nexport class RunStateMalformedError extends AgentRuntimeError {\n  constructor(reason: string) {\n    super('run-state-malformed', `Malformed RunState JSON: ${reason}.`, 'RunStateMalformedError');\n  }\n}\n\n/**\n * Thrown by `Agent.fanOut(...)` when the configured\n * {@link MergeAgentSidewaysInjectionGuard} fires with strictness\n * `'detect-and-block'`.\n *\n * @stable\n */\nexport class MergeBlockedError extends AgentRuntimeError {\n  readonly fanOutId: string;\n  readonly reason: string;\n  constructor(fanOutId: string, reason: string) {\n    super(\n      'merge-blocked',\n      `Agent.fanOut('${fanOutId}') merge blocked by MergeAgentSidewaysInjectionGuard: ${reason}.`,\n      'MergeBlockedError',\n    );\n    this.fanOutId = fanOutId;\n    this.reason = reason;\n  }\n}\n\n/**\n * Thrown by the protocol-injection guard when the operator selected\n * the strictest deployment posture (`escapePolicy: 'reject'`) and a\n * tool result body carries control characters at the corresponding\n * outbound boundary.\n *\n * @stable\n */\nexport class ProtocolInjectionRejectError extends AgentRuntimeError {\n  readonly boundary: string;\n  readonly matchedPattern: string;\n  constructor(boundary: string, matchedPattern: string) {\n    super(\n      'protocol-injection-rejected',\n      `Protocol injection guard rejected output at the '${boundary}' boundary (matched ${matchedPattern}).`,\n      'ProtocolInjectionRejectError',\n    );\n    this.boundary = boundary;\n    this.matchedPattern = matchedPattern;\n  }\n}\n\n/**\n * Thrown by `agent.progress.write(...)` when the atomic write fails\n * (disk full, permission denied, ...). The partial `.tmp` file is\n * unlinked before the error propagates.\n *\n * @stable\n */\nexport class ProgressWriteError extends AgentRuntimeError {\n  readonly path: string;\n  constructor(path: string, cause: unknown) {\n    const message = cause instanceof Error ? cause.message : String(cause);\n    super(\n      'progress-write-failed',\n      `agent.progress.write('${path}') failed: ${message}.`,\n      'ProgressWriteError',\n    );\n    this.path = path;\n    if (cause !== undefined) {\n      // Preserve the underlying cause for diagnostics.\n      Object.defineProperty(this, 'cause', {\n        value: cause,\n        enumerable: false,\n        configurable: true,\n        writable: true,\n      });\n    }\n  }\n}\n\n/**\n * Thrown by `createAgent({...})` when the supplied\n * `composeProviderMiddleware` chain violates the canonical inside-out\n * ordering (DEC-145 / ADR-039).\n *\n * @stable\n */\nexport class ProviderMiddlewareOrderError extends AgentRuntimeError {\n  constructor(reason: string) {\n    super(\n      'middleware-order-violation',\n      `Provider middleware composition violated the inside-out ordering: ${reason}.`,\n      'ProviderMiddlewareOrderError',\n    );\n  }\n}\n"],"mappings":";;;;;;AAsCA,IAAa,oBAAb,cAAuC,MAAM;CAC3C,AAAS;CACT,YAAY,MAA6B,SAAiB,OAAO,qBAAqB;AACpF,QAAM,QAAQ;AACd,OAAK,OAAO;AACZ,OAAK,OAAO;;;;;;;;;;AAWhB,IAAa,0BAAb,cAA6C,kBAAkB;CAC7D,YAAY,QAAgB;AAC1B,QACE,kBACA,uCAAuC,OAAO,IAC9C,0BACD;;;;;;;;;;AAWL,IAAa,6BAAb,cAAgD,kBAAkB;CAChE,AAAS;CACT,YAAY,OAAgB;AAC1B,QACE,2BACA,iCAAiC,KAAK,UAAU,MAAM,CAAC,wDAEvD,6BACD;AACD,OAAK,QAAQ;;;;;;;;;;AAWjB,IAAa,gCAAb,cAAmD,kBAAkB;CACnE,YAAY,QAAgB;AAC1B,QACE,sCACA,8CAA8C,OAAO,IACrD,gCACD;;;;;;;;;;AAWL,IAAa,uBAAb,cAA0C,kBAAkB;CAC1D,AAAS;CACT,YAAY,SAAiB;AAC3B,QACE,2BACA,4BAA4B,QAAQ,6CACpC,uBACD;AACD,OAAK,UAAU;;;;;;;;;AAUnB,IAAa,oBAAb,cAAuC,kBAAkB;CACvD,AAAS;CACT,YAAY,UAAkB;AAC5B,QACE,kBACA,SAAS,SAAS,qCAClB,oBACD;AACD,OAAK,WAAW;;;;;;;;;;;;;;;;;;;;AAqBpB,IAAa,qBAAb,cAAwC,kBAAkB;CACxD,cAAc;AACZ,QACE,kBACA,qKACA,qBACD;;;AAIL,IAAa,8BAAb,cAAiD,kBAAkB;CACjE,AAAS;CACT,YAAY,cAAqC;AAC/C,QACE,6BACA,yDAAyD,aAAa,KAAK,KAAK,CAAC,IACjF,8BACD;AACD,OAAK,eAAe;;;;;;;;;AAUxB,IAAa,kCAAb,cAAqD,kBAAkB;CACrE,AAAS;CACT,AAAS;CACT,YAAY,SAAiB,eAAuB;AAClD,QACE,iCACA,qBAAqB,QAAQ,0BAA0B,cAAc,kDAErE,kCACD;AACD,OAAK,UAAU;AACf,OAAK,gBAAgB;;;;;;;;;AAUzB,IAAa,yBAAb,cAA4C,kBAAkB;CAC5D,YAAY,QAAgB;AAC1B,QAAM,uBAAuB,4BAA4B,OAAO,IAAI,yBAAyB;;;;;;;;;;AAWjG,IAAa,oBAAb,cAAuC,kBAAkB;CACvD,AAAS;CACT,AAAS;CACT,YAAY,UAAkB,QAAgB;AAC5C,QACE,iBACA,iBAAiB,SAAS,wDAAwD,OAAO,IACzF,oBACD;AACD,OAAK,WAAW;AAChB,OAAK,SAAS;;;;;;;;;;;AAYlB,IAAa,+BAAb,cAAkD,kBAAkB;CAClE,AAAS;CACT,AAAS;CACT,YAAY,UAAkB,gBAAwB;AACpD,QACE,+BACA,oDAAoD,SAAS,sBAAsB,eAAe,KAClG,+BACD;AACD,OAAK,WAAW;AAChB,OAAK,iBAAiB;;;;;;;;;;AAW1B,IAAa,qBAAb,cAAwC,kBAAkB;CACxD,AAAS;CACT,YAAY,MAAc,OAAgB;EACxC,MAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;AACtE,QACE,yBACA,yBAAyB,KAAK,aAAa,QAAQ,IACnD,qBACD;AACD,OAAK,OAAO;AACZ,MAAI,UAAU,OAEZ,QAAO,eAAe,MAAM,SAAS;GACnC,OAAO;GACP,YAAY;GACZ,cAAc;GACd,UAAU;GACX,CAAC;;;;;;;;;;AAYR,IAAa,+BAAb,cAAkD,kBAAkB;CAClE,YAAY,QAAgB;AAC1B,QACE,8BACA,qEAAqE,OAAO,IAC5E,+BACD"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/errors/index.ts"],"sourcesContent":["/**\n * Typed error surface for `@graphorin/agent`.\n *\n * Every error class extends the base {@link AgentRuntimeError} which is\n * a thin wrapper around `Error` with a stable `code` discriminator so\n * callers can `switch` on it without parsing messages.\n *\n * @packageDocumentation\n */\n\n/**\n * Stable code discriminator surfaced on every {@link AgentRuntimeError}.\n *\n * @stable\n */\nexport type AgentRuntimeErrorCode =\n  | 'invalid-config'\n  | 'invalid-preferred-model'\n  | 'invalid-fallback-policy'\n  | 'invalid-evaluator-optimizer-config'\n  | 'agent-resolution-failed'\n  | 'tool-not-found'\n  | 'handoff-target-not-found'\n  | 'multiple-handoffs-in-step'\n  | 'run-aborted'\n  | 'middleware-order-violation'\n  | 'progress-write-failed'\n  | 'merge-blocked'\n  | 'protocol-injection-rejected'\n  | 'run-state-version-unsupported'\n  | 'run-state-malformed'\n  | 'concurrent-run';\n\n/**\n * Base class for every error thrown from `@graphorin/agent`.\n *\n * @stable\n */\nexport class AgentRuntimeError extends Error {\n  readonly code: AgentRuntimeErrorCode;\n  constructor(code: AgentRuntimeErrorCode, message: string, name = 'AgentRuntimeError') {\n    super(message);\n    this.name = name;\n    this.code = code;\n  }\n}\n\n/**\n * Thrown by `createAgent({...})` when the supplied options fail\n * structural validation (missing `provider`, empty `name`, an\n * `outputType` of kind `'text'` carrying a `schema`, ...).\n *\n * @stable\n */\nexport class InvalidAgentConfigError extends AgentRuntimeError {\n  constructor(reason: string) {\n    super(\n      'invalid-config',\n      `Invalid createAgent({...}) options: ${reason}.`,\n      'InvalidAgentConfigError',\n    );\n  }\n}\n\n/**\n * Thrown by `createAgent({...})` when `preferredModel` carries an\n * unknown literal (any value outside the `'fast' | 'balanced' |\n * 'smart'` cost-tier vocabulary AND not a valid `ModelSpec`).\n *\n * @stable\n */\nexport class InvalidPreferredModelError extends AgentRuntimeError {\n  readonly value: unknown;\n  constructor(value: unknown) {\n    super(\n      'invalid-preferred-model',\n      `Invalid Agent.preferredModel: ${JSON.stringify(value)}. ` +\n        \"Expected 'fast' | 'balanced' | 'smart' | ModelSpec.\",\n      'InvalidPreferredModelError',\n    );\n    this.value = value;\n  }\n}\n\n/**\n * Thrown by `evaluatorOptimizer({...})` when `maxIterations < 1` at\n * construction time. The helper purposely surfaces the misuse early\n * rather than failing on the first run.\n *\n * @stable\n */\nexport class EvaluatorOptimizerConfigError extends AgentRuntimeError {\n  constructor(reason: string) {\n    super(\n      'invalid-evaluator-optimizer-config',\n      `Invalid evaluatorOptimizer({...}) options: ${reason}.`,\n      'EvaluatorOptimizerConfigError',\n    );\n  }\n}\n\n/**\n * Thrown by `runStateFromJSON(...)` when the agent name in the\n * serialized state cannot be resolved against the supplied agent\n * graph (renamed agent / removed handoff).\n *\n * @stable\n */\nexport class AgentResolutionError extends AgentRuntimeError {\n  readonly agentId: string;\n  constructor(agentId: string) {\n    super(\n      'agent-resolution-failed',\n      `runStateFromJSON: agent '${agentId}' is not registered in the supplied graph.`,\n      'AgentResolutionError',\n    );\n    this.agentId = agentId;\n  }\n}\n\n/**\n * Thrown by the agent loop when the model emits a tool call referring\n * to an unregistered tool (the model hallucinated a name).\n *\n * @stable\n */\nexport class ToolNotFoundError extends AgentRuntimeError {\n  readonly toolName: string;\n  constructor(toolName: string) {\n    super(\n      'tool-not-found',\n      `Tool '${toolName}' is not registered on this agent.`,\n      'ToolNotFoundError',\n    );\n    this.toolName = toolName;\n  }\n}\n\n/**\n * Thrown when the model invokes more than one handoff (`transfer_to_*`)\n * tool in a single response. Per the agent-loop documentation this is\n * an error rather than a silent drop.\n *\n * @stable\n */\n/**\n * Thrown when a second `run()` / `stream()` starts while another run is\n * in flight on the same `Agent` instance (AG-11). The public surface\n * (`steer` / `followUp` / `abort` / `compact`) addresses \"the run\"\n * without a run handle, so overlapping runs would share the abort\n * controller, steer queue, and executor bridge - start the second run\n * on its own `createAgent(...)` instance instead.\n *\n * @stable\n */\nexport class ConcurrentRunError extends AgentRuntimeError {\n  constructor() {\n    super(\n      'concurrent-run',\n      'This Agent instance already has a run in flight. One run per instance: await the active run (or abort it), or create a separate agent instance for parallel work.',\n      'ConcurrentRunError',\n    );\n  }\n}\n\nexport class MultipleHandoffsInStepError extends AgentRuntimeError {\n  readonly handoffNames: ReadonlyArray<string>;\n  constructor(handoffNames: ReadonlyArray<string>) {\n    super(\n      'multiple-handoffs-in-step',\n      `The model invoked multiple handoff tools in one step: ${handoffNames.join(', ')}.`,\n      'MultipleHandoffsInStepError',\n    );\n    this.handoffNames = handoffNames;\n  }\n}\n\n/**\n * Thrown by `runStateFromJSON(...)` when the version field in the\n * serialized state is from a future major version of the framework.\n *\n * @stable\n */\nexport class RunStateVersionUnsupportedError extends AgentRuntimeError {\n  readonly version: string;\n  readonly readerVersion: string;\n  constructor(version: string, readerVersion: string) {\n    super(\n      'run-state-version-unsupported',\n      `RunState version '${version}' is newer than reader '${readerVersion}'. ` +\n        'Upgrade @graphorin/agent to load this state.',\n      'RunStateVersionUnsupportedError',\n    );\n    this.version = version;\n    this.readerVersion = readerVersion;\n  }\n}\n\n/**\n * Thrown by `runStateFromJSON(...)` when the supplied JSON does not\n * shape-match the documented {@link SerializedRunState}.\n *\n * @stable\n */\nexport class RunStateMalformedError extends AgentRuntimeError {\n  constructor(reason: string) {\n    super('run-state-malformed', `Malformed RunState JSON: ${reason}.`, 'RunStateMalformedError');\n  }\n}\n\n/**\n * Thrown by `Agent.fanOut(...)` when the configured\n * {@link MergeAgentSidewaysInjectionGuard} fires with strictness\n * `'detect-and-block'`.\n *\n * @stable\n */\nexport class MergeBlockedError extends AgentRuntimeError {\n  readonly fanOutId: string;\n  readonly reason: string;\n  constructor(fanOutId: string, reason: string) {\n    super(\n      'merge-blocked',\n      `Agent.fanOut('${fanOutId}') merge blocked by MergeAgentSidewaysInjectionGuard: ${reason}.`,\n      'MergeBlockedError',\n    );\n    this.fanOutId = fanOutId;\n    this.reason = reason;\n  }\n}\n\n/**\n * Thrown by the protocol-injection guard when the operator selected\n * the strictest deployment posture (`escapePolicy: 'reject'`) and a\n * tool result body carries control characters at the corresponding\n * outbound boundary.\n *\n * @stable\n */\nexport class ProtocolInjectionRejectError extends AgentRuntimeError {\n  readonly boundary: string;\n  readonly matchedPattern: string;\n  constructor(boundary: string, matchedPattern: string) {\n    super(\n      'protocol-injection-rejected',\n      `Protocol injection guard rejected output at the '${boundary}' boundary (matched ${matchedPattern}).`,\n      'ProtocolInjectionRejectError',\n    );\n    this.boundary = boundary;\n    this.matchedPattern = matchedPattern;\n  }\n}\n\n/**\n * Thrown by `agent.progress.write(...)` when the atomic write fails\n * (disk full, permission denied, ...). The partial `.tmp` file is\n * unlinked before the error propagates.\n *\n * @stable\n */\nexport class ProgressWriteError extends AgentRuntimeError {\n  readonly path: string;\n  constructor(path: string, cause: unknown) {\n    const message = cause instanceof Error ? cause.message : String(cause);\n    super(\n      'progress-write-failed',\n      `agent.progress.write('${path}') failed: ${message}.`,\n      'ProgressWriteError',\n    );\n    this.path = path;\n    if (cause !== undefined) {\n      // Preserve the underlying cause for diagnostics.\n      Object.defineProperty(this, 'cause', {\n        value: cause,\n        enumerable: false,\n        configurable: true,\n        writable: true,\n      });\n    }\n  }\n}\n\n/**\n * Thrown by `createAgent({...})` when the supplied\n * `composeProviderMiddleware` chain violates the canonical inside-out\n * ordering (DEC-145 / ADR-039).\n *\n * @stable\n */\nexport class ProviderMiddlewareOrderError extends AgentRuntimeError {\n  constructor(reason: string) {\n    super(\n      'middleware-order-violation',\n      `Provider middleware composition violated the inside-out ordering: ${reason}.`,\n      'ProviderMiddlewareOrderError',\n    );\n  }\n}\n"],"mappings":";;;;;;AAsCA,IAAa,oBAAb,cAAuC,MAAM;CAC3C,AAAS;CACT,YAAY,MAA6B,SAAiB,OAAO,qBAAqB;AACpF,QAAM,QAAQ;AACd,OAAK,OAAO;AACZ,OAAK,OAAO;;;;;;;;;;AAWhB,IAAa,0BAAb,cAA6C,kBAAkB;CAC7D,YAAY,QAAgB;AAC1B,QACE,kBACA,uCAAuC,OAAO,IAC9C,0BACD;;;;;;;;;;AAWL,IAAa,6BAAb,cAAgD,kBAAkB;CAChE,AAAS;CACT,YAAY,OAAgB;AAC1B,QACE,2BACA,iCAAiC,KAAK,UAAU,MAAM,CAAC,wDAEvD,6BACD;AACD,OAAK,QAAQ;;;;;;;;;;AAWjB,IAAa,gCAAb,cAAmD,kBAAkB;CACnE,YAAY,QAAgB;AAC1B,QACE,sCACA,8CAA8C,OAAO,IACrD,gCACD;;;;;;;;;;AAWL,IAAa,uBAAb,cAA0C,kBAAkB;CAC1D,AAAS;CACT,YAAY,SAAiB;AAC3B,QACE,2BACA,4BAA4B,QAAQ,6CACpC,uBACD;AACD,OAAK,UAAU;;;;;;;;;AAUnB,IAAa,oBAAb,cAAuC,kBAAkB;CACvD,AAAS;CACT,YAAY,UAAkB;AAC5B,QACE,kBACA,SAAS,SAAS,qCAClB,oBACD;AACD,OAAK,WAAW;;;;;;;;;;;;;;;;;;;;AAqBpB,IAAa,qBAAb,cAAwC,kBAAkB;CACxD,cAAc;AACZ,QACE,kBACA,qKACA,qBACD;;;AAIL,IAAa,8BAAb,cAAiD,kBAAkB;CACjE,AAAS;CACT,YAAY,cAAqC;AAC/C,QACE,6BACA,yDAAyD,aAAa,KAAK,KAAK,CAAC,IACjF,8BACD;AACD,OAAK,eAAe;;;;;;;;;AAUxB,IAAa,kCAAb,cAAqD,kBAAkB;CACrE,AAAS;CACT,AAAS;CACT,YAAY,SAAiB,eAAuB;AAClD,QACE,iCACA,qBAAqB,QAAQ,0BAA0B,cAAc,kDAErE,kCACD;AACD,OAAK,UAAU;AACf,OAAK,gBAAgB;;;;;;;;;AAUzB,IAAa,yBAAb,cAA4C,kBAAkB;CAC5D,YAAY,QAAgB;AAC1B,QAAM,uBAAuB,4BAA4B,OAAO,IAAI,yBAAyB;;;;;;;;;;AAWjG,IAAa,oBAAb,cAAuC,kBAAkB;CACvD,AAAS;CACT,AAAS;CACT,YAAY,UAAkB,QAAgB;AAC5C,QACE,iBACA,iBAAiB,SAAS,wDAAwD,OAAO,IACzF,oBACD;AACD,OAAK,WAAW;AAChB,OAAK,SAAS;;;;;;;;;;;AAYlB,IAAa,+BAAb,cAAkD,kBAAkB;CAClE,AAAS;CACT,AAAS;CACT,YAAY,UAAkB,gBAAwB;AACpD,QACE,+BACA,oDAAoD,SAAS,sBAAsB,eAAe,KAClG,+BACD;AACD,OAAK,WAAW;AAChB,OAAK,iBAAiB;;;;;;;;;;AAW1B,IAAa,qBAAb,cAAwC,kBAAkB;CACxD,AAAS;CACT,YAAY,MAAc,OAAgB;EACxC,MAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;AACtE,QACE,yBACA,yBAAyB,KAAK,aAAa,QAAQ,IACnD,qBACD;AACD,OAAK,OAAO;AACZ,MAAI,UAAU,OAEZ,QAAO,eAAe,MAAM,SAAS;GACnC,OAAO;GACP,YAAY;GACZ,cAAc;GACd,UAAU;GACX,CAAC;;;;;;;;;;AAYR,IAAa,+BAAb,cAAkD,kBAAkB;CAClE,YAAY,QAAgB;AAC1B,QACE,8BACA,qEAAqE,OAAO,IAC5E,+BACD"}

package/dist/evaluator-optimizer/index.d.ts

@@ -45,7 +45,7 @@ type GeneratorCallable<TOutput> = (input: string, priorCritique: string | undefi
 type EvaluatorCallable<TOutput> = (input: string, candidate: TOutput, rubric: Rubric, iteration: number) => Promise<EvaluatorOutcome>;
 /**
  * Options accepted by {@link evaluatorOptimizer}. `maxIterations`
- * is REQUIRED — the helper asserts `>= 1` at construction time.
+ * is REQUIRED - the helper asserts `>= 1` at construction time.
  *
  * @stable
  */

package/dist/evaluator-optimizer/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["iterations: Array<{\n    iteration: number;\n    candidate: TOutput;\n    score: number;\n    pass: boolean;\n    critique: string;\n    durationMs: number;\n  }>","priorCritique: string | undefined","terminationReason: EvaluatorOptimizerOutcome<TOutput>['terminationReason']","candidate: TOutput","finalEntry: (typeof iterations)[number]"],"sources":["../../src/evaluator-optimizer/index.ts"],"sourcesContent":["/**\n * `evaluatorOptimizer({...})` — Generator → Evaluator iteration\n * loop with three rubric kinds and a REQUIRED iteration cap.\n *\n * Iteration boundary discipline: each iteration is a fresh\n * agent.run-equivalent boundary. Intra-loop reasoning per RB-42 /\n * suggested DEC-158 applies WITHIN one iteration, not ACROSS\n * iterations. The Generator's iteration-N input is the original\n * user input + the Evaluator's iteration-(N-1) critique (NOT the\n * Generator's iteration-(N-1) internal message history).\n *\n * @packageDocumentation\n */\n\nimport type { AgentEvent } from '@graphorin/core';\nimport { EvaluatorOptimizerConfigError } from '../errors/index.js';\n\n/**\n * Rubric discriminator. Pick the variant that matches your\n * Evaluator's contract.\n *\n * @stable\n */\nexport type Rubric =\n  | { readonly kind: 'free-form'; readonly instructions: string }\n  | { readonly kind: 'zod'; readonly instructions: string }\n  | { readonly kind: 'llm-judge'; readonly promptTemplate: string };\n\n/**\n * Per-iteration evaluation outcome returned by the Evaluator.\n *\n * @stable\n */\nexport interface EvaluatorOutcome {\n  readonly score: number;\n  readonly pass: boolean;\n  readonly critique: string;\n}\n\n/**\n * Generator callable shape. Receives the original user input plus\n * the previous iteration's critique (or `undefined` on the first\n * iteration) and returns the new candidate output.\n *\n * @stable\n */\nexport type GeneratorCallable<TOutput> = (\n  input: string,\n  priorCritique: string | undefined,\n  iteration: number,\n) => Promise<TOutput>;\n\n/**\n * Evaluator callable shape. Receives the original user input + the\n * candidate output and returns the structured outcome.\n *\n * @stable\n */\nexport type EvaluatorCallable<TOutput> = (\n  input: string,\n  candidate: TOutput,\n  rubric: Rubric,\n  iteration: number,\n) => Promise<EvaluatorOutcome>;\n\n/**\n * Options accepted by {@link evaluatorOptimizer}. `maxIterations`\n * is REQUIRED — the helper asserts `>= 1` at construction time.\n *\n * @stable\n */\nexport interface EvaluatorOptimizerOptions<TOutput> {\n  readonly generator: GeneratorCallable<TOutput>;\n  readonly evaluator: EvaluatorCallable<TOutput>;\n  readonly maxIterations: number;\n  readonly rubric: Rubric;\n  readonly mergeStrategy?: 'last-iteration' | 'best-score';\n  readonly signal?: AbortSignal;\n  /** Optional event emitter for `agent.evaluator.iteration / converged`. */\n  readonly emit?: (event: AgentEvent) => void;\n  readonly runId: string;\n  readonly sessionId: string;\n  readonly agentId: string;\n}\n\n/**\n * Aggregate outcome of an `evaluatorOptimizer({...})` run.\n *\n * @stable\n */\nexport interface EvaluatorOptimizerOutcome<TOutput> {\n  readonly output: TOutput;\n  readonly iterations: ReadonlyArray<{\n    readonly iteration: number;\n    readonly candidate: TOutput;\n    readonly score: number;\n    readonly pass: boolean;\n    readonly critique: string;\n    readonly durationMs: number;\n  }>;\n  readonly terminationReason: 'pass' | 'maxIterations' | 'generator-exhausted' | 'cancelled';\n  readonly finalScore: number;\n}\n\n/**\n * Run the Generator → Evaluator iteration loop.\n *\n * @stable\n */\nexport async function evaluatorOptimizer<TOutput>(\n  input: string,\n  options: EvaluatorOptimizerOptions<TOutput>,\n): Promise<EvaluatorOptimizerOutcome<TOutput>> {\n  if (!Number.isFinite(options.maxIterations) || options.maxIterations < 1) {\n    throw new EvaluatorOptimizerConfigError(\n      `'maxIterations' must be >= 1 (got ${String(options.maxIterations)})`,\n    );\n  }\n  const mergeStrategy = options.mergeStrategy ?? 'last-iteration';\n  const iterations: Array<{\n    iteration: number;\n    candidate: TOutput;\n    score: number;\n    pass: boolean;\n    critique: string;\n    durationMs: number;\n  }> = [];\n\n  let priorCritique: string | undefined;\n  let terminationReason: EvaluatorOptimizerOutcome<TOutput>['terminationReason'] = 'maxIterations';\n\n  for (let i = 1; i <= options.maxIterations; i++) {\n    if (options.signal?.aborted) {\n      terminationReason = 'cancelled';\n      break;\n    }\n    const iterStart = Date.now();\n    let candidate: TOutput;\n    try {\n      candidate = await options.generator(input, priorCritique, i);\n    } catch {\n      terminationReason = 'generator-exhausted';\n      break;\n    }\n    const outcome = await options.evaluator(input, candidate, options.rubric, i);\n    const iterDuration = Date.now() - iterStart;\n\n    iterations.push({\n      iteration: i,\n      candidate,\n      score: outcome.score,\n      pass: outcome.pass,\n      critique: outcome.critique,\n      durationMs: iterDuration,\n    });\n\n    options.emit?.({\n      type: 'agent.evaluator.iteration',\n      runId: options.runId,\n      sessionId: options.sessionId,\n      agentId: options.agentId,\n      iteration: i,\n      score: outcome.score,\n      pass: outcome.pass,\n      critique: outcome.critique,\n      durationMs: iterDuration,\n    });\n\n    if (outcome.pass) {\n      terminationReason = 'pass';\n      break;\n    }\n    priorCritique = outcome.critique;\n  }\n\n  let finalEntry: (typeof iterations)[number];\n  if (iterations.length === 0) {\n    // Should only happen on `cancelled` before the first iteration —\n    // synthesize a no-op final entry.\n    finalEntry = {\n      iteration: 0,\n      candidate: '' as unknown as TOutput,\n      score: 0,\n      pass: false,\n      critique: '',\n      durationMs: 0,\n    };\n  } else if (mergeStrategy === 'best-score') {\n    finalEntry = iterations.reduce((best, current) =>\n      current.score > best.score ? current : best,\n    );\n  } else {\n    finalEntry = iterations[iterations.length - 1] as (typeof iterations)[number];\n  }\n\n  options.emit?.({\n    type: 'agent.evaluator.converged',\n    runId: options.runId,\n    sessionId: options.sessionId,\n    agentId: options.agentId,\n    totalIterations: iterations.length,\n    finalScore: finalEntry.score,\n    terminationReason,\n  });\n\n  return {\n    output: finalEntry.candidate,\n    iterations,\n    terminationReason,\n    finalScore: finalEntry.score,\n  };\n}\n"],"mappings":";;;;;;;;AA6GA,eAAsB,mBACpB,OACA,SAC6C;AAC7C,KAAI,CAAC,OAAO,SAAS,QAAQ,cAAc,IAAI,QAAQ,gBAAgB,EACrE,OAAM,IAAI,8BACR,qCAAqC,OAAO,QAAQ,cAAc,CAAC,GACpE;CAEH,MAAM,gBAAgB,QAAQ,iBAAiB;CAC/C,MAAMA,aAOD,EAAE;CAEP,IAAIC;CACJ,IAAIC,oBAA6E;AAEjF,MAAK,IAAI,IAAI,GAAG,KAAK,QAAQ,eAAe,KAAK;AAC/C,MAAI,QAAQ,QAAQ,SAAS;AAC3B,uBAAoB;AACpB;;EAEF,MAAM,YAAY,KAAK,KAAK;EAC5B,IAAIC;AACJ,MAAI;AACF,eAAY,MAAM,QAAQ,UAAU,OAAO,eAAe,EAAE;UACtD;AACN,uBAAoB;AACpB;;EAEF,MAAM,UAAU,MAAM,QAAQ,UAAU,OAAO,WAAW,QAAQ,QAAQ,EAAE;EAC5E,MAAM,eAAe,KAAK,KAAK,GAAG;AAElC,aAAW,KAAK;GACd,WAAW;GACX;GACA,OAAO,QAAQ;GACf,MAAM,QAAQ;GACd,UAAU,QAAQ;GAClB,YAAY;GACb,CAAC;AAEF,UAAQ,OAAO;GACb,MAAM;GACN,OAAO,QAAQ;GACf,WAAW,QAAQ;GACnB,SAAS,QAAQ;GACjB,WAAW;GACX,OAAO,QAAQ;GACf,MAAM,QAAQ;GACd,UAAU,QAAQ;GAClB,YAAY;GACb,CAAC;AAEF,MAAI,QAAQ,MAAM;AAChB,uBAAoB;AACpB;;AAEF,kBAAgB,QAAQ;;CAG1B,IAAIC;AACJ,KAAI,WAAW,WAAW,EAGxB,cAAa;EACX,WAAW;EACX,WAAW;EACX,OAAO;EACP,MAAM;EACN,UAAU;EACV,YAAY;EACb;UACQ,kBAAkB,aAC3B,cAAa,WAAW,QAAQ,MAAM,YACpC,QAAQ,QAAQ,KAAK,QAAQ,UAAU,KACxC;KAED,cAAa,WAAW,WAAW,SAAS;AAG9C,SAAQ,OAAO;EACb,MAAM;EACN,OAAO,QAAQ;EACf,WAAW,QAAQ;EACnB,SAAS,QAAQ;EACjB,iBAAiB,WAAW;EAC5B,YAAY,WAAW;EACvB;EACD,CAAC;AAEF,QAAO;EACL,QAAQ,WAAW;EACnB;EACA;EACA,YAAY,WAAW;EACxB"}
+{"version":3,"file":"index.js","names":["iterations: Array<{\n    iteration: number;\n    candidate: TOutput;\n    score: number;\n    pass: boolean;\n    critique: string;\n    durationMs: number;\n  }>","priorCritique: string | undefined","terminationReason: EvaluatorOptimizerOutcome<TOutput>['terminationReason']","candidate: TOutput","finalEntry: (typeof iterations)[number]"],"sources":["../../src/evaluator-optimizer/index.ts"],"sourcesContent":["/**\n * `evaluatorOptimizer({...})` - Generator → Evaluator iteration\n * loop with three rubric kinds and a REQUIRED iteration cap.\n *\n * Iteration boundary discipline: each iteration is a fresh\n * agent.run-equivalent boundary. Intra-loop reasoning per RB-42 /\n * suggested DEC-158 applies WITHIN one iteration, not ACROSS\n * iterations. The Generator's iteration-N input is the original\n * user input + the Evaluator's iteration-(N-1) critique (NOT the\n * Generator's iteration-(N-1) internal message history).\n *\n * @packageDocumentation\n */\n\nimport type { AgentEvent } from '@graphorin/core';\nimport { EvaluatorOptimizerConfigError } from '../errors/index.js';\n\n/**\n * Rubric discriminator. Pick the variant that matches your\n * Evaluator's contract.\n *\n * @stable\n */\nexport type Rubric =\n  | { readonly kind: 'free-form'; readonly instructions: string }\n  | { readonly kind: 'zod'; readonly instructions: string }\n  | { readonly kind: 'llm-judge'; readonly promptTemplate: string };\n\n/**\n * Per-iteration evaluation outcome returned by the Evaluator.\n *\n * @stable\n */\nexport interface EvaluatorOutcome {\n  readonly score: number;\n  readonly pass: boolean;\n  readonly critique: string;\n}\n\n/**\n * Generator callable shape. Receives the original user input plus\n * the previous iteration's critique (or `undefined` on the first\n * iteration) and returns the new candidate output.\n *\n * @stable\n */\nexport type GeneratorCallable<TOutput> = (\n  input: string,\n  priorCritique: string | undefined,\n  iteration: number,\n) => Promise<TOutput>;\n\n/**\n * Evaluator callable shape. Receives the original user input + the\n * candidate output and returns the structured outcome.\n *\n * @stable\n */\nexport type EvaluatorCallable<TOutput> = (\n  input: string,\n  candidate: TOutput,\n  rubric: Rubric,\n  iteration: number,\n) => Promise<EvaluatorOutcome>;\n\n/**\n * Options accepted by {@link evaluatorOptimizer}. `maxIterations`\n * is REQUIRED - the helper asserts `>= 1` at construction time.\n *\n * @stable\n */\nexport interface EvaluatorOptimizerOptions<TOutput> {\n  readonly generator: GeneratorCallable<TOutput>;\n  readonly evaluator: EvaluatorCallable<TOutput>;\n  readonly maxIterations: number;\n  readonly rubric: Rubric;\n  readonly mergeStrategy?: 'last-iteration' | 'best-score';\n  readonly signal?: AbortSignal;\n  /** Optional event emitter for `agent.evaluator.iteration / converged`. */\n  readonly emit?: (event: AgentEvent) => void;\n  readonly runId: string;\n  readonly sessionId: string;\n  readonly agentId: string;\n}\n\n/**\n * Aggregate outcome of an `evaluatorOptimizer({...})` run.\n *\n * @stable\n */\nexport interface EvaluatorOptimizerOutcome<TOutput> {\n  readonly output: TOutput;\n  readonly iterations: ReadonlyArray<{\n    readonly iteration: number;\n    readonly candidate: TOutput;\n    readonly score: number;\n    readonly pass: boolean;\n    readonly critique: string;\n    readonly durationMs: number;\n  }>;\n  readonly terminationReason: 'pass' | 'maxIterations' | 'generator-exhausted' | 'cancelled';\n  readonly finalScore: number;\n}\n\n/**\n * Run the Generator → Evaluator iteration loop.\n *\n * @stable\n */\nexport async function evaluatorOptimizer<TOutput>(\n  input: string,\n  options: EvaluatorOptimizerOptions<TOutput>,\n): Promise<EvaluatorOptimizerOutcome<TOutput>> {\n  if (!Number.isFinite(options.maxIterations) || options.maxIterations < 1) {\n    throw new EvaluatorOptimizerConfigError(\n      `'maxIterations' must be >= 1 (got ${String(options.maxIterations)})`,\n    );\n  }\n  const mergeStrategy = options.mergeStrategy ?? 'last-iteration';\n  const iterations: Array<{\n    iteration: number;\n    candidate: TOutput;\n    score: number;\n    pass: boolean;\n    critique: string;\n    durationMs: number;\n  }> = [];\n\n  let priorCritique: string | undefined;\n  let terminationReason: EvaluatorOptimizerOutcome<TOutput>['terminationReason'] = 'maxIterations';\n\n  for (let i = 1; i <= options.maxIterations; i++) {\n    if (options.signal?.aborted) {\n      terminationReason = 'cancelled';\n      break;\n    }\n    const iterStart = Date.now();\n    let candidate: TOutput;\n    try {\n      candidate = await options.generator(input, priorCritique, i);\n    } catch {\n      terminationReason = 'generator-exhausted';\n      break;\n    }\n    const outcome = await options.evaluator(input, candidate, options.rubric, i);\n    const iterDuration = Date.now() - iterStart;\n\n    iterations.push({\n      iteration: i,\n      candidate,\n      score: outcome.score,\n      pass: outcome.pass,\n      critique: outcome.critique,\n      durationMs: iterDuration,\n    });\n\n    options.emit?.({\n      type: 'agent.evaluator.iteration',\n      runId: options.runId,\n      sessionId: options.sessionId,\n      agentId: options.agentId,\n      iteration: i,\n      score: outcome.score,\n      pass: outcome.pass,\n      critique: outcome.critique,\n      durationMs: iterDuration,\n    });\n\n    if (outcome.pass) {\n      terminationReason = 'pass';\n      break;\n    }\n    priorCritique = outcome.critique;\n  }\n\n  let finalEntry: (typeof iterations)[number];\n  if (iterations.length === 0) {\n    // Should only happen on `cancelled` before the first iteration -\n    // synthesize a no-op final entry.\n    finalEntry = {\n      iteration: 0,\n      candidate: '' as unknown as TOutput,\n      score: 0,\n      pass: false,\n      critique: '',\n      durationMs: 0,\n    };\n  } else if (mergeStrategy === 'best-score') {\n    finalEntry = iterations.reduce((best, current) =>\n      current.score > best.score ? current : best,\n    );\n  } else {\n    finalEntry = iterations[iterations.length - 1] as (typeof iterations)[number];\n  }\n\n  options.emit?.({\n    type: 'agent.evaluator.converged',\n    runId: options.runId,\n    sessionId: options.sessionId,\n    agentId: options.agentId,\n    totalIterations: iterations.length,\n    finalScore: finalEntry.score,\n    terminationReason,\n  });\n\n  return {\n    output: finalEntry.candidate,\n    iterations,\n    terminationReason,\n    finalScore: finalEntry.score,\n  };\n}\n"],"mappings":";;;;;;;;AA6GA,eAAsB,mBACpB,OACA,SAC6C;AAC7C,KAAI,CAAC,OAAO,SAAS,QAAQ,cAAc,IAAI,QAAQ,gBAAgB,EACrE,OAAM,IAAI,8BACR,qCAAqC,OAAO,QAAQ,cAAc,CAAC,GACpE;CAEH,MAAM,gBAAgB,QAAQ,iBAAiB;CAC/C,MAAMA,aAOD,EAAE;CAEP,IAAIC;CACJ,IAAIC,oBAA6E;AAEjF,MAAK,IAAI,IAAI,GAAG,KAAK,QAAQ,eAAe,KAAK;AAC/C,MAAI,QAAQ,QAAQ,SAAS;AAC3B,uBAAoB;AACpB;;EAEF,MAAM,YAAY,KAAK,KAAK;EAC5B,IAAIC;AACJ,MAAI;AACF,eAAY,MAAM,QAAQ,UAAU,OAAO,eAAe,EAAE;UACtD;AACN,uBAAoB;AACpB;;EAEF,MAAM,UAAU,MAAM,QAAQ,UAAU,OAAO,WAAW,QAAQ,QAAQ,EAAE;EAC5E,MAAM,eAAe,KAAK,KAAK,GAAG;AAElC,aAAW,KAAK;GACd,WAAW;GACX;GACA,OAAO,QAAQ;GACf,MAAM,QAAQ;GACd,UAAU,QAAQ;GAClB,YAAY;GACb,CAAC;AAEF,UAAQ,OAAO;GACb,MAAM;GACN,OAAO,QAAQ;GACf,WAAW,QAAQ;GACnB,SAAS,QAAQ;GACjB,WAAW;GACX,OAAO,QAAQ;GACf,MAAM,QAAQ;GACd,UAAU,QAAQ;GAClB,YAAY;GACb,CAAC;AAEF,MAAI,QAAQ,MAAM;AAChB,uBAAoB;AACpB;;AAEF,kBAAgB,QAAQ;;CAG1B,IAAIC;AACJ,KAAI,WAAW,WAAW,EAGxB,cAAa;EACX,WAAW;EACX,WAAW;EACX,OAAO;EACP,MAAM;EACN,UAAU;EACV,YAAY;EACb;UACQ,kBAAkB,aAC3B,cAAa,WAAW,QAAQ,MAAM,YACpC,QAAQ,QAAQ,KAAK,QAAQ,UAAU,KACxC;KAED,cAAa,WAAW,WAAW,SAAS;AAG9C,SAAQ,OAAO;EACb,MAAM;EACN,OAAO,QAAQ;EACf,WAAW,QAAQ;EACnB,SAAS,QAAQ;EACjB,iBAAiB,WAAW;EAC5B,YAAY,WAAW;EACvB;EACD,CAAC;AAEF,QAAO;EACL,QAAQ,WAAW;EACnB;EACA;EACA,YAAY,WAAW;EACxB"}

package/dist/factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","names":[],"sources":["../src/factory.ts"],"sourcesContent":[],"mappings":";;;;;;;;;iBAovBgB,uDACN,YAAY,OAAO,WAC1B,MAAM,OAAO"}
+{"version":3,"file":"factory.d.ts","names":[],"sources":["../src/factory.ts"],"sourcesContent":[],"mappings":";;;;;;;;;iBAy4BgB,uDACN,YAAY,OAAO,WAC1B,MAAM,OAAO"}