@tangle-network/agent-runtime 0.104.0 → 0.106.0

package/dist/local-harness-Dh8PJ0ot.d.ts

@@ -0,0 +1,455 @@
+import { d as AgentTaskStatus, o as AgentRuntimeEvent, x as RuntimeStreamEvent } from "./types-C9j4qg6l.js";
+import { ControlEvalResult, KnowledgeReadinessReport, KnowledgeRequirement } from "@tangle-network/agent-eval";
+import { AgentProfile as AgentProfile$1 } from "@tangle-network/agent-interface";
+import { ChildProcess } from "node:child_process";
+//#region src/sanitize.d.ts
+/** @stable */
+interface RuntimeTelemetryOptions {
+  /**
+   * Include raw task inputs. Off by default because task inputs often contain
+   * customer facts, credentials, source text, or internal IDs.
+   */
+  includeInputs?: boolean;
+  /** Include requirement descriptions. Secret requirements are always redacted. */
+  includeRequirementDescriptions?: boolean;
+  /** Include evidence IDs. Off by default; counts are safer for shared reports. */
+  includeEvidenceIds?: boolean;
+  /** Include user answers from question preflight. Off by default. */
+  includeUserAnswers?: boolean;
+  /** Include action payloads and action results for control steps. Off by default. */
+  includeControlPayloads?: boolean;
+  /** Include task metadata. Off by default because metadata may carry IDs or policy internals. */
+  includeMetadata?: boolean;
+  /** Include eval detail/evidence strings. Off by default because validators may echo private input. */
+  includeEvalDetails?: boolean;
+}
+/** @stable */
+interface SanitizedKnowledgeRequirement {
+  id: string;
+  description?: string;
+  requiredFor: string[];
+  category: KnowledgeRequirement['category'];
+  acquisitionMode: KnowledgeRequirement['acquisitionMode'];
+  importance: KnowledgeRequirement['importance'];
+  freshness: KnowledgeRequirement['freshness'];
+  sensitivity: KnowledgeRequirement['sensitivity'];
+  confidenceNeeded: number;
+  currentConfidence: number;
+  evidenceCount: number;
+  evidenceIds?: string[];
+  fallbackPolicy: KnowledgeRequirement['fallbackPolicy'];
+}
+/** @stable */
+interface SanitizedKnowledgeReadinessReport {
+  taskId: string;
+  readinessScore: number;
+  recommendedAction: KnowledgeReadinessReport['recommendedAction'];
+  severity: KnowledgeReadinessReport['severity'];
+  reason: string;
+  blockingMissingRequirements: SanitizedKnowledgeRequirement[];
+  nonBlockingGaps: SanitizedKnowledgeRequirement[];
+  evidenceCount: number;
+  evidenceIds?: string[];
+  missingRequirementIds: string[];
+}
+/** Strip PII and large blobs from a `KnowledgeReadinessReport` for safe telemetry emission. @stable */
+declare function sanitizeKnowledgeReadinessReport(report: KnowledgeReadinessReport, options?: RuntimeTelemetryOptions): SanitizedKnowledgeReadinessReport;
+/** Reduce an `AgentRuntimeEvent` to a PII-safe, serializable plain object for telemetry. @stable */
+declare function sanitizeAgentRuntimeEvent<TState, TAction, TActionResult, TEval extends ControlEvalResult>(event: AgentRuntimeEvent<TState, TAction, TActionResult, TEval>, options?: RuntimeTelemetryOptions): Record<string, unknown>;
+/** Reduce a `RuntimeStreamEvent` to a PII-safe, serializable plain object for telemetry. @stable */
+declare function sanitizeRuntimeStreamEvent(event: RuntimeStreamEvent, options?: RuntimeTelemetryOptions): Record<string, unknown>;
+/** @stable */
+interface RuntimeEventCollector<TState = unknown, TAction = unknown, TActionResult = unknown, TEval extends ControlEvalResult = ControlEvalResult> {
+  onEvent: (event: AgentRuntimeEvent<TState, TAction, TActionResult, TEval>) => void;
+  events: Array<Record<string, unknown>>;
+}
+/** @stable */
+type RuntimeStreamEventSink = (event: RuntimeStreamEvent) => void;
+/** @stable */
+interface RuntimeStreamEventSummary {
+  /** Total count of sanitized events collected. */
+  eventCount: number;
+  /** Count of events per `type`. Useful for log-line summaries. */
+  eventCountsByType: Record<string, number>;
+  /** First session id observed in a `session_created` / `session_resumed` event, if any. */
+  firstSessionId?: string;
+  /** Last `final` event's status, if a final event was observed. */
+  finalStatus?: AgentTaskStatus;
+  /** Last `final` event's reason, if a final event was observed. */
+  finalReason?: string;
+  /** Concatenated `text_delta.text` across the stream, even when payloads are redacted. */
+  finalText: string;
+}
+/** @stable */
+interface RuntimeStreamEventCollector {
+  onEvent: RuntimeStreamEventSink;
+  events: Array<Record<string, unknown>>;
+  /** Snapshot of a small streaming-flavored summary derived from collected events. */
+  summary(): RuntimeStreamEventSummary;
+}
+/** Build an in-memory collector that sanitizes and accumulates `AgentRuntimeEvent`s for inspection. @stable */
+declare function createRuntimeEventCollector<TState = unknown, TAction = unknown, TActionResult = unknown, TEval extends ControlEvalResult = ControlEvalResult>(options?: RuntimeTelemetryOptions): RuntimeEventCollector<TState, TAction, TActionResult, TEval>;
+/**
+ *
+ * Streaming-event counterpart of `createRuntimeEventCollector`. Pass each
+ * event yielded by `runAgentTaskStream` through `onEvent` and read the
+ * sanitized copies off `events`; the same `RuntimeTelemetryOptions` redaction
+ * flags apply. Kept distinct from `createRuntimeEventCollector` because the
+ * stream and non-stream event shapes overlap on `type` literals — dispatching
+ * on `type` alone would misroute events.
+ *
+ * @stable
+ */
+declare function createRuntimeStreamEventCollector(options?: RuntimeTelemetryOptions): RuntimeStreamEventCollector;
+//#endregion
+//#region src/runtime/tool-loop.d.ts
+/** Provider-neutral conversation record accepted by a tool-loop brain. */
+type ToolLoopMessageRecord = Record<string, unknown>;
+/** One inference turn over the running conversation + the tool specs → the model's text, any
+ *  tool calls, and token usage. The seam every brain satisfies. */
+type ToolLoopChat = (messages: ReadonlyArray<ToolLoopMessageRecord>, tools: ReadonlyArray<ToolSpec>) => Promise<{
+  content?: string | null;
+  toolCalls: RouterToolCall[];
+  usage?: {
+    input: number;
+    output: number;
+  };
+  /** The turn's inference cost (usd) when the provider priced it — for callers that meter usd
+   *  into a conserved pool (the supervisor brain). `runBrainLoop` itself ignores it. */
+  costUsd?: number;
+}>;
+/** Self-compaction — bound the loop's OWN context window the way a fresh-respawn (dumb-Ralph) loop
+ *  does, but in place. A stateless chat API re-sends the WHOLE running conversation every turn, so an
+ *  agent that accumulates dozens of turns of tool results re-bills its entire transcript on every
+ *  inference — the context-overflow-one-level-up that the conserved budget pool cannot fix. With
+ *  compaction set, once the conversation exceeds `thresholdTokens` the accumulated middle (every prior
+ *  assistant turn + tool result) is distilled into ONE compact progress note and the conversation is
+ *  reset to `[...head, digest]`: the preserved head (system + the original task) survives, the stale
+ *  turn-by-turn history does not. The model keeps deciding; it stops re-billing the whole transcript.
+ *  Fires at a CLEAN turn boundary (after a turn's tool results are folded in, before the next
+ *  inference) so it never orphans an assistant `tool_calls` from its `tool` replies. */
+interface ToolLoopCompaction {
+  /** Compact once the estimated token count of the conversation exceeds this. */
+  readonly thresholdTokens: number;
+  /** Distill the conversation into a compact progress note that REPLACES the middle. Receives the
+   *  full conversation (so it can summarize everything done so far); returns the digest string. */
+  readonly distill: (messages: ReadonlyArray<ToolLoopMessageRecord>) => Promise<string> | string;
+  /** Leading messages preserved verbatim (system + the original task). Default 2. */
+  readonly preserveHead?: number;
+  /** Token estimator over the conversation. Default ≈ chars/4 (incl. tool-call arguments). */
+  readonly estimateTokens?: (messages: ReadonlyArray<ToolLoopMessageRecord>) => number;
+  /** Notified each time a compaction fires — for observability/metering. */
+  readonly onCompact?: (info: {
+    turn: number;
+    beforeTokens: number;
+    afterTokens: number;
+  }) => void;
+}
+/** Public supervisor-facing compaction config: same knobs as the primitive, but `distill` is optional
+ *  because the supervisor has a default digest that combines a brain note with live worker state. */
+type ToolLoopCompactionOptions = Omit<ToolLoopCompaction, 'distill'> & {
+  readonly distill?: ToolLoopCompaction['distill'];
+};
+//#endregion
+//#region src/runtime/router-client.d.ts
+interface RouterConfig {
+  routerBaseUrl: string;
+  routerKey: string;
+  model: string;
+  /**
+   * Optional completion transport. When set, `routerChatWithUsage` / `routerChatWithTools` call it
+   * with the OpenAI-shape request body and use the parsed `/chat/completions` JSON it returns,
+   * INSTEAD of `fetch(routerBaseUrl + '/chat/completions')`. When absent the fetch path runs
+   * unchanged — the live router stays the default. The injection seam an offline benchmark uses to
+   * drive the worker with no network: a deterministic in-process responder satisfies it, no server.
+   */
+  complete?: (body: Record<string, unknown>) => Promise<unknown>;
+}
+interface RouterChatResult {
+  /** The final answer, with any inline `<think>...</think>` block stripped into `reasoning`. */
+  content: string;
+  /**
+   * Thinking-model reasoning, when the provider surfaced it — either as a separate
+   * `reasoning`/`reasoning_content` message field (OpenRouter style) or inlined into
+   * `content` as a `<think>` block (Groq style). Undefined for non-thinking models.
+   * Downstream parsers that match single-token answers must read `content`, which is
+   * clean either way; before this split, Groq-style inlining made the same model look
+   * broken on one provider and fine on another.
+   */
+  reasoning?: string;
+  /** REAL usage, or undefined when the provider reported none. */
+  usage?: {
+    input: number;
+    output: number;
+  };
+  /** Derived from usage via `estimateCost` when the model is priced; else undefined. */
+  costUsd?: number;
+}
+/** One OpenAI-compatible chat completion through the Tangle router, returning text + REAL token usage (`undefined` when the provider omits it — never a fabricated 0). */
+declare function routerChatWithUsage(cfg: RouterConfig, messages: Array<{
+  role: string;
+  content: string;
+}>, opts?: {
+  temperature?: number;
+  signal?: AbortSignal;
+  maxTokens?: number;
+  /**
+   * Reasoning control for thinking models, forwarded as `reasoning_effort`.
+   * 'none' is the load-bearing value: binary/single-token decisions (routing,
+   * gating) on a thinking model otherwise burn the whole token budget inside
+   * the think block — on slow backends (CPU-local) that turns into a client
+   * timeout, not just waste. Providers that ignore the field are handled by
+   * the reasoning/content split in `parseChatResult`.
+   */
+  reasoningEffort?: 'none' | 'low' | 'medium' | 'high';
+}): Promise<RouterChatResult>;
+/** A tool-call the model emitted (provider-neutral; mirrors the runtime's ToolCallRequest). */
+interface RouterToolCall {
+  id: string;
+  name: string;
+  /** Raw JSON arguments string as emitted by the model. */
+  arguments: string;
+}
+interface RouterChatToolsResult {
+  content: string | null;
+  toolCalls: RouterToolCall[];
+  usage?: {
+    input: number;
+    output: number;
+  };
+  costUsd?: number;
+}
+/**
+ * A router completion WITH tool-calling — the operator driver's LLM seam. Passes OpenAI-shape
+ * `messages` (system/user/assistant-with-tool_calls/tool roles) + function `tools`, and returns the
+ * assistant text plus the tool calls the model wants run. Same fail-loud + real-usage discipline as
+ * `routerChatWithUsage`. `tool_choice: 'auto'` lets the model decide; the driver loops on the result.
+ */
+declare function routerChatWithTools(cfg: RouterConfig, messages: ReadonlyArray<Record<string, unknown>>, tools: ReadonlyArray<{
+  type: 'function';
+  function: {
+    name: string;
+    description?: string;
+    parameters: unknown;
+  };
+}>, opts?: {
+  temperature?: number;
+  signal?: AbortSignal;
+  toolChoice?: 'auto' | 'required' | 'none';
+  maxTokens?: number;
+}): Promise<RouterChatToolsResult>;
+interface ToolSpec {
+  type: 'function';
+  function: {
+    name: string;
+    description?: string;
+    parameters: unknown;
+  };
+}
+interface RouterToolLoopResult {
+  /** The model's final assistant text (the turn where it stopped calling tools, or the budget turn). */
+  final: string;
+  /** Inference turns spent (≤ maxTurns) — the equal-budget unit vs random@k. */
+  turns: number;
+  toolCalls: number;
+  /** The behavior trace: each tool call + its result, in order. What a trace-analyst
+   *  steerer reads (behavior, never the verdict) to diagnose + redirect the next shot. */
+  toolTrace: Array<{
+    name: string;
+    args: string;
+    result: string;
+  }>;
+  usage: {
+    input: number;
+    output: number;
+  };
+  /** The full conversation after the loop (seed + every assistant/tool turn). Lets a caller
+   *  CARRY the messages into the next shot (depth continuation) and read the trajectory. */
+  messages: Array<Record<string, unknown>>;
+}
+/**
+ * The tool-using router backend: a real agentic loop OVER the Tangle router (which
+ * supports tool-calling), off-box — no sandbox. Each turn is one router completion
+ * with `tools`; if the model emits tool_calls, `execute` runs them on the host and
+ * their results are folded back as `tool` messages; the loop repeats until the
+ * model answers without a tool call or the turn budget is hit. One turn = one
+ * inference call, so `maxTurns` is the equal-compute unit against random@k.
+ *
+ * This is the depth substrate for agentic gates (the worker ACTS, observes the real
+ * result, and continues) that the chat-only `routerChatWithUsage` cannot express.
+ */
+declare function routerToolLoop(cfg: RouterConfig, system: string, user: string, tools: ReadonlyArray<ToolSpec>, execute: (name: string, args: Record<string, unknown>) => Promise<string>, opts?: {
+  maxTurns?: number;
+  temperature?: number;
+  signal?: AbortSignal;
+  maxTokens?: number;
+  /** Seed the loop with an existing conversation (depth continuation) instead of
+   *  `[system, user]`. When set, `system`/`user` are ignored. The array is copied. */
+  initialMessages?: ReadonlyArray<Record<string, unknown>>;
+}): Promise<RouterToolLoopResult>;
+/**
+ * The router as a supervisor BRAIN: the canonical `ToolLoopChat` seam backed by the router's
+ * tool-calling. The driver's spawn/observe/steer/await/stop turns become real router tool-calls.
+ * The turnkey production brain — tests script a mock `ToolLoopChat`; production passes
+ * `routerBrain(cfg)`. No message translation: the loop already speaks the router's OpenAI shape.
+ */
+declare function routerBrain(cfg: RouterConfig, opts?: {
+  temperature?: number;
+}): ToolLoopChat;
+//#endregion
+//#region src/mcp/local-harness.d.ts
+/** 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>;
+  };
+  /** Allow autonomous Claude edits without an interactive permission prompt.
+   *  Use only when `cwd` is an isolated candidate worktree. */
+  dangerouslySkipPermissions?: boolean;
+  /** Isolate Codex from ambient configuration/instructions and require JSONL token usage.
+   *  The invocation should come from `harnessInvocation(..., { codexReproducible: true })`. */
+  codexReproducible?: boolean;
+  /** Absolute host paths that reproducible Codex must not read. The normalized set is compiled
+   *  into the controlled permission profile and its digest is returned in execution evidence. */
+  codexReadDeniedPaths?: ReadonlyArray<string>;
+  /** Wall-clock kill deadline (ms). Default 5 min. Subprocess SIGTERMed on expiry. */
+  timeoutMs?: number;
+  /** Newest stdout/stderr bytes retained per stream. Default 64 MiB. */
+  maxOutputBytes?: 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';
+    detached: boolean;
+  }) => ChildProcess;
+  /** Test seam for locating the native Codex executable before it is staged in the worktree. */
+  resolveCodexExecutable?: (command: string, env: NodeJS.ProcessEnv) => Promise<string>;
+}
+/** Exact aggregate usage emitted by Codex's terminal `turn.completed` JSONL event. */
+interface CodexTokenUsage {
+  inputTokens: number;
+  cachedInputTokens: number;
+  outputTokens: number;
+  reasoningOutputTokens: number;
+}
+/** Isolation settings asserted before a reproducible Codex run is allowed to start. */
+interface CodexExecutionPolicy {
+  sessionPersistence: 'ephemeral';
+  userConfig: false;
+  rules: false;
+  projectInstructions: false;
+  skillInstructions: false;
+  appInstructions: false;
+  toolSuggestions: false;
+  multiAgentInstructions: false;
+  sandbox: 'workspace-write';
+  permissionProfile: 'agent_runtime_reproducible';
+  approvalPolicy: 'never';
+  shellNetwork: false;
+  webSearch: false;
+  serviceTier: 'default';
+  shellEnvironment: 'core-filtered';
+  loginShell: false;
+  credentialsReadable: false;
+  hostHomeReadable: false;
+  procEnvironment: 'private-sanitized';
+  sensitiveEnvironmentNamesVisible: false;
+  parentRepoRead: false;
+  gitMetadata: false;
+  temporaryDirectory: 'workspace-private';
+  stagedExecutable: 'static-elf-read-only';
+  callerReadDeniedPaths: 'enforced';
+  containerSockets: false;
+}
+/** Zero-model-call evidence for the exact Codex process about to run. */
+interface CodexExecutionEvidence {
+  cliVersion: string;
+  executableSha256: string;
+  /** SHA-256 of the exact composed prompt argument proved present in the rendered prompt. */
+  requestedPromptSha256: string;
+  effectivePromptSha256: string;
+  nonPromptArgsSha256: string;
+  controlledConfigSha256: string;
+  /** Sorted normalized paths compiled into the permission profile. */
+  readDeniedPaths: string[];
+  readDeniedPathsSha256: string;
+  readDeniedPathCount: number;
+  policy: CodexExecutionPolicy;
+}
+/** @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;
+  /**
+   * Set when the caller's AbortSignal fired before this result settled.
+   * Optional so injected runners and stored results from older releases remain valid.
+   */
+  aborted?: boolean;
+  /** Present for a reproducible Codex run; parsed from the real terminal JSONL event. */
+  usage?: CodexTokenUsage;
+  /** Present for reproducible Codex runs; generated and checked before model execution. */
+  evidence?: CodexExecutionEvidence;
+}
+/**
+ * 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)
+ *   - the caller signal was already aborted before process launch
+ *
+ * Does NOT throw when:
+ *   - the subprocess exits non-zero (`result.exitCode` carries the code)
+ *   - a non-reproducible subprocess is aborted / timed out (`result.aborted` /
+ *     `result.timedOut` carries the reason even when a TERM-aware child exits zero)
+ *
+ * Reproducible Codex additionally requires a terminal usage event. If cancellation
+ * prevents that event, this rejects with `CodexExecutionDiagnosticError` instead of
+ * returning an incomplete reproducibility receipt.
+ *
+ * @experimental
+ */
+declare function runLocalHarness(options: RunLocalHarnessOptions): Promise<LocalHarnessResult>;
+/** Parse and validate the one terminal usage event emitted by `codex exec --json`. */
+declare function parseCodexTokenUsage(stdout: string): CodexTokenUsage;
+//#endregion
+export { createRuntimeEventCollector as A, RuntimeEventCollector as C, RuntimeTelemetryOptions as D, RuntimeStreamEventSummary as E, sanitizeAgentRuntimeEvent as M, sanitizeKnowledgeReadinessReport as N, SanitizedKnowledgeReadinessReport as O, sanitizeRuntimeStreamEvent as P, ToolLoopMessageRecord as S, RuntimeStreamEventSink as T, routerChatWithUsage as _, LocalHarnessResult as a, ToolLoopCompaction as b, runLocalHarness as c, RouterConfig as d, RouterToolCall as f, routerChatWithTools as g, routerBrain as h, LocalHarness as i, createRuntimeStreamEventCollector as j, SanitizedKnowledgeRequirement as k, RouterChatResult as l, ToolSpec as m, CodexExecutionPolicy as n, RunLocalHarnessOptions as o, RouterToolLoopResult as p, CodexTokenUsage as r, parseCodexTokenUsage as s, CodexExecutionEvidence as t, RouterChatToolsResult as u, routerToolLoop as v, RuntimeStreamEventCollector as w, ToolLoopCompactionOptions as x, ToolLoopChat as y };
+//# sourceMappingURL=local-harness-Dh8PJ0ot.d.ts.map

