@loops-adk/core 0.1.0

package/dist/api.d.ts

@@ -0,0 +1,949 @@
+import { L as LoopConfig, J as Job, D as DagConfig, O as Outcome, a as JobContext, C as ConditionInput, b as JobMeta, c as EngineRef, W as Workspace, A as AgentDef, d as Condition, e as EngineOptions, f as Engine, g as EngineName, h as AgentRequest, U as Usage, i as EngineEventSink, j as AgentResult, E as Environment, k as EnvHandle, l as LoopEvent, F as Forge, B as BudgetConfig, m as LimitPolicy } from './types-B4wGVpqo.js';
+export { n as AgentJobConfig, o as Budget, p as CommitJobConfig, q as ConditionResult, r as DagNode, s as EngineStreamEvent, t as ForgeOpts, G as GhForge, u as GroundConfig, v as LogLevel, w as LoopError, x as LoopErrorCode, M as MergeOptions, y as MockForge, z as MockForgeOptions, H as OutcomeStatus, P as PrInput, I as PrPatch, K as PrRef, R as RawPredicate, N as RetryPolicy, S as SUBAGENT_TOOLS, Q as Skill, T as agentJob, V as buildChecksArgs, X as buildCreateArgs, Y as buildEditArgs, Z as buildMergeArgs, _ as buildViewArgs, $ as commitJob, a0 as defineAgent, a1 as defineSkill, a2 as fnJob, a3 as fromFile, a4 as isEngine, a5 as isEnvironment, a6 as isForge, a7 as kickback, a8 as resolveSystem } from './types-B4wGVpqo.js';
+
+/**
+ * The loop primitive. `loop(config)` returns a `Job`, so loops nest by simply
+ * passing one as another's `body` or `review`.
+ *
+ * Lifecycle of one loop:
+ *   1. `start` gate (one-or-many conditions) — unmet => `aborted`.
+ *   2. repeat, up to `max`:
+ *        run `body` (fresh context each turn) → `stopOn`? → `until`?
+ *        if `until` is met and there's a `review`, run it:
+ *          review `pass`  => loop completes `pass`
+ *          review !pass   => re-enter the loop  ← "review fails, run main loop again"
+ *      with no `until`, a `pass` body ends the loop; `max` reached => `exhausted`.
+ *   3. `onComplete` post-action runs once, whatever the status.
+ *
+ * The review-restart cycle is bounded: by `max` (shared with ordinary
+ * iterations) and, independently, by `maxReviewRestarts`. The failed review is
+ * threaded to the next iteration as `ctx.lastReview` so the body can act on it.
+ *
+ * Every piece of user code (conditions, the body, hooks, the review) is guarded:
+ * a throw is classified and ends the loop with `fail`, but `loop:end` and the
+ * `onComplete` post-action still run.
+ */
+
+declare function loop(config: LoopConfig): Job;
+
+/**
+ * The DAG / stages layer. `dag(config)` returns a `Job`, so it nests with
+ * `loop()` both ways. Nodes declare `needs` (dependencies); each node waits on
+ * its dependencies' promises, then runs under a shared `p-limit` concurrency
+ * gate. Cycle/missing-dep detection is delegated to `toposort` and happens
+ * before any work runs.
+ *
+ * Failure policy (ours, not the libs'):
+ *   - a required node failing blocks its dependents (they don't run);
+ *   - with `stopOnError` (default) the first required failure stops scheduling
+ *     anything not already in flight;
+ *   - `optional` nodes never fail the DAG nor block dependents;
+ *   - an unmet `when` gate *skips* the node, which counts as green.
+ */
+
+declare function dag(config: DagConfig): Job;
+/** Run jobs strictly in order; stop at the first non-pass. Sugar over `dag`. */
+declare function sequence(name: string, ...jobs: Job[]): Job;
+/** Run jobs concurrently (optionally capped); all run regardless of failures. */
+declare function parallel(name: string, jobs: Record<string, Job> | Job[], concurrency?: number): Job;
+
+/**
+ * Tournament — branch-and-select (GCC's `BRANCH` + pick-the-winner). Where a DAG
+ * fans out DISJOINT work and lands all of it, a tournament explores ALTERNATIVE
+ * approaches to the SAME task: run N candidates, each in its own isolated
+ * worktree, judge them, land only the winner and discard the rest.
+ *
+ * It is a thin composition over the worktree primitives — no new machinery. Only
+ * one branch is ever merged (the winner, off an unchanged HEAD), so there is no
+ * conflict to resolve. Small on purpose.
+ */
+
+interface TournamentConfig {
+    name: string;
+    /** Candidates to run. */
+    n: number;
+    /** Build the candidate job for attempt `i` (0-based) — same task, varied angle. */
+    candidate: (i: number) => Job;
+    /**
+     * Score a finished candidate (higher wins). Run against the candidate's own
+     * context, so it can read the candidate's workspace. The highest-scoring
+     * passing candidate lands back; ties break to the earliest.
+     */
+    judge: (outcome: Outcome, ctx: JobContext) => number | Promise<number>;
+    /** Max candidates running at once. Default `n`. */
+    concurrency?: number;
+}
+declare function tournament(config: TournamentConfig): Job;
+
+/**
+ * Job introspection. The builders register a `JobMeta` for the `Job` they return
+ * (and a short label for the conditions they build) in a side table, so a loop's
+ * shape can be read back without running it. This is what powers `loops validate`
+ * and `loops describe`: an agent authors a loop, then sees what it actually built.
+ *
+ * Kept in `WeakMap`s rather than on the function objects, so the `Job`/`Condition`
+ * types stay plain functions and nothing downstream has to know meta exists.
+ */
+
+/** Read a Job's registered shape, if it has one (a hand-written Job has none). */
+declare function jobMeta(job: Job): JobMeta | undefined;
+/** Flatten a gate input (`until`/`start`/`stopOn`) into one label per condition. */
+declare function describeConditions(input?: ConditionInput): string[];
+/**
+ * Render a `JobMeta` tree to indented lines: the loop's name and cap, its gate
+ * and convergence actions, and its body / dag nodes recursively. A Job with no
+ * meta (hand-written) renders as a single opaque line.
+ */
+declare function renderPlan(meta: JobMeta | undefined, indent?: string): string[];
+
+/**
+ * The git substrate. loops' answer to cross-iteration amnesia is to make the
+ * commit log the convergence ledger: each unit of work commits the "way" (a
+ * structured body) welded to the "what" (the diff), and the next fresh context
+ * reads the log back. This module is the thin, engine-agnostic wrapper that lets
+ * the core do that — every function takes an explicit `cwd` (the worktree dir)
+ * and never throws for an expected "no" answer.
+ *
+ * It is deliberately small: a handful of plumbing/porcelain calls over `execa`,
+ * the same subprocess primitive `commandSucceeds` already uses. No git library,
+ * no parallel state. Git is the state.
+ */
+/** One commit as the ledger sees it: the what (sha) plus the way (body). */
+interface CommitRecord {
+    sha: string;
+    /** Conventional-commit subject line. */
+    subject: string;
+    /** The structured body (the "way") — everything after the subject. */
+    body: string;
+    /** ISO author date. */
+    date: string;
+}
+interface GitOpts {
+    cwd: string;
+    signal?: AbortSignal;
+}
+/** True when `cwd` is inside a git work tree. Never throws. */
+declare function isRepo(opts: GitOpts): Promise<boolean>;
+/** The checked-out branch name, or undefined on a detached HEAD / non-repo. */
+declare function currentBranch(opts: GitOpts): Promise<string | undefined>;
+/** The HEAD commit sha, or undefined when the branch has no commits yet. */
+declare function headSha(opts: GitOpts): Promise<string | undefined>;
+/** Stage every change in the work tree (`git add -A`). */
+declare function stageAll(opts: GitOpts): Promise<void>;
+/** True when there is something staged to commit. */
+declare function hasStagedChanges(opts: GitOpts): Promise<boolean>;
+/** True when the work tree (staged or unstaged) has any change. */
+declare function isDirty(opts: GitOpts): Promise<boolean>;
+interface CommitInput {
+    subject: string;
+    /** The structured body — the "way". Joined to the subject with a blank line. */
+    body?: string;
+    /** Commit even with an empty index (default false). */
+    allowEmpty?: boolean;
+}
+/**
+ * Commit the staged index. The message is passed on stdin (`-F -`) so an
+ * arbitrarily-shaped body never has to survive shell escaping. The repo's
+ * configured author is used — loops never sets an author or a co-author trailer.
+ * Returns the new sha, or undefined when there was nothing to commit and
+ * `allowEmpty` was not set.
+ */
+declare function commit(input: CommitInput, opts: GitOpts): Promise<string | undefined>;
+interface LogQuery extends GitOpts {
+    /** Exclusive lower bound: only commits after this ref (e.g. the loop start). */
+    since?: string;
+    /** Cap the number of commits returned (most recent first). */
+    max?: number;
+    /** The ref to read (default HEAD) — e.g. a fork branch's own line of work. */
+    ref?: string;
+}
+/**
+ * Read the ledger: recent commits, newest first, each with its body (the way).
+ * `since` gives the "this run only" window the loop grounds the next iteration
+ * on; `max` bounds it so the ledger never re-rots the fresh context.
+ */
+declare function log(query: LogQuery): Promise<CommitRecord[]>;
+interface WorktreeHandle {
+    /** The isolated working directory. */
+    dir: string;
+    /** The branch checked out there. */
+    branch: string;
+}
+/**
+ * Fork an isolated worktree on a new branch from `base` (default HEAD). This is
+ * how a concurrency boundary becomes a team: each concurrent writer gets its own
+ * working dir and branch, so siblings never collide on files or the index.
+ */
+declare function addWorktree(repoDir: string, opts: {
+    branch: string;
+    base?: string;
+    signal?: AbortSignal;
+}): Promise<WorktreeHandle>;
+/** Remove a worktree (force-discards anything uncommitted left in it). */
+declare function removeWorktree(repoDir: string, dir: string, opts?: {
+    signal?: AbortSignal;
+}): Promise<void>;
+/** Delete a branch ref (used to clean up a merged fork branch). */
+declare function deleteBranch(repoDir: string, branch: string, opts?: {
+    signal?: AbortSignal;
+}): Promise<void>;
+interface MergeResult {
+    ok: boolean;
+    conflict: boolean;
+}
+/**
+ * Land a fork branch back into the branch checked out at `repoDir`, preserving
+ * the team shape (`--no-ff`). On conflict the merge is aborted so the target
+ * stays clean and the caller can fail the node honestly — loops does not
+ * auto-resolve (a merge-resolver is a separate, later layer).
+ */
+declare function mergeBranch(repoDir: string, branch: string, opts?: {
+    signal?: AbortSignal;
+    message?: string;
+}): Promise<MergeResult>;
+/**
+ * Begin a `--no-ff --no-commit` merge WITHOUT aborting on conflict, so a resolver
+ * can synthesise the result. `clean` means it merged cleanly (staged, ready to
+ * commit); otherwise `conflicted` lists the unresolved paths (with markers).
+ */
+declare function mergeNoCommit(repoDir: string, branch: string, opts?: {
+    signal?: AbortSignal;
+}): Promise<{
+    clean: boolean;
+    conflicted: string[];
+}>;
+/** Paths with unresolved merge conflicts. */
+declare function conflictedFiles(repoDir: string, opts?: {
+    signal?: AbortSignal;
+}): Promise<string[]>;
+/** Abort an in-progress merge. */
+declare function mergeAbort(repoDir: string, opts?: {
+    signal?: AbortSignal;
+}): Promise<void>;
+interface PushOptions extends GitOpts {
+    /** The remote to push to. Default `origin`. */
+    remote?: string;
+    /** The branch to push. Default the branch checked out at `cwd`. */
+    branch?: string;
+    /** Set the upstream tracking ref (`-u`). Default true. */
+    setUpstream?: boolean;
+    /** Force-with-lease the push. Default false. */
+    force?: boolean;
+}
+interface PushResult {
+    ok: boolean;
+    /** The combined git output, surfaced on failure (no remote, rejected, etc.). */
+    output: string;
+}
+/**
+ * Push the branch to a remote — the one place loops reaches past the local
+ * substrate. Honest like the rest of this module: a non-zero exit (no remote, a
+ * rejected non-fast-forward, no upstream) comes back as `{ ok: false, output }`
+ * for the caller to surface, never a throw. `--force-with-lease` is the only
+ * force offered, so a force push still refuses to clobber unseen remote work.
+ */
+declare function push(opts: PushOptions): Promise<PushResult>;
+
+/**
+ * Merge as synthesis (GCC's `MERGE`). A raw `git merge` either applies cleanly or
+ * fails on conflict. `mergeSynthesis` does the thing a teammate does: when two
+ * lines of work collide, an agent RESOLVES each conflicted file coherently
+ * (preserving both intents), and the merge commit body is a SYNTHESIS of what the
+ * two branches were each trying to do — not "merge branch X".
+ *
+ * It is text-in/text-out, so it works through any `Engine` (no tool-use needed):
+ * the conflicted file content goes in, the resolved content comes back. Light: a
+ * call per conflicted file plus one for the synthesis body, and nothing when the
+ * merge is already clean. The merge is aborted if resolution throws, so the target
+ * is never left half-merged.
+ */
+
+interface MergeSynthesisConfig {
+    /** The branch to land into the current workspace. */
+    branch: string;
+    /** Conventional subject for the merge commit. */
+    message?: string;
+    engine?: EngineRef;
+    model?: string;
+}
+interface MergeSynthesisResult {
+    ok: boolean;
+    /** Whether a conflict had to be resolved. */
+    conflict: boolean;
+    sha?: string;
+}
+declare function mergeSynthesis(ctx: JobContext, config: MergeSynthesisConfig): Promise<MergeSynthesisResult>;
+
+/**
+ * Pull-request jobs — how a converged branch becomes a PR whose body stays a
+ * faithful synthesis of the work, so the commit-log memory survives a squash merge.
+ *
+ * The squash-merge problem: a branch carries N milestone commits, each with a rich
+ * structured "way" (the Ledger). A squash merge collapses them into one commit whose
+ * body GitHub defaults to a list of subject lines — the reasoning is lost from the
+ * base branch's history. The fix is small because loops already folds many commit
+ * bodies into one: `pullRequestJob` sets the PR body to `consolidate(since: base)` —
+ * the same decision-preserving fold, scoped to this branch — and keeps it current.
+ * `mergeJob` can then squash with that synthesis as the commit body directly.
+ *
+ * Engine-agnostic and host-agnostic: the host is the injectable `Forge` seam
+ * (default `GhForge`), so these jobs run offline against a `MockForge` in tests.
+ */
+
+type Derive<T> = T | ((ctx: JobContext, last: Outcome | undefined) => T | Promise<T>);
+interface PushJobConfig {
+    label?: string;
+    /** Remote to push to. Default `origin`. */
+    remote?: string;
+    /** Branch to push. Default the workspace branch. */
+    branch?: string;
+    /** Set upstream tracking. Default true. */
+    setUpstream?: boolean;
+    /** Force-with-lease. Default false. */
+    force?: boolean;
+}
+/** Push the work branch to its remote. Idempotent; a rejected push fails honestly. */
+declare function pushJob(config?: PushJobConfig): Job;
+interface PullRequestJobConfig {
+    label?: string;
+    /** PR title, or a function of context. Default: the converged outcome summary. */
+    title?: Derive<string>;
+    /** Base branch to merge into, and the `since` bound for the body fold. Default `main`. */
+    base?: string;
+    /** Push the branch first (idempotent). Default true; pass a config to tune. */
+    push?: boolean | PushJobConfig;
+    /** Open as a draft when first created. */
+    draft?: boolean;
+    /** Model for the body consolidation call. */
+    model?: string;
+    /** Max milestones to fold into the body. Default 50. */
+    max?: number;
+    /** Override the synthesized body (else: consolidate the branch's commit bodies). */
+    body?: Derive<string>;
+}
+/**
+ * Raise the PR, or update it if it already exists, with a body synthesized from the
+ * branch's commit bodies. Idempotent create-or-update: run it after each milestone
+ * (or at convergence) and the PR description stays current — that is what keeps the
+ * eventual squash body honest. Returns the `PrRef` in `outcome.data.pr`.
+ */
+declare function pullRequestJob(config?: PullRequestJobConfig): Job;
+interface MergeJobConfig {
+    label?: string;
+    /** Base branch — the `since` bound for re-synthesizing the squash body. Default `main`. */
+    base?: string;
+    /** Squash merge (default true) — the whole reason this exists. */
+    squash?: boolean;
+    /**
+     * Hand the merge to GitHub auto-merge (`gh pr merge --auto`): it lands once the
+     * required checks pass. The recommended "merge when CI is green" path — non-blocking.
+     */
+    auto?: boolean;
+    /** Delete the head branch after merge. */
+    deleteBranch?: boolean;
+    /** Squash commit subject. */
+    subject?: Derive<string>;
+    /** Squash commit body. Default: re-consolidate the branch (the up-to-date synthesis). */
+    body?: Derive<string>;
+    model?: string;
+    max?: number;
+    /**
+     * A gate that must hold before loops issues the merge — e.g. `forgeChecks()` for a
+     * synchronous "CI is green" check, or any `Condition`. Unmet → the job fails without
+     * merging. (For the non-blocking path, prefer `auto: true` and let GitHub gate.)
+     */
+    when?: ConditionInput;
+}
+/**
+ * Squash-merge the branch's PR with a body synthesized from its commit bodies — so the
+ * one commit that lands on the base branch carries the whole "way", not a list of
+ * subjects. Opt-in (loops performing an outward merge is high-stakes): gate it with
+ * `auto: true` (GitHub merges when checks pass) and/or a `when` condition.
+ */
+declare function mergeJob(config?: MergeJobConfig): Job;
+
+/**
+ * `isolated(job)` — run any Job in its own git worktree on a fork branch, and land
+ * its work back into the parent branch on pass. The concurrency boundary as a Job
+ * WRAPPER, not a node type.
+ *
+ * dag nodes can already fork a worktree (`isolation: 'worktree'`), but that only
+ * works for predeclared nodes. A Tend loop dispatches DYNAMICALLY — it discovers
+ * each ticket at runtime and routes it to the right shape of sub-loop — and each
+ * dispatch wants its own isolated worktree so parallel tickets never collide on
+ * files or the index. `isolated()` makes that composable: wrap the dispatched Job.
+ *
+ * On pass: any uncommitted remainder is committed in the worktree, then the fork
+ * branch merges back (`--no-ff`). Land-back merges are serialised across all
+ * `isolated()` jobs in the process, so concurrent dispatch cannot race the parent
+ * index/HEAD. A conflict fails honestly, or is synthesised when asked. The worktree
+ * is always removed; a cleanly-merged fork branch is deleted. A non-repo workspace
+ * degrades to running in place (a warning, no isolation).
+ *
+ * NOTE: dag's own runNodeJob holds parallel worktree/land-back logic (plus per-team
+ * environments). The two should be unified — dag delegating to `isolated()` — once
+ * `isolated()` grows environment support; until then the land-back logic lives in
+ * both deliberately, to avoid destabilising the dag path.
+ */
+
+interface IsolatedOptions {
+    /** Label for the fork branch and the child path. Default 'isolated'. */
+    label?: string;
+    /** On a land-back conflict: 'fail' (default) or 'synthesize'. */
+    onConflict?: 'fail' | 'synthesize';
+}
+/** Wrap a Job so it runs in an isolated worktree and lands back on pass. */
+declare function isolated(job: Job, opts?: IsolatedOptions): Job;
+
+/**
+ * The scratch files (`.loops/`) — two transient write-ahead buffers that carry a
+ * unit of work's memory forward, split by AUDIENCE:
+ *
+ * - `ledger.md` is WORKING MEMORY, for the agent(s) doing the work NOW. Verbose and
+ *   real-time: the running log of what is being tried, for the agent itself and for
+ *   any concurrent peers fanned out on the same team. The harness appends to it
+ *   automatically after each turn (auto-capture), so the why is recorded even when a
+ *   single agent's context decays or no one holds all the reasoning at the end.
+ *
+ * - `prompt.md` is the HANDOFF, for the NEXT agent(s). Distilled and curated: the
+ *   why, what was ruled out, the constraints, what is left. Grounding injects it
+ *   into the next context as the start of its prompt; `commitJob` crystallises it
+ *   into the commit body (alongside a compacted ledger). Same artifact, two stages.
+ *
+ * The commit body is `prompt.md` + a compacted `ledger.md`, welded to its diff — and
+ * it does not expire at the next turn. It is a permanent record in git history that
+ * ANY later agent can look back to, as far back as it wants: recent-N grounding
+ * surfaces the nearby ones, retrieval selects the relevant ones however old, and an
+ * agent can always walk the log itself. Each one says "here is how to reason about
+ * this snapshot of changes" — the why, what was ruled out, the constraints, and what
+ * the implementer actually did. Both files reset once the commit lands (crystallise,
+ * then reset); the record they became lives on in the history.
+ *
+ * The whole `.loops/` dir is kept out of git (self-managed `.gitignore`), so
+ * `commitJob`'s `git add -A` never stages either file. The files are the draft; the
+ * commit is the record.
+ */
+
+/** Absolute path to a workspace's working memory (`ledger.md`). */
+declare function ledgerPath(workspace: Workspace): string;
+/** Absolute path to a workspace's handoff (`prompt.md`, the staged commit body). */
+declare function promptPath(workspace: Workspace): string;
+/**
+ * Guarantee `.loops/.gitignore` ignores everything, so neither scratch file is ever
+ * staged — even if an agent wrote one directly rather than through these helpers.
+ * No-op when `.loops/` does not exist.
+ */
+declare function ensureIgnored(workspace: Workspace): void;
+interface PromptNote {
+    /** Optional section heading (Why / Alternatives / Constraints / Next…). */
+    heading?: string;
+    /** The reasoning to record — the "why". */
+    body: string;
+    /** Who recorded it, so a fanned-out team's why stays attributable. */
+    author?: string;
+}
+/**
+ * Append a note to the handoff. Durable and append-only: many agents on one team
+ * add to the same handoff as they work, and the order is preserved. Uses an
+ * O_APPEND write, so concurrent appends do not clobber each other.
+ */
+declare function appendPrompt(workspace: Workspace, note: PromptNote | string): void;
+/** Read the handoff, or '' when nothing has been drafted. */
+declare function readPrompt(workspace: Workspace): string;
+/** Clear the handoff at the commit boundary (the atomicity rule: then reset). */
+declare function resetPrompt(workspace: Workspace): void;
+interface LedgerEntry {
+    /** The job/agent label for the turn. */
+    label?: string;
+    /** The iteration number, when inside a loop. */
+    iteration?: number;
+    /** The agent's own reasoning text for the turn. */
+    text?: string;
+    /** Tool actions taken this turn, pre-summarised (e.g. `['Edit×2', 'Bash']`). */
+    tools?: string[];
+}
+/**
+ * Append a turn to the working memory. This is the auto-capture sink: the harness
+ * records each grounded turn here (reasoning + a summary of actions), and agents can
+ * jot their own notes too. Append-only and O_APPEND, so concurrent peers don't
+ * clobber each other.
+ */
+declare function appendLedger(workspace: Workspace, entry: LedgerEntry | string): void;
+/** Read the working memory, or '' when nothing has been logged. */
+declare function readLedger(workspace: Workspace): string;
+/** Clear the working memory at the commit boundary. */
+declare function resetLedger(workspace: Workspace): void;
+
+/**
+ * The read side — grounding. Where the draft carries the within-iteration why,
+ * grounding carries the cross-iteration memory: before a fresh context does
+ * work, it reads the recent commit log so it knows what prior iterations already
+ * tried and why, and does not re-walk a dead end. This is the half of the
+ * fresh-context bet that kills amnesia (the other half being that fresh context
+ * kills rot).
+ *
+ * The reach is deliberately BRANCH-LOCAL. `git log` on the current branch is the
+ * committed truth of this line of work; adjacent active branches are in-flight
+ * and may never land, so grounding on them feeds the agent premises that can
+ * vanish. When a sibling team's work matters, it lands back into this line and
+ * grounding then picks it up naturally — the merge is where work becomes shared
+ * truth. Cross-branch awareness, if ever wanted, is a separate, thin, opt-in
+ * signal, not this read.
+ */
+
+interface GroundOptions {
+    /**
+     * Exclusive lower bound: only commits after this ref. Pass the loop's start
+     * ref to scope the ledger to "this run". Omitted reads recent branch history.
+     */
+    since?: string;
+    /** Max commits to include (newest first). Default 10. */
+    max?: number;
+    /** Truncate each commit body to this many chars, so the ledger never re-rots
+     *  the fresh context. Default 1200. */
+    bodyChars?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Render the recent ledger as a prompt block for the next fresh context. Returns
+ * '' when there is nothing yet (a first iteration on a fresh branch), so callers
+ * can prepend it unconditionally. Newest commit first.
+ */
+declare function groundingText(workspace: Workspace, opts?: GroundOptions): Promise<string>;
+interface RetrieveOptions {
+    /** The task/intent to find relevant prior commits for. */
+    intent: string;
+    /**
+     * The recall window: how many recent commits to offer the selector as
+     * candidates. A relevant commit OLDER than this is invisible — retrieval is not
+     * unbounded, it just has a bigger window than recent-N. Reading subjects is
+     * cheap, so this can be generous. For a log longer than any practical window,
+     * run consolidation: the consolidated-ledger commit stays in-window and indexes the
+     * old history. Default 100.
+     */
+    candidates?: number;
+    /** Max commits to inject. Default 8. */
+    max?: number;
+    /** Truncate each injected body. Default 1200. */
+    bodyChars?: number;
+    /** Engine for the (cheap) selection call. Default the run engine. */
+    engine?: EngineRef;
+    /** Model for the selection call (a small one is plenty). */
+    model?: string;
+}
+/**
+ * Render only the prior commits a cheap model judges relevant to `intent`.
+ * Returns '' when nothing is on the branch or nothing is judged relevant.
+ */
+declare function retrieveLedger(ctx: JobContext, opts: RetrieveOptions): Promise<string>;
+
+/**
+ * Consolidation — the "sleep-time" step (Letta's reflection, DiffMem's consolidate).
+ * A long run accumulates many milestone commits; consolidation folds them into one
+ * bounded CONSOLIDATED LEDGER: the current state, the open threads, and every binding
+ * decision preserved. It is the COARSE tier of the ledger — `ledger.md` is the fine
+ * tier and the milestone commit bodies are the mid tier, so multi-granularity falls
+ * out of git rather than a new artifact to maintain.
+ *
+ * It is decision-PRESERVING, not a progress summary: a fresh context must be able to
+ * honour every convention and constraint the project settled, so consolidation keeps
+ * exact values verbatim while dropping narrative. (A naive summary that compresses
+ * the decisions away lets downstream work silently violate them — measured: top-k
+ * retrieval and a progress summary both miss accrued decisions; only a decision-
+ * preserving ledger keeps them in bounded space.)
+ *
+ * The consolidated ledger is a COMMIT BODY, not a tracked file — the same shape as
+ * every other memory in loops (welded to a diff, read back by grounding). Each
+ * consolidation commits the updated ledger as the body of an empty-tree commit, so
+ * grounding and retrieval surface it like any milestone; the prior ledger is read
+ * back from the last consolidation commit's body. One model call that MERGES new
+ * commits into the prior ledger, not a changelog.
+ */
+
+interface ConsolidateOptions {
+    /** Recent milestones to fold in. Default 30. */
+    max?: number;
+    /**
+     * Exclusive lower bound — fold only commits after this ref (e.g. the base
+     * branch). This scopes the fold to one line of work, exactly the set a squash
+     * merge collapses, so the consolidation can stand in as the squash body.
+     */
+    since?: string;
+    /** The consolidated ledger so far, to update in place. */
+    prior?: string;
+    /** Engine for the (one) consolidation call. Default the run engine. */
+    engine?: EngineRef;
+    model?: string;
+}
+/**
+ * Fold the recent history into one decision-preserving consolidated ledger (a single
+ * model call). Returns the ledger text; the caller decides where it lives (see
+ * `consolidateJob`). Each commit is offered as its subject plus a body digest, so the
+ * exact decisions — not just the headings — reach the consolidation.
+ */
+declare function consolidate(ctx: JobContext, opts?: ConsolidateOptions): Promise<string>;
+interface CompactOptions {
+    engine?: EngineRef;
+    model?: string;
+    /**
+     * The size budget for the working log in the commit body. A log already within
+     * it is kept VERBATIM (no model call); only a longer one is compacted, with this
+     * as the truncation fallback. Default 2000.
+     */
+    maxChars?: number;
+}
+/**
+ * Compress a verbose working log (the ledger) into a tight summary for the commit
+ * body — one cheap model call. A short log (already within `maxChars`) is kept
+ * verbatim: compaction only earns its keep on a long log, and summarising a few
+ * lines just risks dropping the faithful "way" the commit body exists to preserve.
+ * Falls back to truncation when there is no usable reply or the call throws, so a
+ * commit never fails on compaction. '' in, '' out.
+ */
+declare function compactLedger(ctx: JobContext, text: string, opts?: CompactOptions): Promise<string>;
+/**
+ * Compose the commit body — the handoff: everything the next agent needs if it lost all
+ * memory of this work. Two sources, in order: the agent's OWN handoff (captured verbatim by
+ * the handoff contract into `prompt.md`), else a structured handoff DISTILLED from the
+ * working log. The second path is the guarantee — loops owns the commit step, so a terse,
+ * instruction-skipping agent still leaves a rich, structured record rather than a bare
+ * "done". Returns '' only when there is nothing at all, so callers fall back to their floor.
+ */
+declare function composeCommitBody(ctx: JobContext, workspace: Workspace, opts?: CompactOptions): Promise<string>;
+interface ConsolidateJobConfig extends ConsolidateOptions {
+    label?: string;
+    /** Commit subject; also how the prior ledger is found. Default `consolidate: ledger`. */
+    subject?: string;
+}
+/**
+ * Consolidate and commit the CONSOLIDATED LEDGER as a commit body. Reads the prior
+ * ledger from the last consolidation commit's body, folds in the recent history, and
+ * commits the updated ledger as the body of an empty-tree commit — so the coarse
+ * memory is durable and grounded-on like any milestone, never a tracked file.
+ */
+declare function consolidateJob(config?: ConsolidateJobConfig): Job;
+
+/**
+ * Conditions answer a yes/no question against the run context and the latest
+ * body outcome. They power a loop's `start`, `until`, and `stopOn` gates.
+ *
+ * Two flavours, same type:
+ *   - deterministic (`predicate`, `bodyPassed`, `maxConfidence`)
+ *   - agent-validated (`agentCheck`) — a small model returns a verdict +
+ *     confidence, and the gate opens only above a threshold.
+ *
+ * `gateJob` lifts any Condition into a `Job`, so a reviewer can be expressed
+ * as a condition and still slot into `loop({ review })`.
+ */
+
+/**
+ * Coerce any `ConditionInput` — a `Condition`, a bare predicate, or an array
+ * mixing both — into the single `Condition` primitive. This is what lets
+ * `until`/`start`/`stopOn` accept one or many items of either flavour.
+ *
+ * Arrays default to `all` (every item must hold); pass `'any'` for or-semantics.
+ */
+declare function toCondition(input: ConditionInput, combine?: 'all' | 'any'): Condition;
+/** Deterministic predicate over context + last outcome. */
+declare function predicate(fn: (ctx: JobContext, last: Outcome | undefined) => boolean | Promise<boolean>, reason?: string): Condition;
+/** Met when the most recent body outcome passed. */
+declare function bodyPassed(): Condition;
+/** Met when the last outcome carries confidence at or above `threshold`. */
+declare function minConfidence(threshold: number): Condition;
+/**
+ * Deterministic gate that runs a shell command and is met on exit code 0. This
+ * is the honest convergence signal for coding loops: pair it with an `agentCheck`
+ * in an `until` array so the loop stops only when the tests ACTUALLY pass AND a
+ * judge agrees the work matches intent — never on a model's self-report alone.
+ * Runs in `cwd` (default: the process working dir), inherits the run's abort
+ * signal, and never throws (a spawn failure counts as "not met").
+ */
+declare function commandSucceeds(command: string, args?: string[], opts?: {
+    cwd?: string;
+    timeoutMs?: number;
+}): Condition;
+/**
+ * True when the branch's open PR has all required checks green — a synchronous
+ * "CI is green" gate over the `Forge`. Use it as `mergeJob`'s `when`, or anywhere a
+ * `Condition` is taken, for the blocking path; prefer `mergeJob({ auto: true })` to
+ * hand the same gate to GitHub non-blockingly. No PR / no branch → not met.
+ */
+declare function forgeChecks(): Condition;
+declare const always: Condition;
+declare const never: Condition;
+declare function not(c: ConditionInput): Condition;
+/** Met only when every input holds (short-circuits on the first failure). */
+declare function all(...inputs: ConditionInput[]): Condition;
+/** Met when any input holds (short-circuits on the first success). */
+declare function any(...inputs: ConditionInput[]): Condition;
+/**
+ * Met when at least `k` of the inputs hold. The honest hedge against a single
+ * agent judge's self-reported confidence: ask N independent judges and require a
+ * quorum (e.g. `quorum(2, j, j, j)`). All inputs run in parallel; a judge that
+ * throws counts as a "no" vote rather than sinking the whole gate. Each input
+ * may hit a model, so size N with cost in mind. Reported confidence is the mean
+ * of the holding inputs' confidences.
+ */
+declare function quorum(k: number, ...inputs: ConditionInput[]): Condition;
+interface AgentCheckConfig {
+    /** The yes/no question the validator must answer. */
+    question: string;
+    /** Open the gate only at/above this confidence (0..1). Default 0.8. */
+    threshold?: number;
+    /** Small/cheap model recommended. A bare string — provider-agnostic. */
+    model?: string;
+    /**
+     * Give the judge a persona — an `AgentDef` whose resolved system (persona +
+     * skills) is prepended to the validator's scoring instructions, so a reviewer
+     * can be a named specialist (e.g. an adversarial reviewer) instead of an
+     * anonymous yes/no. The validator's output contract stays authoritative (it
+     * comes last); `model` falls back to the agent's `model`. Mirrors `agentJob`.
+     */
+    agent?: AgentDef;
+    /** Engine for validation: a registered name, your own `Engine`, or default. */
+    engine?: EngineRef;
+    /**
+     * What the validator sees. By default: the last outcome's summary/data plus
+     * the shared state. Override to feed something bespoke — may be async, since a
+     * judge often gathers evidence (read the artifact, ground on the history, run a
+     * probe) before ruling. A blind judge cannot honestly confirm correctness, so
+     * give it the thing it is meant to be reviewing.
+     */
+    context?: (ctx: JobContext, last: Outcome | undefined) => string | Promise<string>;
+    maxTokens?: number;
+    /**
+     * Score these named dimensions (0..1 each) instead of a single yes/no
+     * confidence. The gate opens when the GEOMETRIC MEAN of the scores is
+     * >= `threshold`, so one weak dimension drags the whole verdict down. A more
+     * honest judge than a lone self-reported number, e.g.
+     * `['intent match', 'evidence quality', 'outcome coherence']`.
+     */
+    dimensions?: string[];
+    /**
+     * Parse a free-form review that closes with `<confidence>N%</confidence>`
+     * (N is 0-100) instead of forcing a JSON shape. The gate opens at/above
+     * `threshold`; the reviewer's prose before the tag becomes the gate's `reason`,
+     * so a failing review carries its findings to the next iteration (`lastReview`).
+     * More robust than scraping JSON, and the natural fit for a report-then-rate
+     * reviewer persona. Takes precedence over `dimensions`.
+     */
+    confidenceTag?: boolean;
+}
+/**
+ * A Condition decided by a (preferably small) model. With a single yes/no
+ * question the gate opens when the verdict is "yes" AND confidence >= threshold.
+ * With `dimensions`, the model scores each dimension 0..1 and the gate opens
+ * when their geometric mean >= threshold — a more honest judge than one number.
+ */
+declare function agentCheck(config: AgentCheckConfig): Condition;
+/**
+ * Lift a Condition (or one-or-many `ConditionInput`) into a Job: `pass` when
+ * met, `fail` otherwise. This is how a reviewer becomes a drop-in `review` job
+ * (`gateJob('review', agentCheck(...))`).
+ */
+declare function gateJob(label: string, condition: ConditionInput): Job;
+
+/**
+ * The engine registry — the drop-in mechanism. Built-ins are registered by
+ * name; anyone can `register(name, factory)` their own, or pass a ready-made
+ * `Engine` instance anywhere an `EngineRef` is accepted. Factories run lazily
+ * (on first `create`), so the Anthropic API engine never needs a key unless you
+ * actually select it.
+ */
+
+type EngineFactory = (opts: EngineOptions) => Engine;
+declare class EngineRegistry {
+    private readonly opts;
+    private readonly factories;
+    private readonly cache;
+    constructor(opts?: EngineOptions);
+    /** Add or override an engine. The key is what you pass as an `EngineRef`. */
+    register(name: string, factory: EngineFactory): this;
+    has(name: string): boolean;
+    names(): string[];
+    /** Resolve a ref to an `Engine`: instance → as-is; name → built/cached. */
+    create(ref: EngineRef | undefined, fallback: EngineName): Engine;
+    private registerBuiltins;
+}
+
+/**
+ * A scripted, offline engine — the reference "drop-in". It implements the same
+ * `Engine` interface as the real backends, so tests and examples run the exact
+ * same loop/dag/condition code paths with zero network. Writing one of these is
+ * all it takes to add a provider: implement `run`, register a name.
+ */
+
+type MockResponder = (req: AgentRequest) => string | {
+    text: string;
+    usage?: Usage;
+    model?: string;
+};
+declare class MockEngine implements Engine {
+    private readonly responder;
+    readonly name = "mock";
+    constructor(responder: MockResponder);
+    run(req: AgentRequest, onEvent: EngineEventSink, signal: AbortSignal): Promise<AgentResult>;
+}
+/** Convenience: always reply with a verdict JSON (handy for validator tests). */
+declare function mockVerdict(verdict: 'yes' | 'no', confidence: number, reason?: string): MockEngine;
+
+/**
+ * A scripted, offline environment — the reference Environment "drop-in", mirror
+ * of `MockEngine`. It simulates a deploy (hands back a URL + env vars, counts
+ * up/down) with zero network, so the lifecycle binding and gate integration run
+ * the exact same code paths in tests as a real sst/Vercel adapter would.
+ */
+
+interface MockEnvOptions {
+    /** The URL to hand back. A function derives it from the workspace (branch). */
+    url?: string | ((ws: Workspace) => string);
+    /** Extra env vars to inject alongside `BASE_URL`. */
+    env?: Record<string, string>;
+    onUp?: (ws: Workspace) => void;
+    onDown?: () => void;
+}
+declare class MockEnvironment implements Environment {
+    private readonly opts;
+    readonly name = "mock-env";
+    upCount: number;
+    downCount: number;
+    constructor(opts?: MockEnvOptions);
+    up(workspace: Workspace): Promise<EnvHandle>;
+}
+
+/**
+ * Stats collector. Subscribes to the event stream and accumulates everything
+ * the TUI footer and the exit summary need: per-loop iteration counts, review
+ * pass/fail tallies, token usage by model, errors, and wall-clock timing.
+ */
+
+interface LoopStat {
+    path: string;
+    iterations: number;
+    reviewsPassed: number;
+    reviewsFailed: number;
+    lastStatus?: Outcome['status'];
+}
+interface ModelUsage {
+    model: string;
+    calls: number;
+    inputTokens: number;
+    outputTokens: number;
+}
+interface ErrorEntry {
+    path: string;
+    code: string;
+    message: string;
+    ts: number;
+}
+interface StatsSnapshot {
+    startedAt: number;
+    elapsedMs: number;
+    loops: LoopStat[];
+    models: ModelUsage[];
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    agentCalls: number;
+    errors: ErrorEntry[];
+}
+declare class Stats {
+    private readonly startedAt;
+    private readonly loops;
+    private readonly models;
+    private readonly errors;
+    record(event: LoopEvent): void;
+    snapshot(): StatsSnapshot;
+    private loopFor;
+    private modelFor;
+}
+
+/**
+ * The runner assembles a `JobContext` and executes a root `Job` (a loop, a dag,
+ * or any job). It owns the engine registry, the abort controller, the shared
+ * state, and the stats collector. Reporters/TUI observe via `onEvent`.
+ */
+
+/**
+ * Exit code for a `paused` run: EX_TEMPFAIL (sysexits.h). Distinct from `fail`
+ * (1) so a wrapper/cron can tell "paused, resumable" from "failed".
+ */
+declare const EXIT_PAUSED = 75;
+interface RunOptions {
+    /** Default engine selected when a job/condition names none. Default agent-sdk. */
+    engine?: EngineName;
+    engineOptions?: EngineOptions;
+    /** Register custom engines (drop-in): name → factory or ready-made instance. */
+    engines?: Record<string, EngineFactory | Engine>;
+    /** External abort signal (the CLI wires SIGINT + keypress here). */
+    signal?: AbortSignal;
+    /** Root working directory the run operates in. Default: process.cwd(). */
+    cwd?: string;
+    /**
+     * Bring an environment up for the run (the root workspace) before the job, and
+     * tear it down after — so the gate can test the running thing. The adapter
+     * (sst, Vercel, …) is yours; loops owns only the seam. Per-team environments
+     * at the worktree boundary are a separate, later binding.
+     */
+    environment?: Environment;
+    /**
+     * The PR host for `pushJob`/`pullRequestJob`/`mergeJob`. Default: `GhForge`
+     * (the `gh` CLI) when a job needs one. Pass a `MockForge` to run offline.
+     */
+    forge?: Forge;
+    onEvent?: (event: LoopEvent) => void;
+    /** Seed the shared, mutable run state. */
+    state?: Record<string, unknown>;
+    /**
+     * Cap total tokens (input + output) for the run. A bare number is the limit;
+     * pass `{ limit, headroom?, soft? }` for headroom or warn-don't-refuse mode.
+     * Engine call sites refuse to spend past it (see `Budget`).
+     */
+    budget?: number | BudgetConfig;
+    /** Append every structured event as JSONL here — a readable run record. */
+    recordTo?: string;
+    /** Snapshot the shared run state here at each loop/dag/job boundary. */
+    checkpoint?: string;
+    /** Restore shared run state written by a prior `checkpoint` before starting. */
+    resumeFrom?: string;
+    /**
+     * How a loop reacts to a rate limit / quota / token budget. Default `auto`:
+     * wait out a known reset within `maxWaitMs`, else checkpoint and exit with a
+     * resume command (the `paused` status, exit code 75). `wait` waits any known
+     * reset with no ceiling; `exit-resume` never waits; `fail` is the old fatal
+     * behaviour.
+     */
+    onLimit?: LimitPolicy;
+    /** Ceiling on a single interruptible limit-wait, in ms. Default 300000. */
+    maxWaitMs?: number;
+    /**
+     * Ready-to-paste command to resume a paused run, surfaced to reporters and the
+     * `limit:pause` event. The CLI reconstructs this from the invocation.
+     */
+    resumeCommand?: string;
+}
+interface RunResult {
+    outcome: Outcome;
+    stats: StatsSnapshot;
+    /** Final token accounting, when a budget was set. */
+    budget?: {
+        limit: number;
+        spent: number;
+        remaining: number;
+    };
+}
+declare function run(job: Job, options?: RunOptions): Promise<RunResult>;
+/** Process exit code mapped from a terminal outcome. */
+declare function exitCodeFor(outcome: Outcome): number;
+
+/**
+ * Public API. A loop-definition file imports from here and `export default`s a
+ * `Job` (usually a `loop(...)` or `dag(...)`). The CLI runs that default export.
+ *
+ *   import { loop, agentJob, agentCheck, defineJob } from 'loops';
+ *   export default defineJob(loop({ ... }));
+ */
+
+/** Identity helper that pins the type of a default export to `Job`. */
+declare function defineJob(job: Job): Job;
+
+export { type AgentCheckConfig, AgentDef, AgentRequest, AgentResult, BudgetConfig, type CommitInput, type CommitRecord, type CompactOptions, Condition, ConditionInput, type ConsolidateJobConfig, type ConsolidateOptions, DagConfig, EXIT_PAUSED, Engine, type EngineFactory, EngineName, EngineOptions, EngineRef, EngineRegistry, EnvHandle, Environment, Forge, type GroundOptions, type IsolatedOptions, Job, JobContext, JobMeta, type LedgerEntry, LimitPolicy, type LogQuery, LoopConfig, LoopEvent, type MergeJobConfig, type MergeResult, type MergeSynthesisConfig, type MergeSynthesisResult, MockEngine, type MockEnvOptions, MockEnvironment, type MockResponder, Outcome, type PromptNote, type PullRequestJobConfig, type PushJobConfig, type PushOptions, type PushResult, type RetrieveOptions, type RunOptions, type RunResult, Stats, type StatsSnapshot, type TournamentConfig, Usage, Workspace, type WorktreeHandle, addWorktree, agentCheck, all, always, any, appendLedger, appendPrompt, bodyPassed, commandSucceeds, commit, compactLedger, composeCommitBody, conflictedFiles, consolidate, consolidateJob, currentBranch, dag, defineJob, deleteBranch, describeConditions, ensureIgnored, exitCodeFor, forgeChecks, gateJob, groundingText, hasStagedChanges, headSha, isDirty, isRepo, isolated, jobMeta, ledgerPath, log, loop, mergeAbort, mergeBranch, mergeJob, mergeNoCommit, mergeSynthesis, minConfidence, mockVerdict, never, not, parallel, predicate, promptPath, pullRequestJob, push, pushJob, quorum, readLedger, readPrompt, removeWorktree, renderPlan, resetLedger, resetPrompt, retrieveLedger, run, sequence, stageAll, toCondition, tournament };