@spendgraph/workflows 0.2.0

package/dist/noesis/run/stream.d.ts

@@ -0,0 +1,28 @@
+import type { Llm } from "@spendgraph/llms";
+import type { PromptClient } from "@spendgraph/prompt";
+import type { NoesisEvent } from "../events.js";
+import type { NoesisOptions, NoesisResult } from "../types.js";
+/** A run as it happens, and the same run once it is over. */
+export interface NoesisStream extends AsyncIterable<NoesisEvent> {
+    /**
+     * The finished run.
+     *
+     * Resolves whether or not anyone iterated, and rejects where `run()` would
+     * have — watching a run changes what you can see, not what happens.
+     */
+    result: Promise<NoesisResult>;
+}
+/**
+ * `run()`, watched.
+ *
+ * The run starts on the call rather than on the first read, so a client that
+ * connects late still receives everything that already happened, and a caller
+ * who only wants the answer never has to iterate.
+ *
+ * Events arrive unwrapped — a consumer switches on `event.type` directly rather
+ * than reaching through the harness envelope the queue underneath uses.
+ *
+ * `opts.onEvent` still works and is called first, so a caller can log and
+ * stream from the same run.
+ */
+export declare function runStream(client: PromptClient, llm: Llm, question: string, opts?: NoesisOptions): NoesisStream;

package/dist/noesis/run/stream.js

@@ -0,0 +1,33 @@
+import { streamed } from "@spendgraph/harness";
+import { run } from "./run.js";
+/**
+ * `run()`, watched.
+ *
+ * The run starts on the call rather than on the first read, so a client that
+ * connects late still receives everything that already happened, and a caller
+ * who only wants the answer never has to iterate.
+ *
+ * Events arrive unwrapped — a consumer switches on `event.type` directly rather
+ * than reaching through the harness envelope the queue underneath uses.
+ *
+ * `opts.onEvent` still works and is called first, so a caller can log and
+ * stream from the same run.
+ */
+export function runStream(client, llm, question, opts = {}) {
+    const inner = streamed((_emit, note) => run(client, llm, question, {
+        ...opts,
+        onEvent: (event) => {
+            opts.onEvent?.(event);
+            note(event);
+        },
+    }));
+    return {
+        result: inner.result,
+        async *[Symbol.asyncIterator]() {
+            for await (const wrapped of inner) {
+                if (wrapped.type === "note")
+                    yield wrapped.data;
+            }
+        },
+    };
+}

package/dist/noesis/run/verify.d.ts

@@ -0,0 +1,27 @@
+import type { Llm } from "@spendgraph/llms";
+import type { PromptClient } from "@spendgraph/prompt";
+import { type Draft } from "../draft/index.js";
+import type { NoesisOptions } from "../types.js";
+import type { StageId } from "./ledger.js";
+import type { RunState } from "./state.js";
+/**
+ * Stages 5A, 5B and the pairing between them.
+ *
+ * 5B is given `blind()` rather than the questions themselves, so it answers
+ * without sight of the claims it settles. Putting the two back together is the
+ * step in between, and it stays in code for the same reason.
+ *
+ * A 5A that found nothing to check skips 5B rather than sending it an empty
+ * turn, which every provider rejects.
+ */
+export declare function checks(client: PromptClient, llm: Llm, opts: NoesisOptions, state: RunState, draft: Draft): Promise<string>;
+/**
+ * Stage R. The earliest wrong decision, and the stage to redo from.
+ *
+ * The gate says where the problem surfaced; this says where it started, which
+ * is rarely the same place and is the only one worth returning to. The gate's
+ * own suggestion is the fallback, not the answer.
+ */
+export declare function reflect(client: PromptClient, llm: Llm, question: string, opts: NoesisOptions, state: RunState, gate: StageId, reason: string, hint?: string | null): Promise<StageId | undefined>;
+/** Stage 6C. Everything the ledger holds, compiled into a claim. */
+export declare function compile(client: PromptClient, llm: Llm, question: string, opts: NoesisOptions, state: RunState): Promise<string>;

