@spendgraph/harness 0.1.0 → 0.2.1

package/dist/chain/gate.js

@@ -0,0 +1,25 @@
+import { node } from "@spendgraph/graph";
+export function gateName(step) {
+    return `gate_${step}`;
+}
+export class GateRefused extends Error {
+    step;
+    reason;
+    constructor(step, reason) {
+        super(`"${step}" did not pass its gate: ${reason}`);
+        this.step = step;
+        this.reason = reason;
+        this.name = "GateRefused";
+    }
+}
+export function gateNode(step) {
+    return node({
+        name: gateName(step.name),
+        run: async (_values, ctx) => {
+            const verdict = await step.gate?.(ctx.outputs[step.name], ctx);
+            if (!verdict || verdict.ok)
+                return verdict ?? { ok: true };
+            throw new GateRefused(step.name, verdict.reason ?? "no reason given");
+        },
+    });
+}

package/dist/chain/index.d.ts

@@ -0,0 +1,3 @@
+export { chain } from "./chain.js";
+export { GateRefused, gateName } from "./gate.js";
+export type { ChainOptions, ChainResult, Gate, Step } from "./types.js";

package/dist/chain/index.js

@@ -0,0 +1,2 @@
+export { chain } from "./chain.js";
+export { GateRefused, gateName } from "./gate.js";

package/dist/chain/step.d.ts

@@ -0,0 +1,9 @@
+import type { Step } from "./types.js";
+/**
+ * A stage as a node.
+ *
+ * `previous` is read from the context rather than threaded through the input,
+ * because a gate may sit between two stages and its return is not what the next
+ * stage wants — the stage before it is.
+ */
+export declare function stepNode(step: Step, previous: string | null): import("@spendgraph/graph").Node<import("@spendgraph/graph").ArgsOf<readonly import("@spendgraph/graph").ArgSpec[]>>;

package/dist/chain/step.js

@@ -0,0 +1,7 @@
+import { node } from "@spendgraph/graph";
+export function stepNode(step, previous) {
+    return node({
+        name: step.name,
+        run: (values, ctx) => step.run(previous ? ctx.outputs[previous] : values, ctx),
+    });
+}

package/dist/chain/types.d.ts

@@ -0,0 +1,50 @@
+import type { GraphContext, GraphResult } from "@spendgraph/graph";
+import type { Emit } from "../stream/index.js";
+/** Whether the chain may continue, and why not when it may not. */
+export interface Gate {
+    ok: boolean;
+    /** Said in the record and in the error. A failed gate with no reason is a mystery. */
+    reason?: string;
+}
+/**
+ * One stage.
+ *
+ * `run` is handed whatever the previous stage returned — the values the chain
+ * was called with, for the first one.
+ */
+export interface Step {
+    /** Unique in the chain, and the key its output is stored under. */
+    name: string;
+    run(previous: unknown, ctx: GraphContext): Promise<unknown> | unknown;
+    /**
+     * Whether that will do to continue on.
+     *
+     * The reason this pattern is worth naming: without a gate, a stage that
+     * produced nothing useful is passed to the next one, which confidently works
+     * on it, and you get a polished answer three calls later that is about
+     * nothing. A gate stops at the stage that went wrong and says which.
+     */
+    gate?(output: unknown, ctx: GraphContext): Promise<Gate> | Gate;
+}
+export interface ChainOptions {
+    steps: Step[];
+    /**
+     * Where the tokens go while this runs.
+     *
+     * Passed down to whatever makes the model call; omit it and nothing is
+     * emitted. `streamed()` supplies one.
+     */
+    emit?: Emit;
+    /** Ceiling on total steps, nested ones included. Default 25. */
+    maxSteps?: number;
+    /** Injectable clock, so tests do not measure real time. */
+    now?: () => number;
+}
+export interface ChainResult extends GraphResult {
+    /** The stages that ran, in order. */
+    ran: string[];
+    /** The stage whose gate refused, or which threw. Null when the chain finished. */
+    stoppedAt: string | null;
+    /** What the gate said. */
+    reason?: string;
+}

