@tangle-network/agent-runtime 0.68.0 → 0.70.0

package/dist/index.d.ts

@@ -1,23 +1,21 @@
-import { AgentProfile, AgentEvalError, KnowledgeReadinessReport, RunRecord, ControlEvalResult, KnowledgeRequirement } from '@tangle-network/agent-eval';
+import { AgentProfile, AgentEvalError, AnalystFinding, KnowledgeReadinessReport, RunRecord, ControlEvalResult, KnowledgeRequirement } from '@tangle-network/agent-eval';
 export { AgentEvalError, AgentEvalErrorCode, ConfigError, ControlBudget, ControlDecision, ControlEvalResult, ControlRunResult, ControlStep, DataAcquisitionPlan, JudgeError, KnowledgeReadinessReport, KnowledgeRequirement, NotFoundError, RunRecord, ValidationError } from '@tangle-network/agent-eval';
-import { h as AgentBackendInput, i as AgentExecutionBackend, c as OpenAIChatTool, j as OpenAIChatToolChoice, k as AgentBackendContext, R as RuntimeStreamEvent, K as KnowledgeReadinessDecision, l as RunAgentTaskOptions, m as AgentTaskRunResult, n as RunAgentTaskStreamOptions, o as AgentRuntimeEvent, p as AgentTaskStatus, q as RuntimeSessionStore, r as RuntimeSession } from './types-Crxftafi.js';
-export { s as AgentAdapter, t as AgentKnowledgeProvider, u as AgentRuntimeEventSink, v as AgentTaskContext, w as AgentTaskSpec, B as BackendErrorDetail, x as RuntimeRunHandle, y as RuntimeRunPersistenceAdapter, z as RuntimeRunRow, C as startRuntimeRun } from './types-Crxftafi.js';
-import { Scenario, ProfileDispatchFn } from '@tangle-network/agent-eval/campaign';
-export { C as CoderLoopRunnerOptions, D as DELEGATED_LOOP_MODES, a as DelegatedLoopMode, b as DelegatedLoopRegistry, c as DelegatedLoopResult, d as DelegatedLoopRunner, L as LoopRunnerCliArgs, e as LoopRunnerCliResult, R as ResearchLoopResult, f as ResearchLoopRunnerOptions, g as RunDelegatedLoopOptions, V as VetoedFact, W as WorktreeLoopRunnerOptions, h as auditLoopRunner, i as coderLoopRunner, j as isDelegatedLoopMode, p as parseLoopRunnerArgv, r as researchLoopRunner, k as runDelegatedLoop, l as runLoopRunnerCli, s as selfImproveLoopRunner, w as worktreeLoopRunner } from './loop-runner-bin-B6dzNZC8.js';
-export { m as mcpToolsForRuntimeMcp, a as mcpToolsForRuntimeMcpSubset } from './openai-tools-CA2N3-Ak.js';
-export { aU as EvalRunEvent, aV as EvalRunGeneration, aW as EvalRunsExportConfig, aX as EvalRunsExportResult, aY as INTELLIGENCE_WIRE_VERSION, aZ as LoopSpanNode, a_ as OtelAttribute, a$ as OtelExportConfig, b0 as OtelExporter, b1 as OtelSpan, b2 as buildLoopOtelSpans, b3 as buildLoopSpanNodes, b4 as createOtelExporter, b5 as exportEvalRuns, b6 as loopEventToOtelSpan } from './delegates-CLFNAKyi.js';
-import { R as RuntimeHooks } from './runtime-hooks-C7JwKb9E.js';
-export { b as RuntimeDecisionEvidenceRef, c as RuntimeDecisionKind, d as RuntimeDecisionPoint, e as RuntimeHookContext, f as RuntimeHookErrorContext, a as RuntimeHookEvent, g as RuntimeHookPhase, h as RuntimeHookTarget, i as composeRuntimeHooks, j as defineRuntimeHooks, n as notifyRuntimeDecisionPoint, k as notifyRuntimeHookEvent } from './runtime-hooks-C7JwKb9E.js';
+import { f as AgentBackendInput, g as AgentExecutionBackend, O as OpenAIChatTool, h as OpenAIChatToolChoice, i as AgentBackendContext, R as RuntimeStreamEvent, K as KnowledgeReadinessDecision, j as RunAgentTaskOptions, k as AgentTaskRunResult, l as RunAgentTaskStreamOptions, m as AgentRuntimeEvent, n as AgentTaskStatus, o as RuntimeSessionStore, p as RuntimeSession, b as RuntimeHooks } from './types-BYa2ZOAx.js';
+export { q as AgentAdapter, r as AgentKnowledgeProvider, s as AgentRuntimeEventSink, t as AgentTaskContext, u as AgentTaskSpec, B as BackendErrorDetail, v as RuntimeDecisionEvidenceRef, w as RuntimeDecisionKind, x as RuntimeDecisionPoint, y as RuntimeHookContext, z as RuntimeHookErrorContext, C as RuntimeHookEvent, D as RuntimeHookPhase, E as RuntimeHookTarget, F as RuntimeRunHandle, G as RuntimeRunPersistenceAdapter, H as RuntimeRunRow, J as composeRuntimeHooks, M as defineRuntimeHooks, N as notifyRuntimeDecisionPoint, P as notifyRuntimeHookEvent, Q as startRuntimeRun } from './types-BYa2ZOAx.js';
+import { AgentProfile as AgentProfile$1 } from '@tangle-network/agent-interface';
+import { Scenario, ProfileDispatchFn, LabeledScenarioStore, WorktreeAdapter, SurfaceProposer } from '@tangle-network/agent-eval/campaign';
+import { L as LocalHarness, r as runLocalHarness } from './delegates-DqAgo32T.js';
+export { aY as EvalRunEvent, aZ as EvalRunGeneration, a_ as EvalRunsExportConfig, a$ as EvalRunsExportResult, b0 as INTELLIGENCE_WIRE_VERSION, b1 as LoopSpanNode, b2 as OtelAttribute, b3 as OtelExportConfig, b4 as OtelExporter, b5 as OtelSpan, b6 as buildLoopOtelSpans, b7 as buildLoopSpanNodes, b8 as createOtelExporter, b9 as exportEvalRuns, ba as loopEventToOtelSpan } from './delegates-DqAgo32T.js';
+import { Scenario as Scenario$1, SurfaceProposer as SurfaceProposer$1, JudgeConfig, MutableSurface, DispatchContext, SelfImproveBudget, SelfImproveLlm, SelfImproveResult } from '@tangle-network/agent-eval/contract';
+import { S as SurfaceImprovementEdit } from './improvement-adapter-BVuMragr.js';
+import { I as ImprovementAdapter } from './types-DJu6TBGp.js';
+export { C as CoderLoopRunnerOptions, D as DELEGATED_LOOP_MODES, a as DelegatedLoopMode, b as DelegatedLoopRegistry, c as DelegatedLoopResult, d as DelegatedLoopRunner, L as LoopRunnerCliArgs, e as LoopRunnerCliResult, R as ResearchLoopResult, f as ResearchLoopRunnerOptions, g as RunDelegatedLoopOptions, V as VetoedFact, W as WorktreeLoopRunnerOptions, h as auditLoopRunner, i as coderLoopRunner, j as isDelegatedLoopMode, p as parseLoopRunnerArgv, r as researchLoopRunner, k as runDelegatedLoop, l as runLoopRunnerCli, s as selfImproveLoopRunner, w as worktreeLoopRunner } from './loop-runner-bin-B0NeLTRd.js';
+export { m as mcpToolsForRuntimeMcp, a as mcpToolsForRuntimeMcpSubset } from './openai-tools-DPx9Gzvn.js';
 import '@tangle-network/sandbox';