package/dist/noesis/run/verify.js

@@ -0,0 +1,78 @@
+import { unattributed } from "../attribution.js";
+import { render as renderDraft } from "../draft/index.js";
+import { invoke as coveAnswers } from "../producers/cove-answers/index.js";
+import { invoke as coveQuestions } from "../producers/cove-questions/index.js";
+import { answer } from "../producers/toulmin/index.js";
+import { invoke as reflection } from "../repair/reflection/index.js";
+import { blind, compare, render as renderChecks } from "../verify/index.js";
+import { soFar } from "./produce.js";
+import { parseStage, resumeAt } from "./redo.js";
+/**
+ * Stages 5A, 5B and the pairing between them.
+ *
+ * 5B is given `blind()` rather than the questions themselves, so it answers
+ * without sight of the claims it settles. Putting the two back together is the
+ * step in between, and it stays in code for the same reason.
+ *
+ * A 5A that found nothing to check skips 5B rather than sending it an empty
+ * turn, which every provider rejects.
+ */
+export async function checks(client, llm, opts, state, draft) {
+    const drafted = renderDraft(draft);
+    const questions = state.ledger.record("5A", await coveQuestions(client, llm, { question: drafted, ...opts.context }, opts.stage));
+    const answers = questions.questions.length
+        ? state.ledger.record("5B", await coveAnswers(client, llm, { question: blind(questions), ...opts.context }, opts.stage))
+        : { answers: [] };
+    const verification = compare(questions, answers, opts.verify?.confidenceFloor);
+    state.emit?.({
+        type: "checks.paired",
+        checked: verification.checked.length,
+        settled: verification.checked.filter((one) => one.settled).length,
+        unsettled: verification.unsettled,
+        unanswered: verification.unanswered,
+        unasked: verification.unasked,
+        overclaimed: verification.overclaimed,
+    });
+    state.ledger.record("5", {
+        data: verification,
+        rolloutIds: [],
+        model: "",
+        inputTokens: 0,
+        outputTokens: 0,
+        latencyMs: 0,
+    });
+    return `${drafted}\n\n${renderChecks(verification)}`;
+}
+/**
+ * Stage R. The earliest wrong decision, and the stage to redo from.
+ *
+ * The gate says where the problem surfaced; this says where it started, which
+ * is rarely the same place and is the only one worth returning to. The gate's
+ * own suggestion is the fallback, not the answer.
+ */
+export async function reflect(client, llm, question, opts, state, gate, reason, hint) {
+    const looked = state.ledger.record("R", await reflection(client, llm, { question: `${soFar(state, question)}\n\nThe gate said: ${reason}`, ...opts.context }, opts.stage));
+    const redoFrom = parseStage(looked.redo_from_stage) ?? parseStage(hint ?? "");
+    state.emit?.({
+        type: "reflect.pointed",
+        from: gate,
+        redoFrom,
+        resumeAt: resumeAt(redoFrom),
+        lesson: looked.lesson,
+    });
+    return redoFrom;
+}
+/** Stage 6C. Everything the ledger holds, compiled into a claim. */
+export async function compile(client, llm, question, opts, state) {
+    const answered = await answer(client, llm, { question, ...state.ledger.artifacts() }, opts.answer ?? {});
+    state.answered = answered;
+    const loose = unattributed(answered.answer, state.ledger.byStage().map((one) => one.stage));
+    state.unattributed = loose;
+    state.emit?.({
+        type: "grounds.checked",
+        cited: answered.answer.grounds?.length ?? 0,
+        unattributed: loose,
+    });
+    state.text = state.ledger.record("6C", { ...answered, data: answered.answer }).claim;
+    return state.text;
+}

package/dist/noesis/slugs.d.ts

