@spendgraph/harness 0.1.0 → 0.2.0

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[];
+}

package/dist/loop/types.js

@@ -0,0 +1 @@
+export {};

package/dist/orchestrate/index.d.ts

@@ -0,0 +1,4 @@
+export { orchestrate } from "./orchestrate.js";
+export { capped, planStep } from "./plan.js";
+export type { OrchestrateEnd, OrchestrateOptions, OrchestrateResult, Outcome, Plan, Subtask, } from "./types.js";
+export { synthesisStep, work } from "./work.js";

package/dist/orchestrate/index.js

@@ -0,0 +1,3 @@
+export { orchestrate } from "./orchestrate.js";
+export { capped, planStep } from "./plan.js";
+export { synthesisStep, work } from "./work.js";

package/dist/orchestrate/orchestrate.d.ts

@@ -0,0 +1,12 @@
+import type { OrchestrateOptions, OrchestrateResult } from "./types.js";
+/**
+ * A lead decomposes, workers do the pieces, the lead puts it back together.
+ *
+ * The workflow for work whose shape is not known until the input is read — the
+ * difference from `chain`, where the stages are named in advance.
+ *
+ * It is also the one that can spend the most: the lead decides how many calls
+ * to make, so `maxWorkers` is a cap on something a model chose rather than on
+ * something you did.
+ */
+export declare function orchestrate(values: Record<string, unknown>, opts: OrchestrateOptions): Promise<OrchestrateResult>;

package/dist/orchestrate/orchestrate.js

@@ -0,0 +1,68 @@
+import { capped, planStep } from "./plan.js";
+import { synthesisStep, work } from "./work.js";
+function tokens(steps) {
+    let inputTokens = 0;
+    let outputTokens = 0;
+    for (const step of steps) {
+        inputTokens += step.inputTokens ?? 0;
+        outputTokens += step.outputTokens ?? 0;
+    }
+    return { inputTokens, outputTokens };
+}
+/**
+ * A lead decomposes, workers do the pieces, the lead puts it back together.
+ *
+ * The workflow for work whose shape is not known until the input is read — the
+ * difference from `chain`, where the stages are named in advance.
+ *
+ * It is also the one that can spend the most: the lead decides how many calls
+ * to make, so `maxWorkers` is a cap on something a model chose rather than on
+ * something you did.
+ */
+export async function orchestrate(values, opts) {
+    const startedAt = Date.now();
+    const steps = [];
+    let subtasks = [];
+    let dropped = [];
+    let results = [];
+    const finish = (status, stoppedBy, output, error) => ({
+        status,
+        output,
+        error,
+        steps,
+        outputs: { subtasks, results },
+        latencyMs: Date.now() - startedAt,
+        ...tokens(steps),
+        subtasks,
+        dropped,
+        ran: results.filter((r) => r.status === "completed").map((r) => r.name),
+        failed: results.filter((r) => r.status === "failed").map((r) => r.name),
+        stoppedBy,
+    });
+    const plan = await opts.plan(values);
+    ({ subtasks, dropped } = capped(plan, opts.maxWorkers));
+    steps.push(planStep(steps.length, plan, dropped));
+    opts.onPlan?.(plan, dropped);
+    if (subtasks.length === 0) {
+        // Nothing to delegate. Handing back the lead's own words beats synthesising
+        // over an empty list, which invents an answer from nothing.
+        return finish("completed", "planned-nothing", plan.output ?? "");
+    }
+    const spentOnPlan = (plan.inputTokens ?? 0) + (plan.outputTokens ?? 0);
+    if (opts.maxTokens !== undefined && spentOnPlan >= opts.maxTokens) {
+        return finish("failed", "tokens", "", "The plan alone reached the token ceiling.");
+    }
+    const done = await work(subtasks, values, opts);
+    steps.push(...done.steps.map((step, at) => ({ ...step, index: steps.length + at })));
+    results = done.results;
+    if (done.status === "failed") {
+        return finish("failed", "workers-failed", "", done.error);
+    }
+    const { inputTokens, outputTokens } = tokens(steps);
+    if (opts.maxTokens !== undefined && inputTokens + outputTokens >= opts.maxTokens) {
+        return finish("failed", "tokens", "", "The workers reached the token ceiling before synthesis.");
+    }
+    const synthesis = await opts.synthesise(results.filter((r) => r.status === "completed"), values, (text, stage) => opts.emit?.(text, stage ?? "synthesis"));
+    steps.push(synthesisStep(steps.length, synthesis));
+    return finish("completed", "completed", synthesis.output);
+}

