@tangle-network/agent-runtime 0.73.0 → 0.74.0

package/dist/mcp-serve-verifier-CT1KLTG_.d.ts

@@ -0,0 +1,162 @@
+import { AnalystFinding } from '@tangle-network/agent-eval';
+import { L as LocalHarness, r as runLocalHarness } from './local-harness-BE_h8szs.js';
+import { LabeledScenarioStore, WorktreeAdapter, SurfaceProposer } from '@tangle-network/agent-eval/campaign';
+
+/**
+ * @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;
+
+/**
+ * `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;
+
+export { type AgenticGeneratorOptions as A, type CandidateGenerator as C, type ImprovementDriverOptions as I, type McpServeSpec as M, type Verifier as V, type VerifyResult as a, agenticGenerator as b, commandVerifier as c, improvementDriver as i, mcpServeVerifier as m };

package/dist/{openai-tools-CBurv8Cu.d.ts → openai-tools-D-VCAEmw.d.ts}

@@ -1,4 +1,4 @@
-import { O as OpenAIChatTool } from './types-JufmXF2a.js';
+import { O as OpenAIChatTool } from './types-YimN9PQP.js';
 
 /**
  * @experimental

package/dist/profiles.d.ts

@@ -1,6 +1,6 @@
 import { a as UiFinding, U as UiLens } from './substrate-rNj6TDc3.js';
 export { C as CoderTask, b as UI_FINDING_SEVERITIES, c as UI_LENSES, d as UiFindingScreenshot, e as UiFindingSeverity, f as coderTaskToPrompt } from './substrate-rNj6TDc3.js';
-import { S as SandboxClient, a as OutputAdapter, V as Validator, A as AgentRunSpec } from './types-JufmXF2a.js';
+import { S as SandboxClient, b as OutputAdapter, V as Validator, A as AgentRunSpec } from './types-YimN9PQP.js';
 import { SandboxEvent } from '@tangle-network/sandbox';
 import { AgentProfile } from '@tangle-network/agent-interface';
 import '@tangle-network/agent-eval';

package/dist/{types-JufmXF2a.d.ts → types-YimN9PQP.d.ts}

@@ -1257,4 +1257,4 @@ interface ExecCtx {
     parentSpanId?: string;
 }
 
-export { type LoopEndedPayload as $, type AgentRunSpec as A, type BackendErrorDetail as B, type RuntimeHookEvent as C, type RuntimeHookPhase as D, type ExecCtx as E, type RuntimeHookTarget as F, type RuntimeRunHandle as G, type RuntimeRunPersistenceAdapter as H, type Iteration as I, type RuntimeRunRow as J, type KnowledgeReadinessDecision as K, type LoopTokenUsage as L, composeRuntimeHooks as M, defineRuntimeHooks as N, type OpenAIChatTool as O, notifyRuntimeDecisionPoint as P, notifyRuntimeHookEvent as Q, type RuntimeStreamEvent as R, type SandboxClient as S, startRuntimeRun as T, type Driver as U, type Validator as V, type LoopWinner as W, type LoopLineageOptions as X, type LoopResult as Y, type MountRecorder as Z, type LoopDecisionPayload as _, type OutputAdapter as a, type LoopIterationDispatchPayload as a0, type LoopIterationEndedPayload as a1, type LoopIterationStartedPayload as a2, type LoopPlanDescription as a3, type LoopPlanPayload as a4, type LoopStartedPayload as a5, type LoopTeardownFailedPayload as a6, type MountManifestEntry as a7, type RunProvenance as a8, type SelectionReceipt as a9, type ValidationCtx as aa, type RuntimeHooks as b, type LoopTraceEvent as c, type LoopSandboxPlacement as d, type LoopTraceEmitter as e, type AgentBackendInput as f, type AgentExecutionBackend as g, type OpenAIChatToolChoice as h, type AgentBackendContext as i, type RunAgentTaskOptions as j, type AgentTaskRunResult as k, type RunAgentTaskStreamOptions as l, type AgentRuntimeEvent as m, type AgentTaskStatus as n, type RuntimeSessionStore as o, type RuntimeSession as p, type AgentAdapter as q, type AgentKnowledgeProvider as r, type AgentRuntimeEventSink as s, type AgentTaskContext as t, type AgentTaskSpec as u, type RuntimeDecisionEvidenceRef as v, type RuntimeDecisionKind as w, type RuntimeDecisionPoint as x, type RuntimeHookContext as y, type RuntimeHookErrorContext as z };
+export { type LoopEndedPayload as $, type AgentRunSpec as A, type BackendErrorDetail as B, type RuntimeHookEvent as C, type RuntimeHookPhase as D, type ExecCtx as E, type RuntimeHookTarget as F, type RuntimeRunHandle as G, type RuntimeRunPersistenceAdapter as H, type Iteration as I, type RuntimeRunRow as J, type KnowledgeReadinessDecision as K, type LoopTokenUsage as L, composeRuntimeHooks as M, defineRuntimeHooks as N, type OpenAIChatTool as O, notifyRuntimeDecisionPoint as P, notifyRuntimeHookEvent as Q, type RuntimeHooks as R, type SandboxClient as S, startRuntimeRun as T, type Driver as U, type Validator as V, type LoopWinner as W, type LoopLineageOptions as X, type LoopResult as Y, type MountRecorder as Z, type LoopDecisionPayload as _, type RuntimeStreamEvent as a, type LoopIterationDispatchPayload as a0, type LoopIterationEndedPayload as a1, type LoopIterationStartedPayload as a2, type LoopPlanDescription as a3, type LoopPlanPayload as a4, type LoopStartedPayload as a5, type LoopTeardownFailedPayload as a6, type MountManifestEntry as a7, type RunProvenance as a8, type SelectionReceipt as a9, type ValidationCtx as aa, type OutputAdapter as b, type LoopTraceEvent as c, type LoopSandboxPlacement as d, type LoopTraceEmitter as e, type AgentBackendInput as f, type AgentExecutionBackend as g, type OpenAIChatToolChoice as h, type AgentBackendContext as i, type RunAgentTaskOptions as j, type AgentTaskRunResult as k, type RunAgentTaskStreamOptions as l, type AgentRuntimeEvent as m, type AgentTaskStatus as n, type RuntimeSessionStore as o, type RuntimeSession as p, type AgentAdapter as q, type AgentKnowledgeProvider as r, type AgentRuntimeEventSink as s, type AgentTaskContext as t, type AgentTaskSpec as u, type RuntimeDecisionEvidenceRef as v, type RuntimeDecisionKind as w, type RuntimeDecisionPoint as x, type RuntimeHookContext as y, type RuntimeHookErrorContext as z };

package/dist/{worktree-DaxOvw-C.d.ts → worktree-CtuEQ7bZ.d.ts}

@@ -1,98 +1,7 @@
-import { ChildProcess } from 'node:child_process';
 import { DefaultVerdict } from '@tangle-network/agent-eval';
 import { AgentProfile } from '@tangle-network/agent-interface';
 import { BackendType } from '@tangle-network/sandbox';
-import { L as LoopTokenUsage, b as RuntimeHooks } from './types-JufmXF2a.js';
-
-/**
- * @experimental
- *
- * Subprocess wrappers for the local coding-harness CLIs installed in the
- * sandbox image (claude-code, codex, opencode). Used by the in-process
- * delegation executor (`createInProcessExecutor`) so a `delegate_code` call
- * spawns a real harness on a real git worktree instead of provisioning a
- * sibling sandbox.
- *
- * All harness invocations:
- *   - run with `cwd` set to the worktree
- *   - inherit env from the parent (the MCP server inside the sandbox has
- *     the harness's auth already)
- *   - capture stdout/stderr
- *   - support cancellation via AbortSignal
- *   - enforce a wall-clock timeout
- */
-
-/** Local coding harness available inside the sandbox. */
-type LocalHarness = 'claude' | 'codex' | 'opencode';
-/** @experimental */
-interface RunLocalHarnessOptions {
-    harness: LocalHarness;
-    /** Working directory for the subprocess (typically a worktree path). */
-    cwd: string;
-    /** Prompt forwarded as the harness CLI's task argument. */
-    taskPrompt: string;
-    /**
-     * Pre-built command + args (e.g. from `harnessInvocation` so the full authored
-     * `AgentProfile` — systemPrompt + model — reaches the harness). When set it OVERRIDES the
-     * default prompt-only `buildArgs(taskPrompt)` path; `command` defaults to the harness's
-     * default binary when only `args` is supplied. When absent the legacy prompt-only shape
-     * is used unchanged.
-     */
-    invocation?: {
-        command?: string;
-        args: ReadonlyArray<string>;
-    };
-    /** Wall-clock kill deadline (ms). Default 5 min. Subprocess SIGTERMed on expiry. */
-    timeoutMs?: number;
-    /** Caller cancellation. SIGTERM is sent on abort. */
-    signal?: AbortSignal;
-    /** Override env (defaults to inheriting from the parent). */
-    env?: NodeJS.ProcessEnv;
-    /**
-     * Test seam — inject a custom spawner so unit tests can mock the
-     * subprocess without touching the OS. Defaults to node's `child_process.spawn`.
-     */
-    spawn?: (command: string, args: ReadonlyArray<string>, opts: {
-        cwd: string;
-        env: NodeJS.ProcessEnv;
-        stdio: 'pipe';
-    }) => ChildProcess;
-}
-/** @experimental */
-interface LocalHarnessResult {
-    /** OS exit code. `null` when killed before exit. */
-    exitCode: number | null;
-    /** Concatenated stdout. */
-    stdout: string;
-    /** Concatenated stderr. */
-    stderr: string;
-    /** Set when the process exited via signal (timeout / abort). */
-    killedBySignal: NodeJS.Signals | null;
-    /** Wall-clock duration ms (spawn → exit). */
-    durationMs: number;
-    /** Set when timeoutMs elapsed before exit. */
-    timedOut: boolean;
-}
-/**
- * Spawn a local coding harness CLI as a subprocess + collect its output.
- *
- * NOT responsible for parsing the harness's output or extracting a diff —
- * the in-process executor's `streamPrompt` orchestrates `git diff` against
- * the worktree after this resolves. This function is intentionally narrow:
- * spawn, wait, capture, return.
- *
- * Fails loud — throws when:
- *   - `cwd` doesn't exist (subprocess emits ENOENT; surfaced as Error)
- *   - the harness binary is not on PATH (ENOENT)
- *
- * Does NOT throw when:
- *   - the subprocess exits non-zero (`result.exitCode` carries the code)
- *   - the subprocess is aborted / timed out (`result.killedBySignal` /
- *     `result.timedOut` carries the reason)
- *
- * @experimental
- */
-declare function runLocalHarness(options: RunLocalHarnessOptions): Promise<LocalHarnessResult>;
+import { L as LoopTokenUsage, R as RuntimeHooks } from './types-YimN9PQP.js';
 
 /**
  * @experimental
@@ -699,4 +608,4 @@ declare function captureWorktreeDiff(options: DiffOptions): Promise<DiffResult>;
 /** @experimental */
 declare function removeWorktree(options: RemoveWorktreeOptions): Promise<void>;
 