package/dist/index.d.ts

@@ -1,9 +1,16 @@
-export { Harness, type HarnessOptions } from "./harness.js";
-export { Budget, BudgetExceededError, Client, HarnessError, PullCache, pullWithCache, type CacheHit, type CacheOptions, type ClientOptions, } from "./core/index.js";
-export type { FieldSpec, FieldType } from "./core/schema/types.js";
-export { FieldValidationError, validateFields, type FieldError, } from "./core/schema/validate.js";
-export { serializeFields } from "./core/schema/serialize.js";
-export { applyVariables, compileSystemPrompt, findVariables, renderMessages, type Block, type Message, } from "./prompt/render.js";
-export { mapLimit, newRolloutId } from "./prompt/run.js";
-export { emitPromptTypes, typeOf, valuesTypeFor, type CodegenPrompt, type EmitOptions, } from "./prompt/codegen.js";
-export type { DatasetCase, DatasetSummary, Prompt, PromptPayload, ReportInput, Rollout, RunOptions, PromptVersion, Prompts, RunResult, Split, ValuesFor, } from "./prompt/types.js";
+export type { Answer, CascadeOptions, CascadeResult, Escalation, Tier, TierRecord, } from "./cascade/index.js";
+export { cascade } from "./cascade/index.js";
+export type { ChainOptions, ChainResult, Gate, Step } from "./chain/index.js";
+export { chain, GateRefused } from "./chain/index.js";
+export type { Call, Compaction, Hooks, Invoker, LoopEnd, LoopOptions, LoopResult, Refusal, Remaining, Summary, Turn, TurnRecord, TurnState, } from "./loop/index.js";
+export { loop } from "./loop/index.js";
+export type { OrchestrateEnd, OrchestrateOptions, OrchestrateResult, Outcome, Plan, Subtask, } from "./orchestrate/index.js";
+export { orchestrate } from "./orchestrate/index.js";
+export type { ParallelOptions, ParallelResult, Task, TaskResult } from "./parallel/index.js";
+export { majority, parallel, repeat, type Vote } from "./parallel/index.js";
+export type { Attempt, RefineOptions, RefineResult, RoundRecord, Verdict } from "./refine/index.js";
+export { refine } from "./refine/index.js";
+export type { Classification, Handler, RouteOptions, RouteResult } from "./route/index.js";
+export { route } from "./route/index.js";
+export type { Emit, HarnessEvent, HarnessStream } from "./stream/index.js";
+export { streamed } from "./stream/index.js";

package/dist/index.js

@@ -1,7 +1,8 @@
-export { Harness } from "./harness.js";
-export { Budget, BudgetExceededError, Client, HarnessError, PullCache, pullWithCache, } from "./core/index.js";
-export { FieldValidationError, validateFields, } from "./core/schema/validate.js";
-export { serializeFields } from "./core/schema/serialize.js";
-export { applyVariables, compileSystemPrompt, findVariables, renderMessages, } from "./prompt/render.js";
-export { mapLimit, newRolloutId } from "./prompt/run.js";
-export { emitPromptTypes, typeOf, valuesTypeFor, } from "./prompt/codegen.js";
+export { cascade } from "./cascade/index.js";
+export { chain, GateRefused } from "./chain/index.js";
+export { loop } from "./loop/index.js";
+export { orchestrate } from "./orchestrate/index.js";
+export { majority, parallel, repeat } from "./parallel/index.js";
+export { refine } from "./refine/index.js";
+export { route } from "./route/index.js";
+export { streamed } from "./stream/index.js";

package/dist/loop/act.d.ts

