@odla-ai/harness 0.1.2 → 0.3.0

package/dist/node.d.ts

@@ -1,7 +1,8 @@
-import { r as HarnessTaskSpec, g as HarnessAgentOutput, f as HarnessAgentInput, H as HarnessControlPlane, u as HarnessToolBroker, a as HarnessLease, d as HarnessInferenceRequest, e as HarnessInferenceResponse, i as CodeSessionEventData, w as HarnessToolRequest, v as HarnessToolName } from './types-D12vK3K9.js';
+import { r as HarnessTaskSpec, g as HarnessAgentOutput, f as HarnessAgentInput, H as HarnessControlPlane, u as HarnessToolBroker, a as HarnessLease, d as HarnessInferenceRequest, e as HarnessInferenceResponse, i as CodeSessionEventData, v as HarnessToolName, w as HarnessToolRequest } from './types-0_H9TKkO.js';
 import { CodePortableCheckpoint, CodeSourceFile, CodeVerificationReceipt, CodeCheckpointState } from '@odla-ai/camel/code';
+import { Skill, Inference, AgentRunBudget, AgentRun, CompactionPolicy } from '@odla-ai/ai';
 import { PolicyOutcome } from '@odla-ai/camel/policy';
-import '@odla-ai/ai';
+import { Graph, PartitionVerdict } from '@odla-ai/graph';
 
 /** Supported command-line container engines for isolated harness attempts. */
 type ContainerEngine = "container" | "podman" | "docker";