-export { type AgentSpec as A, type Budget as B, type CreateWorktreeOptions as C, type DiffOptions as D, type ExecutorRegistry as E, type GitRunner as G, type LocalHarness as L, type NodeId as N, type RemoveWorktreeOptions as R, type SpawnJournal as S, type TreeView as T, type UsageEvent as U, type WorktreeHandle as W, type DiffResult as a, type LocalHarnessResult as b, type RunLocalHarnessOptions as c, captureWorktreeDiff as d, createWorktree as e, removeWorktree as f, type Agent as g, type ResultBlobStore as h, type RootHandle as i, type SupervisedResult as j, type Settled as k, type Spend as l, type Scope as m, type Executor as n, type DeliverableSpec as o, type ExecutorFactory as p, type SpawnEvent as q, runLocalHarness as r, type Supervisor as s, type ExecutorContext as t, type ExecutorResult as u, type SupervisorOpts as v, type WidenGate as w, gateOnDeliverable as x };
+export { type AgentSpec as A, type Budget as B, type CreateWorktreeOptions as C, type DiffOptions as D, type ExecutorRegistry as E, type GitRunner as G, type NodeId as N, type RemoveWorktreeOptions as R, type SpawnJournal as S, type TreeView as T, type UsageEvent as U, type WorktreeHandle as W, type DiffResult as a, createWorktree as b, captureWorktreeDiff as c, type Agent as d, type ResultBlobStore as e, type RootHandle as f, type SupervisedResult as g, type Settled as h, type Spend as i, type Scope as j, type Executor as k, type DeliverableSpec as l, type ExecutorFactory as m, type SpawnEvent as n, type Supervisor as o, type ExecutorContext as p, type ExecutorResult as q, removeWorktree as r, type SupervisorOpts as s, type WidenGate as t, gateOnDeliverable as u };

