@cerebriline/core 4.100.240

package/dist/extensions/tools/team/agent-rounds.d.ts

@@ -0,0 +1,666 @@
+/**
+ * Every delegation the lead makes, as a round it can come back to.
+ *
+ * A spawn call used to exist only as the tool call that made it: the lead
+ * learned what its agents did when the call returned, and not before or after.
+ * After the 75-agent swarm on 4.100.199 the lead's own evaluation named what
+ * that cost -- it sat idle for the whole round, could not see why an agent
+ * had stopped, and once its history was compacted it no longer had the tasks
+ * it had given, so a failed agent could not be run again without rewriting
+ * its task from memory.
+ *
+ * So each spawn call opens a round here: its id, every agent's original task,
+ * sampler, iteration cap and check, where each one ran, what state it is in
+ * and why it stopped, and its result. The round is the lead's handle for
+ * `agents_status`, the controls (`requeue_agent`, `restart_agent`,
+ * `resume_agent`, `retry_failed`), and `await_agents` for a round that runs in
+ * the background.
+ *
+ * Two lifetimes, kept apart:
+ *
+ * - **The record** is plain data, persisted beside the session
+ *   (`<session>.rounds.json`), so it survives the lead's compaction and a
+ *   reload of the window. Agents that were running when the process went away
+ *   come back as cancelled -- "interrupted" -- which is what `retry_failed`
+ *   runs again.
+ * - **The live state** -- the round's abort signal, its slots' promises, the
+ *   runners that can start an agent -- belongs to this process and is never
+ *   written.
+ *
+ * What an agent is doing reaches its record through the same progress
+ * updates its chat row is drawn from (`emitUpdate`): placement, model, tokens,
+ * speed, compactions, sampler, activity, and the `waiting` report of a wait on
+ * infrastructure. Nothing here polls anything.
+ */
+import type { AgentToolContext } from "@cerebriline/shared";
+import type { CompactionCause } from "../../context/compaction-cause";
+import type { AgentOracleResult } from "./agent-check";
+import { type SpawnBatchFailureClass } from "./batch-report";
+import type { RealizedSpawnSampling, SpawnSampling } from "./spawn-sampling";
+import { type SubagentStopActor } from "./subagent-cancellation";
+import type { AgentPhase } from "./subagent-progress";
+import { type MemberUsage } from "./token-split";
+/** Which tool opened the round, which decides how an agent is run again. */
+export type RoundKind = "spawn_agent" | "swarm" | "configured";
+/** Where one agent is. The lead's status tool counts rounds by these. */
+export type AgentRunState = "queued" | "running" | "waiting_infra" | "awaiting_lead" | "done" | "failed" | "cancelled";
+/**
+ * Why an agent stopped (ruling 6). Waiting on infrastructure is a state, not
+ * a stop: an agent never fails on infrastructure.
+ */
+export type AgentStopReason = "completed"
+/** Reached its iteration cap. */
+ | "iteration_cap"
+/** The loop guard stopped it for sending the same call again. */
+ | "looping"
+/** The struggle supervisor stopped it for grinding after its nudge. */
+ | "struggling"
+/** Its context overflowed and could not be recovered. */
+ | "context_overflow"
+/** Too many consecutive mistakes, or a loop guard ended it. */
+ | "mistake_limit"
+/** The engine or the connection returned an error it could not retry. */
+ | "engine_error"
+/** Its own run failed: a tool, the model, a bad request. */
+ | "task_error" | "cancelled_by_lead" | "cancelled_by_user"
+/** The lead's turn or the session was stopped under it. */
+ | "cancelled_by_session"
+/** The process went away while it ran (a reload). */
+ | "interrupted";
+export declare const LIVE_STATES: ReadonlySet<AgentRunState>;
+/** What a round's agent is waiting on, while it waits. */
+export interface AgentWaitInfo {
+    kind: "refusal" | "transport";
+    /** The node or server. */
+    where: string;
+    /** The refusal's text, or why the server is gone. */
+    detail: string;
+    since: number;
+}
+/** The check's verdict on an agent's work (section E): `agent-check.ts`. */
+export type { AgentOracleResult };
+/** The check's verdict in a few words: `pass`, `FAIL (exit 1)`, `not run (why)`. */
+export declare function oracleWords(oracle: AgentOracleResult): string;
+/** An agent as the lead asked for it: what `retry_failed` runs again. */
+export interface RoundAgentSpec {
+    name: string;
+    task: string;
+    /** Its role, when it differs from the round's. */
+    instructions?: string;
+    /** A configured agent to run it as. */
+    type?: string;
+    /** A swarm worker's own system prompt. */
+    systemPrompt?: string;
+    /** A swarm worker's tool list. */
+    tools?: string[];
+    /** The sampler as asked for, "random" and all. */
+    sampling?: SpawnSampling;
+    maxIterations?: number;
+    /** The oracle, as asked for (section E). */
+    check?: unknown;
+}
+export interface ActivityLine {
+    at: number;
+    text: string;
+    severity?: "warn";
+}
+export interface AgentErrorLine {
+    at: number;
+    class: SpawnBatchFailureClass;
+    text: string;
+}
+export interface RoundAgentRecord extends RoundAgentSpec {
+    /** `r<round>-<n>`, what the lead's controls take. */
+    id: string;
+    index: number;
+    state: AgentRunState;
+    stopReason?: AgentStopReason;
+    /** A line on the stop: the error, the abort's reason. */
+    stopDetail?: string;
+    /**
+     * While it waits on the lead: its cap, a loop the guard stopped, or a
+     * grind the struggle supervisor stopped.
+     */
+    awaitingReason?: "iteration_cap" | "looping" | "struggling";
+    queuedAt: number;
+    startedAt?: number;
+    endedAt?: number;
+    nodeId?: string;
+    nodeLabel?: string;
+    providerId?: string;
+    modelId?: string;
+    contextWindow?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    /**
+     * How much of `inputTokens` the provider served from its cache (the KV
+     * cache on a local server, a billed cache read on a cloud one). Absent
+     * when the provider reported none: unknown, not zero.
+     */
+    cachedTokens?: number;
+    /**
+     * Of the cached input, what came from a PolyKV pool the agent attached to
+     * (the engine's `n_pool_shared`, summed over its requests). Absent off
+     * PolyKV.
+     */
+    poolSharedTokens?: number;
+    contextTokens?: number;
+    /** Recent generation speed, tokens per second. */
+    genTps?: number;
+    /** Its session on the engine: its row of a PolyKV server's `/kv`. */
+    engineSessionId?: string;
+    /** Start times of its latest iterations, for its pace. */
+    iterationTimes?: number[];
+    /** The stretch it is in while it runs, and since when. */
+    phase?: {
+        name: AgentPhase;
+        detail?: string;
+        since: number;
+    };
+    iterations?: number;
+    toolCalls?: number;
+    /** Of those, the calls that came back failed or refused. */
+    toolFailures?: number;
+    compactions?: number;
+    compactionsByCause?: Partial<Record<CompactionCause, number>>;
+    /** The sampler it actually ran with. */
+    samplingUsed?: RealizedSpawnSampling;
+    oracle?: AgentOracleResult;
+    /** The last thing it wrote while running, or the tail of its report. */
+    outputTail?: string;
+    /** Its report, bounded: the summary the lead was handed. */
+    result?: string;
+    activity: ActivityLine[];
+    errors: AgentErrorLine[];
+    waiting?: AgentWaitInfo;
+    /** Runs of it: 1, plus one per restart or retry. */
+    attempts: number;
+    /** Times the lead requeued it. */
+    requeues: number;
+    /** What the lead added to its task on a restart, kept for a retry. */
+    revisedInstructions?: string;
+}
+/** What a round shares across its agents, for a retry after compaction. */
+export interface RoundShared {
+    knowledge?: {
+        files?: string[];
+        text?: string;
+    };
+    instructions?: string;
+    systemPrompt?: string;
+    sampling?: SpawnSampling;
+    maxIterations?: number;
+    check?: unknown;
+}
+export interface RoundRecord {
+    /** `r<n>`, unique in the session. */
+    id: string;
+    kind: RoundKind;
+    /** The tool the lead called. */
+    tool: string;
+    toolCallId?: string;
+    createdAt: number;
+    endedAt?: number;
+    /** Runs beside the lead (`wait: false`); its report arrives on its own. */
+    background: boolean;
+    status: "running" | "done";
+    shared: RoundShared;
+    agents: RoundAgentRecord[];
+    /** The report has reached the lead: returned, awaited, or delivered. */
+    delivered: boolean;
+    /** A swarm's merged report, as its call returned it. */
+    digest?: string;
+    /**
+     * Each agent has its own row under the call, keyed `<call>#<index>`; a
+     * round without it is one row, keyed by the call. Where a rerun's updates
+     * go, after the call is gone.
+     */
+    rowed?: boolean;
+}
+/**
+ * Where a rerun's updates belong, when the call that drew the agent's row is
+ * gone: the control call carries them, tagged with the row -- the original
+ * call and, for a rowed round, the agent's index.
+ */
+export interface RoundRowTarget {
+    toolCallId: string;
+    member?: number;
+}
+/**
+ * What one agent of a round came back with. The spawn paths' own output
+ * shapes all fit it: a single agent's, a batch member's, a swarm worker's.
+ */
+export interface RoundMemberOutput {
+    name?: string;
+    text?: string;
+    iterations?: number;
+    finishReason?: string;
+    usage?: Partial<MemberUsage>;
+    error?: string;
+    model?: {
+        id: string;
+        provider: string;
+    };
+    nodeId?: string;
+    nodeLabel?: string;
+    sampling?: RealizedSpawnSampling;
+    /** `awaiting_lead`: returned while it waits at its cap, work kept. */
+    state?: string;
+    /** `iteration_cap` when the cap ended it. */
+    stopReason?: string;
+    maxIterations?: number;
+    /** The check's verdict, when one was set. */
+    oracle?: AgentOracleResult;
+    /** Its runtime's id: what a detached agent's later events name it by. */
+    agentId?: string;
+}
+/**
+ * Runs one agent of a round again, from its stored spec: what makes
+ * `retry_failed` and a restart of a finished agent possible after the
+ * original call is long gone.
+ */
+export type RoundRunner = (input: {
+    round: RoundRecord;
+    agent: RoundAgentRecord;
+    /** Its task as it should run now: the original, plus revised instructions. */
+    task: string;
+    context: AgentToolContext;
+}) => Promise<RoundMemberOutput>;
+/** A report the lead has not seen, for the host to deliver. */
+export interface SettledRound {
+    record: RoundRecord;
+    /** What the lead is handed: the round's report, bounded. */
+    report: string;
+}
+/**
+ * A settled round as the lead reads it when it was not waiting for it: a
+ * background round, or an agent that finished after its call returned. It
+ * arrives at the lead's next boundary, the way a background delegation's
+ * report does, so it says what it is before it says what happened.
+ */
+export declare function renderRoundNotice(settled: SettledRound): string;
+/**
+ * The lead's completion, held while a round it did not wait for is still
+ * out: a background round, or an agent detached at its cap. Its report would
+ * otherwise arrive into a finished task. No wall clock: the round ends when
+ * its agents do, or when the lead stops them.
+ */
+export declare function roundsCompletionGuard(sessionId: string): () => string | undefined;
+/** Longest output tail kept per agent (spec B: "e.g. 1,500 chars"). */
+export declare const ROUND_OUTPUT_TAIL_CHARS = 1500;
+/** Activity lines kept per agent. */
+export declare const ROUND_ACTIVITY_LIMIT = 20;
+/** One runtime's cumulative report, folded into the agent's lifetime totals. */
+export declare function recordAgentSpend(agent: RoundAgentRecord, report: {
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedTokens?: number;
+    poolSharedTokens?: number;
+}): void;
+/**
+ * A run's end, reported whole: the finish sums every segment the run took
+ * (`runDelegatedWithCap` folds each `continue` into it), so it is added to
+ * what earlier runs spent rather than folded like a live report -- which
+ * would count the segments already folded a second time. The larger of the
+ * two stands, so a finish that summed less than was seen lowers nothing.
+ */
+export declare function recordAgentFinalSpend(agent: RoundAgentRecord, usage: Partial<MemberUsage>): void;
+/**
+ * The state and stop reason one finished run comes to.
+ *
+ * `stoppedBy` is who stopped it, when someone did; `sessionAborted` whether
+ * the lead's turn or the session was stopped under it.
+ */
+export declare function classifyAgentEnd(outcome: RoundMemberOutput | {
+    thrown: unknown;
+}, stoppedBy: SubagentStopActor | undefined, sessionAborted: boolean): {
+    state: AgentRunState;
+    reason: AgentStopReason;
+    detail?: string;
+};
+/** The task an agent runs now: its own, with the lead's revision after it. */
+export declare function taskWithRevision(agent: RoundAgentRecord): string;
+interface LiveRound {
+    record: RoundRecord;
+    controller: AbortController;
+    /** Each agent's current run, when it has one. */
+    slots: Map<number, Promise<RoundMemberOutput>>;
+    /** Each agent's latest output, for the round's report. */
+    outputs: Map<number, RoundMemberOutput>;
+    /** Each agent's live control id. */
+    cancelIds: Map<number, string>;
+    /** Each agent's channel to its row, kept for news after its call returned. */
+    rows?: Map<number, (update: unknown) => void>;
+    /** Where the original call's progress went, while it is still open. */
+    emitUpdate?: (update: unknown) => void;
+    /** Tags an update with its agent, as the call's rows expect. */
+    rowed: boolean;
+    idleWaiters: Array<() => void>;
+    /**
+     * Held open by the call that opened it while it is still launching agents:
+     * a swarm launches over time, and a round whose first worker finished
+     * before the second started is not a finished round.
+     */
+    holds: number;
+    /** Callers inside `await_agents` for it: its report goes to them. */
+    awaited: number;
+    /** Lets go of the lead's turn signal, for a blocking round detached. */
+    unlinkTurn?: () => void;
+    /** Reruns started, for unique tool-call ids. */
+    reruns: number;
+    /** A report from the call itself, in place of one built from results. */
+    reportOverride?: string;
+}
+export interface OpenRoundInput {
+    kind: RoundKind;
+    tool: string;
+    toolCallId?: string;
+    background: boolean;
+    shared?: RoundShared;
+    agents: RoundAgentSpec[];
+    /**
+     * The lead's call signal, for a blocking round: stopping the lead's turn
+     * stops the round. A background round is not tied to the turn it started
+     * in, and runs until it ends, is stopped, or the session goes.
+     */
+    signal?: AbortSignal;
+    /** The call's own progress channel, for its rows. */
+    emitUpdate?: (update: unknown) => void;
+    /** Each agent has its own row, keyed by `member`. */
+    rowed?: boolean;
+}
+type SettledListener = (settled: SettledRound) => void;
+/** Renders a finished round's report for the lead. Set by the tools. */
+export type RoundReportRenderer = (record: RoundRecord, outputs: ReadonlyMap<number, RoundMemberOutput>, sessionId: string | undefined) => string;
+export declare class AgentRounds {
+    readonly sessionId: string;
+    private readonly now;
+    private readonly rounds;
+    private readonly live;
+    private readonly runners;
+    private readonly listeners;
+    private persistTimer;
+    private path;
+    private blocking;
+    private renderReport;
+    constructor(sessionId: string, now?: () => number);
+    /**
+     * Persist to `path`, loading what is there first. Agents recorded as live
+     * were running when the process went away: they are cancelled now, as
+     * `interrupted`, which `retry_failed` runs again.
+     */
+    attachStore(path: string): void;
+    /**
+     * The session is going with rounds still out: a reload of the window, or
+     * the task closed. Their agents are about to be stopped, and whatever they
+     * would report on the way out is not what the record keeps: each is
+     * `interrupted` now, its round is over with a report owed to the lead, and
+     * that is what is written. Nothing is written after it -- the late ends of
+     * the agents being stopped would otherwise land a second later as
+     * "cancelled by the session", or not at all if the process is gone by
+     * then. The next start of the session delivers the notice.
+     */
+    interruptAll(): void;
+    private interruptRound;
+    /** Write now, and stop writing: the session is going. */
+    flush(): void;
+    /** Stop every live round; the session is ending. */
+    stopAll(reason?: string): void;
+    setReportRenderer(renderer: RoundReportRenderer): void;
+    registerRunner(kind: RoundKind, runner: RoundRunner): void;
+    hasRunner(kind: RoundKind): boolean;
+    /** Told once per settle of a round whose report the lead has not had. */
+    onSettled(listener: SettledListener): () => void;
+    /**
+     * The lead is inside a call that waits on its agents: a blocking spawn, or
+     * `await_agents`. A user's steer is then answered in a side turn; with the
+     * lead working beside a background round it goes to the lead as usual.
+     */
+    enterBlocking(): () => void;
+    get leadBlocked(): boolean;
+    /**
+     * The lead's waits on its agents in progress -- `await_agents`, a blocking
+     * spawn -- each ended by {@link wakeAwaits}.
+     */
+    private readonly wakers;
+    /**
+     * `work`, or a message for the lead, whichever comes first. A blocking
+     * spawn waits here: measured 2026-09-26, a `wait: true` spawn of 50
+     * agents held the lead for the whole round while the user's steers went
+     * to side turns and their results queued behind it.
+     */
+    untilWoken<T>(work: Promise<T>): Promise<{
+        woken: false;
+        value: T;
+    } | {
+        woken: true;
+    }>;
+    /**
+     * Whether a message for the lead is already queued, as the host knows it.
+     *
+     * A wait is ended when a message is queued. One queued a moment earlier,
+     * while the lead was still writing the turn in which it then called
+     * `await_agents`, woke nothing: the wait began after it. The user's
+     * second message sat in the queue for the rest of the round, under a
+     * lead that read as "monitoring" (pandorum, session wlafh, 2026-10-04
+     * 05:33:46Z).
+     */
+    messageWaiting: (() => boolean) | undefined;
+    /** Register a wait on the agents that a message for the lead ends. */
+    onWake(wake: () => void): () => void;
+    /**
+     * The lead is waiting on its agents (`await_agents`, a blocking spawn):
+     * a message for it should end the wait rather than sit behind the round.
+     */
+    get leadAwaiting(): boolean;
+    /**
+     * Something is waiting for the lead -- the user's message, the harness's
+     * report of a stuck agent. Its `await_agents` returns now, so the message
+     * reaches it at the turn boundary right after; the rounds carry on.
+     * Returns whether a wait was ended.
+     */
+    wakeAwaits(): boolean;
+    list(): RoundRecord[];
+    get(roundId: string): RoundRecord | undefined;
+    /** Rounds still running in the background whose report is not yet in. */
+    pendingBackground(): RoundRecord[];
+    /**
+     * An agent by id (`r2-3`) or by name. A name used in several rounds means
+     * the newest round's agent of that name.
+     */
+    findAgent(ref: string): {
+        round: RoundRecord;
+        agent: RoundAgentRecord;
+    } | undefined;
+    /** The live control id of an agent that is running now. */
+    cancelIdOf(roundId: string, index: number): string | undefined;
+    isLive(roundId: string): boolean;
+    /** The round's signal, while it is live in this process. */
+    signalOf(roundId: string): AbortSignal | undefined;
+    open(input: OpenRoundInput): RoundHandle;
+    /** Add an agent to a live round: a swarm's `max` finds its size as it goes. */
+    addAgent(roundId: string, spec: RoundAgentSpec): RoundAgentRecord;
+    /**
+     * Run one agent of the round again, from its stored spec. For a restart of
+     * an agent that has finished, and for `retry_failed`. The round reopens,
+     * and its report goes to the lead again when it is done.
+     *
+     * `context` is the control call's: a rerun borrows its session and parent,
+     * never its signal -- it runs under the round's.
+     */
+    rerun(roundId: string, index: number, context: AgentToolContext, options?: {
+        instructions?: string;
+    }): {
+        started: boolean;
+        why?: string;
+    };
+    /** Wait for these rounds -- or every running one -- to finish. */
+    waitFor(roundIds: readonly string[] | undefined, signal?: AbortSignal): Promise<RoundRecord[]>;
+    /** The report of a finished round, as the lead reads it. */
+    reportFor(roundId: string): string;
+    markDelivered(roundId: string): void;
+    /** @internal */
+    schedulePersist(): void;
+    /** @internal */
+    settleIfIdle(live: LiveRound): void;
+    /** @internal */
+    resetForRun(agent: RoundAgentRecord): void;
+    /** @internal */
+    now_(): number;
+    private milestones;
+    private milestoneTimer;
+    /**
+     * An agent has run another {@link LEAD_ITERATION_NUDGE_EVERY} iterations:
+     * tell the lead, with every other agent that crosses a line in the next
+     * {@link LEAD_NUDGE_BATCH_MS}.
+     *
+     * This is what replaced the iteration cap the lead used to set (user
+     * ruling, 2026-09-28): nothing stops the agent, the lead is asked to look.
+     * @internal
+     */
+    noteIterationMilestone(milestone: IterationMilestone): void;
+    private newAgent;
+    private nextRoundNumber;
+    private writeNow;
+}
+/** Marks a tool context as one agent of a round already open. */
+export declare const ROUND_MEMBER_KEY = "cerebrilineRoundMember";
+/** Whether a tool call runs as a member of a round a caller already opened. */
+export declare function isRoundMember(context: AgentToolContext | undefined): boolean;
+/** One open round, as the tool that opened it drives it. */
+export declare class RoundHandle {
+    private readonly rounds;
+    private readonly live;
+    constructor(rounds: AgentRounds, live: LiveRound);
+    get id(): string;
+    get record(): RoundRecord;
+    /** The round's own stop: the lead's turn for a blocking round. */
+    get signal(): AbortSignal;
+    agent(index: number): RoundAgentRecord | undefined;
+    /** The control id agent `index` is stopped, requeued and messaged by. */
+    bindControl(index: number, cancelId: string): void;
+    /** Grow the round by one agent; returns its index. */
+    add(spec: RoundAgentSpec): number;
+    /**
+     * Run agent `index` under `context`, recording what it does and how it
+     * ends. The context handed to `fn` taps the agent's progress updates on
+     * their way to its row. Never throws: a failed agent is an output with an
+     * `error`, as a batch member's always was.
+     */
+    run(index: number, context: AgentToolContext, fn: (context: AgentToolContext) => Promise<RoundMemberOutput>): Promise<RoundMemberOutput>;
+    /**
+     * Record an agent that never ran: stopped or left in the queue when the
+     * round ended.
+     */
+    never(index: number, why: string): void;
+    /** Resolves when no agent of the round is running. */
+    idle(): Promise<void>;
+    /** The latest output of every agent, in order. */
+    outputs(): RoundMemberOutput[];
+    /** A report from the call itself -- a swarm's digest -- for this settle. */
+    setReport(report: string, digest?: string): void;
+    /**
+     * The call is returning its report to the lead itself: nothing to deliver.
+     * Also lets go of the call's progress channel, which is closed once the
+     * call returns.
+     */
+    delivered(): void;
+    /**
+     * A blocking round whose call returns before it ends: a message for the
+     * lead woke it. The round goes on in the background, no longer stopped by
+     * the turn's signal, and its report is delivered when it ends.
+     */
+    detach(): void;
+    /**
+     * The opening call has launched everything it will: the round settles
+     * once its last agent ends (now, if none runs). Idempotent.
+     */
+    close(): void;
+    /** Where agent `index`'s updates go: its record, then its row. */
+    private tap;
+    private observe;
+    private pushActivity;
+    private runAgent;
+    /**
+     * An agent whose run returned while it waits at its cap, its call gone
+     * (`agent-iteration-cap.ts`: detached). The round stays open for it, its
+     * resume and its real end are recorded as they happen, and its end
+     * settles the round again -- a report the lead has not had.
+     */
+    private followDetached;
+    private finish;
+}
+/**
+ * A session's rounds, for a view drawn after the fact -- a task reopened, a
+ * window reloaded: this process's registry when it holds them, else the file
+ * the session wrote beside its transcript. A round the file says is running
+ * was not ended by any process alive now, so it reads as interrupted, as the
+ * session's next start will record it. Copies: nothing here changes a round.
+ */
+export declare function readRoundRecords(sessionId: string, path?: string): RoundRecord[];
+/** This session's rounds, created on first use. */
+export declare function roundsFor(sessionId: string | undefined): AgentRounds;
+/** The session is gone: stop its rounds, write them, forget them. */
+export declare function releaseRounds(sessionId: string): void;
+/** Test seam. */
+export declare function __resetAgentRounds(): void;
+/**
+ * An agent's trouble watch, also reporting each wait on its row's channel --
+ * `{waiting: {kind, where, detail}}` while it waits, `{waiting: null}` when
+ * the engine produces for it again -- so its round knows it is waiting on
+ * infrastructure and on what. The watch itself is untouched: the lead's
+ * nudge after a long wait works exactly as it did.
+ */
+export declare function reportWaits<T extends {
+    waiting(state: {
+        kind: string;
+        where: string;
+        detail: string;
+    }): void;
+    progressed(): void;
+    dispose(): void;
+}>(watch: T, emitUpdate: ((update: unknown) => void) | undefined, control?: {
+    setWaitingInfra(waiting: boolean): void;
+}): T;
+/**
+ * What every agent's result carries (section F): its state and why it
+ * stopped, iterations against its cap, tokens, compactions, the oracle's
+ * verdict, its sampler, and where it ran.
+ */
+export interface AgentFacts {
+    id: string;
+    round: string;
+    state: AgentRunState;
+    stopReason?: AgentStopReason;
+    iterations?: number;
+    maxIterations?: number;
+    tokens?: {
+        input: number;
+        output: number;
+    };
+    compactions?: {
+        count: number;
+        byCause?: Partial<Record<CompactionCause, number>>;
+    };
+    oracle?: AgentOracleResult;
+    sampling?: RealizedSpawnSampling;
+    node?: string;
+    model?: string;
+}
+export declare function agentFacts(round: Pick<RoundRecord, "id">, agent: RoundAgentRecord): AgentFacts;
+/** One agent's crossing of an iteration line, for the lead's note. */
+export interface IterationMilestone {
+    round: string;
+    id: string;
+    name: string;
+    iterations: number;
+    phase?: string;
+    toolCalls?: number;
+    toolFailures?: number;
+}
+/** `22 of 95 tool calls failed`, when any did. */
+export declare function toolFailureNote(toolCalls: number | undefined, toolFailures: number | undefined): string | undefined;
+/** The note that asks the lead to look at agents that have run a long time. */
+export declare function describeIterationMilestones(milestones: readonly IterationMilestone[]): string;
+/** The same facts on one line, for a round's per-agent report entries. */
+export declare function agentFactsLine(agent: RoundAgentRecord): string;