@loops-adk/core 0.1.0

package/dist/types-B4wGVpqo.d.ts

@@ -0,0 +1,898 @@
+/**
+ * The pluggable execution backend. A `Step` asks an `Engine` to run one agent
+ * turn with a *fresh context* and stream events back. Each call is independent —
+ * that is what gives every loop iteration its clean slate.
+ */
+/**
+ * Built-in, registry-resolvable adapter names. The union is open (`& {}` trick)
+ * so callers can name and register their own engines — the core never assumes a
+ * fixed provider set. (`mock` is constructed directly in tests/examples, not
+ * registered by name, so it is intentionally not listed here.)
+ */
+type EngineName = 'agent-sdk' | 'claude-cli' | 'anthropic-api' | (string & {});
+interface Usage {
+    inputTokens: number;
+    outputTokens: number;
+}
+/** Tools an agent uses to spawn sub-agents / fan out. A `leaf` request disallows these. */
+declare const SUBAGENT_TOOLS: string[];
+interface AgentRequest {
+    prompt: string;
+    system?: string;
+    model?: string;
+    maxTokens?: number;
+    /** Tool allowlist, where the backend supports tools (SDK / CLI). */
+    allowedTools?: string[];
+    cwd?: string;
+    timeoutMs?: number;
+    /**
+     * Forbid this agent from spawning sub-agents (fanning out). A leaf agent is told to
+     * disallow the sub-agent tool (`SUBAGENT_TOOLS`), so a branch of the graph bottoms out
+     * here instead of expanding into an uncontrolled swarm — control over where work stops.
+     * Authoritative over `allowedTools` (a disallow wins). Engines with no sub-agent tool
+     * (anthropic-api, mock) ignore it.
+     */
+    leaf?: boolean;
+}
+interface AgentResult {
+    /** Final assistant text (concatenated across blocks). */
+    text: string;
+    usage: Usage;
+    model: string;
+    stopReason?: string;
+    /** Backend-native final payload, for escape-hatch inspection. */
+    raw?: unknown;
+}
+/** Streamed during a run. The runtime re-tags these as `LoopEvent`s. */
+type EngineStreamEvent = {
+    type: 'text';
+    delta: string;
+} | {
+    type: 'thinking';
+    delta: string;
+} | {
+    type: 'tool';
+    name: string;
+    phase: 'use' | 'result';
+} | {
+    type: 'usage';
+    usage: Usage;
+    model: string;
+};
+type EngineEventSink = (event: EngineStreamEvent) => void;
+interface Engine {
+    readonly name: EngineName;
+    /**
+     * Run one fresh agent turn. Contract for the `usage` stream event: emit it
+     * **exactly once, at the end** of the turn — stats sums every `usage` event,
+     * so a backend that emits incremental usage mid-stream would inflate totals.
+     */
+    run(req: AgentRequest, onEvent: EngineEventSink, signal: AbortSignal): Promise<AgentResult>;
+}
+/**
+ * Anywhere an engine can be selected, accept either a registered name or a
+ * ready-made `Engine`. The latter is the "bring your own provider/framework"
+ * escape hatch — the runtime treats every backend through this one interface.
+ */
+type EngineRef = EngineName | Engine;
+declare function isEngine(ref: EngineRef | undefined): ref is Engine;
+/**
+ * How a tool-using engine (claude-cli / agent-sdk) treats permission prompts.
+ * Mirrors the Claude Code values. `bypassPermissions` lets a headless worker
+ * read/write/run without prompting — required for an unattended agent that must
+ * touch the filesystem or shell, and to be set deliberately.
+ */
+type PermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'dontAsk' | 'auto';
+/** Per-run options that the registry uses to construct engines. */
+interface EngineOptions {
+    /** Default model when a request/step does not name one. */
+    defaultModel?: string;
+    apiKey?: string;
+    /** For `claude-cli`: path to the binary (defaults to `claude` on PATH). */
+    cliBinary?: string;
+    /** Extra args appended to the `claude` invocation. */
+    cliArgs?: string[];
+    /**
+     * Permission mode for tool-using engines (claude-cli `--permission-mode`,
+     * agent-sdk `permissionMode`). Unset = the engine/CLI default (prompts).
+     */
+    permissionMode?: PermissionMode;
+}
+
+/**
+ * Structured, classified errors so the exit report can say *what* failed,
+ * *where* in the loop tree, and *why* — instead of dumping a stack.
+ */
+type LoopErrorCode = 'ENGINE' | 'TIMEOUT' | 'ABORTED' | 'VALIDATION' | 'CONFIG' | 'BUDGET' | 'RATE_LIMIT' | 'QUOTA' | 'BODY' | 'UNKNOWN';
+type LoopPhase = 'start' | 'body' | 'until' | 'stopOn' | 'review' | 'engine';
+interface LoopErrorInit {
+    code: LoopErrorCode;
+    message: string;
+    phase?: LoopPhase;
+    path?: readonly string[];
+    iteration?: number;
+    cause?: unknown;
+    retryable?: boolean;
+    /** Suggested wait before retry, in ms (e.g. a `retry-after` header). */
+    retryAfterMs?: number;
+    /** When the limit resets, as epoch ms. The wait policy prefers this. */
+    resetAt?: number;
+}
+declare class LoopError extends Error {
+    readonly code: LoopErrorCode;
+    readonly phase?: LoopPhase;
+    readonly path?: readonly string[];
+    readonly iteration?: number;
+    readonly retryable: boolean;
+    /** Suggested wait before retry, in ms (e.g. a `retry-after` header). */
+    readonly retryAfterMs?: number;
+    /** When the limit resets, as epoch ms. The wait policy prefers this. */
+    readonly resetAt?: number;
+    constructor(init: LoopErrorInit);
+    /** Wrap an arbitrary thrown value, preserving a `LoopError` as-is. */
+    static from(value: unknown, fallback: Omit<LoopErrorInit, 'message' | 'cause'>): LoopError;
+    toJSON(): {
+        name: string;
+        code: LoopErrorCode;
+        message: string;
+        phase: LoopPhase | undefined;
+        path: readonly string[] | undefined;
+        iteration: number | undefined;
+        retryable: boolean;
+        retryAfterMs: number | undefined;
+        resetAt: number | undefined;
+    };
+}
+
+/**
+ * A token-denominated budget for a whole run, threaded through the JobContext so
+ * every engine call site can refuse to spend past the cap. The honest cost guard
+ * for a loop that may fire a worker plus several judges per iteration: `max` and
+ * depth bound the *count* of calls, this bounds their *cost*.
+ *
+ * The runner feeds `add()` from each `engine:usage` event, so `spent()` is live.
+ * `assertBudget(ctx)` runs before an engine call; once the cap is reached it
+ * throws a non-retryable BUDGET error (hard mode, terminates the run) or logs
+ * and continues (soft mode, for exploratory runs).
+ */
+
+interface BudgetConfig {
+    /** Cap on total tokens (input + output) for the whole run. */
+    limit: number;
+    /**
+     * Refuse a new engine call once `spent + headroom >= limit`, i.e. stop with
+     * room to spare rather than only after the cap is already blown. Default 0.
+     */
+    headroom?: number;
+    /** Warn and continue instead of refusing when the cap is hit. Default false. */
+    soft?: boolean;
+}
+declare class Budget {
+    readonly limit: number;
+    readonly headroom: number;
+    readonly soft: boolean;
+    private tokens;
+    constructor(config: BudgetConfig);
+    /** Record consumed tokens. Non-finite or non-positive values are ignored. */
+    add(tokens: number): void;
+    spent(): number;
+    remaining(): number;
+    /** True once the next call would breach the cap (accounting for headroom). */
+    exceeded(): boolean;
+}
+
+/**
+ * AgentDef — a reusable, job-specific agent definition. The persona and methodology
+ * (the prose: `system`, skill `instructions`) live in editable markdown files; the
+ * structure and types live here in TypeScript. The `.ts` is the strongly-typed wrapper
+ * around the `.md` — author the prompt as markdown, get type safety and validation in code.
+ *
+ * Grounded in the amps-os agent profile, minus the amps-specific machinery loops already
+ * provides: `dag` is the dispatcher, `conditions`/`quorum` are the gates, `Outcome` is the
+ * result channel. So AgentDef is just the contract — who the agent is, what it may touch,
+ * how it works — that `agentJob` resolves into an engine request.
+ */
+/** A skill is a METHODOLOGY (how to do the work — TDD, writing-plans), not a worker.
+ *  An agent composes skills; a skill never dispatches an agent. */
+interface Skill {
+    name: string;
+    /** The methodology instructions — prepended to the agent's system when it applies them. */
+    instructions: string;
+}
+interface AgentDef {
+    /** Identity (also the default job label). */
+    name: string;
+    /** What and why — for humans, docs, and (if loops scales) discovery. */
+    description?: string;
+    /** The system prompt: who the agent is and how it works. Use `fromFile('x.md')`. */
+    system: string;
+    /** Model id; omitted = inherit the run default. */
+    model?: string;
+    /** Allowed tool names — the permission boundary. */
+    tools?: string[];
+    /**
+     * Mark this agent a leaf: it may not spawn sub-agents / fan out (the engine disallows
+     * the sub-agent tool). Use it to control where a branch of the graph bottoms out — to
+     * stop a thorough agent from quietly expanding into a slow, expensive swarm.
+     */
+    leaf?: boolean;
+    /** Structured job descriptions (not prose) — for discovery / docs. */
+    capabilities?: string[];
+    /** Methodologies the agent applies; their instructions are folded into the system. */
+    skills?: Skill[];
+    /** Named failure modes + their recovery — first-class contracts, not buried prose. */
+    failureModes?: {
+        mode: string;
+        recovery: string;
+    }[];
+}
+/** Read a markdown file as a string — for `system` or skill `instructions`. Pass an
+ *  absolute path, or `new URL('./x.md', import.meta.url)` for a path relative to the file. */
+declare function fromFile(path: string | URL): string;
+/** Define a skill (a methodology). Identity + validation; strongly typed. */
+declare function defineSkill(skill: Skill): Skill;
+/** Define an agent. Identity + validation; strongly typed (the wrapper around the md). */
+declare function defineAgent(def: AgentDef): AgentDef;
+/**
+ * Resolve an agent's system prompt, folding in its skills' methodologies. This is what
+ * `agentJob` hands the engine as `system`.
+ */
+declare function resolveSystem(agent: AgentDef): string;
+
+/**
+ * Job builders. A `Job` is the unit of work; these are the common shapes.
+ * The agent launch (`agentJob`) is deliberately provider-agnostic: it only
+ * ever calls `Engine.run`, so it knows nothing about Claude, the CLI, an SDK,
+ * an HTTP API, or any framework — swap the engine and the same job runs.
+ */
+
+interface AgentJobConfig {
+    /** Job label (for events). Defaults to the agent's name, then `'agent'`. */
+    label?: string;
+    /**
+     * A reusable agent definition — supplies `system` (persona + skills), `model`, and
+     * `tools` (the job's `system`/`model`/`allowedTools` override it when also set). The
+     * persona lives in markdown via `fromFile`; this is the typed wrapper around it.
+     */
+    agent?: AgentDef;
+    /** The prompt, or a function of the context (e.g. include the iteration). */
+    prompt: string | ((ctx: JobContext) => string | Promise<string>);
+    system?: string | ((ctx: JobContext) => string);
+    /** Engine override: a registered name, your own `Engine`, or the default. */
+    engine?: EngineRef;
+    /** Bare model id — passed straight through to the engine. */
+    model?: string;
+    maxTokens?: number;
+    allowedTools?: string[];
+    /**
+     * Mark this turn a leaf: forbid spawning sub-agents (the engine disallows the sub-agent
+     * tool), so a branch bottoms out here. Falls back to the agent def's `leaf`.
+     */
+    leaf?: boolean;
+    /** Working dir for the turn. Default: the workspace dir (the worktree). */
+    cwd?: string;
+    timeoutMs?: number;
+    /**
+     * Ground the turn in memory before it works: prepend the branch-local commit log
+     * (recent committed milestones), the live working memory (`ledger.md`) and handoff
+     * (`prompt.md`) from this run, and tell the agent where to record its own
+     * reasoning. With grounding on, the harness also auto-captures the turn into
+     * `ledger.md` afterwards. `true` uses defaults; an object tunes the reach. This is
+     * how a fresh context stops repeating what earlier iterations already tried.
+     */
+    ground?: boolean | GroundConfig;
+    /**
+     * Map the agent's raw text into an `Outcome`. Default: `pass`, with the text
+     * as the summary. Return `fail` to keep an enclosing loop going.
+     */
+    outcome?: (text: string, ctx: JobContext) => Outcome | Promise<Outcome>;
+}
+interface GroundConfig {
+    /** Max committed milestones to include (newest first). Default 10. */
+    max?: number;
+    /** Truncate each commit body to this many chars. Default 1200. */
+    bodyChars?: number;
+    /** Include the live scratch files (this run's working memory + handoff). Default true. */
+    includeScratch?: boolean;
+    /** Tell the agent to leave memory for the next agent. Default true. */
+    recordInstruction?: boolean;
+    /**
+     * Retrieve relevant commits with a cheap model instead of taking recent-N.
+     * Far less noisy when the branch log carries unrelated work (a shared repo).
+     * `true` uses defaults; an object tunes the candidate window / selection model.
+     */
+    retrieve?: boolean | {
+        candidates?: number;
+        model?: string;
+    };
+}
+/** Run one fresh agent turn through whichever engine is selected. */
+declare function agentJob(config: AgentJobConfig): Job;
+interface CommitJobConfig {
+    label?: string;
+    /** Conventional-commit subject, or a function of context + last outcome. */
+    subject: string | ((ctx: JobContext, last: Outcome | undefined) => string | Promise<string>);
+    /**
+     * The "way" — the structured commit body. Precedence when composing it:
+     *   1. this `body` (an explicit override — a string or function), else
+     *   2. the scratch files: the handoff (`prompt.md`) plus a compacted working log
+     *      (`ledger.md`) — the trusted source, capturing the why as it happens across
+     *      a long unit of work and across fanned-out sub-agents, else
+     *   3. a default composed from the last outcome (the floor).
+     * Set `body` only to override the scratch files.
+     */
+    body?: string | ((ctx: JobContext, last: Outcome | undefined) => string | Promise<string>);
+    /** Model for the (cheap) ledger-compaction call. A small one is plenty. */
+    compactModel?: string;
+    /** Stage every change before committing (default true). */
+    stageAll?: boolean;
+    /** Commit even with nothing staged (default false → a no-op `pass`). */
+    allowEmpty?: boolean;
+}
+/**
+ * Commit the workspace — write the "way" (a structured body) welded to the
+ * "what" (the staged diff) onto the work branch. This is the loop's memory: the
+ * next fresh context reads these commits back. The body is composed from the
+ * scratch files (the handoff plus a compacted working log agents accrued as they
+ * worked), falling back to the outcome floor — so the rich why survives context
+ * decay and fan-out. Both scratch files are cleared once the commit lands.
+ * Engine-agnostic; it only touches `ctx.workspace.dir` and git. A non-repo
+ * workspace fails loudly (a non-retryable CONFIG error) rather than silently
+ * dropping the work's record.
+ */
+declare function commitJob(config: CommitJobConfig): Job;
+/**
+ * Build an `Outcome` that sends work back to an earlier dag node — real-team
+ * feedback ("marketing found the contract drifted; re-run engineering"). Return
+ * it from any job or `agentJob({ outcome })` mapper. The enclosing `dag` re-runs
+ * `to` and its dependents with `reason` threaded in as `lastReview`, bounded by
+ * `DagConfig.maxKickbacks`. Defaults to a `fail` status, so an unresolved
+ * kickback (budget spent) leaves the dag failing honestly; override via `over`
+ * (e.g. `{ status: 'pass' }`) when the kicking node's own work is fine and it is
+ * only requesting an upstream revision.
+ */
+declare function kickback(to: string, reason: string, over?: Partial<Outcome>): Outcome;
+/** A deterministic step from a plain function — for glue, checks, side effects. */
+declare function fnJob(label: string, fn: (ctx: JobContext) => Outcome | Promise<Outcome>): Job;
+
+/**
+ * The Environment provider — the third axis, after Engine (where the agent
+ * thinks) and Workspace (where the code lives). Environment is where the code
+ * RUNS: local services, or a per-branch cloud preview. It is what lets the gate
+ * be fully honest — "done" can mean "the e2e suite passes against the running
+ * preview", not just "unit tests pass against static files on disk".
+ *
+ * Like `Engine`, this is only an interface. loops owns the seam and the
+ * lifecycle binding; the actual adapter (sst, Vercel, Docker, …) is
+ * provider-specific and lives in the CONSUMER's loop definition, next to the
+ * deploy config it wraps. loops never takes a dependency on a deploy tool. Bring
+ * your own in a few lines: implement `up`, return a handle.
+ *
+ *   const sstEnv: Environment = {
+ *     name: 'sst',
+ *     async up(ws) {
+ *       const stage = slug(ws.branch);           // per-branch stage
+ *       const out = await sh('sst', ['deploy', '--stage', stage], ws.dir);
+ *       return {
+ *         url: out.url,
+ *         env: { BASE_URL: out.url },
+ *         down: () => sh('sst', ['remove', '--stage', stage], ws.dir),
+ *       };
+ *     },
+ *   };
+ */
+
+/** A running environment for one workspace. Returned by `Environment.up`. */
+interface EnvHandle {
+    /** Addressable base URL (a preview deployment, or a local server), if any. */
+    readonly url?: string;
+    /**
+     * Variables injected into gate commands (and, later, agent turns) — e.g.
+     * `BASE_URL`, `DATABASE_URL`. This is how `commandSucceeds('playwright', …)`
+     * reaches the running preview.
+     */
+    readonly env: Record<string, string>;
+    /**
+     * Redeploy when the branch advances (a cloud preview that tracks commits).
+     * Optional: a local-services env has nothing to sync.
+     */
+    sync?(commit: string, signal: AbortSignal): Promise<void>;
+    /** Tear the environment down. */
+    down(signal: AbortSignal): Promise<void>;
+}
+/** Brings a workspace's code up so the gate can test the running thing. */
+interface Environment {
+    readonly name: string;
+    up(workspace: Workspace, signal: AbortSignal): Promise<EnvHandle>;
+}
+/** Duck-type guard: a ready-made `Environment` rather than something else. */
+declare function isEnvironment(value: unknown): value is Environment;
+
+/**
+ * The Forge provider — the host where a branch becomes a pull request. It sits
+ * alongside Engine (where the agent thinks) and Environment (where the code runs)
+ * as a thin, swappable seam: loops owns the interface and the jobs that drive it
+ * (`pullRequestJob`, `mergeJob` in `pr.ts`); the default adapter shells out to the
+ * GitHub CLI (`gh`), the same subprocess instinct as the `git`/claude-cli engines.
+ *
+ * Why a seam at all: the squash-merge boundary is where loops' commit-log memory
+ * would otherwise be lost. A PR carries a body, and a squash merge can be made to
+ * use that body as the merged commit message — so if loops keeps the PR body a
+ * faithful synthesis of the branch's commit "ways", the Ledger survives the squash.
+ * The Forge is how loops reaches the PR to write that body and (optionally) drive
+ * the merge. A `MockForge` keeps the jobs offline-testable, the loops convention.
+ */
+/** Identifies a pull request on the host. */
+interface PrRef {
+    number: number;
+    url: string;
+    /** The head branch the PR is for. */
+    branch?: string;
+}
+/** Everything needed to open a PR. */
+interface PrInput {
+    title: string;
+    body: string;
+    /** The branch to merge into (e.g. `main`). */
+    base: string;
+    /** The branch carrying the work (the PR head). */
+    branch: string;
+    draft?: boolean;
+}
+/** A partial update to an existing PR (the body is the synthesis we keep current). */
+interface PrPatch {
+    title?: string;
+    body?: string;
+}
+/** Where the host command runs (the repo working dir) + the run's abort signal. */
+interface ForgeOpts {
+    cwd: string;
+    signal?: AbortSignal;
+}
+interface MergeOptions extends ForgeOpts {
+    /** Squash merge (default). The whole point — collapse the branch to one commit. */
+    squash?: boolean;
+    /** The squash commit subject. */
+    subject?: string;
+    /** The squash commit body — the synthesis, written directly so it cannot be lost. */
+    body?: string;
+    /** Enqueue GitHub auto-merge: the merge happens once required checks pass. */
+    auto?: boolean;
+    /** Delete the head branch after merge. */
+    deleteBranch?: boolean;
+}
+/**
+ * The host seam. Five operations, each taking an explicit working dir — no hidden
+ * global state, mirroring `git.ts`. `viewPr` answers an expected "no" with
+ * `undefined` (no PR yet); the mutating ops throw a clear `CONFIG` error when the
+ * CLI is missing/unauthed, never a cryptic crash.
+ */
+interface Forge {
+    readonly name: string;
+    /** The open PR whose head is `branch`, or undefined when there is none. */
+    viewPr(branch: string, opts: ForgeOpts): Promise<PrRef | undefined>;
+    createPr(input: PrInput, opts: ForgeOpts): Promise<PrRef>;
+    editPr(pr: PrRef, patch: PrPatch, opts: ForgeOpts): Promise<void>;
+    mergePr(pr: PrRef, opts: MergeOptions): Promise<void>;
+    /** True when the PR's required checks are all green (for a synchronous gate). */
+    checksPass(pr: PrRef, opts: ForgeOpts): Promise<boolean>;
+}
+/** Duck-type guard: a ready-made `Forge` rather than something else. */
+declare function isForge(value: unknown): value is Forge;
+declare function buildViewArgs(branch: string): string[];
+declare function buildCreateArgs(input: PrInput): string[];
+declare function buildEditArgs(pr: PrRef, patch: PrPatch): string[];
+declare function buildMergeArgs(pr: PrRef, opts: MergeOptions): string[];
+declare function buildChecksArgs(pr: PrRef): string[];
+/** The GitHub CLI adapter. Everything `pr.ts` needs, over `gh`. */
+declare class GhForge implements Forge {
+    private readonly bin;
+    readonly name = "gh";
+    constructor(bin?: string);
+    viewPr(branch: string, opts: ForgeOpts): Promise<PrRef | undefined>;
+    createPr(input: PrInput, opts: ForgeOpts): Promise<PrRef>;
+    editPr(pr: PrRef, patch: PrPatch, opts: ForgeOpts): Promise<void>;
+    mergePr(pr: PrRef, opts: MergeOptions): Promise<void>;
+    checksPass(pr: PrRef, opts: ForgeOpts): Promise<boolean>;
+}
+interface MockForgeOptions {
+    /** Branch → a PR that already exists (so the job takes the update path). */
+    existing?: Record<string, PrRef>;
+    /** What `checksPass` returns. Default true. */
+    checks?: boolean;
+}
+/** Records every call and keeps a tiny in-memory PR store. No network. */
+declare class MockForge implements Forge {
+    private readonly opts;
+    readonly name = "mock-forge";
+    readonly calls: {
+        method: string;
+        args: Record<string, unknown>;
+    }[];
+    private readonly prs;
+    private seq;
+    constructor(opts?: MockForgeOptions);
+    viewPr(branch: string): Promise<PrRef | undefined>;
+    createPr(input: PrInput): Promise<PrRef>;
+    editPr(pr: PrRef, patch: PrPatch): Promise<void>;
+    mergePr(pr: PrRef, opts: MergeOptions): Promise<void>;
+    checksPass(): Promise<boolean>;
+}
+
+/**
+ * The core contract. Borrowing the Jenkins instinct — "everything is a job" —
+ * there is one universal runnable unit and two supporting types:
+ *
+ *   - a `Job`       — a unit of work that runs once and returns an `Outcome`.
+ *                     Any size: a single agent turn, or a whole nested loop.
+ *   - a `Condition` — a question answered against the current context (a `when`).
+ *   - a `Loop`      — produced by `loop()`, and is *itself a `Job`*.
+ *
+ * Because a `Loop` is a `Job`, a loop's `body`/`review`/any stage can be
+ * another `loop(...)`. Nesting is the absence of a special case, not a feature.
+ *
+ * The Jenkins mapping, for the parts we borrow: Job≈job/pipeline, Engine≈agent/
+ * node (where it runs), `start`≈trigger, `Condition`≈`when`, `review`+`onComplete`
+ * ≈`post`, `retry`≈`retry`/`catchError`. We deliberately do NOT import the
+ * stage/DAG machinery — the primitive here is the loop, not a pipeline.
+ */
+
+/** Terminal disposition of a `Job`. */
+type OutcomeStatus = 'pass' | 'fail' | 'aborted' | 'exhausted' | 'paused';
+/**
+ * How the run reacts to a provider rate limit, account/usage allowance, or its
+ * own token budget. `auto` (the default) waits when the reset is known and
+ * within `maxWaitMs`, else checkpoints and exits with a resume command.
+ */
+type LimitPolicy = 'auto' | 'wait' | 'exit-resume' | 'fail';
+interface Outcome {
+    status: OutcomeStatus;
+    /** 0..1 confidence, when the outcome was decided by an agent validator. */
+    confidence?: number;
+    /** One-line human summary, surfaced in the TUI and exit report. */
+    summary?: string;
+    /** Arbitrary payload threaded to the next step / surfaced to the caller. */
+    data?: unknown;
+    /** Present when `status` is driven by a failure. */
+    error?: LoopError;
+    /**
+     * A request to send work back to an earlier dag node (real-team feedback: a
+     * later stage that found a problem upstream). The enclosing `dag` re-runs `to`
+     * and its transitive dependents with `reason` threaded in as `lastReview`,
+     * bounded by `DagConfig.maxKickbacks` (default 0 — ignored). A feedback cycle
+     * is a loop boundary, not a backward edge: the graph stays acyclic and the
+     * re-run budget guarantees it terminates. Use the `kickback(to, reason)`
+     * helper to produce one.
+     */
+    kickback?: {
+        to: string;
+        reason: string;
+    };
+}
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Where a job's code lives: a working directory and (when it is a git repo) the
+ * branch checked out there. This is the substrate the commit ledger is written
+ * to and read back from. A sequential loop's iterations share one `Workspace`
+ * (the ledger accumulates on one branch); concurrency is where workspaces fork
+ * into isolated worktrees. Default: the process working directory.
+ */
+interface Workspace {
+    /** Absolute path to the working tree this job operates in. */
+    readonly dir: string;
+    /** The branch checked out in `dir`, when known (undefined on detached HEAD). */
+    readonly branch?: string;
+}
+/**
+ * Threaded into every `Job`. Carries the engine, the abort signal, the event
+ * sink, a mutable scratchpad shared across the run, the workspace the work
+ * happens in, and the position in the loop tree (used by the TUI and stats).
+ */
+interface JobContext {
+    /** Default engine for this run; overridable per-step via `resolveEngine`. */
+    readonly engine: Engine;
+    /**
+     * Resolve an engine for a step. Accepts a registered name, a ready-made
+     * `Engine` (bring-your-own provider/framework), or nothing (the run default).
+     */
+    resolveEngine(ref?: EngineRef): Engine;
+    readonly signal: AbortSignal;
+    emit(event: LoopEvent): void;
+    /** Shared mutable state for the whole run (e.g. accumulating notes). */
+    readonly state: Record<string, unknown>;
+    /** Where this job's code lives — the working dir and branch (the substrate). */
+    readonly workspace: Workspace;
+    /** The running environment for this workspace, when one is up (gate target). */
+    readonly environment?: EnvHandle;
+    /** The PR host, when one is configured — where `pullRequestJob`/`mergeJob` run. */
+    readonly forge?: Forge;
+    /** 1-based iteration index within the enclosing loop; 0 outside a loop. */
+    readonly iteration: number;
+    /** Nesting depth (root steps are 0). */
+    readonly depth: number;
+    /** Loop/step names from the root down to here. */
+    readonly path: readonly string[];
+    /** The previous body outcome in the enclosing loop (used by `review`/gates). */
+    readonly lastOutcome?: Outcome;
+    /** The most recent failed-review outcome, so a restart can act on it. */
+    readonly lastReview?: Outcome;
+    /** The run's token budget, when one is set; engine call sites guard on it. */
+    readonly budget?: Budget;
+    /** How a loop reacts to a rate/quota/budget limit. Default `auto`. */
+    readonly onLimit: LimitPolicy;
+    /** Cap on an interruptible limit-wait under `auto`/`wait`. */
+    readonly maxWaitMs: number;
+    /** Ready-to-paste command to resume a paused run, when reconstructable. */
+    readonly resumeCommand?: string;
+    log(message: string, level?: LogLevel): void;
+}
+type Job = (ctx: JobContext) => Promise<Outcome>;
+/**
+ * The introspectable shape of a `Job`, attached by the builders (`loop`, `dag`,
+ * `agentJob`, ...) and read back by `loops validate` / `loops describe` and any
+ * agent that wants to inspect a loop without running it. Held in a side table
+ * (see `core/describe.ts`), so the `Job` type stays a plain function. `kind`
+ * names the builder; the rest is builder-specific (a loop carries its gate and
+ * body, a dag carries its nodes).
+ */
+interface JobMeta {
+    kind: 'loop' | 'dag' | 'agent' | 'fn' | (string & {});
+    name?: string;
+    [key: string]: unknown;
+}
+interface ConditionResult {
+    met: boolean;
+    /** 0..1 when an agent decided this; undefined for deterministic checks. */
+    confidence?: number;
+    reason: string;
+}
+/**
+ * The single condition primitive. A question answered against the context and
+ * the most recent body outcome. Both deterministic checks and agent validators
+ * are this same type — `agentCheck(...)` simply returns one.
+ */
+type Condition = (ctx: JobContext, last: Outcome | undefined) => Promise<ConditionResult>;
+/** A bare deterministic predicate — accepted anywhere a `Condition` is. */
+type RawPredicate = (ctx: JobContext, last: Outcome | undefined) => boolean | Promise<boolean>;
+/**
+ * What a gate (`start`/`until`/`stopOn`) accepts: one item or many, freely
+ * mixing deterministic predicates and agent conditions. Arrays are reduced to
+ * the single `Condition` primitive by `toCondition` (default: all must hold;
+ * wrap in `any(...)` for or-semantics).
+ */
+type ConditionInput = Condition | RawPredicate | ConditionInput[];
+interface RetryPolicy {
+    /** On a thrown error in the body: keep looping, or end the loop as failed. */
+    onError: 'continue' | 'fail';
+    /** Cap on consecutive errored iterations before forcing 'fail'. */
+    maxConsecutive?: number;
+    backoffMs?: number;
+}
+interface LoopConfig {
+    name: string;
+    /** The work done each iteration. Pass another `loop(...)` to nest. */
+    body: Job;
+    /** Gate before iterating; one or many checks. Unmet => loop is `aborted`. */
+    start?: ConditionInput;
+    /** After each body run; one or many checks. Met => stop (then `review`). */
+    until?: ConditionInput;
+    /** Hard early-exit per iteration; one or many checks. Met => `aborted`. */
+    stopOn?: ConditionInput;
+    /** Iteration cap. Reached without passing => `exhausted`. */
+    max?: number;
+    /**
+     * Runs when `until` is met. If it returns `pass`, the loop completes.
+     * Any other status re-enters the loop — this is the "review fails, run the
+     * main loop again" behaviour, and `review` may itself be a `loop(...)`. The
+     * failed review outcome is exposed to the next iteration as `ctx.lastReview`.
+     */
+    review?: Job;
+    /**
+     * Cap on consecutive failed reviews before giving up with `exhausted`.
+     * Bounds the review-restart cycle independently of `max`; strongly advised
+     * when `review` is set with no `max` (otherwise a worker/reviewer standoff
+     * never terminates). Default: unbounded (relies on `max`).
+     */
+    maxReviewRestarts?: number;
+    /**
+     * Record a checkpoint commit when the loop converges — the milestone. A commit
+     * is a milestone, not an iteration: iterations accumulate the why in the draft,
+     * and `commitJob` composes one structured commit from it on convergence. `true`
+     * derives the subject from the converged outcome; pass a `CommitJobConfig` to
+     * set the subject/body. Off by default. Finer granularity comes from finer
+     * structure (more loops/nodes), not per-iteration commits.
+     */
+    commit?: boolean | CommitJobConfig;
+    /** Delay between iterations (polling intervals). Interruptible by abort. */
+    delayMs?: number;
+    retry?: RetryPolicy;
+    /** Side-effect hook after each iteration (logging, custom stats). */
+    onIteration?: (outcome: Outcome, ctx: JobContext) => void | Promise<void>;
+    /**
+     * Post-action run exactly once when the loop ends, whatever the status
+     * (Jenkins `post { always }`). For cleanup, notifications, final logging.
+     */
+    onComplete?: (outcome: Outcome, ctx: JobContext) => void | Promise<void>;
+}
+interface DagNode {
+    job: Job;
+    /** Names of nodes that must finish (passing) before this one runs. */
+    needs?: string[];
+    /** Gate (one or many) — when unmet the node is skipped, not failed. */
+    when?: ConditionInput;
+    /** A failure here does not fail the DAG, and does not block dependents. */
+    optional?: boolean;
+    /**
+     * Run this node in its own git worktree on a fork branch (branches-as-teams).
+     * Concurrent writers then never collide on files or the index, and the node's
+     * committed work lands back into the parent branch on pass. Defaults to the
+     * DAG's `isolation`. Opt-in: forking a worktree has a real setup cost, and a
+     * read-only node never needs it.
+     */
+    isolate?: boolean;
+    /**
+     * Restrict which upstream nodes this node may kick work back to. When set, a
+     * `kickback` whose `to` is not in this list is rejected (logged, not run); when
+     * unset, any ancestor is a valid target. A kickback to a non-ancestor is always
+     * rejected. Only consulted when the dag's `maxKickbacks` is set.
+     */
+    acceptsKickbackTo?: string[];
+}
+interface DagConfig {
+    name: string;
+    /** Node name → a `DagNode`, or a bare `Job` (shorthand for no deps/gates). */
+    nodes: Record<string, DagNode | Job>;
+    /** Max nodes running at once. Default: unbounded. */
+    concurrency?: number;
+    /** When a required node fails, abort the rest. Default: true. */
+    stopOnError?: boolean;
+    /**
+     * Default isolation for nodes that do not set `isolate`. `'worktree'` runs each
+     * such node in its own worktree + fork branch, landed back on pass. Off by
+     * default — the shared workspace.
+     */
+    isolation?: 'worktree';
+    /**
+     * Give each ISOLATED node its own environment, brought up when its worktree
+     * forks and torn down when it joins — so every branch-team gets its own stage,
+     * named by the provider from the workspace branch. Requires isolation; a
+     * non-isolated node shares the workspace and gets no per-team env.
+     */
+    environment?: Environment;
+    /**
+     * What to do when an isolated node's land-back conflicts. `'fail'` (default)
+     * fails the node honestly. `'synthesize'` runs `mergeSynthesis` — an agent
+     * resolves the conflict and writes a synthesised merge body.
+     */
+    onConflict?: 'fail' | 'synthesize';
+    /**
+     * Total re-run budget for cross-stage feedback. When a node's outcome carries
+     * a `kickback`, the dag re-runs the target node and its transitive dependents,
+     * threading the reason in as `lastReview`. Each such re-run spends one unit of
+     * this budget; once it is exhausted, a further kickback is rejected and the dag
+     * terminates. Default 0 — kickbacks are ignored and behaviour is unchanged.
+     * This bound is what makes a feedback cycle provably terminate.
+     */
+    maxKickbacks?: number;
+}
+/** Per-node disposition within a DAG run. */
+type NodePhase = 'start' | 'skip' | 'done';
+type ConditionKind = 'start' | 'until' | 'stopOn';
+type LoopEvent = {
+    kind: 'loop:start';
+    ts: number;
+    path: string[];
+    depth: number;
+    max?: number;
+} | {
+    kind: 'loop:iteration';
+    ts: number;
+    path: string[];
+    iteration: number;
+} | {
+    kind: 'loop:condition';
+    ts: number;
+    path: string[];
+    which: ConditionKind;
+    result: ConditionResult;
+} | {
+    kind: 'loop:review';
+    ts: number;
+    path: string[];
+    outcome: Outcome;
+} | {
+    kind: 'loop:end';
+    ts: number;
+    path: string[];
+    outcome: Outcome;
+    iterations: number;
+} | {
+    kind: 'limit:wait';
+    ts: number;
+    path: string[];
+    code: string;
+    waitMs: number;
+    /** Wall-clock epoch ms the wait ends at (ts + waitMs). */
+    resumeAt: number;
+} | {
+    kind: 'limit:pause';
+    ts: number;
+    path: string[];
+    code: string;
+    reason: string;
+    resumeCommand?: string;
+} | {
+    kind: 'dag:start';
+    ts: number;
+    path: string[];
+    depth: number;
+    nodes: string[];
+} | {
+    kind: 'dag:node';
+    ts: number;
+    path: string[];
+    node: string;
+    phase: NodePhase;
+    outcome?: Outcome;
+} | {
+    kind: 'dag:end';
+    ts: number;
+    path: string[];
+    outcome: Outcome;
+} | {
+    kind: 'dag:kickback';
+    ts: number;
+    path: string[];
+    from: string;
+    to: string;
+    reason: string;
+    accepted: boolean;
+    note?: string;
+} | {
+    kind: 'job:start';
+    ts: number;
+    path: string[];
+    label: string;
+} | {
+    kind: 'job:end';
+    ts: number;
+    path: string[];
+    label: string;
+    outcome: Outcome;
+} | {
+    kind: 'engine:text';
+    ts: number;
+    path: string[];
+    delta: string;
+} | {
+    kind: 'engine:thinking';
+    ts: number;
+    path: string[];
+    delta: string;
+} | {
+    kind: 'engine:tool';
+    ts: number;
+    path: string[];
+    name: string;
+    phase: 'use' | 'result';
+} | {
+    kind: 'engine:usage';
+    ts: number;
+    path: string[];
+    model: string;
+    usage: Usage;
+} | {
+    kind: 'log';
+    ts: number;
+    path: string[];
+    level: LogLevel;
+    message: string;
+} | {
+    kind: 'error';
+    ts: number;
+    path: string[];
+    message: string;
+    code: string;
+};
+
+export { commitJob as $, type AgentDef as A, type BudgetConfig as B, type ConditionInput as C, type DagConfig as D, type Environment as E, type Forge as F, GhForge as G, type OutcomeStatus as H, type PrPatch as I, type Job as J, type PrRef as K, type LoopConfig as L, type MergeOptions as M, type RetryPolicy as N, type Outcome as O, type PrInput as P, type Skill as Q, type RawPredicate as R, SUBAGENT_TOOLS as S, agentJob as T, type Usage as U, buildChecksArgs as V, type Workspace as W, buildCreateArgs as X, buildEditArgs as Y, buildMergeArgs as Z, buildViewArgs as _, type JobContext as a, defineAgent as a0, defineSkill as a1, fnJob as a2, fromFile as a3, isEngine as a4, isEnvironment as a5, isForge as a6, kickback as a7, resolveSystem as a8, type JobMeta as b, type EngineRef as c, type Condition as d, type EngineOptions as e, type Engine as f, type EngineName as g, type AgentRequest as h, type EngineEventSink as i, type AgentResult as j, type EnvHandle as k, type LoopEvent as l, type LimitPolicy as m, type AgentJobConfig as n, Budget as o, type CommitJobConfig as p, type ConditionResult as q, type DagNode as r, type EngineStreamEvent as s, type ForgeOpts as t, type GroundConfig as u, type LogLevel as v, LoopError as w, type LoopErrorCode as x, MockForge as y, type MockForgeOptions as z };