@@ -0,0 +1,16 @@
+import type { StageId } from "./run/ledger.js";
+/**
+ * Which stage a slug belongs to.
+ *
+ * The inverse of what the fifteen modules already declare, and the reason
+ * `runStage` can announce a stage it was only ever told the slug of. A slug
+ * nobody claims is not an error — it means a caller reached `runStage` with a
+ * prompt of their own, and an event for it would be a lie.
+ *
+ * Imported from each `prompt.ts` rather than from the module's `index.ts`,
+ * which would be a cycle: an index re-exports `invoke`, `invoke` reaches
+ * `announce`, and `announce` reads this map. A computed key whose value is
+ * still uninitialised becomes the literal string "undefined" — no error, just a
+ * stage that silently never announces itself.
+ */
+export declare const STAGE_OF_SLUG: Record<string, StageId>;

package/dist/noesis/slugs.js

@@ -0,0 +1,46 @@
+import { CLOSURE_SLUG } from "./gates/closure-checklist/prompt.js";
+import { GATE_SLUG } from "./gates/cqot-gate/prompt.js";
+import { PREMORTEM_SLUG } from "./gates/premortem/prompt.js";
+import { RED_TEAM_SLUG } from "./gates/red-team/prompt.js";
+import { STANDARDS_SLUG } from "./gates/standards-review/prompt.js";
+import { CHECKPOINT_SLUG } from "./gates/think-checkpoint/prompt.js";
+import { COVE_ANSWERS_SLUG } from "./producers/cove-answers/prompt.js";
+import { COVE_QUESTIONS_SLUG } from "./producers/cove-questions/prompt.js";
+import { DECOMPOSE_SLUG } from "./producers/decompose/prompt.js";
+import { TEST_SLUG } from "./producers/discriminating-test/prompt.js";
+import { PLAN_SLUG } from "./producers/plan-candidates/prompt.js";
+import { BRIEF_SLUG } from "./producers/qn-brief/prompt.js";
+import { TOULMIN_SLUG } from "./producers/toulmin/prompt.js";
+import { REFLECTION_SLUG } from "./repair/reflection/prompt.js";
+import { TRIAGE_SLUG } from "./router/triage/prompt.js";
+/**
+ * Which stage a slug belongs to.
+ *
+ * The inverse of what the fifteen modules already declare, and the reason
+ * `runStage` can announce a stage it was only ever told the slug of. A slug
+ * nobody claims is not an error — it means a caller reached `runStage` with a
+ * prompt of their own, and an event for it would be a lie.
+ *
+ * Imported from each `prompt.ts` rather than from the module's `index.ts`,
+ * which would be a cycle: an index re-exports `invoke`, `invoke` reaches
+ * `announce`, and `announce` reads this map. A computed key whose value is
+ * still uninitialised becomes the literal string "undefined" — no error, just a
+ * stage that silently never announces itself.
+ */
+export const STAGE_OF_SLUG = {
+    [TRIAGE_SLUG]: "0",
+    [BRIEF_SLUG]: "1",
+    [DECOMPOSE_SLUG]: "2",
+    [PLAN_SLUG]: "3A",
+    [PREMORTEM_SLUG]: "3B",
+    [GATE_SLUG]: "3C",
+    [CHECKPOINT_SLUG]: "4A",
+    [TEST_SLUG]: "4B",
+    [COVE_QUESTIONS_SLUG]: "5A",
+    [COVE_ANSWERS_SLUG]: "5B",
+    [STANDARDS_SLUG]: "5C",
+    [CLOSURE_SLUG]: "6A",
+    [RED_TEAM_SLUG]: "6B",
+    [TOULMIN_SLUG]: "6C",
+    [REFLECTION_SLUG]: "R",
+};

package/dist/noesis/stage.d.ts