-import '@tangle-network/agent-eval/contract';
-import './types-p8dWBIXL.js';
-import './kb-gate-CuzMYGYM.js';
-import './worktree-fanout-DUiKPApb.js';
-import '@tangle-network/agent-interface';
-import './local-harness-BE_h8szs.js';
 import 'node:child_process';
-import './coder-2leJPOvC.js';
-import './substrate-CUgk7F7s.js';
+import './substrate-BoRXgvka.js';
+import './kb-gate-CuzMYGYM.js';
+import './worktree-fanout-gNfl0Byj.js';
 
 /**
  * @stable
@@ -671,6 +669,144 @@ declare function defineConversation(input: {
     policy: ConversationPolicy;
 }): Conversation;
 
+/**
+ * `runPersonaConversation` — the persona loop runner: run a WORKER `AgentProfile`
+ * (the agent under test) as a multi-round conversation driven by a PERSONA (the
+ * simulated user), over the persistent conversation transcript.
+ *
+ * It is profiles-vs-profiles: the persona is itself a driver `AgentProfile` (an
+ * LLM role-playing the user from its facts) — `runConversation` runs the two
+ * against each other. Scripted persona turns are kept as a deterministic
+ * fast-path. Only the WORKER is metered (it is the side under test); the
+ * persona-driver is the test harness, not billed against the agent.
+ *
+ * `runPersonaDispatch` wraps the runner as a `ProfileDispatchFn` so it drops
+ * straight into `runProfileMatrix({ dispatch })` — the same loop serves a single
+ * cell and the whole matrix, replacing the per-agent hand-rolled
+ * `dispatchWithSurface` bridges.
+ */
+
+/** A persona that drives the conversation: either a full driver `AgentProfile`
+ *  (an LLM user-sim) or a deterministic script of user turns (the fast-path). */
+type PersonaDriver = {
+    kind: 'profile';
+    profile: AgentProfile;
+} | {
+    kind: 'scripted';
+    turns: string[];
+};
+interface RunPersonaConversationOptions {
+    /** The agent under test. Metered; its rendered prompt leads its turns. */
+    worker: AgentProfile;
+    /** The simulated user driving the dialogue. */
+    persona: PersonaDriver;
+    /** Turn an `AgentProfile` into a runnable backend (router / sandbox / fake).
+     *  Applied to the worker and to a `profile`-kind persona. */
+    backendFor: (profile: AgentProfile, role: 'worker' | 'persona') => AgentExecutionBackend;
+    /** Render a profile's system prompt — prepended to that profile's messages. */
+    systemPromptOf: (profile: AgentProfile) => string;
+    /** Speaker-turn cap. Default for a scripted persona = `2 * turns.length`
+     *  (worker answers each user turn). REQUIRED for a `profile` persona. */
+    maxTurns?: number;
+    /** Kickoff message routed to the first speaker (the persona). Default 'Begin.' */
+    seed?: string;
+    /** Content-based "until satisfied" halt, called after every turn. `maxTurns` is the
+     *  hard ceiling; this is the early stop (the persona declares the goal met / unreachable). */
+    haltOn?: HaltPredicate;
+    signal?: AbortSignal;
+    /** Worker participant / transcript speaker label. Default 'agent'. */
+    workerName?: string;
+}
+interface PersonaConversationResult {
+    transcript: ConversationTurn[];
+    turns: number;
+    halted: HaltReason;
+    /** Worker-only spend (the side under test). */
+    costUsd: number;
+    tokensIn: number;
+    tokensOut: number;
+}
+/**
+ * Run one worker profile against one persona as a multi-round conversation.
+ * The persona leads (participant 0): it speaks, the worker answers, repeat,
+ * until `maxTurns`. Returns the persistent transcript + worker-only usage.
+ */
+declare function runPersonaConversation(opts: RunPersonaConversationOptions): Promise<PersonaConversationResult>;
+interface RunPersonaConfig<TScenario extends Scenario, TArtifact> {
+    /** Turn an `AgentProfile` into a runnable backend (router / sandbox / fake). */
+    backendFor: (profile: AgentProfile, role: 'worker' | 'persona') => AgentExecutionBackend;
+    /** Render a profile's system prompt. */
+    systemPromptOf: (profile: AgentProfile) => string;
+    /** The persona driving each scenario — a driver profile or scripted turns. */
+    personaOf: (scenario: TScenario) => PersonaDriver;
+    /** Build the scored artifact from the finished transcript. */
+    artifactOf: (transcript: ConversationTurn[], scenario: TScenario) => TArtifact;
+    /** Speaker-turn cap (required when a persona is profile-driven). */
+    maxTurns?: (scenario: TScenario) => number;
+    seed?: (scenario: TScenario) => string;
+    workerName?: string;
+}
+/**
+ * Wrap {@link runPersonaConversation} as a `ProfileDispatchFn` for
+ * `runProfileMatrix`: the profile axis is the worker-under-test, the scenario
+ * axis is the persona, and the runner is the cell. Meters the worker through
+ * `ctx.cost` so the matrix's backend-integrity guard sees real usage.
+ */
+declare function runPersonaDispatch<TScenario extends Scenario, TArtifact>(config: RunPersonaConfig<TScenario, TArtifact>): ProfileDispatchFn<TScenario, TArtifact>;
+
+/**
+ * `evalPersona` — the one-call user-sim product eval. Run a worker `AgentProfile` (the agent under
+ * test) against a PERSONA (a simulated user — a scripted script or an LLM driver profile) as a
+ * multi-round conversation, with the two seams `runPersonaConversation` otherwise makes you hand-wire
+ * defaulted:
+ *
+ *  - `backendFor` defaults to `createOpenAICompatibleBackend({ apiKey, baseUrl, model })` (the
+ *    OpenAI-compatible router endpoint) for both the worker and a profile-driven persona;
+ *  - `systemPromptOf` defaults to `p.prompt?.systemPrompt ?? ''`.
+ *
+ * Either is overridable (tests pass a fake `backendFor` to run offline). `maxTurns` (the hard
+ * ceiling) and `haltOn` (the "until satisfied" early stop) pass straight through. Mirrors
+ * `supervise()`'s defaulting style: the common case is one call; the raw `runPersonaConversation`
+ * seam stays available for full control.
+ *
+ * The profile here is the authored `AgentProfile` (with `prompt.systemPrompt`), which is why the
+ * default `systemPromptOf` can read it. `runPersonaConversation` treats the profile opaquely — only
+ * the two callbacks inspect it — so the worker/persona profiles flow straight through.
+ */
+
+interface EvalPersonaOptions {
+    /** Router (or OpenAI-compatible) endpoint for the DEFAULT backend. Required unless `backendFor`
+     *  is supplied (tests/advanced override the backend entirely and may omit these). */
+    apiKey?: string;
+    baseUrl?: string;
+    model?: string;
+    /** Override the backend seam directly instead of deriving it from `apiKey`/`baseUrl`/`model`
+     *  (the offline-test path: pass a fake here and the credentials are not needed). */
+    backendFor?: (profile: AgentProfile$1, role: 'worker' | 'persona') => AgentExecutionBackend;
+    /** Override system-prompt rendering. Default: `p.prompt?.systemPrompt ?? ''`. */
+    systemPromptOf?: (profile: AgentProfile$1) => string;
+    /** Hard speaker-turn ceiling. REQUIRED for a profile-driven persona; for a scripted persona it
+     *  defaults to `2 * turns.length`. `maxTurns` is a CEILING, NOT a target — `maxTurns: 0` is zero
+     *  turns, not run-until-done; `haltOn` is the "until satisfied" knob. */
+    maxTurns?: number;
+    /** Content-based early stop (the persona declares the goal met / unreachable). */
+    haltOn?: HaltPredicate;
+    /** Kickoff message to the persona. Default 'Begin.' */
+    seed?: string;
+    signal?: AbortSignal;
+    /** Worker transcript speaker label. Default 'agent'. */
+    workerName?: string;
+}
+/** The persona side, authored against the same `AgentProfile` shape as the worker. */
+type EvalPersona = {
+    kind: 'scripted';
+    turns: string[];
+} | {
+    kind: 'profile';
+    profile: AgentProfile$1;
+};
+declare function evalPersona(worker: AgentProfile$1, persona: EvalPersona, opts?: EvalPersonaOptions): Promise<PersonaConversationResult>;
+
 /**
  * @stable
  *
@@ -805,88 +941,6 @@ declare class SqlConversationJournal implements ConversationJournal {
 declare function runConversation(conversation: Conversation, options: RunConversationOptions): Promise<ConversationResult>;
 declare function runConversationStream(conversation: Conversation, options: RunConversationOptions): AsyncIterable<ConversationStreamEvent>;
 
-/**
- * `runPersonaConversation` — the persona loop runner: run a WORKER `AgentProfile`
- * (the agent under test) as a multi-round conversation driven by a PERSONA (the
- * simulated user), over the persistent conversation transcript.
- *
- * It is profiles-vs-profiles: the persona is itself a driver `AgentProfile` (an
- * LLM role-playing the user from its facts) — `runConversation` runs the two
- * against each other. Scripted persona turns are kept as a deterministic
- * fast-path. Only the WORKER is metered (it is the side under test); the
- * persona-driver is the test harness, not billed against the agent.
- *
- * `runPersonaDispatch` wraps the runner as a `ProfileDispatchFn` so it drops
- * straight into `runProfileMatrix({ dispatch })` — the same loop serves a single
- * cell and the whole matrix, replacing the per-agent hand-rolled
- * `dispatchWithSurface` bridges.
- */
-
-/** A persona that drives the conversation: either a full driver `AgentProfile`
- *  (an LLM user-sim) or a deterministic script of user turns (the fast-path). */
-type PersonaDriver = {
-    kind: 'profile';
-    profile: AgentProfile;
-} | {
-    kind: 'scripted';
-    turns: string[];
-};
-interface RunPersonaConversationOptions {
-    /** The agent under test. Metered; its rendered prompt leads its turns. */
-    worker: AgentProfile;
-    /** The simulated user driving the dialogue. */
-    persona: PersonaDriver;
-    /** Turn an `AgentProfile` into a runnable backend (router / sandbox / fake).
-     *  Applied to the worker and to a `profile`-kind persona. */
-    backendFor: (profile: AgentProfile, role: 'worker' | 'persona') => AgentExecutionBackend;
-    /** Render a profile's system prompt — prepended to that profile's messages. */
-    systemPromptOf: (profile: AgentProfile) => string;
-    /** Speaker-turn cap. Default for a scripted persona = `2 * turns.length`
-     *  (worker answers each user turn). REQUIRED for a `profile` persona. */
-    maxTurns?: number;
-    /** Kickoff message routed to the first speaker (the persona). Default 'Begin.' */
-    seed?: string;
-    signal?: AbortSignal;
-    /** Worker participant / transcript speaker label. Default 'agent'. */
-    workerName?: string;
-}
-interface PersonaConversationResult {
-    transcript: ConversationTurn[];
-    turns: number;
-    halted: HaltReason;
-    /** Worker-only spend (the side under test). */
-    costUsd: number;
-    tokensIn: number;
-    tokensOut: number;
-}
-/**
- * Run one worker profile against one persona as a multi-round conversation.
- * The persona leads (participant 0): it speaks, the worker answers, repeat,
- * until `maxTurns`. Returns the persistent transcript + worker-only usage.
- */
-declare function runPersonaConversation(opts: RunPersonaConversationOptions): Promise<PersonaConversationResult>;
-interface RunPersonaConfig<TScenario extends Scenario, TArtifact> {
-    /** Turn an `AgentProfile` into a runnable backend (router / sandbox / fake). */
-    backendFor: (profile: AgentProfile, role: 'worker' | 'persona') => AgentExecutionBackend;
-    /** Render a profile's system prompt. */
-    systemPromptOf: (profile: AgentProfile) => string;
-    /** The persona driving each scenario — a driver profile or scripted turns. */
-    personaOf: (scenario: TScenario) => PersonaDriver;
-    /** Build the scored artifact from the finished transcript. */
-    artifactOf: (transcript: ConversationTurn[], scenario: TScenario) => TArtifact;
-    /** Speaker-turn cap (required when a persona is profile-driven). */
-    maxTurns?: (scenario: TScenario) => number;
-    seed?: (scenario: TScenario) => string;
-    workerName?: string;
-}
-/**
- * Wrap {@link runPersonaConversation} as a `ProfileDispatchFn` for
- * `runProfileMatrix`: the profile axis is the worker-under-test, the scenario
- * axis is the persona, and the runner is the cell. Meters the worker through
- * `ctx.cost` so the matrix's backend-integrity guard sees real usage.
- */
-declare function runPersonaDispatch<TScenario extends Scenario, TArtifact>(config: RunPersonaConfig<TScenario, TArtifact>): ProfileDispatchFn<TScenario, TArtifact>;
-
 /**
  * @stable
  *
@@ -1103,6 +1157,291 @@ declare class PlannerError extends AgentEvalError {
     });
 }
 
+/**
+ * @experimental
+ *
+ * `improvementDriver` — the ONE reflective/agentic improvement proposer for
+ * agent-eval's improvement loop. It implements `SurfaceProposer` and owns
+ * the candidate lifecycle (worktree create → generate → finalize/discard,
+ * × populationSize); it delegates the only thing that genuinely varies — HOW
+ * a candidate change is produced — to a pluggable `CandidateGenerator`.
+ *
+ * There is no separate "analyst driver" vs "autoresearch driver": those are
+ * the SAME driver at two settings of a dial.
+ *   - cheap reflective path  → `reflectiveGenerator` (shots=1, no sandbox;
+ *                              applies pre-drafted patches)
+ *   - full agentic path      → `agenticGenerator` (shots=N, multi-shot
+ *                              verify-in-session loop; an agent reads code +
+ *                              report, edits, and re-tries on verifier failure)
+ * Both emit changes into a worktree the driver finalizes into a
+ * `CodeSurface{ worktreeRef }` the loop measures on the holdout. See
+ * agent-eval's `docs/design/self-improvement-engine.md`.
+ */
+
+/** The byte-producing seam — the ONE thing that differs between the cheap
+ *  reflective path and the full agentic path. A generator makes (uncommitted)
+ *  changes inside `worktreePath`; the driver commits them via the worktree
+ *  adapter's `finalize`. */
+interface CandidateGenerator {
+    kind: string;
+    generate(args: {
+        /** The candidate worktree — a fresh checkout of baseRef. Write changes here. */
+        worktreePath: string;
+        /** Phase-2 research report (analyst findings + diff), opaque. */
+        report: unknown;
+        /** Findings resolved from the report or the loop context. */
+        findings: AnalystFinding[];
+        /** Handle to all captured data, to ground the change. */
+        dataset?: LabeledScenarioStore;
+        /** DEPTH: max iterations the generator may take (agentic uses this; the
+         *  reflective generator ignores it). */
+        maxShots: number;
+        signal: AbortSignal;
+    }): Promise<{
+        applied: boolean;
+        summary: string;
+    }>;
+}
+interface ImprovementDriverOptions {
+    worktree: WorktreeAdapter;
+    generator: CandidateGenerator;
+    /** Base ref candidate worktrees fork from. Default `main`. */
+    baseRef?: string;
+}
+declare function improvementDriver(opts: ImprovementDriverOptions): SurfaceProposer<AnalystFinding>;
+
+/**
+ * @experimental
+ *
+ * `agenticGenerator` — the full-agentic `CandidateGenerator`: the
+ * `shots=N, sandbox=on` setting of the one `improvementDriver`. It runs a real
+ * coding harness (claude / codex / opencode) inside the candidate worktree the
+ * driver already created, letting the agent read the codebase + the research
+ * report and make the change in place. The driver then commits the worktree
+ * into a `CodeSurface`.
+ *
+ * Mechanism: identical to the proven Phase-2.8 in-process executor — spawn the
+ * harness as a subprocess with `cwd` = the worktree, on the same filesystem,
+ * so edits land in place (no sandbox-mount round-trip). `runLocalHarness` is
+ * the verified primitive. The OUTER sandbox is the improvement loop's own
+ * execution context; the generator does not nest a second sandbox per
+ * candidate (which would reintroduce a host↔sandbox worktree-transport
+ * problem that does not need solving here).
+ *
+ * `maxShots` is the DEPTH dial — a multi-shot verify-in-session loop, NOT the
+ * kernel `runLoop`. Each shot runs one full harness session in the (persistent)
+ * worktree; between shots the loop refines based on what the last shot produced:
+ *   - empty tree   → "you changed nothing, make the edits" → retry
+ *   - dirty + `verify` fails → feed the verifier's failure into the next shot
+ *       (the worktree persists, so the harness RESUMES atop its own failing
+ *       edits with the error in hand — no `--resume` session plumbing needed,
+ *       and harness-agnostic across claude/codex/opencode)
+ *   - dirty + `verify` ok (or no verifier configured) → return the candidate
+ * A candidate that never verifies within `maxShots` is discarded (`applied:
+ * false`), never shipped — if you configured a verifier, a non-passing tree is
+ * not a candidate. With no verifier the legacy behavior holds: first dirty shot
+ * is the candidate.
+ */
+
+/** Outcome of verifying a candidate worktree. `feedback` (compiler errors,
+ *  failing test output) is fed into the next shot when `ok` is false. */
+interface VerifyResult {
+    ok: boolean;
+    feedback?: string;
+}
+/** Verifies the edited worktree. Sync or async; throws only on a setup fault
+ *  (a candidate that fails verification returns `{ok:false}`, it does not
+ *  throw). */
+type Verifier = (worktreePath: string) => Promise<VerifyResult> | VerifyResult;
+interface AgenticGeneratorOptions {
+    /** Local coding harness to run in the worktree. Default `claude`. */
+    harness?: LocalHarness;
+    /** Per-shot wall-clock timeout (ms). Default = `runLocalHarness` default (5m). */
+    timeoutMs?: number;
+    /** Build the harness task prompt from the report + findings. Override for
+     *  domain phrasing; the default turns findings into a concrete coder task. */
+    buildPrompt?: (args: {
+        report: unknown;
+        findings: AnalystFinding[];
+    }) => string;
+    /** Verify the worktree after each dirtying shot. When set, a candidate that
+     *  fails verification is NOT returned — the failure feeds the next shot
+     *  (verify-in-session), up to `maxShots`; a candidate that never verifies is
+     *  discarded (`applied:false`), never shipped. Omitted ⇒ legacy behavior:
+     *  the first dirty shot is the candidate. See `commandVerifier`. */
+    verify?: Verifier;
+    /** Test seam — inject the harness runner (defaults to `runLocalHarness`). */
+    runHarness?: typeof runLocalHarness;
+    /** Test seam — inject the worktree-dirty check (defaults to `git status`). */
+    isDirty?: (worktreePath: string) => boolean;
+}
+declare function agenticGenerator(opts?: AgenticGeneratorOptions): CandidateGenerator;
+/** A `Verifier` that runs a command in the worktree: exit 0 ⇒ ok, any other
+ *  exit ⇒ failed with stdout+stderr as feedback. The common case — verify by
+ *  `tsc --noEmit`, `pnpm build`, or a test command. A timeout is treated as a
+ *  FAILED candidate (a change that hangs the build is a bad change); a missing
+ *  binary or spawn fault throws (a setup bug, not a failed candidate — no
+ *  silent fallback). */
+declare function commandVerifier(command: string, args?: string[], timeoutMs?: number): Verifier;
+
+/**
+ * Build-prompt starting points for the two buildable artifact types. There is
+ * NO `toolGenerator`/`mcpGenerator` wrapper — the factory is `agenticGenerator`
+ * + a verifier (docs/artifact-lifecycle-frontier.md), so a tool or an MCP
+ * server is built by composing the pieces directly:
+ *
+ *   // a tool:
+ *   agenticGenerator({ buildPrompt: toolBuildPrompt, verify: commandVerifier('pnpm', ['test']) })
+ *   // an MCP server:
+ *   agenticGenerator({ buildPrompt: mcpBuildPrompt, verify: mcpServeVerifier({ command: 'node', args: ['server.mjs'] }) })
+ *
+ * These are the only type-specific bit (the phrasing that points the agent at a
+ * tool vs. an MCP); the worktree, resume-on-failure loop, and improvement-loop
+ * wrapper are shared. MCP is the load-bearing target — it is how a harness
+ * acquires tools; raw tools matter where we control the loader.
+ */
+
+type FindingsArg = {
+    report: unknown;
+    findings: AnalystFinding[];
+};
+declare function toolBuildPrompt(args: FindingsArg): string;
+declare function mcpBuildPrompt(args: FindingsArg): string;
+
+/**
+ * @experimental
+ *
+ * `improve` — the ONE public, surface-pluggable RSI verb.
+ *
+ * A thin facade over agent-eval's `selfImprove` (the held-out-gated closed
+ * loop). It removes the two things a caller otherwise has to know to drive the
+ * loop by hand: WHICH `MutableSurface` of the profile is being optimized, and
+ * WHICH `SurfaceProposer` mutates that surface. You name a `surface`; the
+ * facade picks the matching default proposer, extracts the baseline surface from
+ * the profile, runs `selfImprove`, and (on a ship verdict) writes the promoted
+ * winner back into the corresponding profile field.
+ *
+ *   - `surface: 'prompt'` → `gepaProposer` mutates `profile.prompt.systemPrompt`.
+ *   - `surface: 'skills'` → `skillOptProposer` mutates a skills document string.
+ *   - `surface` ∈ {`tools`, `mcp`, `hooks`, `code`} → no zero-config default
+ *     proposer exists (a code/config proposer needs caller-supplied wiring — a
+ *     worktree repo root, a candidate generator, a serializer). The facade
+ *     requires an explicit `opts.generator` for these and throws a `ConfigError`
+ *     otherwise. This is a designed boundary, not a missing default: there is
+ *     no safe value the facade could invent for those seams.
+ *
+ * Everything else (`scenarios`, `judge`, `agent`, `budget`, `llm`) passes
+ * straight through to `selfImprove`.
+ */
+
+/** The agent-profile lever `improve` optimizes. Mirrors the AgentProfile-law
+ *  profile levers; `code` is the implementation-tier surface. */
+type ImproveSurface = 'prompt' | 'skills' | 'tools' | 'mcp' | 'hooks' | 'code';
+interface ImproveOptions<TScenario extends Scenario$1, TArtifact> {
+    /** Which profile lever to optimize. Default `'prompt'`. Selects the default
+     *  generator + the baseline-surface extraction shape. */
+    surface?: ImproveSurface;
+    /** The `SurfaceProposer` that mutates the surface. When unset, the facade
+     *  picks the default for `surface` (`gepaProposer` for prompt, `skillOptProposer`
+     *  for skills); surfaces with no default REQUIRE this (fail-loud otherwise). */
+    generator?: SurfaceProposer$1;
+    /** Gate mode. `'holdout'` (default) runs the held-out promotion gate;
+     *  `'none'` is a baseline-only run (`budget.generations = 0`). */
+    gate?: 'holdout' | 'none';
+    /** Scenarios to evaluate against. Passthrough to `selfImprove`. */
+    scenarios: TScenario[];
+    /** Judge that scores artifacts. Passthrough to `selfImprove`. */
+    judge: JudgeConfig<TArtifact, TScenario>;
+    /** The agent under improvement — same shape as `selfImprove.agent`: it takes
+     *  the current surface + scenario + ctx and returns the artifact to judge. */
+    agent: (surface: MutableSurface, scenario: TScenario, ctx: DispatchContext) => Promise<TArtifact>;
+    /** Budget + loop shape. Passthrough; `gate: 'none'` forces `generations = 0`. */
+    budget?: SelfImproveBudget;
+    /** LLM config. Passthrough to `selfImprove` AND used to construct the default
+     *  reflective proposer (`gepaProposer`/`skillOptProposer`) when `generator` is unset. */
+    llm?: SelfImproveLlm;
+    /** Restrict the run to this subset of models. When set, the reflection model
+     *  (`llm.model`, or the default when unset) must be a member, or `improve()` throws
+     *  a `ConfigError` before the generator is built. Unset = unrestricted. */
+    allowedModels?: readonly string[];
+}
+interface ImproveResult<TScenario extends Scenario$1, TArtifact> {
+    /** The profile after improvement: the winner surface applied back into the
+     *  matching field when the gate shipped, else the input profile unchanged. */
+    profile: AgentProfile$1;
+    /** True when `gateDecision === 'ship'`. */
+    shipped: boolean;
+    /** Held-out lift (`winner − baseline` composite). */
+    lift: number;
+    /** The five-valued gate verdict from `selfImprove`. */
+    gateDecision: SelfImproveResult<TScenario, TArtifact>['gateDecision'];
+    /** Full `selfImprove` result for advanced inspection. */
+    raw: SelfImproveResult<TScenario, TArtifact>;
+}
+/**
+ * Run the held-out-gated self-improvement loop on ONE profile surface.
+ *
+ * @example Optimize the system prompt, default holdout gate:
+ *
+ *   const out = await improve(profile, findings, {
+ *     surface: 'prompt',
+ *     scenarios,
+ *     judge,
+ *     agent: (surface, scenario, ctx) => runAgent(surface, scenario, ctx.signal),
+ *   })
+ *   if (out.shipped) deploy(out.profile)
+ */
+declare function improve<TScenario extends Scenario$1, TArtifact>(profile: AgentProfile$1, findings: unknown[], opts: ImproveOptions<TScenario, TArtifact>): Promise<ImproveResult<TScenario, TArtifact>>;
+
+/**
+ * `mcpServeVerifier` — the intrinsic verifier for a built MCP server: the
+ * boot-and-probe checker named in docs/artifact-lifecycle-frontier.md. A
+ * generated MCP server is only a candidate if it actually *serves* — so this
+ * boots it over stdio (the default local MCP transport) and runs the real
+ * handshake: `initialize` → `notifications/initialized` → `tools/list`, and
+ * asserts the server answers with at least `minTools` tools.
+ *
+ * Outcomes follow the `Verifier` contract: a server that fails to start, exits
+ * early, errors the handshake, times out, or exposes no tools is a FAILED
+ * candidate (`{ok:false}`, fed back into the next generation shot); a missing
+ * start binary or spawn fault THROWS (a setup bug, never a silent fallback).
+ *
+ * Protocol matches the runtime's own stdio MCP server (src/mcp/server.ts):
+ * newline-delimited JSON-RPC 2.0, protocol version 2024-11-05.
+ */
+
+interface McpServeSpec {
+    /** Command that starts the built MCP server in the worktree (stdio transport). */
+    command: string;
+    args?: string[];
+    /** Extra env for the server process (merged over `process.env`). */
+    env?: Record<string, string>;
+    /** Handshake timeout (ms). Default 30s. */
+    timeoutMs?: number;
+    /** Minimum tools the server must expose to pass. Default 1. */
+    minTools?: number;
+}
+declare function mcpServeVerifier(spec: McpServeSpec): Verifier;
+
+/**
+ * @experimental
+ *
+ * `reflectiveGenerator` — the cheap, no-sandbox `CandidateGenerator`. It drafts
+ * surface edits via the existing improvement adapter (`proposeFromFindings`,
+ * one LLM patch per finding) and applies them as ONE coherent improvement into
+ * the candidate worktree. `maxShots` is ignored — reflection is single-shot by
+ * construction (the patches are already drafted).
+ *
+ * This is the `shots=1, sandbox=off` setting of the one improvement driver.
+ * The `agenticGenerator` (a multi-shot verify-in-session loop) is the
+ * `shots=N` setting — both plug into the same `improvementDriver`.
+ */
+
+interface ReflectiveGeneratorOptions {
+    improvementAdapter: ImprovementAdapter<SurfaceImprovementEdit>;
+}
+declare function reflectiveGenerator(opts: ReflectiveGeneratorOptions): CandidateGenerator;
+
 /**
  * @stable
  *
@@ -1547,4 +1886,4 @@ interface StreamToolLoopOptions<Raw> {
  *  `capped` if it stops for any non-completed reason with calls still pending. */
 declare function streamToolLoop<Raw>(opts: StreamToolLoopOptions<Raw>): AsyncGenerator<StreamToolLoopYield<Raw>, void, unknown>;
 