@@ -0,0 +1,21 @@
+import type { RolloutStep } from "@spendgraph/sdk";
+import { type ToolResult } from "@spendgraph/tools";
+import { type Hooks } from "./hooks.js";
+import type { Call, Invoker } from "./types.js";
+/** One tool call as a step, failures included. */
+export declare function callStep(index: number, result: ToolResult): RolloutStep;
+/**
+ * Runs what the model asked for, in the order it asked.
+ *
+ * Never throws — `invoke` returns a failed result rather than raising, so a
+ * tool that fell over is something the model can read and try around, not
+ * something that ends the run.
+ */
+export declare function act(tools: Invoker, calls: Call[], hooks?: Hooks): Promise<ToolResult[]>;
+/**
+ * The answer, when the model said it was done.
+ *
+ * Reading `finish` here is what separates "it is done" from "it stopped asking",
+ * which otherwise look identical from outside and are opposite problems.
+ */
+export declare function finished(results: ToolResult[]): string | null;

package/dist/loop/act.js

@@ -0,0 +1,29 @@
+import { answerOf, isFinished } from "@spendgraph/tools";
+import { ask, blockedResult, tell } from "./hooks.js";
+export function callStep(index, result) {
+    return {
+        index,
+        source: result.name,
+        input: result.args,
+        output: result.output,
+        status: result.status,
+        error: result.error,
+        latencyMs: result.latencyMs,
+    };
+}
+export async function act(tools, calls, hooks = {}) {
+    const results = [];
+    for (const call of calls) {
+        const refused = await ask(hooks.beforeTool, call, tools.effectOf?.(call.name));
+        const result = refused
+            ? blockedResult(call, refused)
+            : await tools.invoke(call.name, call.args);
+        await tell(hooks.afterTool, result);
+        results.push(result);
+    }
+    return results;
+}
+export function finished(results) {
+    const done = results.find((result) => isFinished(result));
+    return done ? answerOf(done) : null;
+}

package/dist/loop/compact.d.ts

@@ -0,0 +1,49 @@
+import type { RolloutStep } from "@spendgraph/sdk";
+import type { ToolResult } from "@spendgraph/tools";
+import type { Turn } from "./types.js";
+/** What the summariser produced, and what producing it cost. */
+export interface Summary {
+    output: string;
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+}
+export interface Compaction {
+    /**
+     * Fraction of `maxTokens` the resent context may reach before compacting.
+     * Default 0.7.
+     */
+    at?: number;
+    /** Compact once there are more results than this, whatever the tokens say. */
+    after?: number;
+    /** Most recent results kept verbatim. Default 4. */
+    keep?: number;
+    /** Turns the older results into one. */
+    summarise(older: ToolResult[]): Promise<Summary> | Summary;
+}
+declare const DEFAULT_KEEP = 4;
+/**
+ * Whether the context is big enough to be worth summarising.
+ *
+ * Measured on the **last turn's input tokens**, not on what the run has spent.
+ * Spend only ever rises, so a threshold on it fires once and then every turn
+ * after; the input count is the size of what is actually being resent, and it
+ * falls the moment a compaction lands — which is what stops this firing twice
+ * for the same reason.
+ */
+export declare function shouldCompact(compact: Compaction, last: Turn | null, results: ToolResult[], maxTokens?: number): boolean;
+/** The summary as a tool result, so the next turn reads it like any other. */
+export declare function summaryResult(summary: Summary, replaced: number): ToolResult;
+/** The summarising call as a step, because deciding what to forget is not free. */
+export declare function compactStep(index: number, summary: Summary, replaced: number): RolloutStep;
+/**
+ * Replaces the older results with one summary, in place.
+ *
+ * The most recent `keep` survive verbatim: summarising what just happened is
+ * how a loop forgets what it was in the middle of doing.
+ */
+export declare function applyCompaction(results: ToolResult[], summary: Summary, keep: number): {
+    replaced: number;
+    summarised: ToolResult;
+};
+export { DEFAULT_KEEP };

package/dist/loop/compact.js