@@ -0,0 +1,56 @@
+import type { JsonSchema, Llm } from "@spendgraph/llms";
+import type { PromptClient } from "@spendgraph/prompt";
+import { type Asked } from "./context.js";
+import type { Emit } from "./events.js";
+import { type Usage } from "./usage.js";
+/** The reply came back, but not as the object the stage is supposed to return. */
+export declare class StageReplyError extends Error {
+    readonly slug: string;
+    readonly raw: string;
+    constructor(slug: string, raw: string);
+}
+export interface StageOptions {
+    /**
+     * Attempts for this call, counting the first. Default 2.
+     *
+     * Separate from `maxRetries`, the loop's budget for a gate sending work
+     * backwards. This one covers a call that produced nothing to think about, and
+     * the two must not share an allowance.
+     */
+    attempts?: number;
+    /** Overrides the model the `Llm` was built with. */
+    model?: string;
+    /** Merged into the request body. Where `temperature` goes, and it is per model. */
+    params?: Record<string, unknown>;
+    /**
+     * Where this stage says what it is doing.
+     *
+     * Set by `run()` on the options it threads to every stage, which is why no
+     * stage had to be edited to announce itself.
+     */
+    emit?: Emit;
+}
+export interface StageOutcome<T> extends Usage {
+    data: T;
+    rolloutId: string;
+    model: string;
+    latencyMs: number;
+    /**
+     * What the server will price this call at, still in flight.
+     *
+     * Not awaited here. A stage that stalled on a report round trip would pay it
+     * once per stage over a run, for a number nothing reads until the end — so
+     * the ledger keeps these and `settle()` folds them in once.
+     */
+    pricing?: Promise<number | undefined>;
+}
+/**
+ * One stored prompt, called and parsed.
+ *
+ * Every stage does the same four things — pull by slug, put the request through
+ * `{question}`, force the schema, hand back the object with what it cost — so
+ * they do it here rather than thirteen times over. The call is recorded once,
+ * as the prompt's rollout: the model client is told not to trace, or the same
+ * tokens land again as usage and every run prices double.
+ */
+export declare function runStage<T>(client: PromptClient, llm: Llm, slug: string, schema: JsonSchema, input: Asked, opts?: StageOptions): Promise<StageOutcome<T>>;

package/dist/noesis/stage.js

@@ -0,0 +1,52 @@
+import { asked } from "./context.js";
+import { askThrough, QUESTION_FIELD } from "./question.js";
+import { attempting } from "./retry.js";
+import { announce, failed } from "./started.js";
+import { usageOf } from "./usage.js";
+/** The reply came back, but not as the object the stage is supposed to return. */
+export class StageReplyError extends Error {
+    slug;
+    raw;
+    constructor(slug, raw) {
+        super(`${slug} returned no object matching its schema.`);
+        this.slug = slug;
+        this.raw = raw;
+        this.name = "StageReplyError";
+    }
+}
+/**
+ * One stored prompt, called and parsed.
+ *
+ * Every stage does the same four things — pull by slug, put the request through
+ * `{question}`, force the schema, hand back the object with what it cost — so
+ * they do it here rather than thirteen times over. The call is recorded once,
+ * as the prompt's rollout: the model client is told not to trace, or the same
+ * tokens land again as usage and every run prices double.
+ */
+export async function runStage(client, llm, slug, schema, input, opts = {}) {
+    announce(opts.emit, slug, opts.model);
+    return attempting(async () => {
+        const prompt = await client.pull(slug);
+        const question = asked(input);
+        let reply;
+        const outcome = await prompt.call({ [QUESTION_FIELD]: question }, async ({ messages }) => {
+            reply = await llm.call(askThrough(messages, question, slug), {
+                model: opts.model,
+                schema,
+                trace: false,
+                params: opts.params,
+            });
+            return reply;
+        });
+        if (reply?.data === undefined)
+            throw new StageReplyError(slug, outcome.output);
+        return {
+            ...usageOf(outcome),
+            ...(outcome.pricing ? { pricing: outcome.pricing } : {}),
+            data: reply.data,
+            rolloutId: outcome.rolloutId,
+            model: outcome.model,
+            latencyMs: reply.latencyMs ?? 0,
+        };
+    }, { attempts: opts.attempts, onFailure: (err) => failed(opts.emit, slug, err) });
+}