package/dist/orchestrate/plan.d.ts

@@ -0,0 +1,18 @@
+import type { RolloutStep } from "@spendgraph/sdk";
+import type { Plan, Subtask } from "./types.js";
+/**
+ * The subtasks that will run, and the ones the cap refused.
+ *
+ * Dropping the tail rather than the head: a lead asked for the most important
+ * piece first usually gives it first, and truncating from the front would throw
+ * away exactly what it thought mattered.
+ *
+ * Duplicated names are made unique rather than rejected — a lead naming two
+ * sections "summary" is a wording problem, not a reason to lose the run.
+ */
+export declare function capped(plan: Plan, max?: number): {
+    subtasks: Subtask[];
+    dropped: Subtask[];
+};
+/** The lead's own call as a step, because deciding is not free. */
+export declare function planStep(index: number, plan: Plan, dropped: Subtask[]): RolloutStep;

package/dist/orchestrate/plan.js

@@ -0,0 +1,38 @@
+const DEFAULT_MAX_WORKERS = 5;
+/**
+ * The subtasks that will run, and the ones the cap refused.
+ *
+ * Dropping the tail rather than the head: a lead asked for the most important
+ * piece first usually gives it first, and truncating from the front would throw
+ * away exactly what it thought mattered.
+ *
+ * Duplicated names are made unique rather than rejected — a lead naming two
+ * sections "summary" is a wording problem, not a reason to lose the run.
+ */
+export function capped(plan, max = DEFAULT_MAX_WORKERS) {
+    const limit = Math.max(1, max);
+    const seen = new Map();
+    const named = plan.subtasks.map((subtask) => {
+        const count = seen.get(subtask.name) ?? 0;
+        seen.set(subtask.name, count + 1);
+        return count === 0 ? subtask : { ...subtask, name: `${subtask.name}_${count}` };
+    });
+    return { subtasks: named.slice(0, limit), dropped: named.slice(limit) };
+}
+/** The lead's own call as a step, because deciding is not free. */
+export function planStep(index, plan, dropped) {
+    return {
+        index,
+        source: "plan",
+        model: plan.model,
+        output: plan.output ?? JSON.stringify(plan.subtasks.map((s) => s.name)),
+        status: "completed",
+        inputTokens: plan.inputTokens,
+        outputTokens: plan.outputTokens,
+        ...(dropped.length > 0
+            ? {
+                error: `${dropped.length} subtask(s) past the worker cap were dropped: ${dropped.map((s) => s.name).join(", ")}`,
+            }
+            : {}),
+    };
+}

package/dist/orchestrate/types.d.ts