package/dist/loop-runner-bin-BXsFEUcf.d.ts

@@ -0,0 +1,162 @@
+import { d as RunAnalystLoopOpts, f as RunAnalystLoopResult } from "./types-Cja5OTGh.js";
+import { R as Budget } from "./environment-provider-IUGU3epE.js";
+import { E as WorktreeFanoutOptions, G as WorktreePatchArtifact, T as AuthoredHarness, no as WinnerStrategy } from "./index-DruSKs3Z.js";
+import { n as FactCandidate, t as CreateKbGateOptions } from "./kb-gate-C8z2juK8.js";
+//#region src/loop-runner.d.ts
+/** All valid delegated-loop mode names — used for validation and CLI surfaces. @experimental */
+declare const DELEGATED_LOOP_MODES: readonly ["code", "review", "research", "audit", "self-improve"];
+/** @experimental */
+type DelegatedLoopMode = (typeof DELEGATED_LOOP_MODES)[number];
+/** Type guard — returns true when `value` is a valid `DelegatedLoopMode` string. @experimental */
+declare function isDelegatedLoopMode(value: unknown): value is DelegatedLoopMode;
+/** @experimental A pre-configured loop for one mode. Returns the mode's raw
+ *  output; the dispatcher wraps it in a {@link DelegatedLoopResult}. */
+type DelegatedLoopRunner<T = unknown> = (signal: AbortSignal) => Promise<T>;
+/** @experimental Mode → configured runner. Partial: only register the modes a
+ *  given product/routine actually uses. */
+type DelegatedLoopRegistry = Partial<Record<DelegatedLoopMode, DelegatedLoopRunner>>;
+/** @experimental Uniform result — never throws from a registered runner; a
+ *  thrown engine becomes `{ ok: false, error }` so a routine can record + move on. */
+interface DelegatedLoopResult<T = unknown> {
+  mode: DelegatedLoopMode;
+  ok: boolean;
+  output?: T;
+  error?: string;
+  durationMs: number;
+}
+/** @experimental */
+interface RunDelegatedLoopOptions {
+  signal?: AbortSignal;
+  /** Clock override for deterministic tests. */
+  now?: () => number;
+}
+/**
+ *
+ * Dispatch a configured loop by mode. Fails loud (throws `ConfigError`) when no
+ * runner is registered for the mode — a routine pointed at an unwired mode is a
+ * config bug, not a silent no-op. A runner that throws is captured as
+ * `{ ok: false }` so unattended runs record the failure rather than crash.
+ *
+ * @experimental
+ */
+declare function runDelegatedLoop<T = unknown>(mode: DelegatedLoopMode, registry: DelegatedLoopRegistry, options?: RunDelegatedLoopOptions): Promise<DelegatedLoopResult<T>>;
+/** @experimental Options for the local-repo `code` runner over the GENERIC recursive path. */
+interface WorktreeLoopRunnerOptions {
+  /** Absolute path to the local git checkout each worktree is cut from. */
+  repoRoot: string;
+  /** The instruction handed to every authored harness (composed under each profile's systemPrompt). */
+  taskPrompt: string;
+  /** The supervisor-authored harness profiles — one fanout item (one worktree-CLI leaf) each. */
+  harnesses: ReadonlyArray<AuthoredHarness>;
+  /** Conserved budget pool bounding the fanout (equal-k holds by construction). */
+  budget: Budget;
+  /** Shell command run in each worktree to derive the tests-PASS signal. */
+  testCmd?: string;
+  /** Shell command run in each worktree to derive the typecheck-PASS signal. */
+  typecheckCmd?: string;
+  /** Which verification signals the deliverable REQUIRES present-and-passing (default none). */
+  require?: ReadonlyArray<'tests' | 'typecheck'>;
+  /** Diff-size cap (lines). */
+  maxDiffLines?: number;
+  /** Literal path prefixes the patch must not touch (the secret-floor is always on regardless). */
+  forbiddenPaths?: string[];
+  /** Winner-selection strategy among gated candidates. Default `highest-score`. */
+  winnerStrategy?: WinnerStrategy;
+  /** Test seams forwarded to the worktree-CLI leaves so the runner drives offline. */
+  runGit?: WorktreeFanoutOptions['runGit'];
+  runHarness?: WorktreeFanoutOptions['runHarness'];
+  runCommand?: WorktreeFanoutOptions['runCommand'];
+}
+/**
+ *
+ * `code` mode on the GENERIC recursive path: author one `AgentProfile` per harness, run them as a
+ * `worktreeFanout` (N `createWorktreeCliExecutor` leaves, each `gateOnDeliverable`) through
+ * `runPersonified` on the keystone Supervisor. The sandbox-session counterpart that drives the in-box
+ * harness over a `SandboxClient` is `detachedSessionDelegate` (`./mcp/delegates`); here there is no
+ * `runAgentRounds` driver, no role-coupled delegate — the harness list is the fanout, the gate is
+ * `patchDelivered`,
+ * the winner is the shared valid-only selector (NOT `defaultSelectWinner`, whose non-valid fallback
+ * would surface an ungated patch). Equal-k holds by the conserved budget pool. Returns the winning
+ * patch artifact, or throws when no candidate is delivered (fail loud, never a vacuous done).
+ *
+ * @experimental
+ */
+declare function worktreeLoopRunner(options: WorktreeLoopRunnerOptions): DelegatedLoopRunner<WorktreePatchArtifact>;
+/** @experimental A fact rejected at the KB gate — surfaced, never dropped. */
+interface VetoedFact {
+  candidate: FactCandidate;
+  vetoedBy?: string;
+  reason?: string;
+}
+/** @experimental */
+interface ResearchLoopResult {
+  /** Facts that passed the fail-closed gate — safe to write to the KB. */
+  accepted: FactCandidate[];
+  /** Facts the gate vetoed in the final round — escalate, do not silently drop. */
+  vetoed: VetoedFact[];
+  /** Research rounds actually run. */
+  rounds: number;
+}
+/** @experimental Options for the default `research` runner. */
+interface ResearchLoopRunnerOptions {
+  /**
+   * The research engine (the consumer's web/doc searcher + extractor). Called
+   * each round with the prior round's vetoes so it can re-research the gaps.
+   * Returns fact candidates carrying their grounding (`verbatimPassage` +
+   * `sourceText`).
+   */
+  research: (round: number, vetoed: VetoedFact[]) => Promise<FactCandidate[]>;
+  /** Gate config (extra judges, self-artifact kinds, …). The floor is always on. */
+  gate?: CreateKbGateOptions;
+  /** Max research rounds (correct-on-veto remediation). Default 1. */
+  maxRounds?: number;
+}
+/**
+ * `research` mode — research-in-a-loop with valid-only KB growth.
+ *
+ * Each round: research → gate every candidate (fail-closed; passage MUST be in
+ * the source) → accept the clean ones → re-research the vetoed ones next round,
+ * up to `maxRounds`. Vetoed facts in the final round are RETURNED (escalate,
+ * never silently dropped) so the caller audits vs retries.
+ *
+ * @experimental
+ */
+declare function researchLoopRunner(o: ResearchLoopRunnerOptions): DelegatedLoopRunner<ResearchLoopResult>;
+/**
+ * `audit` mode — analyst loop over captured trace/run data.
+ *
+ * @experimental
+ */
+declare function auditLoopRunner<TProposal = unknown, TEdit = unknown>(options: RunAnalystLoopOpts): DelegatedLoopRunner<RunAnalystLoopResult<TProposal, TEdit>>;
+//#endregion
+//#region src/loop-runner-bin.d.ts
+/** @experimental Parsed CLI invocation. */
+interface LoopRunnerCliArgs {
+  mode: string;
+  /** Loads the registry — the bin wires this from `--config`; tests inject a stub. */
+  loadRegistry: () => Promise<DelegatedLoopRegistry> | DelegatedLoopRegistry;
+  now?: () => number;
+}
+/** @experimental */
+interface LoopRunnerCliResult {
+  exitCode: number;
+  result?: DelegatedLoopResult;
+  error?: string;
+}
+/**
+ *
+ * Pure CLI core (no process / argv / IO) so it's unit-testable: validate the
+ * mode, load the registry, dispatch, map to an exit code (0 ok / 1 failed /
+ * 2 usage). Exported for embedding in custom runners + tests.
+ *
+ * @experimental
+ */
+declare function runLoopRunnerCli(args: LoopRunnerCliArgs): Promise<LoopRunnerCliResult>;
+/** Parse `--mode X --config Y` from an argv tail (`process.argv.slice(2)`). */
+declare function parseLoopRunnerArgv(argv: string[]): {
+  mode?: string;
+  config?: string;
+};
+//#endregion
+export { researchLoopRunner as _, DELEGATED_LOOP_MODES as a, DelegatedLoopResult as c, ResearchLoopRunnerOptions as d, RunDelegatedLoopOptions as f, isDelegatedLoopMode as g, auditLoopRunner as h, runLoopRunnerCli as i, DelegatedLoopRunner as l, WorktreeLoopRunnerOptions as m, LoopRunnerCliResult as n, DelegatedLoopMode as o, VetoedFact as p, parseLoopRunnerArgv as r, DelegatedLoopRegistry as s, LoopRunnerCliArgs as t, ResearchLoopResult as u, runDelegatedLoop as v, worktreeLoopRunner as y };
+//# sourceMappingURL=loop-runner-bin-BXsFEUcf.d.ts.map