package/dist/noesis/started.d.ts

@@ -0,0 +1,18 @@
+import type { Emit } from "./events.js";
+/**
+ * Say a stage has begun, if anyone is listening and the slug is one of ours.
+ *
+ * Shared by the three call paths — `runStage` and the copies triage and 6C keep
+ * — so the three of them cannot drift on what a `stage.started` looks like.
+ */
+export declare function announce(emit: Emit | undefined, slug: string, model?: string): void;
+/**
+ * Say a stage did not produce what it was asked for.
+ *
+ * The kind is read off the error's name rather than by importing the three
+ * reply errors, which would be a cycle — `stage.ts` reaches this file, and the
+ * errors live beside the calls that throw them. Every one of them ends in
+ * `ReplyError`, and that is the distinction worth drawing: a reply that came
+ * back wrong is the prompt's problem, anything else is the provider's.
+ */
+export declare function failed(emit: Emit | undefined, slug: string, err: unknown): void;

package/dist/noesis/started.js

@@ -0,0 +1,39 @@
+import { STAGE_NAMES } from "./run/ledger.js";
+import { STAGE_OF_SLUG } from "./slugs.js";
+/**
+ * Say a stage has begun, if anyone is listening and the slug is one of ours.
+ *
+ * Shared by the three call paths — `runStage` and the copies triage and 6C keep
+ * — so the three of them cannot drift on what a `stage.started` looks like.
+ */
+export function announce(emit, slug, model) {
+    if (!emit)
+        return;
+    const stage = STAGE_OF_SLUG[slug];
+    if (!stage)
+        return;
+    emit({ type: "stage.started", stage, name: STAGE_NAMES[stage], slug, model });
+}
+const message = (err) => (err instanceof Error ? err.message : String(err));
+/**
+ * Say a stage did not produce what it was asked for.
+ *
+ * The kind is read off the error's name rather than by importing the three
+ * reply errors, which would be a cycle — `stage.ts` reaches this file, and the
+ * errors live beside the calls that throw them. Every one of them ends in
+ * `ReplyError`, and that is the distinction worth drawing: a reply that came
+ * back wrong is the prompt's problem, anything else is the provider's.
+ */
+export function failed(emit, slug, err) {
+    if (!emit)
+        return;
+    const stage = STAGE_OF_SLUG[slug];
+    if (!stage)
+        return;
+    emit({
+        type: "stage.failed",
+        stage,
+        kind: err instanceof Error && err.name.endsWith("ReplyError") ? "reply" : "transport",
+        error: message(err),
+    });
+}

package/dist/noesis/types.d.ts