-export { AgentBackendContext, AgentBackendInput, AgentExecutionBackend, AgentRuntimeEvent, AgentTaskRunResult, AgentTaskStatus, type AuthSource, type BackendCallPolicy, BackendTransportError, type ChatStreamEvent, type ChatTurnHooks, type ChatTurnIdentity, type ChatTurnProducer, type ChatTurnResult, type CircuitBreakerConfig, CircuitBreakerState, CircuitOpenError, type Conversation, type ConversationDriveState, type ConversationJournal, type ConversationJournalEntry, type ConversationParticipant, type ConversationPolicy, type ConversationResult, type ConversationStreamEvent, type ConversationTurn, type D1DatabaseLike, type D1StmtLike, DEFAULT_MAX_DEPTH, DEFAULT_ROUTER_BASE_URL, DeadlineExceededError, FORWARD_HEADERS, FileConversationJournal, type ForwardHeaderName, type HaltContext, type HaltPredicate, type HaltReason, type HaltSignal, InMemoryConversationJournal, InMemoryRuntimeSessionStore, type ModelInfo, OpenAIChatTool, OpenAIChatToolChoice, type PersonaConversationResult, type PersonaDriver, PlannerError, type PropagatedHeaders, type ResolvedChatModel, type RetryBackoff, type RetryableErrorPredicate, type RouterEnv, type RunChatTurnInput, type RunConversationOptions, type RunPersonaConfig, type RunPersonaConversationOptions, type RunToolLoopOptions, type RuntimeEventCollector, RuntimeHooks, RuntimeRunStateError, RuntimeSessionStore, RuntimeStreamEvent, type RuntimeStreamEventCollector, type RuntimeTelemetryOptions, type SanitizedKnowledgeReadinessReport, type SqlAdapter, SqlConversationJournal, type StreamToolLoopOptions, type StreamToolLoopYield, type ToolCallOutcome, type ToolLoopAssistantToolCall, type ToolLoopCall, type ToolLoopEvent, type ToolLoopMessage, type ToolLoopResult, type ToolLoopStopReason, type TurnOrder, applyRunRecordDefaults, buildForwardHeaders, cleanModelId, computeBackoff, createConversationBackend, createIterableBackend, createOpenAICompatibleBackend, createRuntimeEventCollector, createRuntimeStreamEventCollector, createSandboxPromptBackend, d1ToSqlAdapter, decideKnowledgeReadiness, defaultIsRetryable, defineConversation, deriveExecutionId, getModels, handleChatTurn, isDepthExceeded, makePerAttemptSignal, readDepth, readinessServerSentEvent, resolveChatModel, resolveRouterBaseUrl, runAgentTask, runAgentTaskStream, runConversation, runConversationStream, runPersonaConversation, runPersonaDispatch, runToolLoop, runtimeStreamServerSentEvent, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, sleep, slugifySpeaker, streamToolLoop, turnId, validateChatModelId };
+export { AgentBackendContext, AgentBackendInput, AgentExecutionBackend, AgentRuntimeEvent, AgentTaskRunResult, AgentTaskStatus, type AgenticGeneratorOptions, type AuthSource, type BackendCallPolicy, BackendTransportError, type CandidateGenerator, type ChatStreamEvent, type ChatTurnHooks, type ChatTurnIdentity, type ChatTurnProducer, type ChatTurnResult, type CircuitBreakerConfig, CircuitBreakerState, CircuitOpenError, type Conversation, type ConversationDriveState, type ConversationJournal, type ConversationJournalEntry, type ConversationParticipant, type ConversationPolicy, type ConversationResult, type ConversationStreamEvent, type ConversationTurn, type D1DatabaseLike, type D1StmtLike, DEFAULT_MAX_DEPTH, DEFAULT_ROUTER_BASE_URL, DeadlineExceededError, type EvalPersonaOptions, FORWARD_HEADERS, FileConversationJournal, type ForwardHeaderName, type HaltContext, type HaltPredicate, type HaltReason, type HaltSignal, type ImproveOptions, type ImproveResult, type ImproveSurface, type ImprovementDriverOptions, InMemoryConversationJournal, InMemoryRuntimeSessionStore, type McpServeSpec, type ModelInfo, OpenAIChatTool, OpenAIChatToolChoice, type PersonaConversationResult, type PersonaDriver, PlannerError, type PropagatedHeaders, type ReflectiveGeneratorOptions, type ResolvedChatModel, type RetryBackoff, type RetryableErrorPredicate, type RouterEnv, type RunChatTurnInput, type RunConversationOptions, type RunPersonaConfig, type RunPersonaConversationOptions, type RunToolLoopOptions, type RuntimeEventCollector, RuntimeHooks, RuntimeRunStateError, RuntimeSessionStore, RuntimeStreamEvent, type RuntimeStreamEventCollector, type RuntimeTelemetryOptions, type SanitizedKnowledgeReadinessReport, type SqlAdapter, SqlConversationJournal, type StreamToolLoopOptions, type StreamToolLoopYield, type ToolCallOutcome, type ToolLoopAssistantToolCall, type ToolLoopCall, type ToolLoopEvent, type ToolLoopMessage, type ToolLoopResult, type ToolLoopStopReason, type TurnOrder, type Verifier, type VerifyResult, agenticGenerator, applyRunRecordDefaults, buildForwardHeaders, cleanModelId, commandVerifier, computeBackoff, createConversationBackend, createIterableBackend, createOpenAICompatibleBackend, createRuntimeEventCollector, createRuntimeStreamEventCollector, createSandboxPromptBackend, d1ToSqlAdapter, decideKnowledgeReadiness, defaultIsRetryable, defineConversation, deriveExecutionId, evalPersona, getModels, handleChatTurn, improve, improvementDriver, isDepthExceeded, makePerAttemptSignal, mcpBuildPrompt, mcpServeVerifier, readDepth, readinessServerSentEvent, reflectiveGenerator, resolveChatModel, resolveRouterBaseUrl, runAgentTask, runAgentTaskStream, runConversation, runConversationStream, runPersonaConversation, runPersonaDispatch, runToolLoop, runtimeStreamServerSentEvent, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, sleep, slugifySpeaker, streamToolLoop, toolBuildPrompt, turnId, validateChatModelId };