package/dist/{worktree-fanout-DIffZohV.d.ts → worktree-fanout-Cdez8GR7.d.ts}

@@ -1,8 +1,9 @@
 import { AgentProfile } from '@tangle-network/agent-interface';
 import { AnalystFinding, DefaultVerdict } from '@tangle-network/agent-eval';
-import { A as AgentSpec, E as ExecutorRegistry, B as Budget, g as Agent, S as SpawnJournal, h as ResultBlobStore, i as RootHandle, j as SupervisedResult, N as NodeId, k as Settled, l as Spend, m as Scope, L as LocalHarness, G as GitRunner, r as runLocalHarness, n as Executor, o as DeliverableSpec } from './worktree-DaxOvw-C.js';
-import { b as RuntimeHooks, I as Iteration } from './types-JufmXF2a.js';
+import { A as AgentSpec, E as ExecutorRegistry, B as Budget, d as Agent, S as SpawnJournal, e as ResultBlobStore, f as RootHandle, g as SupervisedResult, N as NodeId, h as Settled, i as Spend, j as Scope, G as GitRunner, k as Executor, l as DeliverableSpec } from './worktree-CtuEQ7bZ.js';
+import { R as RuntimeHooks, I as Iteration } from './types-YimN9PQP.js';
 import { BackendType } from '@tangle-network/sandbox';
+import { L as LocalHarness, r as runLocalHarness } from './local-harness-BE_h8szs.js';
 
 /**
  * @experimental

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-runtime",
-  "version": "0.73.0",
+  "version": "0.74.0",
   "description": "Shared task-lifecycle skeleton for agents: a recursive loop kernel for chat turns, one-shot tasks, and multi-attempt loops, with trace capture and eval-gated self-improvement. Domain behavior lives in adapters; scoring and ship-gates in @tangle-network/agent-eval.",
   "homepage": "https://github.com/tangle-network/agent-runtime#readme",
   "repository": {