@@ -0,0 +1,167 @@
+import type { ToolBus } from "@spendgraph/tools";
+import type { Asked } from "./context.js";
+import type { NoesisEvent } from "./events.js";
+import type { SubQuestionTool } from "./producers/decompose/index.js";
+import type { AnswerOptions, AnswerResult } from "./producers/toulmin/index.js";
+import type { TriageEstimates, TriageInput, TriageOptions } from "./router/triage/index.js";
+import type { Escalation, StageUsage } from "./run/ledger.js";
+import type { StageOptions } from "./stage.js";
+import type { Usage } from "./usage.js";
+/**
+ * How much of the loop a question earns.
+ *
+ * Derived in code from the triage estimates, which is what the router prompt
+ * itself says: it returns signals and never a route.
+ */
+export type Route = "direct" | "retrieve" | "standard" | "full";
+/** What the estimates decide, before any of it is acted on. */
+export interface Routing {
+    route: Route;
+    /** True where 6B runs before the answer is allowed out. */
+    redTeam: boolean;
+    /** Which signal decided it, for the record and for tuning the thresholds. */
+    reason: string;
+}
+/**
+ * What a stage wants a person for, while the run is still going.
+ *
+ * Returning a replacement question restarts the framing with it; returning
+ * nothing carries on with the question as asked. The only stage that asks is 1,
+ * and only when it says the asker aimed at the wrong thing.
+ */
+export type Ask = (asked: AskedOfYou) => Promise<string | undefined> | string | undefined;
+export interface AskedOfYou {
+    /** The question as it was put. */
+    question: string;
+    /** What stage 1 thinks should have been asked instead. */
+    better: string;
+    /** Why it says so. */
+    reason: string;
+}
+export interface RetrieveOptions {
+    /**
+     * What a lookup reaches for. Default `"deeprecall"`.
+     *
+     * Triage says how much a question needs a tool and never which one, so the
+     * route picks. The enum is ordered cheapest first and the knowledge base
+     * comes before the open web, which is the same preference.
+     */
+    tool?: SubQuestionTool;
+}
+export interface VerifyOptions {
+    /**
+     * The confidence a blind check has to reach before it settles a claim.
+     * Default 0.6.
+     *
+     * Exposed for the same reason `route.ts` exposes its thresholds: it decides
+     * how much of stage 5 comes back `unsettled`, which is what 5C and 6A read,
+     * and moving it is a calibration rather than a rewrite.
+     */
+    confidenceFloor?: number;
+}
+export interface NoesisOptions {
+    /**
+     * Everything triage takes except the question, which `run()` supplies.
+     *
+     * `currentTask` is the one worth passing on a second turn — it seeds the run
+     * and comes back on the result, updated.
+     */
+    triage?: Omit<TriageInput, "question"> & TriageOptions;
+    /** The tools any route that looks something up may reach for. */
+    tools?: ToolBus;
+    /**
+     * The `now` and `locale` every stage is given rather than asked for.
+     *
+     * Without them anything turning on the date or the jurisdiction comes back as
+     * something the stage does not know.
+     */
+    context?: Omit<Asked, "question">;
+    /** Model and params for every stage between triage and the answer. */
+    stage?: StageOptions;
+    /**
+     * Reached when a stage wants a person before it can go on.
+     *
+     * Without one the run proceeds on the question as asked, which is what it did
+     * before anybody could be asked at all.
+     */
+    onAsk?: Ask;
+    /** Reached once an answer is trustworthy. Never on an abstention or an escalation. */
+    onDeliver?: (result: NoesisResult) => Promise<unknown> | unknown;
+    /**
+     * Reached as the run happens, for a progress display.
+     *
+     * Synchronous and fire-and-forget: a listener that throws is swallowed, and a
+     * slow one blocks the loop, so write to a queue rather than to a socket. For
+     * an async iterable instead of a callback, use `runStream()`.
+     */
+    onEvent?: (event: NoesisEvent) => void;
+    /**
+     * How many times a gate may send work backwards before the run asks for a
+     * person. Default 5, counted across every gate together.
+     */
+    maxRetries?: number;
+    retrieve?: RetrieveOptions;
+    /** How the blind checks in stage 5 are read. */
+    verify?: VerifyOptions;
+    answer?: AnswerOptions;
+}
+/**
+ * Whether the answer can be acted on.
+ *
+ * `abstained` is 6C saying the grounds supported no claim, or no tier clearing
+ * the confidence bar. `escalated` is a gate or a spent retry budget asking for
+ * a person. Both still carry `text`, because saying what is not known is an
+ * answer — it is just not one to build on.
+ */
+export type Status = "answered" | "abstained" | "escalated";
+export interface NoesisResult {
+    /** The reply, as a person reads it. */
+    text: string;
+    status: Status;
+    /** Set where a gate or the retry budget asked for a person. */
+    escalation?: Escalation;
+    route: Route;
+    routing: Routing;
+    estimates: TriageEstimates;
+    /** The open task after this run. Pass it to the next one as `opts.triage.currentTask`. */
+    currentTask: string;
+    answer: AnswerResult;
+    /** Every rollout the run recorded, triage first. */
+    rolloutIds: string[];
+    /**
+     * `source_stage` values the answer cited that no stage in this run produced.
+     *
+     * Empty on a healthy run. A non-empty list is the answer citing evidence the
+     * loop never gathered, which is worth seeing before the claim is acted on.
+     */
+    unattributed: string[];
+    /**
+     * Every token the run was billed for.
+     *
+     * Six numbers, not two: a cached read and a cache write are priced apart from
+     * a fresh input token, and a grounded or thinking model bills citations and
+     * reasoning on their own lines. `byModel` is the split a price list can
+     * actually be applied to — 6C cascades, so one run can span two models at
+     * different rates.
+     *
+     * A back edge does not refund anything. Retries are counted here in full even
+     * where `dropFrom` threw the artifacts away.
+     *
+     * Tool spend is not here. A tool call is no rollout and no tokens of ours;
+     * `deep_recall` reports `costMicroUsd` and `web_search` its own token counts,
+     * each inside its own output under the stage `4` artifact.
+     */
+    usage: RunUsage;
+    /** @deprecated Read `usage.inputTokens`. Kept so existing callers still work. */
+    inputTokens: number;
+    /** @deprecated Read `usage.outputTokens`. Kept so existing callers still work. */
+    outputTokens: number;
+    latencyMs: number;
+}
+export interface RunUsage extends Usage {
+    /** Summed over every time the loop ran each stage. */
+    byStage: StageUsage[];
+    byModel: Record<string, Usage>;
+    /** Model calls made, counting a stage the loop ran more than once each time. */
+    calls: number;
+}