@@ -0,0 +1,75 @@
+import type { RolloutStep } from "@spendgraph/sdk";
+import type { TaskResult } from "../parallel/index.js";
+import type { Emit } from "../stream/index.js";
+/** One piece of work the lead invented. Anything else on it is yours. */
+export interface Subtask {
+    /** Unique in the run, and the name its step is recorded under. */
+    name: string;
+    [key: string]: unknown;
+}
+/** What the lead decided to do, and what deciding cost. */
+export interface Plan {
+    subtasks: Subtask[];
+    output?: string;
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+}
+/** What a worker or the synthesis produced. */
+export interface Outcome {
+    output: string;
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+}
+export interface OrchestrateOptions {
+    /** The lead reads the input and says what the pieces are. */
+    plan(values: Record<string, unknown>): Promise<Plan> | Plan;
+    /** One piece of work. */
+    work(subtask: Subtask, values: Record<string, unknown>, emit: Emit): Promise<Outcome> | Outcome;
+    /** The lead turns what came back into the answer. */
+    synthesise(results: TaskResult[], values: Record<string, unknown>, emit: Emit): Promise<Outcome> | Outcome;
+    /**
+     * 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;
+    /**
+     * Most workers to run. Default 5.
+     *
+     * The failure this exists for: a lead asked to decompose a large input
+     * invents twelve subtasks, and twelve model calls leave before anyone has
+     * decided that was reasonable. Anything past the cap is dropped and **said**,
+     * never dropped quietly.
+     */
+    maxWorkers?: number;
+    /** Most workers in flight at once. Default 4. */
+    concurrency?: number;
+    /** How many must succeed before synthesising. Defaults to all that ran. */
+    minSuccess?: number;
+    /** Checked before the workers and before the synthesis. */
+    maxTokens?: number;
+    onPlan?: (plan: Plan, dropped: Subtask[]) => void;
+    onWork?: (result: TaskResult) => void;
+}
+/** Why it ended. `planned-nothing` is the lead finding no work to do. */
+export type OrchestrateEnd = "completed" | "planned-nothing" | "workers-failed" | "tokens" | "failed";
+export interface OrchestrateResult {
+    status: "completed" | "failed";
+    output: string;
+    error?: string;
+    steps: RolloutStep[];
+    outputs: Record<string, unknown>;
+    latencyMs: number;
+    inputTokens: number;
+    outputTokens: number;
+    /** What the lead asked for, after the cap. */
+    subtasks: Subtask[];
+    /** What the cap refused. Empty when the lead stayed within it. */
+    dropped: Subtask[];
+    ran: string[];
+    failed: string[];
+    stoppedBy: OrchestrateEnd;
+}

package/dist/orchestrate/types.js

@@ -0,0 +1 @@
+export {};

package/dist/orchestrate/work.d.ts

@@ -0,0 +1,13 @@
+import type { RolloutStep } from "@spendgraph/sdk";
+import { type ParallelResult } from "../parallel/index.js";
+import type { OrchestrateOptions, Outcome, Subtask } from "./types.js";
+/**
+ * Every worker at once.
+ *
+ * Delegated to `parallel` rather than fanned out again here: it already caps the
+ * concurrency, already turns a thrown worker into a result so the others land,
+ * and already numbers the steps by declaration so two runs can be compared.
+ */
+export declare function work(subtasks: Subtask[], values: Record<string, unknown>, opts: OrchestrateOptions): Promise<ParallelResult>;
+/** The lead's second call as a step. */
+export declare function synthesisStep(index: number, outcome: Outcome): RolloutStep;

package/dist/orchestrate/work.js

@@ -0,0 +1,35 @@
+import { parallel } from "../parallel/index.js";
+/**
+ * Every worker at once.
+ *
+ * Delegated to `parallel` rather than fanned out again here: it already caps the
+ * concurrency, already turns a thrown worker into a result so the others land,
+ * and already numbers the steps by declaration so two runs can be compared.
+ */
+export function work(subtasks, values, opts) {
+    return parallel(values, {
+        tasks: subtasks.map((subtask) => ({
+            name: subtask.name,
+            run: (_values, emit) => opts.work(subtask, values, emit),
+        })),
+        emit: opts.emit,
+        concurrency: opts.concurrency,
+        minSuccess: opts.minSuccess ?? subtasks.length,
+        onTask: opts.onWork,
+        // `orchestrate` synthesises with the lead rather than merging here, so this
+        // only has to hand the results back untouched.
+        merge: (results) => results,
+    });
+}
+/** The lead's second call as a step. */
+export function synthesisStep(index, outcome) {
+    return {
+        index,
+        source: "synthesise",
+        model: outcome.model,
+        output: outcome.output,
+        status: "completed",
+        inputTokens: outcome.inputTokens,
+        outputTokens: outcome.outputTokens,
+    };
+}

package/dist/parallel/index.d.ts

@@ -0,0 +1,4 @@
+export { majority, repeat, type Vote } from "./merge.js";
+export { parallel } from "./parallel.js";
+export { runTask, taskStep } from "./task.js";
+export type { ParallelOptions, ParallelResult, Task, TaskResult } from "./types.js";

package/dist/parallel/index.js

@@ -0,0 +1,3 @@
+export { majority, repeat } from "./merge.js";
+export { parallel } from "./parallel.js";
+export { runTask, taskStep } from "./task.js";

package/dist/parallel/merge.d.ts