@@ -0,0 +1,41 @@
+const DEFAULT_AT = 0.7;
+const DEFAULT_KEEP = 4;
+export function shouldCompact(compact, last, results, maxTokens) {
+    const keep = compact.keep ?? DEFAULT_KEEP;
+    if (results.length <= keep)
+        return false;
+    if (compact.after !== undefined && results.length > compact.after)
+        return true;
+    if (maxTokens === undefined || last === null)
+        return false;
+    const context = last.inputTokens ?? 0;
+    return context >= (compact.at ?? DEFAULT_AT) * maxTokens;
+}
+export function summaryResult(summary, replaced) {
+    return {
+        name: "compacted",
+        args: { replaced },
+        status: "completed",
+        output: summary.output,
+        latencyMs: 0,
+    };
+}
+export function compactStep(index, summary, replaced) {
+    return {
+        index,
+        source: "compact",
+        input: { replaced },
+        model: summary.model,
+        output: summary.output,
+        status: "completed",
+        inputTokens: summary.inputTokens,
+        outputTokens: summary.outputTokens,
+    };
+}
+export function applyCompaction(results, summary, keep) {
+    const older = results.splice(0, results.length - keep);
+    const summarised = summaryResult(summary, older.length);
+    results.unshift(summarised);
+    return { replaced: older.length, summarised };
+}
+export { DEFAULT_KEEP };

package/dist/loop/hooks.d.ts

@@ -0,0 +1,43 @@
+import type { Effect, ToolResult } from "@spendgraph/tools";
+import type { Call, Turn, TurnState } from "./types.js";
+/** Return a reason to refuse; return nothing to allow. */
+export type Refusal = {
+    block: string;
+} | undefined | void;
+/**
+ * Deterministic code at fixed points in the loop.
+ *
+ * A guardrail written into the prompt is a request. This is enforcement: it
+ * runs whether or not the model read the instruction, and it cannot be argued
+ * out of by the next turn's wording.
+ */
+export interface Hooks {
+    /** Before a model call. Blocking here ends the run — a turn has no way around it. */
+    beforeTurn?(state: TurnState): Promise<Refusal> | Refusal;
+    /**
+     * Before a tool runs. Blocking here is a failed result the model can work
+     * around.
+     *
+     * `effect` is what the tool declared, and `undefined` when it declared
+     * nothing. Gate on it rather than on `call.name`: a rule written against a
+     * name stops firing the day the tool is renamed, silently and in the
+     * permissive direction.
+     */
+    beforeTool?(call: Call, effect: Effect | undefined): Promise<Refusal> | Refusal;
+    /** After a tool ran. Observation only — the audit trail's natural home. */
+    afterTool?(result: ToolResult): Promise<void> | void;
+    /** After a model call. Observation only. */
+    afterTurn?(turn: Turn): Promise<void> | void;
+}
+/**
+ * Runs a hook that can refuse, treating its own failure as permission.
+ *
+ * A hook that throws is a bug in the guardrail, and taking the run down with it
+ * is worse than the thing it was guarding against — the call it was checking
+ * has not happened yet, and the next hook still gets its say.
+ */
+export declare function ask(hook: ((...args: never[]) => Promise<Refusal> | Refusal) | undefined, ...args: unknown[]): Promise<string | null>;
+/** Runs an observing hook. Its failure changes nothing; it was only watching. */
+export declare function tell(hook: ((arg: never) => Promise<void> | void) | undefined, arg: unknown): Promise<void>;
+/** A refused call, in the shape the model already knows how to read. */
+export declare function blockedResult(call: Call, reason: string): ToolResult;

package/dist/loop/hooks.js