@@ -181,7 +182,6 @@ interface CodeRuntimeCapabilities {
     source?: CodeLocalSourceDescriptor;
     images?: {
         ready: boolean;
-        pi: string;
         recipes: Array<{
             id: string;
             image: string;
@@ -210,7 +210,7 @@ interface CodeRuntimeSnapshot {
     commands: CodeRuntimeCommand[];
 }
 /** Commands accepted by the outbound Code runtime. */
-type CodeRuntimeCommandKind = "start" | "prompt" | "checkpoint_stop" | "resume";
+type CodeRuntimeCommandKind = "start" | "prompt" | "checkpoint_stop" | "resume" | "pursue";
 /** One sequenced command fenced to an exact host-binding generation. */
 interface CodeRuntimeCommand {
     commandId: string;
@@ -313,6 +313,79 @@ interface FrozenCodeLocalSource {
     sourceDir: string;
 }
 
+/** v1's system prompt, verbatim. Do not edit without re-baselining the bench. */
+declare const V1_SYSTEM_PROMPT = "You are Pi, the coding agent inside an odla Code harness.\nUse only the odla_read, odla_apply_git_diff, and odla_run_recipe tools.\nFor mutations, call odla_apply_git_diff with raw git diff text. It must start\nwith \"diff --git a/<path> b/<path>\", include matching \"---\" and \"+++\" file\nheaders and numbered \"@@\" hunks, and never use \"*** Begin Patch\" wrappers.\nThe workspace, model, and tool effects are controlled by the host broker.\nNever claim a build or test passed unless odla_run_recipe returned that result.";
+/** The v2 prompt. v1's said "Use only the odla_read, odla_apply_git_diff, and
+ *  odla_run_recipe tools", so leaving it in place would have told the model not
+ *  to touch the tools this milestone exists to test. */
+declare const V2_SYSTEM_PROMPT = "You are the coding agent inside an odla Code harness.\nStart by orienting: odla_list shows the files in the workspace and odla_search\nfinds a literal string across them. Prefer those over guessing a path.\nThen odla_read a bounded range, and odla_apply_git_diff to mutate.\nFor mutations, call odla_apply_git_diff with raw git diff text. It must start\nwith \"diff --git a/<path> b/<path>\", include matching \"---\" and \"+++\" file\nheaders and numbered \"@@\" hunks, and never use \"*** Begin Patch\" wrappers.\nThe workspace, model, and tool effects are controlled by the host broker.\nNever claim a build or test passed unless odla_run_recipe returned that result.";
+/** Which tool surface the agent sees. `v1` reproduces the Pi container's exact
+ *  three tools so the recorded baseline stays comparable. */
+type CodeSurface = "v1" | "v2" | "v3";
+/** v3 leads with orientation, because that is where the tokens went. */
+declare const V3_SYSTEM_PROMPT = "You are the coding agent inside an odla Code harness.\n\nOrient before you look. odla_overview gives the directory shape of the whole\nrepository in a few hundred lines; odla_where_is finds where a symbol is defined,\ndisambiguated by package; odla_who_imports finds what depends on a file; and\nodla_who_touches finds the code that reads and writes a table or database\nnamespace, which is how a bug report about wrong data becomes a file path.\nPrefer these over listing the tree \u2014 a full listing of a real repository is tens\nof thousands of tokens and you will carry it for the rest of the session.\n\nThen odla_search for a literal string, odla_read for a bounded range, and\nodla_apply_git_diff to change something. A patch must start with\n\"diff --git a/<path> b/<path>\", include matching \"---\" and \"+++\" headers and\nnumbered \"@@\" hunks with at least one line of surrounding context, and must never\nuse \"*** Begin Patch\" wrappers.\n\nThe workspace, model, and tool effects are controlled by the host broker.\nNever claim a build or test passed unless odla_run_recipe returned that result.";
+/**
+ * The system prompt for each tool surface, keyed by version.
+ *
+ * Kept addressable so a benchmark can hold everything else fixed and vary only
+ * the prompt — v1 is byte-identical to what the retired Pi agent shipped, which
+ * is what makes the comparison against v2 and v3 meaningful.
+ */
+declare const SYSTEM_PROMPT_FOR: Record<CodeSurface, string>;
+/** Which tool surface the skill describes, and the recipes it may run. */
+interface CodeSkillOpts {
+    broker: HarnessToolBroker;
+    lease: HarnessLease;
+    workspaceDir: string;
+    /** Defaults to v1 so an unqualified run reproduces the baseline. */
+    surface?: CodeSurface;
+    /** Records every brokered call so the report can attribute errors per tool. */
+    onToolCall?(call: {
+        tool: HarnessToolName;
+        ok: boolean;
+        durationMs: number;
+    }): void;
+}
+/**
+ * The three v1 tools, brokered. Each handler is a thin adapter: it forwards the
+ * model's arguments to the broker unchanged and maps the bounded
+ * `HarnessToolResponse` onto the agent loop's `ToolOutput`, so a policy denial
+ * or a failed patch reaches the model as a tool error rather than an exception.
+ */
+declare function codeSkill(opts: CodeSkillOpts): Skill;
+
+/** The workspace, tools, and budget for a single attempt inside the runtime. */
+interface CodeAgentAttemptOptions {
+    inference: Inference;
+    broker: HarnessToolBroker;
+    lease: HarnessLease;
+    workspaceDir: string;
+    prompt: string;
+    surface?: CodeSurface;
+    maxSteps?: number;
+    /** Run-wide ceiling enforced by runAgent against incremental usage. */
+    budget?: AgentRunBudget;
+    signal?: AbortSignal;
+    /** Emitted per brokered call so the engine can report tool activity. */
+    onToolCall?(call: {
+        tool: HarnessToolName;
+        ok: boolean;
+        durationMs: number;
+    }): void;
+}
+/** Whether one attempt completed, and the text it ended on. */
+interface CodeAgentAttemptResult {
+    status: "completed" | "failed";
+    /** The agent's closing text, surfaced to the owner as its final message. */
+    finalText: string;
+    /** Present only when the attempt failed. */
+    error?: string;
+    /** Why the loop stopped, for diagnostics. */
+    stoppedReason?: string;
+}
+/** Run one attempt with runAgent over the brokered surface. */
+declare function runCodeAgentAttempt(options: CodeAgentAttemptOptions): Promise<CodeAgentAttemptResult>;
+
 /** One control-owned regular file expected from a clean build recipe. */
 interface CodeExpectedArtifact {
     id: string;
@@ -380,13 +453,11 @@ interface CodeToolBrokerOptions {
 interface CodePiRuntimeEngineOptions {
     control: CodeRuntimeAgentControlPlane;
     engine: ContainerEngine;
-    image: string;
-    /** The Code CLI may build its bundled, content-addressed Pi adapter locally. */
-    imageAuthorization?: "digest" | "cli_embedded";
     recipes: readonly CodeBuildRecipe[];
     recipeAuthorization?: "registered_recipe" | "exact_approval";
     limits?: ContainerLimits;
-    runAttempt?: (options: ContainerRunOptions) => Promise<ContainerRunResult>;
+    /** Injectable agent attempt. Defaults to runAgent over the brokered surface. */
+    runAgentAttempt?: (options: CodeAgentAttemptOptions) => Promise<CodeAgentAttemptResult>;
     recipeExecutor?: CodeRecipeExecutor;
     /** Owner-visible and terminal-visible bounded runtime failures. */
     onDiagnostic?: (message: string) => void;
@@ -457,7 +528,7 @@ declare function prepareRuntimeCheckpoint(input: PrepareRuntimeCheckpointInput):
 /** Active isolated workspace state required to prepare and publish a Code checkpoint candidate. */
 interface RuntimeCheckpointSession {
     workspace: StagedWorkspace;
-    done: Promise<ContainerRunResult | null>;
+    done: Promise<CodeAgentAttemptResult | null>;
     abort: AbortController;
     baseCommitSha: string;
     trustedBaseDigest: `sha256:${string}`;
@@ -481,6 +552,18 @@ declare class CodeRuntimeCheckpointManager {
     acknowledged(command: CodeRuntimeCommand, result: CodeRuntimeCommandResult): Promise<boolean>;
 }
 
+interface CodeCommandMetadata {
+    role: "coding" | "review";
+    title: string;
+    prompt: string;
+    maxTokensPerInteraction: number;
+    planningInputDigest: `sha256:${string}` | null;
+    attestationDigest: string;
+    repository: string;
+    baseCommitSha: string;
+    sourceTreeDigest: `sha256:${string}`;
+}
+
 /** Disposable local source tree materialized from an exact, validated Code snapshot. */
 interface MaterializedCodeSource {
     sourceDir: string;
@@ -492,10 +575,656 @@ declare function materializeCodeRuntimeSource(snapshot: CodeRuntimeSourceSnapsho
  * checkout. They remain outside the candidate diff and the tool broker denies
  * every write beneath the reference root. */
 declare function attachCodeRuntimeReferences(workspace: StagedWorkspace, references: NonNullable<CodeRuntimeSourceSnapshot["references"]>): Promise<void>;
+/**
+ * Obtain the staged workspace one start/resume command should run in.
+ *
+ * Extracted from the engine because it is a different job: bringing a
+ * workspace into being from either a terminal's frozen checkout or the
+ * control plane's attested GitHub snapshot, with the checks that each source
+ * demands. The engine's remaining concern is what to RUN in it.
+ */
+declare function materializeCommandWorkspace(input: {
+    command: CodeRuntimeCommand;
+    metadata: CodeCommandMetadata;
+    resume: boolean;
+    control: Pick<CodeRuntimeAgentControlPlane, "source">;
+    localSource?: FrozenCodeLocalSource;
+}): Promise<{
+    workspace: StagedWorkspace;
+    sourceDigest: `sha256:${string}`;
+    localTrustedBaseDigest?: `sha256:${string}`;
+    requestedLocal: CodeLocalSourceDescriptor | null;
+}>;
 
 /** Create the trusted CaMeL boundary for all Pi filesystem and build effects. */
 declare function createCodeToolBroker(options: CodeToolBrokerOptions): HarnessToolBroker;
 
+/** One brokered tool call, recorded for per-tool error attribution. */
+interface CodeToolCallRecord {
+    tool: HarnessToolName;
+    ok: boolean;
+    durationMs: number;
+}
+/** One coding run: which tool surface, which model, and what it may spend. */
+interface RunCodeAgentOptions {
+    inference: Inference;
+    broker: HarnessToolBroker;
+    lease: HarnessLease;
+    workspaceDir: string;
+    /** The owner task. Becomes the single user turn that opens the run. */
+    prompt: string;
+    model: string;
+    /** Model turns before the loop stops. v1 had no equivalent bound. */
+    maxSteps?: number;
+    /** Run-wide token and tool-call ceilings, enforced by runAgent. */
+    budget?: AgentRunBudget;
+    /**
+     * Shorten the conversation when it gets expensive. Defaults to keeping the
+     * task and the three most recent tool exchanges once a turn bills more than
+     * 120k input tokens; pass `null` to keep the whole history.
+     *
+     * A default rather than opt-in because the failure it prevents is silent:
+     * without it a long run simply costs more each turn until the model's context
+     * ends the run, and nothing in the trace says that is what happened.
+     */
+    compaction?: CompactionPolicy | null;
+    /** Tool surface the agent sees. Defaults to v1, the recorded baseline. */
+    surface?: CodeSurface;
+    /** Overrides the surface's system prompt. Leave unset to keep runs comparable. */
+    system?: string;
+    maxTokens?: number;
+    signal?: AbortSignal;
+    deadline?: number;
+    /** Observe each brokered call as it completes, for live engine events. */
+    onToolCall?(call: CodeToolCallRecord): void;
+    /**
+     * Extra skills composed alongside the code tools — PM, chat, anything else
+     * the host can authorize.
+     *
+     * They arrive as an argument rather than being built here on purpose: those
+     * skills need a database credential scoped to a tenant, which the host has
+     * and the harness must not. It also keeps @odla-ai/pm and @odla-ai/chat out
+     * of this package's install graph for a capability not every consumer wants.
+     */
+    extraSkills?: Skill[];
+}
+/** A finished run — its final text, why it stopped, and what it cost. */
+interface CodeAgentRun {
+    run: AgentRun;
+    toolCalls: CodeToolCallRecord[];
+}
+/**
+ * Drive one Code attempt to completion and return the agent run plus the
+ * brokered tool calls it made.
+ *
+ * `budget` is enforced by runAgent against *incremental* usage per turn, which
+ * is the fix for v1's per-interaction accounting: v1 summed `inputTokens +
+ * outputTokens` from every response into one counter, so re-sent context was
+ * charged again on each turn and a 32k allowance died in two turns.
+ */
+declare function runCodeAgent(options: RunCodeAgentOptions): Promise<CodeAgentRun>;
+
+interface CodeInteractionBudgetState {
+    tokens: number;
+    noticeEmitted: boolean;
+}
+
+/** How a runtime attempt reaches a model: through the control plane, never direct. */
+interface CodeRuntimeInferenceOptions {
+    command: CodeRuntimeCommand;
+    metadata: CodeCommandMetadata;
+    state: CodeInteractionBudgetState;
+    control: CodeRuntimeAgentControlPlane;
+    event(value: CodeSessionEventData): Promise<void>;
+}
+/**
+ * Build the brokered `Inference` for one attempt.
+ *
+ * `catalog` is deliberately empty. The runtime does not know what the platform
+ * policy resolved the model to, and the trace's cost contract is that unknown
+ * pricing is absent rather than zero — a run that silently reported $0 would
+ * make the brokered route look free next to a priced one.
+ */
+declare function createCodeRuntimeInference(options: CodeRuntimeInferenceOptions): Inference;
+
+/** What kind of thing was learned. */
+type CodeMemoryKind = 
+/** An approach that failed, and what the gate said about it. */
+"hazard"
+/** Something true of this codebase that reading it does not reveal. */
+ | "invariant"
+/** What a goal actually achieved, judged by a verifier rather than claimed. */
+ | "outcome"
+/** Everything else worth carrying forward. */
+ | "note";
+/**
+ * What produced a memory.
+ *
+ * This field is what stops a shared store becoming a rumour mill. An agent that
+ * can write unfalsifiable claims into memory poisons every run that follows, so
+ * a finding carries the thing that produced it and a bare assertion is visibly
+ * a lesser class of claim.
+ */
+interface CodeMemoryEvidence {
+    kind: "gate" | "receipt" | "human";
+    /** A verification id, a receipt digest, or a person. */
+    ref: string;
+}
+/** One thing the agent learned about this codebase. */
+interface CodeMemory {
+    id: string;
+    /** A graph node id — `file:src/a.ts`, `table:orders`, `symbol:runAgent`. */
+    subject: string;
+    kind: CodeMemoryKind;
+    body: string;
+    evidence?: CodeMemoryEvidence;
+    /** Principal that recorded it. Attributed, never authenticated — see PM. */
+    authorId: string;
+    createdAt: number;
+    /** Set when a later memory contradicts this one. */
+    supersededBy?: string;
+}
+/** A memory before it has an id or a timestamp. */
+type NewCodeMemory = Omit<CodeMemory, "id" | "createdAt">;
+/**
+ * Where memories live.
+ *
+ * An interface rather than a database, because a Code host holds no tenant
+ * credential — the same reason inference is brokered. The control plane
+ * supplies the implementation; the agent only ever sees this.
+ */
+interface CodeMemoryStore {
+    /** Memories about any of these subjects, newest first. */
+    recall(subjects: readonly string[], limit: number): Promise<CodeMemory[]>;
+    remember(memory: NewCodeMemory): Promise<CodeMemory>;
+}
+/** Longest body worth storing. A memory is a lesson, not a transcript. */
+declare const MAX_MEMORY_BODY = 4000;
+/** Reject a memory that would be useless or unbounded before it is stored. */
+declare function validateMemory(memory: NewCodeMemory): void;
+/** How wide to cast when gathering what is known about some subjects. */
+interface RecallOptions {
+    /**
+     * Also recall memories about what the subjects reach.
+     *
+     * A hazard recorded against a module matters to everything that imports it,
+     * and the whole reason subjects are graph ids is that this is one traversal.
+     * Off by default: the neighbourhood of a hub is most of the repository.
+     */
+    graph?: Graph;
+    /** Edge kinds to spread across when `graph` is given. */
+    kinds?: readonly string[];
+    /** How far to spread. Default 1 — direct neighbours only. */
+    depth?: number;
+    /** Cap on returned memories. Default 20. */
+    limit?: number;
+}
+/**
+ * Gather what is known about some subjects, optionally including their
+ * neighbourhood.
+ *
+ * Superseded memories are dropped. Keeping them would mean the agent reads a
+ * correction and its own contradiction in the same breath, and has to guess
+ * which is current — which is worse than not remembering at all.
+ */
+declare function recallAbout(store: CodeMemoryStore, subjects: readonly string[], options?: RecallOptions): Promise<CodeMemory[]>;
+/** Render memories for a prompt — the cheapest form that still says enough. */
+declare function renderMemories(memories: readonly CodeMemory[]): string;
+/**
+ * Turn a failed attempt into something the next run does not have to pay for.
+ *
+ * This is the write that justifies the store. The gate's verdict is the most
+ * expensive knowledge a run produces — it cost a whole attempt — and until now
+ * it was dropped the moment the next prompt was built.
+ *
+ * Recorded against the files the attempt actually touched, so it surfaces to
+ * whoever works on them next rather than being filed under the goal, which
+ * nobody will ever search for.
+ */
+declare function hazardFromAttempt(input: {
+    goal: string;
+    attempt: number;
+    feedback: string;
+    touched: readonly string[];
+    verificationId: string;
+    authorId: string;
+}): NewCodeMemory[];
+
+/** What a run actually did, judged rather than claimed. */
+interface GoalOutcome {
+    /** The PM entity this goal came from, when it came from one. */
+    pmEntityId?: string;
+    goal: string;
+    /** How the goal said it would be judged. */
+    proof: string;
+    /** Whether the clean verifier agreed. */
+    met: boolean;
+    /** Why it stopped — `proof_passed`, or the budget that ran out. */
+    stoppedReason: string;
+    attempts: number;
+    tokens: number;
+    costUsd?: number;
+    /** The receipt that backs a met verdict. Absent means nothing backs it. */
+    evidence?: CodeMemoryEvidence;
+}
+/**
+ * Whether an outcome may move a PM item to done.
+ *
+ * Two conditions, and the second is the one that matters: the verifier agreed,
+ * AND it left a receipt. A `met` with no evidence is an agent's assertion
+ * wearing a verdict's clothes, and admitting it would make the whole audit
+ * trail decorative.
+ */
+declare function outcomeCloses(outcome: GoalOutcome): boolean;
+/**
+ * Say plainly what happened, for the PM comment that records it.
+ *
+ * Written for a human deciding whether to trust the result, so the numbers that
+ * bound the claim — attempts, tokens, cost — are in the sentence rather than in
+ * a linked artifact nobody opens. Unknown cost is said as unknown; reporting
+ * $0.00 for a run whose pricing was unavailable would be a lie in the direction
+ * that flatters the agent.
+ */
+declare function renderOutcome(outcome: GoalOutcome): string;
+/**
+ * Record the outcome as a memory, so the next run knows what this one settled.
+ *
+ * Filed against the goal's subject rather than a file: an outcome is about an
+ * intention, and the useful question later is "has anyone tried this before",
+ * not "what happened to line 40".
+ */
+declare function outcomeMemory(outcome: GoalOutcome, subject: string, authorId: string): NewCodeMemory;
+
+/** Everything the runner learns from one attempt. */
+interface GoalAttemptOutcome {
+    /** Did the goal's proof pass on the resulting tree? */
+    gatePassed: boolean;
+    /** What the gate said, fed back as the next instruction when it failed. */
+    feedback: string;
+    /** Tokens this attempt consumed, for the budget. */
+    tokens: number;
+    /** USD this attempt cost, when known. Unknown is not zero. */
+    costUsd?: number;
+    /** Set when the attempt could not run at all, as opposed to running and failing. */
+    error?: string;
+    /** Model turns taken. Used to rank racers; optional elsewhere. */
+    steps?: number;
+    /** Size of the candidate patch produced. Used to break a tie between racers. */
+    patchBytes?: number;
+}
+/** What one attempt is told: which try this is, and what to do. */
+interface GoalAttemptInput {
+    /** 1-based attempt number. */
+    attempt: number;
+    /** What to tell the agent this time. */
+    prompt: string;
+    signal?: AbortSignal;
+}
+/** Run one attempt and report what the gate made of it. */
+type GoalAttempt = (input: GoalAttemptInput) => Promise<GoalAttemptOutcome>;
+/** Bounds on autonomous pursuit. Every one of them is a stop, not a suggestion. */
+interface GoalBudget {
+    /** Hard cap on attempts. Required — an unbounded loop is not a budget. */
+    maxAttempts: number;
+    maxTokens?: number;
+    maxUsd?: number;
+    /** Absolute epoch milliseconds. */
+    deadline?: number;
+}
+/** What the runner reports as it goes, so a board can follow from evidence. */
+type GoalEvent = {
+    type: "attempt_started";
+    attempt: number;
+    prompt: string;
+} | {
+    type: "attempt_failed";
+    attempt: number;
+    feedback: string;
+    error?: string;
+} | {
+    type: "goal_met";
+    attempts: number;
+    tokens: number;
+    costUsd?: number;
+} | {
+    type: "goal_abandoned";
+    reason: GoalStoppedReason;
+    attempts: number;
+    tokens: number;
+    costUsd?: number;
+};
+/**
+ * One goal, its proof, and the budget the runner may spend pursuing it.
+ *
+ * The budget is not advisory. Every ceiling is checked after the attempt that
+ * consumed it, so a run always stops on a named reason rather than drifting.
+ */
+interface GoalRunSpec {
+    /** The objective, in the owner's words. */
+    goal: string;
+    /** How the runner knows it is met — surfaced to the agent so it aims at the
+     *  same thing the gate measures. */
+    proof?: string;
+    budget: GoalBudget;
+    signal?: AbortSignal;
+    now?: () => number;
+    /**
+     * Follow the run. Called for every transition so a project board can be
+     * updated from what actually happened rather than from the agent's account
+     * of it.
+     *
+     * Failures here are SWALLOWED. The work is authoritative and the board is a
+     * projection of it: a PM outage must not abandon a goal that is succeeding,
+     * and losing a comment is cheaper than losing the run. `boardErrors` on the
+     * result records what did not land, so silence is never mistaken for success.
+     */
+    onEvent?(event: GoalEvent): Promise<void> | void;
+}
+/** Why a run ended. `proof_passed` is the only success; the rest are budgets. */
+type GoalStoppedReason = "proof_passed" | "max_attempts" | "token_budget" | "cost_budget" | "deadline" | "cancelled" | "attempt_failed";
+/** One attempt as it actually went, including what the gate said about it. */
+interface GoalAttemptRecord {
+    attempt: number;
+    gatePassed: boolean;
+    tokens: number;
+    costUsd?: number;
+    feedback: string;
+    error?: string;
+}
+/**
+ * The whole pursuit: whether the proof passed, why it stopped, and every
+ * attempt along the way. `boardErrors` records handler failures the runner
+ * swallowed, so a silent kanban outage is visible rather than invisible.
+ */
+interface GoalRun {
+    met: boolean;
+    /** Event-handler failures, in order. Empty when the board kept up. */
+    boardErrors: string[];
+    stoppedReason: GoalStoppedReason;
+    attempts: GoalAttemptRecord[];
+    tokens: number;
+    /** Summed cost, or undefined when no attempt reported one. */
+    costUsd?: number;
+    durationMs: number;
+}
+/**
+ * Pursue one goal.
+ *
+ * The re-prompt carries the GATE's output, not a restatement of the goal. That
+ * is the whole trick: an agent told only "try again" repeats itself, while an
+ * agent handed the failing test output has something new to act on. It is also
+ * why the runner refuses to continue without feedback — a gate that fails
+ * silently would produce an expensive loop that cannot learn.
+ */
+declare function runGoal(spec: GoalRunSpec, attempt: GoalAttempt): Promise<GoalRun>;
+
+/** One racer's result, tagged with which racer produced it. */
+interface RacedOutcome extends GoalAttemptOutcome {
+    racer: number;
+}
+/**
+ * One race: N independent attempts at the same goal, cheapest winner taken.
+ *
+ * The run is charged for every racer, not just the winner. Racing answers
+ * variance, not size; at equal budget, depth beat it on every axis measured.
+ */
+interface RacedAttemptOptions {
+    /** How many attempts run per round. */
+    racers: number;
+    /** Runs one racer. Each MUST get an isolated workspace — racers edit in
+     *  parallel, and a shared tree would have them overwrite each other. */
+    attempt(input: GoalAttemptInput & {
+        racer: number;
+    }): Promise<GoalAttemptOutcome>;
+    /** Override the ranking. Default: {@link selectWinner}. */
+    select?(outcomes: RacedOutcome[]): RacedOutcome;
+    /** Observe the whole field, for reporting what racing cost and bought. */
+    onRound?(outcomes: RacedOutcome[], winner: RacedOutcome): void;
+}
+/**
+ * Rank a field of racers.
+ *
+ * Passing candidates first — that is the only thing that decides the goal. Then
+ * fewest steps, then cheapest, then smallest patch: three tie-breaks that all
+ * prefer the attempt which did LESS to get there, on the view that a smaller
+ * change reaching the same verified state is the better one to keep.
+ *
+ * Unknown cost ranks LAST among passing candidates rather than cheapest. An
+ * unpriced racer must not win a cost comparison it never entered.
+ */
+declare function selectWinner(outcomes: RacedOutcome[]): RacedOutcome;
+/**
+ * Build a GoalAttempt that races `racers` attempts and returns the winner.
+ *
+ * The returned outcome reports the round's TOTAL tokens and cost, not the
+ * winner's. The runner charges its budget from what an attempt reports, and
+ * charging only the winner would make racing look free — three racers would
+ * cost what one did, and every budget in the system would be wrong by a factor
+ * of N. Racing trades depth for breadth at honest spend, or it is not a trade.
+ */
+declare function racedAttempt(options: RacedAttemptOptions): GoalAttempt;
+
+/** One independent slice of a goal, scoped to the files it may touch. */
+interface SubGoal {
+    id: string;
+    /** What this sub-agent is asked to do. */
+    goal: string;
+    /** The files it declares it will touch. Its patch is rejected if it strays. */
+    files: string[];
+}
+/** A plan that cannot be run in parallel — overlapping files, or a stray edit. */
+declare class DecompositionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Reject a plan that cannot be worked in parallel, BEFORE any agent starts.
+ *
+ * Two sub-goals declaring the same file is the whole failure mode: they would
+ * produce patches against the same lines and one of them could not be applied.
+ * Catching it here costs nothing; catching it at integration costs every token
+ * both sub-agents spent.
+ */
+declare function assertDisjointPlan(plan: readonly SubGoal[]): void;
+/** Files a patch actually touches, or null when it is not a valid patch. */
+declare function patchPaths(patch: string, maxBytes?: number): string[] | null;
+/**
+ * Check a sub-agent stayed inside what it declared.
+ *
+ * This is what makes the partition a guarantee rather than a hope: the plan is
+ * checked up front, and each patch is checked against the plan. A sub-agent that
+ * wandered into a neighbour's file is refused even if its patch would have
+ * applied cleanly, because the NEXT sub-patch was written against a tree where
+ * that edit does not exist.
+ */
+declare function straySubGoalFiles(sub: SubGoal, patch: string): string[];
+/** What one sub-goal produced: its patch, its cost, and whether it worked. */
+interface SubGoalResult {
+    sub: SubGoal;
+    /** The candidate patch, or empty when the sub-agent changed nothing. */
+    patch: string;
+    tokens: number;
+    costUsd?: number;
+    error?: string;
+}
+/** Applying one sub-goal's patch to the accumulating tree, and the verdict. */
+interface IntegrationStep {
+    subGoalId: string;
+    /** Did the accumulated tree still satisfy the proof after applying this one? */
+    gatePassed: boolean;
+    applied: boolean;
+    reason?: "stray_files" | "did_not_apply" | "gate_failed" | "sub_goal_failed" | "no_changes";
+    detail?: string;
+}
+/**
+ * A decomposed pursuit end to end.
+ *
+ * Measured at 1.68x the tokens of straight depth for 0.88x the wall clock, so
+ * this buys latency, not efficiency — see chooseStrategy for when that trade
+ * is worth making.
+ */
+interface DecomposedRun {
+    met: boolean;
+    steps: IntegrationStep[];
+    tokens: number;
+    costUsd?: number;
+}
+/** The plan, its results, and the two callbacks that apply and judge them. */
+interface IntegrateOptions {
+    plan: readonly SubGoal[];
+    results: readonly SubGoalResult[];
+    /** Apply one patch to the accumulating tree; reject means it did not apply. */
+    apply(patch: string): Promise<boolean>;
+    /** Run the proof against the accumulating tree. */
+    gate(): Promise<boolean>;
+}
+/**
+ * Integrate sub-results one at a time, gating after each.
+ *
+ * Order follows the plan, and the first failure stops integration. Continuing
+ * past one would mean gating a tree whose earlier layer is already known bad,
+ * so every later verdict would describe a state nobody intends to ship.
+ */
+declare function integrateSubGoals(options: IntegrateOptions): Promise<DecomposedRun>;
+/**
+ * The check `assertDisjointPlan` cannot make: do the sub-goals collide through
+ * what they *reach*, not merely through what they declare?
+ *
+ * Collision ids are graph ids (`file:src/a.ts`, `table:orders`), because the
+ * answer is no longer only about files — a shared table is a real collision and
+ * naming it as a bare path would be a lie about what it is.
+ *
+ * Declared files being disjoint is necessary and not sufficient. Two sub-goals
+ * can own different modules and still both depend on a third; a change either
+ * one makes to that shared module lands in one patch and is invisible to the
+ * other's verification. The import graph is the only thing that can see this,
+ * and it is cheap — the graph over 3,400 files builds in ~400ms, against the
+ * cost of running two agents to completion and discovering it at integration.
+ *
+ * Reported rather than thrown, because a shared dependency is sometimes fine:
+ * two sub-goals may both READ a types module neither intends to touch. The
+ * caller decides whether the overlap is one it can live with.
+ */
+declare function planReachCollisions(plan: readonly SubGoal[], workspace: {
+    paths: readonly string[];
+    read(path: string): Promise<string>;
+}): Promise<PartitionVerdict>;
+
+/** What is known about a goal before choosing how to pursue it. */
+interface StrategySignals {
+    /** Prior attempts, oldest first. Empty on the first pass. */
+    priorAttempts?: Array<{
+        gatePassed: boolean;
+        feedback: string;
+        error?: string;
+    }>;
+    /** True when wall clock is the binding constraint — a human is waiting, or a
+     *  deadline is close — and paying more per solve to finish sooner is correct. */
+    latencyBound?: boolean;
+    /** Estimated tokens needed to hold the whole goal at once. */
+    estimatedContextTokens?: number;
+    /** What one agent can actually hold. */
+    contextLimit?: number;
+    /** A checked disjoint partition, when the planner produced one. */
+    partitionable?: boolean;
+    /** Racers/sub-agents available if fanning out. */
+    width?: number;
+}
+/** How to spend a goal's budget: straight depth, N racers, or a split plan. */
+type GoalStrategy = "sequential" | "race" | "decompose";
+/** The chosen strategy, why, and what it is expected to cost against depth. */
+interface StrategyChoice {
+    strategy: GoalStrategy;
+    /** Why, in terms a human reviewing a run can check. */
+    reason: string;
+    /** Expected cost multiplier vs sequential, from the measurements above.
+     *  1 for sequential; fan-out is charged what it was observed to cost. */
+    expectedCostMultiplier: number;
+    /** False when the branch rests on something not yet measured. */
+    measured: boolean;
+}
+/** Observed premiums. Update these from the bench, not from expectation. */
+declare const MEASURED_PREMIUM: Readonly<{
+    /** 3 racers vs pure depth at equal budget: 21,044 / 7,936. */
+    racePerRacer: 0.55;
+    /** Decomposition across 3 sub-agents: 10,897 / 6,474. */
+    decomposePerSubGoal: 0.23;
+}>;
+/**
+ * Choose a strategy.
+ *
+ * Order matters and encodes the evidence: depth first, because it won every
+ * measured comparison; fan-out only where depth demonstrably cannot help.
+ */
+declare function chooseStrategy(signals?: StrategySignals): StrategyChoice;
+/** Whether the gate's output gives the next attempt something to work with. */
+declare const feedbackIsActionable: (feedback: string) => boolean;
+
+/**
+ * Strip an apply_patch envelope from around a git diff.
+ *
+ * Models emit `*** Begin Patch` / `*** End Patch` constantly — twice in five
+ * tool calls during the first real dogfood — even with a system prompt that
+ * forbids it by name, because it is the dominant format elsewhere. What they
+ * wrap in it is usually a perfectly good unified diff, and git apply then dies
+ * on "unexpected line: *** End Patch".
+ *
+ * Refusing that is a surface arguing with its users and charging them a turn to
+ * lose. The envelope is stripped ONLY when a real `diff --git` survives
+ * underneath: this accepts a mis-wrapped diff, and does not attempt to
+ * translate the genuinely different apply_patch dialect, which would mean
+ * inventing hunks nobody wrote.
+ */
+declare function stripPatchEnvelope(patch: string): string;
+/** Validate a text-only, same-path unified patch and return every affected path. */
+declare function validateCodePatch(rawPatch: string, maxBytes: number): string[];
+/** Restrict Code tool paths to ordinary files outside filtered/secret trees. */
+declare function validateRelativePath(path: string): void;
+/** Resolve a validated relative path without permitting a root escape. */
+declare function resolveCodePath(workspaceDir: string, path: string): string;
+/**
+ * Why `git apply` rejected a patch, in terms the author can act on.
+ *
+ * A hunk with no context lines is the common case and the least obvious: git
+ * refuses it whenever the file has more lines than the hunk claims, with only
+ * "patch does not apply" to show for it. Models emit context-free hunks
+ * constantly, so saying this plainly turns a silent retry loop into one
+ * corrected call.
+ */
+declare function describePatchFailure(patch: string, detail: string): string;
+/** Apply a previously validated patch without invoking a shell or repository hooks. */
+declare function applyCodePatch(workspaceDir: string, rawPatch: string, paths: readonly string[]): Promise<void>;
+
+/**
+ * An installed dependency tree lent to a recipe for the length of one run.
+ *
+ * Mounted under a reserved name and removed in a finally, so the agent can run
+ * a real build without the tree ever being addressable by a patch.
+ */
+interface RecipeDependencies {
+    /** Absolute path to an installed dependency tree on the host. */
+    source: string;
+    /** Where it appears inside the workspace. Must be a reserved name, so the
+     *  agent still cannot address it. */
+    mountAs?: string;
+}
+/**
+ * Wrap an executor so `dependencies.source` is present during each recipe run.
+ *
+ * It is linked, not copied. A link costs nothing per run, and dependencies are
+ * identical across every attempt, racer and verification — copying them would
+ * multiply the largest thing in the tree by the number of stages.
+ *
+ * The link is removed in a `finally`, so a recipe that times out or throws
+ * cannot leave it behind for `workspace.patch()` to diff or
+ * `digestStagedWorkspace` to hash.
+ */
+declare function withRecipeDependencies(executor: CodeRecipeExecutor, dependencies: RecipeDependencies): CodeRecipeExecutor;
+/** Resolve the dependency tree for a repository root, when it has one. */
+declare function installedDependencies(repoRoot: string): Promise<RecipeDependencies | null>;
+
+/** Every ordinary, policy-legal source path under `root`, sorted. */
+declare function registeredFiles(root: string, limit?: number): Promise<string[]>;
+
 /** Build a trusted, fixed command for an isolated and networkless recipe container. */
 declare function buildRecipeContainerArgs(engine: ContainerEngine, workspaceDir: string, recipe: CodeBuildRecipe, name?: string): string[];
 /** Create a recipe executor that never invokes a shell and never mounts credentials. */
@@ -541,4 +1270,4 @@ interface CodeVerificationEvidence {
 /** Rebuild a candidate from an exact trusted base and emit a prose-free clean-verifier receipt. */
 declare function verifyCodeCandidate(input: VerifyCodeCandidateInput): Promise<CodeVerificationEvidence>;
 
-export { CODE_RUNTIME_PROTOCOL_VERSION, type CodeBuildRecipe, type CodeExpectedArtifact, type CodeLocalSourceDescriptor, CodePiRuntimeEngine, type CodePiRuntimeEngineOptions, type CodeRecipeExecutor, type CodeRecipeResult, type CodeRuntimeAgentControlPlane, type CodeRuntimeBinding, type CodeRuntimeCandidateResponse, type CodeRuntimeCapabilities, CodeRuntimeCheckpointManager, type CodeRuntimeClientOptions, type CodeRuntimeCommand, type CodeRuntimeCommandEngine, type CodeRuntimeCommandKind, type CodeRuntimeCommandResult, CodeRuntimeControlError, type CodeRuntimeControlPlane, type CodeRuntimeLoopOptions, CodeRuntimeReconciler, type CodeRuntimeReviewRequest, type CodeRuntimeReviewResponse, type CodeRuntimeSnapshot, type CodeRuntimeSourceSnapshot, type CodeToolBrokerOptions, type CodeToolDecision, type CodeVerificationEvidence, type CodeVerificationLog, type CodeVerificationPolicy, type ContainerEngine, type ContainerEngineSelectionOptions, type ContainerEngineVerificationOptions, type ContainerLimits, type ContainerRunOptions, type ContainerRunResult, type CreateCodeWorkspaceCheckpointInput, type HarnessRunnerOptions, type MaterializedCodeSource, type MaterializedGitTree, type PrepareRuntimeCheckpointInput, type PreparedRuntimeCheckpoint, type RestoreCodeWorkspaceCheckpointInput, type RestoredCodeWorkspaceCheckpoint, type RuntimeCheckpointSession, type StageWorkspaceOptions, type StagedWorkspace, type VerifyCodeCandidateInput, assertCodeBuildRecipe, assertPinnedImage, attachCodeRuntimeReferences, buildContainerRunArgs, buildRecipeContainerArgs, createCodeRuntimeControlClient, createCodeToolBroker, createCodeWorkspaceCheckpoint, createContainerRecipeExecutor, digestStagedWorkspace, isCheckpointEffectCompleted, materializeCodeRuntimeSource, materializeGitTree, prepareRuntimeCheckpoint, restoreCodeWorkspaceCheckpoint, runCodeRuntimeHeartbeatLoop, runContainerAttempt, runHarnessRunner, runLeasedAttempt, safeWorkspaceLabel, selectContainerEngine, stageWorkspace, stageWorkspacePair, verifyCodeCandidate, verifyContainerEngineBoundary };
+export { CODE_RUNTIME_PROTOCOL_VERSION, type CodeAgentAttemptOptions, type CodeAgentAttemptResult, type CodeAgentRun, type CodeBuildRecipe, type CodeExpectedArtifact, type CodeLocalSourceDescriptor, type CodeMemory, type CodeMemoryEvidence, type CodeMemoryKind, type CodeMemoryStore, CodePiRuntimeEngine, type CodePiRuntimeEngineOptions, type CodeRecipeExecutor, type CodeRecipeResult, type CodeRuntimeAgentControlPlane, type CodeRuntimeBinding, type CodeRuntimeCandidateResponse, type CodeRuntimeCapabilities, CodeRuntimeCheckpointManager, type CodeRuntimeClientOptions, type CodeRuntimeCommand, type CodeRuntimeCommandEngine, type CodeRuntimeCommandKind, type CodeRuntimeCommandResult, CodeRuntimeControlError, type CodeRuntimeControlPlane, type CodeRuntimeInferenceOptions, type CodeRuntimeLoopOptions, CodeRuntimeReconciler, type CodeRuntimeReviewRequest, type CodeRuntimeReviewResponse, type CodeRuntimeSnapshot, type CodeRuntimeSourceSnapshot, type CodeSkillOpts, type CodeSurface, type CodeToolBrokerOptions, type CodeToolCallRecord, type CodeToolDecision, type CodeVerificationEvidence, type CodeVerificationLog, type CodeVerificationPolicy, type ContainerEngine, type ContainerEngineSelectionOptions, type ContainerEngineVerificationOptions, type ContainerLimits, type ContainerRunOptions, type ContainerRunResult, type CreateCodeWorkspaceCheckpointInput, type DecomposedRun, DecompositionError, type GoalAttempt, type GoalAttemptInput, type GoalAttemptOutcome, type GoalAttemptRecord, type GoalBudget, type GoalEvent, type GoalOutcome, type GoalRun, type GoalRunSpec, type GoalStoppedReason, type GoalStrategy, type HarnessRunnerOptions, type IntegrateOptions, type IntegrationStep, MAX_MEMORY_BODY, MEASURED_PREMIUM, type MaterializedCodeSource, type MaterializedGitTree, type NewCodeMemory, type PrepareRuntimeCheckpointInput, type PreparedRuntimeCheckpoint, type RacedAttemptOptions, type RacedOutcome, type RecallOptions, type RecipeDependencies, type RestoreCodeWorkspaceCheckpointInput, type RestoredCodeWorkspaceCheckpoint, type RunCodeAgentOptions, type RuntimeCheckpointSession, SYSTEM_PROMPT_FOR, type StageWorkspaceOptions, type StagedWorkspace, type StrategyChoice, type StrategySignals, type SubGoal, type SubGoalResult, V1_SYSTEM_PROMPT, V2_SYSTEM_PROMPT, V3_SYSTEM_PROMPT, type VerifyCodeCandidateInput, applyCodePatch, assertCodeBuildRecipe, assertDisjointPlan, assertPinnedImage, attachCodeRuntimeReferences, buildContainerRunArgs, buildRecipeContainerArgs, chooseStrategy, codeSkill, createCodeRuntimeControlClient, createCodeRuntimeInference, createCodeToolBroker, createCodeWorkspaceCheckpoint, createContainerRecipeExecutor, describePatchFailure, digestStagedWorkspace, feedbackIsActionable, hazardFromAttempt, installedDependencies, integrateSubGoals, isCheckpointEffectCompleted, materializeCodeRuntimeSource, materializeCommandWorkspace, materializeGitTree, outcomeCloses, outcomeMemory, patchPaths, planReachCollisions, prepareRuntimeCheckpoint, racedAttempt, recallAbout, registeredFiles, renderMemories, renderOutcome, resolveCodePath, restoreCodeWorkspaceCheckpoint, runCodeAgent, runCodeAgentAttempt, runCodeRuntimeHeartbeatLoop, runContainerAttempt, runGoal, runHarnessRunner, runLeasedAttempt, safeWorkspaceLabel, selectContainerEngine, selectWinner, stageWorkspace, stageWorkspacePair, straySubGoalFiles, stripPatchEnvelope, validateCodePatch, validateMemory, validateRelativePath, verifyCodeCandidate, verifyContainerEngineBoundary, withRecipeDependencies };