@@ -0,0 +1,26 @@
+import type { Task, TaskResult } from "./types.js";
+/**
+ * The same task, N times over, for voting.
+ *
+ * An odd N on purpose — an even one ties, and a tie has no answer that is not
+ * arbitrary. Ask for an even number and you get the next one up.
+ */
+export declare function repeat(name: string, times: number, run: (values: Record<string, unknown>, at: number) => Promise<unknown> | unknown): Task[];
+export interface Vote<T = unknown> {
+    value: T;
+    /** How many of the tasks agreed on it. */
+    count: number;
+    /** Of the ones that succeeded. */
+    of: number;
+}
+/**
+ * The answer most of them gave.
+ *
+ * Voting is worth the tokens where a model is right most of the time and wrong
+ * differently each time — the wrong answers scatter and the right one repeats.
+ * It buys nothing where the model is confidently wrong the same way every time,
+ * which is the failure it is easiest to mistake it for a fix for.
+ *
+ * Ties go to the first declared, so the result is the same on every run.
+ */
+export declare function majority<T = unknown>(results: TaskResult[]): Vote<T> | undefined;

package/dist/parallel/merge.js

@@ -0,0 +1,52 @@
+/**
+ * The same task, N times over, for voting.
+ *
+ * An odd N on purpose — an even one ties, and a tie has no answer that is not
+ * arbitrary. Ask for an even number and you get the next one up.
+ */
+export function repeat(name, times, run) {
+    const odd = Math.max(1, times % 2 === 0 ? times + 1 : times);
+    return Array.from({ length: odd }, (_, at) => ({
+        name: `${name}_${at}`,
+        run: (values) => run(values, at),
+    }));
+}
+/** How a value is compared when voting. Its own text, or the whole thing. */
+function ballot(value) {
+    if (value &&
+        typeof value === "object" &&
+        typeof value.output === "string") {
+        return value.output;
+    }
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+/**
+ * The answer most of them gave.
+ *
+ * Voting is worth the tokens where a model is right most of the time and wrong
+ * differently each time — the wrong answers scatter and the right one repeats.
+ * It buys nothing where the model is confidently wrong the same way every time,
+ * which is the failure it is easiest to mistake it for a fix for.
+ *
+ * Ties go to the first declared, so the result is the same on every run.
+ */
+export function majority(results) {
+    const done = results.filter((r) => r.status === "completed");
+    if (done.length === 0)
+        return undefined;
+    const tally = new Map();
+    for (const result of done) {
+        const key = ballot(result.value);
+        const seen = tally.get(key);
+        if (seen)
+            seen.count++;
+        else
+            tally.set(key, { value: result.value, count: 1 });
+    }
+    let best = { value: done[0].value, count: 0 };
+    for (const entry of tally.values()) {
+        if (entry.count > best.count)
+            best = entry;
+    }
+    return { value: best.value, count: best.count, of: done.length };
+}

package/dist/parallel/parallel.d.ts

@@ -0,0 +1,12 @@
+import type { ParallelOptions, ParallelResult } from "./types.js";
+/**
+ * Every task at once, then one answer out of what came back.
+ *
+ * Not compiled to a graph like `route` and `chain`: `@spendgraph/graph` walks one
+ * node at a time and picks a single edge, so a fan-out is not a shape it can
+ * express. The concurrency comes from `mapLimit`, which already exists.
+ *
+ * A task that throws is a result, not an exception — the point of running five
+ * is that the other four still land.
+ */
+export declare function parallel(values: Record<string, unknown>, opts: ParallelOptions): Promise<ParallelResult>;

package/dist/parallel/parallel.js

@@ -0,0 +1,66 @@
+import { mapLimit } from "@spendgraph/prompt/internals";
+import { runTask, taskStep } from "./task.js";
+const DEFAULT_CONCURRENCY = 4;
+function totals(results) {
+    let inputTokens = 0;
+    let outputTokens = 0;
+    for (const result of results) {
+        inputTokens += result.inputTokens;
+        outputTokens += result.outputTokens;
+    }
+    return { inputTokens, outputTokens };
+}
+function stringify(value) {
+    if (value === undefined || value === null)
+        return "";
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+/**
+ * Every task at once, then one answer out of what came back.
+ *
+ * Not compiled to a graph like `route` and `chain`: `@spendgraph/graph` walks one
+ * node at a time and picks a single edge, so a fan-out is not a shape it can
+ * express. The concurrency comes from `mapLimit`, which already exists.
+ *
+ * A task that throws is a result, not an exception — the point of running five
+ * is that the other four still land.
+ */
+export async function parallel(values, opts) {
+    if (opts.tasks.length === 0)
+        throw new Error("A parallel run needs at least one task.");
+    const names = new Set();
+    for (const task of opts.tasks) {
+        if (names.has(task.name))
+            throw new Error(`Two tasks are called "${task.name}".`);
+        names.add(task.name);
+    }
+    const startedAt = Date.now();
+    const results = await mapLimit(opts.tasks, opts.concurrency ?? DEFAULT_CONCURRENCY, async (task) => {
+        const result = await runTask(task, values, opts.emit);
+        opts.onTask?.(result);
+        return result;
+    });
+    const steps = results.map((result, at) => taskStep(at, result));
+    const succeeded = results.filter((r) => r.status === "completed");
+    const needed = opts.minSuccess ?? opts.tasks.length;
+    const outputs = Object.fromEntries(results.map((r) => [r.name, r.value]));
+    const base = {
+        steps,
+        outputs,
+        latencyMs: Date.now() - startedAt,
+        ...totals(results),
+        results,
+        succeeded: succeeded.map((r) => r.name),
+        failed: results.filter((r) => r.status === "failed").map((r) => r.name),
+    };
+    if (succeeded.length < needed) {
+        return {
+            ...base,
+            status: "failed",
+            output: "",
+            error: `${succeeded.length} of ${opts.tasks.length} tasks succeeded, and ${needed} were needed.`,
+        };
+    }
+    const merged = opts.merge(succeeded, values);
+    return { ...base, status: "completed", output: stringify(merged), merged };
+}

package/dist/parallel/task.d.ts

@@ -0,0 +1,13 @@
+import type { RolloutStep } from "@spendgraph/sdk";
+import type { Emit } from "../stream/index.js";
+import type { Task, TaskResult } from "./types.js";
+/** Runs one task. Never throws — a failure is a result, so the others still land. */
+export declare function runTask(task: Task, values: Record<string, unknown>, emit?: Emit): Promise<TaskResult>;
+/**
+ * One task as a step.
+ *
+ * Indexed by where it was declared rather than when it landed: a fan-out that
+ * numbered its steps by completion order would record a different run every
+ * time for the same work, which makes two runs impossible to compare.
+ */
+export declare function taskStep(index: number, result: TaskResult): RolloutStep;

package/dist/parallel/task.js

@@ -0,0 +1,45 @@
+function counted(value) {
+    return value && typeof value === "object" ? value : {};
+}
+/** Runs one task. Never throws — a failure is a result, so the others still land. */
+export async function runTask(task, values, emit) {
+    try {
+        const value = await task.run(values, (text, stage) => emit?.(text, stage ?? task.name));
+        const { inputTokens = 0, outputTokens = 0 } = counted(value);
+        return { name: task.name, status: "completed", value, inputTokens, outputTokens };
+    }
+    catch (err) {
+        return {
+            name: task.name,
+            status: "failed",
+            error: err instanceof Error ? err.message : String(err),
+            inputTokens: 0,
+            outputTokens: 0,
+        };
+    }
+}
+/**
+ * One task as a step.
+ *
+ * Indexed by where it was declared rather than when it landed: a fan-out that
+ * numbered its steps by completion order would record a different run every
+ * time for the same work, which makes two runs impossible to compare.
+ */
+export function taskStep(index, result) {
+    const { output, model } = counted(result.value);
+    return {
+        index,
+        source: result.name,
+        model,
+        output: result.status === "completed" ? (output ?? stringify(result.value)) : "",
+        status: result.status,
+        error: result.error,
+        inputTokens: result.inputTokens,
+        outputTokens: result.outputTokens,
+    };
+}
+function stringify(value) {
+    if (value === undefined || value === null)
+        return "";
+    return typeof value === "string" ? value : JSON.stringify(value);
+}