package/dist/noesis/types.js

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

package/dist/noesis/usage.d.ts

@@ -0,0 +1,49 @@
+/**
+ * What one call cost, in tokens.
+ *
+ * Six numbers rather than two because four of them are billed separately: a
+ * cached read is a fraction of a fresh input token and a cache write is more
+ * than one, and a grounded or thinking model bills citations and reasoning on
+ * their own lines. Summing only `inputTokens` prices a cached run too high and
+ * a grounded one too low.
+ */
+export interface Usage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    citationTokens: number;
+    reasoningTokens: number;
+    /**
+     * What the calls cost, in micro-USD, where the server priced them.
+     *
+     * Undefined rather than zero when nothing priced it, because the two are not
+     * the same claim: zero says the call was free, undefined says nobody knows.
+     * A run summed as zero would read as a free run, which is the one wrong
+     * answer a cost report must not give.
+     *
+     * This is the number to compare routes on. Tokens cannot be: 6C cascades
+     * cheap to expensive, so adding a haiku token to a sonnet token adds two
+     * different prices as though they were one unit, and an escalation reads as
+     * twice the tokens while costing far more than twice the money.
+     */
+    costMicros?: number;
+}
+/** What a call reports, where every field is optional. */
+export type PartialUsage = Partial<Usage>;
+export declare const NO_USAGE: Usage;
+/** Every token field filled, so a caller never has to guard one. Cost stays absent when it is. */
+export declare const usageOf: (reported: PartialUsage) => Usage;
+export declare const addUsage: (total: Usage, next: PartialUsage) => Usage;
+/** Every token the call is billed for, however the provider split them. */
+export declare const billableTokens: (usage: Usage) => number;
+/** What the run is known to have cost, in micro-USD, or undefined where nothing priced it. */
+export declare const spend: (usage: Usage) => number | undefined;
+/**
+ * One price for several calls: undefined unless at least one of them was priced.
+ *
+ * The cascade in 6C runs a tier at a time, so a run can hold several prices
+ * still in flight. Summing them with `?? 0` alone would turn "nobody priced
+ * any of these" into a confident zero.
+ */
+export declare const totalCost: (costs: (number | undefined)[]) => number | undefined;