@@ -0,0 +1,31 @@
+export async function ask(hook, ...args) {
+    if (!hook)
+        return null;
+    try {
+        const call = hook;
+        const verdict = await call(...args);
+        return verdict?.block ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function tell(hook, arg) {
+    if (!hook)
+        return;
+    try {
+        await hook(arg);
+    }
+    catch {
+    }
+}
+export function blockedResult(call, reason) {
+    return {
+        name: call.name,
+        args: call.args,
+        status: "failed",
+        output: "",
+        error: `blocked: ${reason}`,
+        latencyMs: 0,
+    };
+}

package/dist/loop/index.d.ts

@@ -0,0 +1,6 @@
+export { act, callStep, finished } from "./act.js";
+export { applyCompaction, type Compaction, type Summary, shouldCompact } from "./compact.js";
+export { blockedResult, type Hooks, type Refusal } from "./hooks.js";
+export { loop } from "./loop.js";
+export { tokensOf, turnStep } from "./turn.js";
+export type { Call, Invoker, LoopEnd, LoopOptions, LoopResult, Remaining, Turn, TurnRecord, TurnState, } from "./types.js";

package/dist/loop/index.js

@@ -0,0 +1,5 @@
+export { act, callStep, finished } from "./act.js";
+export { applyCompaction, shouldCompact } from "./compact.js";
+export { blockedResult } from "./hooks.js";
+export { loop } from "./loop.js";
+export { tokensOf, turnStep } from "./turn.js";

package/dist/loop/loop.d.ts

@@ -0,0 +1,13 @@
+import type { LoopOptions, LoopResult } from "./types.js";
+/**
+ * Model, tools, model again, until it stops asking.
+ *
+ * Not compiled to a graph: this is a cycle, and `@spendgraph/graph` is a DAG
+ * whose step ceiling exists to stop one. Same reasoning as `refine`.
+ *
+ * What this adds over a provider SDK's own tool loop is the part that is always
+ * hand-rolled and always wrong the same way: a ceiling that is checked before
+ * the spend rather than after, every turn and every tool call recorded, and
+ * `finished` told apart from `quiet`.
+ */
+export declare function loop(opts: LoopOptions): Promise<LoopResult>;

package/dist/loop/loop.js

@@ -0,0 +1,99 @@
+import { act, callStep, finished } from "./act.js";
+import { applyCompaction, compactStep, DEFAULT_KEEP, shouldCompact } from "./compact.js";
+import { ask, tell } from "./hooks.js";
+import { tokensOf, turnStep } from "./turn.js";
+const DEFAULT_MAX_TURNS = 8;
+export async function loop(opts) {
+    const startedAt = Date.now();
+    const maxTurns = Math.max(1, opts.maxTurns ?? DEFAULT_MAX_TURNS);
+    const steps = [];
+    const history = [];
+    const results = [];
+    let last = null;
+    let spent = 0;
+    let answer = null;
+    let stoppedBy = "turns";
+    const compactions = { count: 0, replaced: 0 };
+    const compactIfNeeded = async () => {
+        if (!opts.compact || !shouldCompact(opts.compact, last, results, opts.maxTokens))
+            return;
+        try {
+            const keep = opts.compact.keep ?? DEFAULT_KEEP;
+            const older = results.slice(0, results.length - keep);
+            const summary = await opts.compact.summarise(older);
+            const { replaced } = applyCompaction(results, summary, keep);
+            steps.push(compactStep(steps.length, summary, replaced));
+            spent += (summary.inputTokens ?? 0) + (summary.outputTokens ?? 0);
+            compactions.count += 1;
+            compactions.replaced += replaced;
+        }
+        catch {
+        }
+    };
+    const finish = (status, error) => ({
+        status,
+        output: status === "completed" ? (answer ?? last?.output ?? "") : "",
+        error,
+        steps,
+        outputs: { history },
+        latencyMs: Date.now() - startedAt,
+        inputTokens: history.reduce((n, r) => n + (r.outcome.inputTokens ?? 0), 0),
+        outputTokens: history.reduce((n, r) => n + (r.outcome.outputTokens ?? 0), 0),
+        turns: history.length,
+        stoppedBy,
+        compactions,
+        ...(answer === null ? {} : { answer }),
+        history,
+    });
+    for (let at = 0; at < maxTurns; at++) {
+        if (opts.maxTokens !== undefined && spent >= opts.maxTokens) {
+            stoppedBy = "tokens";
+            break;
+        }
+        await compactIfNeeded();
+        const remaining = {
+            turns: maxTurns - at,
+            tokens: opts.maxTokens === undefined ? Infinity : Math.max(0, opts.maxTokens - spent),
+        };
+        const state = {
+            turn: at,
+            results: [...results],
+            last,
+            remaining,
+            emit: (text, stage) => opts.emit?.(text, stage ?? `turn ${at}`),
+        };
+        const refused = await ask(opts.hooks?.beforeTurn, state);
+        if (refused) {
+            stoppedBy = "blocked";
+            return finish("failed", `A hook stopped the run: ${refused}`);
+        }
+        const outcome = await opts.turn(state);
+        steps.push(turnStep(steps.length, at, outcome));
+        spent += tokensOf(outcome);
+        last = outcome;
+        if (outcome.status === "failed") {
+            stoppedBy = "failed";
+            return finish("failed", outcome.error ?? "The turn failed.");
+        }
+        await tell(opts.hooks?.afterTurn, outcome);
+        const calls = outcome.toolCalls ?? [];
+        const ran = calls.length > 0 ? await act(opts.tools, calls, opts.hooks ?? {}) : [];
+        for (const result of ran) {
+            steps.push(callStep(steps.length, result));
+            results.push(result);
+        }
+        const record = { turn: at, outcome, results: ran, tokens: tokensOf(outcome) };
+        history.push(record);
+        opts.onTurn?.(record);
+        answer = finished(ran);
+        if (answer !== null) {
+            stoppedBy = "finished";
+            break;
+        }
+        if (calls.length === 0) {
+            stoppedBy = "quiet";
+            break;
+        }
+    }
+    return finish("completed");
+}

package/dist/loop/turn.d.ts

@@ -0,0 +1,6 @@
+import type { RolloutStep } from "@spendgraph/sdk";
+import type { Turn } from "./types.js";
+/** What one turn consumed. Both halves, since the history is resent every time. */
+export declare function tokensOf(turn: Turn): number;
+/** One model call as a step. */
+export declare function turnStep(index: number, at: number, turn: Turn): RolloutStep;

package/dist/loop/turn.js

@@ -0,0 +1,15 @@
+export function tokensOf(turn) {
+    return (turn.inputTokens ?? 0) + (turn.outputTokens ?? 0);
+}
+export function turnStep(index, at, turn) {
+    return {
+        index,
+        source: `turn_${at}`,
+        model: turn.model,
+        output: turn.output,
+        status: turn.status ?? "completed",
+        error: turn.error,
+        inputTokens: turn.inputTokens,
+        outputTokens: turn.outputTokens,
+    };
+}

package/dist/loop/types.d.ts

@@ -0,0 +1,140 @@
+import type { RolloutStep } from "@spendgraph/sdk";
+import type { Effect, ToolResult } from "@spendgraph/tools";
+import type { Emit } from "../stream/index.js";
+import type { Compaction } from "./compact.js";
+import type { Hooks } from "./hooks.js";
+/** One call the model wants made. */
+export interface Call {
+    id?: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+/** What one model call produced. */
+export interface Turn {
+    output: string;
+    model: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    status?: "completed" | "failed";
+    error?: string;
+    /** What the model wants run. Empty means it has stopped asking. */
+    toolCalls?: Call[];
+}
+/**
+ * What is left of the ceilings, so the model can plan inside them.
+ *
+ * `Infinity` where no ceiling was set, never zero. A missing budget read as an
+ * exhausted one turns the obvious `remaining.tokens < 1000` into a check that
+ * fires on the first turn of every unbounded run, and the agent gives up before
+ * starting.
+ */
+export interface Remaining {
+    /** Turns left, this one included. */
+    turns: number;
+    /** Tokens left before `maxTokens`, or `Infinity` when there is none. */
+    tokens: number;
+}
+/** What the model has been told so far. */
+export interface TurnState {
+    /** Which turn this is, from zero. */
+    turn: number;
+    /** Every tool result so far, in call order. */
+    results: ToolResult[];
+    /** What the last turn said, or null on the first. */
+    last: Turn | null;
+    /**
+     * What is left to spend.
+     *
+     * Put it in the prompt yourself. A loop that knows it has one turn left and
+     * does not say so gets a five-step plan and cuts it off after the first —
+     * paid for in full. Which wording works is task-specific, and injecting a
+     * sentence into your messages would break your cached prefix without asking.
+     */
+    remaining: Remaining;
+    /** Where this turn's tokens go. A no-op unless the loop was given an `emit`. */
+    emit: Emit;
+}
+/** Anything that can run a tool by name. A `toolbus()` turn satisfies it. */
+export interface Invoker {
+    invoke(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+    /**
+     * What a tool declares it does, handed to `beforeTool` so a guard can gate on
+     * the effect rather than on the name.
+     *
+     * Optional, so anything with an `invoke` is still an `Invoker`. Where it is
+     * missing every effect reads as unknown, which is what it is.
+     */
+    effectOf?(name: string): Effect | undefined;
+}
+export interface LoopOptions {
+    /** One model call. Hand it whatever your provider needs. */
+    turn(state: TurnState): Promise<Turn> | Turn;
+    /**
+     * Where the tokens go while this runs.
+     *
+     * Passed down to whatever makes the model call; omit it and nothing is
+     * emitted. `streamed()` supplies one.
+     */
+    emit?: Emit;
+    /** Runs what the model asked for. */
+    tools: Invoker;
+    /** Most model calls. Default 8. */
+    maxTurns?: number;
+    /**
+     * Stop once the turns have consumed this many tokens.
+     *
+     * Tokens rather than money because this package cannot price a call — that
+     * happens on the server, after the fact. Checked before each turn, so the
+     * ceiling is never crossed rather than merely noticed.
+     */
+    maxTokens?: number;
+    /**
+     * Summarise the older tool results once the resent context gets large.
+     *
+     * A long run gets expensive because the transcript grows, not because the
+     * work got harder. Without this the token ceiling is reached by history
+     * rather than by progress.
+     */
+    compact?: Compaction;
+    /**
+     * Deterministic code at fixed points, so a guardrail does not depend on the
+     * model having read the prompt.
+     */
+    hooks?: Hooks;
+    /** Called after each turn, so a long loop is not silent. */
+    onTurn?: (record: TurnRecord) => void;
+}
+export interface TurnRecord {
+    turn: number;
+    outcome: Turn;
+    results: ToolResult[];
+    tokens: number;
+}
+/**
+ * Why the loop ended.
+ *
+ * `finished` and `quiet` are the pair worth telling apart: the first is the
+ * model saying it is done, the second is it simply not asking for anything
+ * more — which is also what being confused looks like.
+ */
+export type LoopEnd = "finished" | "quiet" | "turns" | "tokens" | "blocked" | "failed";
+export interface LoopResult {
+    status: "completed" | "failed";
+    output: string;
+    error?: string;
+    steps: RolloutStep[];
+    outputs: Record<string, unknown>;
+    latencyMs: number;
+    inputTokens: number;
+    outputTokens: number;
+    turns: number;
+    stoppedBy: LoopEnd;
+    /** How many times the history was summarised, and how many results that replaced. */
+    compactions: {
+        count: number;
+        replaced: number;
+    };
+    /** The answer `finish` carried, when the model used it. */
+    answer?: string;
+    history: TurnRecord[];
+}