@spendgraph/workflows 0.2.1 → 0.3.1

package/README.md

@@ -70,6 +70,59 @@ answer. Stage 5 pairs 5A's claims back to 5B's blind answers, and it has to be
 code: whatever does it sees both the claim and the answer written without it,
 and a model given both is no longer a blind check of anything.
 
+## Choosing models
+
+`stage` sets the model every stage runs on. `stages` overrides it by name, for
+the stages worth paying more or less for.
+
+```ts
+await run(client, llm, question, {
+  stage: { model: "claude-haiku-4-5" },
+  stages: {
+    plan_candidates: { model: "claude-sonnet-4-6" },
+    red_team: { model: "claude-opus-4-8" },
+    answer: { model: "claude-sonnet-4-6" },
+  },
+});
+```
+
+The keys are the stage names from the table above with the spaces closed up —
+`triage`, `question_brief`, `plan_candidates`, `red_team`, `answer` — and
+`STAGE_KEYS` maps every id to its own. `triage` and `answer` also have
+`opts.triage` and `opts.answer`, which
+take more than a model — a current task, and the answer's escalating tiers —
+and win where both are set.
+
+**`params` does not follow a model it was not written for.** A stage naming its
+own `model` gets its own `params` or none: Haiku takes `temperature`, Sonnet 5
+rejects it outright, and one shared request body fails on whichever it was not
+written for. A stage overriding only `params` still merges over `stage` — except
+`answer`, which escalates through tiers, so its `params` reach it only alongside
+a `model`.
+
+## What a run cost
+
+`usage` is the model spend: six numbers rather than two, summed across every
+stage and every retry, split `byStage` and `byModel` because the answer can
+cascade. A back edge refunds nothing.
+
+`usage.tools` is what the tools reported, and it is deliberately **not** folded
+in — a tool call is somebody else's API at somebody else's rates and is no
+rollout of ours.
+
+```ts
+result.usage.inputTokens;              // the model side
+result.usage.byModel["claude-sonnet-4-6"];
+
+result.usage.tools.calls;              // the tool side
+result.usage.tools.costMicros;         // where a tool priced itself
+result.usage.tools.byTool.web_search;  // tokens, keyed by the tool that ran
+```
+
+Bill both or you undercharge every run that touched the web: `web_search`
+reports Perplexity's four token counts and `deep_recall` reports micro-USD,
+and stage 4 records zero tokens of its own.
+
 ## The ledger
 
 Every stage files its result, its rollouts and its tokens in one place. That

package/dist/noesis/execute/execute.js

@@ -1,4 +1,5 @@
 import { order } from "./order.js";
+import { toolSpendOf } from "./spend.js";
 export const DEFAULT_TOOLS = {
     calculator: { name: "calculate", arg: "expression" },
     deeprecall: { name: "deep_recall", arg: "question" },
@@ -63,6 +64,7 @@ export async function execute(bus, plan, opts = {}) {
     return {
         answers,
         unresolved,
+        spend: toolSpendOf(answers, wiring),
         toolMs: answers.reduce((total, answer) => total + answer.latencyMs, 0),
     };
 }

package/dist/noesis/execute/index.d.ts

@@ -1,3 +1,5 @@
 export { DEFAULT_TOOLS, execute } from "./execute.js";
 export { order } from "./order.js";
 export type { ExecuteOptions, Execution, SubAnswer, Waves, Wiring } from "./types.js";
+export type { ToolSpend, ToolUsage } from "./spend.js";
+export { addToolSpend, NO_TOOL_SPEND, readToolUsage, recorded, toolSpendOf } from "./spend.js";

package/dist/noesis/execute/index.js

@@ -1,2 +1,3 @@
 export { DEFAULT_TOOLS, execute } from "./execute.js";
 export { order } from "./order.js";
+export { addToolSpend, NO_TOOL_SPEND, readToolUsage, recorded, toolSpendOf } from "./spend.js";

package/dist/noesis/execute/spend.d.ts

@@ -0,0 +1,45 @@
+import type { Execution, SubAnswer, Wiring } from "./types.js";
+import type { SubQuestionTool } from "../producers/decompose/index.js";
+/** What one tool reported it cost, keyed by the tool that reported it. */
+export interface ToolSpend {
+    /** Tool calls that ran, whether or not the tool priced itself. */
+    calls: number;
+    /** Summed where a tool priced itself. Undefined where none did. */
+    costMicros?: number;
+    byTool: Record<string, ToolUsage>;
+}
+export interface ToolUsage {
+    calls: number;
+    model?: string;
+    inputTokens: number;
+    outputTokens: number;
+    citationTokens: number;
+    reasoningTokens: number;
+    costMicros?: number;
+}
+export declare const NO_TOOL_SPEND: ToolSpend;
+/**
+ * What a tool result says it cost, read by duck typing.
+ *
+ * A tool is somebody else's API and prices itself however it likes: `web_search`
+ * reports Perplexity's four token counts, `deep_recall` reports micro-USD. Both
+ * are read where present and nothing is invented where absent.
+ */
+export declare function readToolUsage(result: unknown): Omit<ToolUsage, "calls"> | null;
+/**
+ * Every tool call in one execution, summed under the tool that actually ran.
+ *
+ * Keyed by the bus tool's name rather than the sub-question's, because that is
+ * the one a rate applies to and the one the bus offered.
+ */
+export declare function toolSpendOf(answers: SubAnswer[], wiring?: Partial<Record<SubQuestionTool, Wiring>>): ToolSpend;
+/** Two executions' tool spend, added. A retry does not refund the first attempt. */
+export declare function addToolSpend(a: ToolSpend, b: ToolSpend): ToolSpend;
+/**
+ * The execution as the ledger should keep it: everything but the billing.
+ *
+ * Stage 4's artifact is serialized into every later stage's prompt and into the
+ * answer's evidence, so what a tool cost would ride along as citable material
+ * and be paid for again in tokens at each stage that reads it.
+ */
+export declare function recorded(execution: Execution): Omit<Execution, "spend">;

package/dist/noesis/execute/spend.js

@@ -0,0 +1,87 @@
+export const NO_TOOL_SPEND = { calls: 0, byTool: {} };
+const numberAt = (source, field) => {
+    const value = source[field];
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+};
+export function readToolUsage(result) {
+    if (!result || typeof result !== "object")
+        return null;
+    const shape = result;
+    const usage = (shape.usage ?? {});
+    const tokens = {
+        inputTokens: numberAt(usage, "inputTokens"),
+        outputTokens: numberAt(usage, "outputTokens"),
+        citationTokens: numberAt(usage, "citationTokens"),
+        reasoningTokens: numberAt(usage, "reasoningTokens"),
+    };
+    const priced = typeof shape.costMicroUsd === "number" ? shape.costMicroUsd : undefined;
+    const model = typeof shape.model === "string" ? shape.model : undefined;
+    const spent = tokens.inputTokens + tokens.outputTokens + tokens.citationTokens + tokens.reasoningTokens;
+    if (spent === 0 && priced === undefined)
+        return null;
+    return { ...tokens, ...(model ? { model } : {}), ...(priced !== undefined ? { costMicros: priced } : {}) };
+}
+export function toolSpendOf(answers, wiring = {}) {
+    const byTool = {};
+    let calls = 0;
+    let costMicros;
+    for (const answer of answers) {
+        if (answer.status === "answered")
+            calls++;
+        const one = readToolUsage(answer.result);
+        if (!one)
+            continue;
+        const named = wiring[answer.tool]?.name ?? answer.tool;
+        const prior = byTool[named] ?? {
+            calls: 0,
+            inputTokens: 0,
+            outputTokens: 0,
+            citationTokens: 0,
+            reasoningTokens: 0,
+        };
+        const merged = {
+            calls: prior.calls + 1,
+            inputTokens: prior.inputTokens + one.inputTokens,
+            outputTokens: prior.outputTokens + one.outputTokens,
+            citationTokens: prior.citationTokens + one.citationTokens,
+            reasoningTokens: prior.reasoningTokens + one.reasoningTokens,
+            ...(one.model ?? prior.model ? { model: one.model ?? prior.model } : {}),
+        };
+        if (one.costMicros !== undefined || prior.costMicros !== undefined) {
+            merged.costMicros = (prior.costMicros ?? 0) + (one.costMicros ?? 0);
+            costMicros = (costMicros ?? 0) + (one.costMicros ?? 0);
+        }
+        byTool[named] = merged;
+    }
+    return { calls, byTool, ...(costMicros !== undefined ? { costMicros } : {}) };
+}
+export function addToolSpend(a, b) {
+    const byTool = { ...a.byTool };
+    for (const [tool, one] of Object.entries(b.byTool)) {
+        const prior = byTool[tool];
+        byTool[tool] = prior
+            ? {
+                calls: prior.calls + one.calls,
+                inputTokens: prior.inputTokens + one.inputTokens,
+                outputTokens: prior.outputTokens + one.outputTokens,
+                citationTokens: prior.citationTokens + one.citationTokens,
+                reasoningTokens: prior.reasoningTokens + one.reasoningTokens,
+                ...(one.model ?? prior.model ? { model: one.model ?? prior.model } : {}),
+                ...(prior.costMicros !== undefined || one.costMicros !== undefined
+                    ? { costMicros: (prior.costMicros ?? 0) + (one.costMicros ?? 0) }
+                    : {}),
+            }
+            : one;
+    }
+    const costMicros = a.costMicros !== undefined || b.costMicros !== undefined
+        ? (a.costMicros ?? 0) + (b.costMicros ?? 0)
+        : undefined;
+    return { calls: a.calls + b.calls, byTool, ...(costMicros !== undefined ? { costMicros } : {}) };
+}
+export function recorded(execution) {
+    return {
+        answers: execution.answers,
+        unresolved: execution.unresolved,
+        toolMs: execution.toolMs,
+    };
+}

package/dist/noesis/execute/types.d.ts

@@ -1,3 +1,4 @@
+import type { ToolSpend } from "./spend.js";
 import type { Emit } from "../events.js";
 import type { SubQuestion, SubQuestionTool } from "../producers/decompose/index.js";
 /** Which tool answers a sub-question, and the argument its question fills. */
@@ -27,6 +28,7 @@ export interface Execution {
     answers: SubAnswer[];
     /** Ids that could never run: a cycle, or a dependency nothing created. */
     unresolved: string[];
+    spend: ToolSpend;
     /** Time spent inside tools. Not wall clock — a wave runs together. */
     toolMs: number;
 }

package/dist/noesis/index.d.ts

@@ -6,7 +6,8 @@ export { assemble, render as renderDraft } from "./draft/index.js";
 export type { Emit, EventBase, NoesisEvent, NoesisEventInput } from "./events.js";
 export { emitter } from "./events.js";
 export type { ExecuteOptions, Execution, SubAnswer, Waves, Wiring, } from "./execute/index.js";
-export { DEFAULT_TOOLS, execute, order } from "./execute/index.js";
+export type { ToolSpend, ToolUsage } from "./execute/index.js";
+export { addToolSpend, DEFAULT_TOOLS, execute, NO_TOOL_SPEND, order, readToolUsage, recorded, toolSpendOf, } from "./execute/index.js";
 export type { ClosureChecklist, ClosureChecklistInput, ClosureChecklistOptions, ClosureChecklistResult, ClosureGate, } from "./gates/closure-checklist/index.js";
 export { invoke as closureChecklist } from "./gates/closure-checklist/index.js";
 export type { CqotGate, CqotGateInput, CqotGateOptions, CqotGateResult, Gate, GateQuestion, GateVerdict, } from "./gates/cqot-gate/index.js";
@@ -38,8 +39,8 @@ export { invoke as reflection } from "./repair/reflection/index.js";
 export { routeFor } from "./route.js";
 export type { Difficulty, Stakes, TriageEstimates, TriageInput, TriageOptions, TriageResult, } from "./router/triage/index.js";
 export { invoke as triage, TriageReplyError } from "./router/triage/index.js";
-export type { Entry, Escalation, Ledger, NoesisStream, Recorded, StageId, StageUsage, } from "./run/index.js";
-export { NoToolsError, newLedger, RouteFailedError, RouteNotBuiltError, run, runStream, STAGE_NAMES, STAGES, } from "./run/index.js";
+export type { Entry, Escalation, Ledger, NoesisStream, Recorded, StageId, StageKey, StageName, StageUsage, } from "./run/index.js";
+export { NoToolsError, newLedger, RouteFailedError, RouteNotBuiltError, run, runStream, STAGE_KEYS, STAGE_NAMES, STAGES, } from "./run/index.js";
 export { dropPoint, parseStage, resumeAt } from "./run/redo.js";
 export { STAGE_OF_SLUG } from "./slugs.js";
 export type { StageOptions, StageOutcome } from "./stage.js";

package/dist/noesis/index.js

@@ -2,7 +2,7 @@ export { stageCited, unattributed } from "./attribution.js";
 export { asked } from "./context.js";
 export { assemble, render as renderDraft } from "./draft/index.js";
 export { emitter } from "./events.js";
-export { DEFAULT_TOOLS, execute, order } from "./execute/index.js";
+export { addToolSpend, DEFAULT_TOOLS, execute, NO_TOOL_SPEND, order, readToolUsage, recorded, toolSpendOf, } from "./execute/index.js";
 export { invoke as closureChecklist } from "./gates/closure-checklist/index.js";
 export { invoke as cqotGate } from "./gates/cqot-gate/index.js";
 export { invoke as premortem } from "./gates/premortem/index.js";
@@ -19,7 +19,7 @@ export { answer, invoke as toulmin, NoAnswerError, render, ToulminReplyError, }
 export { invoke as reflection } from "./repair/reflection/index.js";
 export { routeFor } from "./route.js";
 export { invoke as triage, TriageReplyError } from "./router/triage/index.js";
-export { NoToolsError, newLedger, RouteFailedError, RouteNotBuiltError, run, runStream, STAGE_NAMES, STAGES, } from "./run/index.js";
+export { NoToolsError, newLedger, RouteFailedError, RouteNotBuiltError, run, runStream, STAGE_KEYS, STAGE_NAMES, STAGES, } from "./run/index.js";
 export { dropPoint, parseStage, resumeAt } from "./run/redo.js";
 export { STAGE_OF_SLUG } from "./slugs.js";
 export { runStage, StageReplyError } from "./stage.js";

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

@@ -1,6 +1,6 @@
 export { NoToolsError, RouteFailedError, RouteNotBuiltError } from "./errors.js";
-export type { Entry, Escalation, Ledger, Recorded, StageId, StageUsage } from "./ledger.js";
-export { newLedger, STAGE_NAMES, STAGES } from "./ledger.js";
+export type { Entry, Escalation, Ledger, Recorded, StageId, StageKey, StageName, StageUsage } from "./ledger.js";
+export { newLedger, STAGE_KEYS, STAGE_NAMES, STAGES } from "./ledger.js";
 export { run } from "./run.js";
 export type { NoesisStream } from "./stream.js";
 export { runStream } from "./stream.js";

package/dist/noesis/run/index.js

@@ -1,4 +1,4 @@
 export { NoToolsError, RouteFailedError, RouteNotBuiltError } from "./errors.js";
-export { newLedger, STAGE_NAMES, STAGES } from "./ledger.js";
+export { newLedger, STAGE_KEYS, STAGE_NAMES, STAGES } from "./ledger.js";
 export { run } from "./run.js";
 export { runStream } from "./stream.js";

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

@@ -4,7 +4,62 @@ import { type PartialUsage, type Usage } from "../usage.js";
 export declare const STAGES: readonly ["0", "1", "2", "3A", "3B", "3C", "4", "4A", "4B", "5A", "5B", "5", "5C", "6A", "6B", "6C", "R"];
 export type StageId = (typeof STAGES)[number];
 /** What a stage is called where a person or a model has to read it. */
-export declare const STAGE_NAMES: Record<StageId, string>;
+export declare const STAGE_NAMES: {
+    readonly "0": "triage";
+    readonly "1": "question brief";
+    readonly "2": "decomposition";
+    readonly "3A": "plan candidates";
+    readonly "3B": "premortem";
+    readonly "3C": "cqot gate";
+    readonly "4": "execution";
+    readonly "4A": "think checkpoint";
+    readonly "4B": "discriminating test";
+    readonly "5A": "verification questions";
+    readonly "5B": "verification answers";
+    readonly "5": "verification";
+    readonly "5C": "standards review";
+    readonly "6A": "closure checklist";
+    readonly "6B": "red team";
+    readonly "6C": "answer";
+    readonly R: "root cause";
+};
+/** A stage by the name it announces itself under. */
+export type StageName = (typeof STAGE_NAMES)[StageId];
+/**
+ * What a stage is called where it is a key rather than prose.
+ *
+ * `STAGE_NAMES` with the spaces closed up, kept apart from it because those
+ * names are read back out of the artifacts by the answer and cannot be renamed
+ * for a config's convenience.
+ */
+export declare const STAGE_KEYS: {
+    readonly "0": "triage";
+    readonly "1": "question_brief";
+    readonly "2": "decomposition";
+    readonly "3A": "plan_candidates";
+    readonly "3B": "premortem";
+    readonly "3C": "cqot_gate";
+    readonly "4": "execution";
+    readonly "4A": "think_checkpoint";
+    readonly "4B": "discriminating_test";
+    readonly "5A": "verification_questions";
+    readonly "5B": "verification_answers";
+    readonly "5": "verification";
+    readonly "5C": "standards_review";
+    readonly "6A": "closure_checklist";
+    readonly "6B": "red_team";
+    readonly "6C": "answer";
+    readonly R: "root_cause";
+};
+/** Stages that dispatch or pair rather than call a model. */
+type CodeOnly = "execution" | "verification" | "discriminating_test";
+/**
+ * A stage by the key a config names it under.
+ *
+ * The code-only stages are excluded: naming a model for the tool dispatcher or
+ * the blind-check pairing would typecheck and do nothing.
+ */
+export type StageKey = Exclude<(typeof STAGE_KEYS)[StageId], CodeOnly>;
 /** What one stage left behind, and what it cost. */
 export interface Entry extends Usage {
     stage: StageId;
@@ -108,3 +163,4 @@ export interface Ledger {
  * failing once each are the same amount of a run going nowhere.
  */
 export declare function newLedger(maxRetries?: number, emit?: Emit): Ledger;
+export {};

package/dist/noesis/run/ledger.js

@@ -38,6 +38,25 @@ export const STAGE_NAMES = {
     "6C": "answer",
     R: "root cause",
 };
+export const STAGE_KEYS = {
+    "0": "triage",
+    "1": "question_brief",
+    "2": "decomposition",
+    "3A": "plan_candidates",
+    "3B": "premortem",
+    "3C": "cqot_gate",
+    "4": "execution",
+    "4A": "think_checkpoint",
+    "4B": "discriminating_test",
+    "5A": "verification_questions",
+    "5B": "verification_answers",
+    "5": "verification",
+    "5C": "standards_review",
+    "6A": "closure_checklist",
+    "6B": "red_team",
+    "6C": "answer",
+    R: "root_cause",
+};
 const DEFAULT_MAX_RETRIES = 5;
 const rolloutsOf = (result) => "rolloutIds" in result ? result.rolloutIds : [result.rolloutId];
 export function newLedger(maxRetries = DEFAULT_MAX_RETRIES, emit) {

package/dist/noesis/run/loop.js

@@ -4,6 +4,7 @@ import { invoke as standardsReview } from "../gates/standards-review/index.js";
 import { STAGE_NAMES } from "./ledger.js";
 import { dropPoint, resumeAt } from "./redo.js";
 import { checks, reflect } from "./verify.js";
+import { stageOptionsFor } from "./options.js";
 async function stepBack(client, llm, question, opts, state, gates, gate, reason, hint) {
     if (!state.ledger.retry(gate)) {
         state.ledger.escalate(gate, `Out of retries. ${gate} last said: ${reason}`);
@@ -16,7 +17,7 @@ async function stepBack(client, llm, question, opts, state, gates, gate, reason,
 }
 async function judge(client, llm, opts, state, checked, gates) {
     if (gates.standards) {
-        const review = state.ledger.record("5C", await standardsReview(client, llm, { question: checked, ...opts.context }, opts.stage));
+        const review = state.ledger.record("5C", await standardsReview(client, llm, { question: checked, ...opts.context }, stageOptionsFor(opts, "5C")));
         if (review.overall !== "accept") {
             return {
                 stage: "5C",
@@ -25,7 +26,7 @@ async function judge(client, llm, opts, state, checked, gates) {
         }
         state.emit?.({ type: "gate.passed", stage: "5C", name: STAGE_NAMES["5C"] });
     }
-    const closure = state.ledger.record("6A", await closureChecklist(client, llm, { question: checked, ...opts.context }, opts.stage));
+    const closure = state.ledger.record("6A", await closureChecklist(client, llm, { question: checked, ...opts.context }, stageOptionsFor(opts, "6A")));
     if (closure.gate !== "close") {
         return {
             stage: "6A",
@@ -36,7 +37,7 @@ async function judge(client, llm, opts, state, checked, gates) {
     }
     state.emit?.({ type: "gate.passed", stage: "6A", name: STAGE_NAMES["6A"] });
     if (gates.redTeam) {
-        const attacked = state.ledger.record("6B", await redTeam(client, llm, { question: checked, ...opts.context }, opts.stage));
+        const attacked = state.ledger.record("6B", await redTeam(client, llm, { question: checked, ...opts.context }, stageOptionsFor(opts, "6B")));
         if (attacked.verdict !== "survives") {
             return { stage: "6B", reason: `${attacked.verdict}: ${attacked.would_break_it}` };
         }

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

@@ -0,0 +1,24 @@
+import type { AnswerOptions } from "../producers/toulmin/index.js";
+import type { StageOptions } from "../stage.js";
+import type { NoesisOptions } from "../types.js";
+import { type StageId } from "./ledger.js";
+/**
+ * What one stage runs on: `stages[id]` over `stage`, with `params` dropped
+ * rather than inherited when the stage names a model of its own.
+ */
+export declare function stageOptionsFor(opts: NoesisOptions, id: StageId): StageOptions;
+/**
+ * Triage's options: `stages.triage` under `opts.triage`.
+ *
+ * `stage` is deliberately not a base here — it is the model for the stages
+ * between triage and the answer, and folding it in would send triage a body
+ * written for a different model.
+ */
+export declare function triageOptions(opts: NoesisOptions): StageOptions;
+/**
+ * The answer's tiers, defaulting to whatever `stages.answer` named.
+ *
+ * `params` reaches the answer only alongside a `model`, because the answer
+ * escalates through tiers and a tier carries its own params.
+ */
+export declare function answerOptions(opts: NoesisOptions): AnswerOptions;

package/dist/noesis/run/options.js

@@ -0,0 +1,26 @@
+import { STAGE_KEYS } from "./ledger.js";
+export function stageOptionsFor(opts, id) {
+    const base = opts.stage ?? {};
+    const per = opts.stages?.[STAGE_KEYS[id]];
+    if (!per)
+        return base;
+    const ownModel = per.model !== undefined && per.model !== base.model;
+    const params = ownModel ? per.params : { ...base.params, ...per.params };
+    const rest = Object.fromEntries(Object.entries({ ...base, ...per }).filter(([field]) => field !== "params"));
+    return params && Object.keys(params).length > 0 ? { ...rest, params } : rest;
+}
+export function triageOptions(opts) {
+    const per = opts.stages?.[STAGE_KEYS["0"]] ?? {};
+    const own = opts.triage ?? {};
+    const ownModel = own.model !== undefined && own.model !== per.model;
+    const params = ownModel ? own.params : { ...per.params, ...own.params };
+    const rest = Object.fromEntries(Object.entries({ ...per, ...own }).filter(([field]) => field !== "params"));
+    return params && Object.keys(params).length > 0 ? { ...rest, params } : rest;
+}
+export function answerOptions(opts) {
+    const base = opts.answer ?? {};
+    const sixC = opts.stages?.[STAGE_KEYS["6C"]];
+    if (base.tiers || !sixC?.model)
+        return base;
+    return { ...base, tiers: [{ model: sixC.model, ...(sixC.params ? { params: sixC.params } : {}) }] };
+}

package/dist/noesis/run/plan.js

@@ -2,20 +2,21 @@ import { invoke as cqotGate } from "../gates/cqot-gate/index.js";
 import { invoke as premortem } from "../gates/premortem/index.js";
 import { invoke as planCandidates } from "../producers/plan-candidates/index.js";
 import { soFar } from "./produce.js";
+import { stageOptionsFor } from "./options.js";
 export async function plan(client, llm, question, opts, state, audits) {
     for (;;) {
         state.ledger.dropFrom("3A");
-        state.ledger.record("3A", await planCandidates(client, llm, { question: soFar(state, question), ...opts.context }, opts.stage));
+        state.ledger.record("3A", await planCandidates(client, llm, { question: soFar(state, question), ...opts.context }, stageOptionsFor(opts, "3A")));
         if (!audits)
             return;
-        const dead = state.ledger.record("3B", await premortem(client, llm, { question: soFar(state, question), ...opts.context }, opts.stage));
+        const dead = state.ledger.record("3B", await premortem(client, llm, { question: soFar(state, question), ...opts.context }, stageOptionsFor(opts, "3B")));
         if (dead.fatal || dead.verdict === "replan") {
             if (state.ledger.retry("3B"))
                 continue;
             state.ledger.escalate("3B", "Out of retries: the premortem keeps killing the plan.");
             return;
         }
-        const gate = state.ledger.record("3C", await cqotGate(client, llm, { question: soFar(state, question), ...opts.context }, opts.stage));
+        const gate = state.ledger.record("3C", await cqotGate(client, llm, { question: soFar(state, question), ...opts.context }, stageOptionsFor(opts, "3C")));
         if (gate.gate === "pass")
             return;
         if (state.ledger.retry("3C"))

package/dist/noesis/run/produce.js

@@ -6,9 +6,13 @@ import { invoke as brief } from "../producers/qn-brief/index.js";
 import { digest } from "./artifacts.js";
 import { NoToolsError } from "./errors.js";
 import { plan } from "./plan.js";
+import { stageOptionsFor } from "./options.js";
+import { NO_TOOL_SPEND } from "../execute/spend.js";
+import { recorded } from "../execute/index.js";
+import { recordToolSpend } from "./state.js";
 export const soFar = (state, question) => JSON.stringify({ question, ...digest(state.ledger.artifacts()) }, null, 2);
 export async function frame(client, llm, question, opts, state) {
-    const brief1 = state.ledger.record("1", await brief(client, llm, { question, ...opts.context }, opts.stage));
+    const brief1 = state.ledger.record("1", await brief(client, llm, { question, ...opts.context }, stageOptionsFor(opts, "1")));
     let asked = question;
     if (!brief1.is_right_question && brief1.better_question && opts.onAsk) {
         state.emit?.({
@@ -25,15 +29,16 @@ export async function frame(client, llm, question, opts, state) {
         state.emit?.({ type: "ask.answered", replacement: replacement ?? null });
         asked = replacement ?? question;
     }
-    const split = state.ledger.record("2", await decompose(client, llm, { question: asked, ...opts.context }, opts.stage));
+    const split = state.ledger.record("2", await decompose(client, llm, { question: asked, ...opts.context }, stageOptionsFor(opts, "2")));
     return { asked, split };
 }
 export async function work(client, llm, question, opts, state, split) {
     if (!opts.tools)
         throw new NoToolsError();
     const execution = await execute(opts.tools, split.sub_questions, { emit: state.emit });
+    recordToolSpend(state, execution.spend);
     state.ledger.record("4", {
-        data: execution,
+        data: recorded(execution),
         rolloutIds: [],
         model: "",
         inputTokens: 0,
@@ -46,7 +51,7 @@ export async function work(client, llm, question, opts, state, split) {
         findings: draft.findings.length,
         missing: draft.missing.map((one) => ({ id: one.id, reason: one.reason })),
     });
-    const checkpoint = state.ledger.record("4A", await thinkCheckpoint(client, llm, { question: soFar(state, question), ...opts.context }, opts.stage));
+    const checkpoint = state.ledger.record("4A", await thinkCheckpoint(client, llm, { question: soFar(state, question), ...opts.context }, stageOptionsFor(opts, "4A")));
     if (checkpoint.next_action === "replan")
         return { draft, action: "replan" };
     if (checkpoint.next_action === "escalate")
@@ -61,6 +66,7 @@ export async function produce(client, llm, question, opts, state, audits) {
             return assemble(asked, split, {
                 answers: [],
                 unresolved: split.sub_questions.map((sub) => sub.id),
+                spend: NO_TOOL_SPEND,
                 toolMs: 0,
             });
         }

package/dist/noesis/run/result.js

@@ -11,6 +11,7 @@ function usageOfRun(state) {
         ...state.ledger.usage(),
         byStage,
         byModel: state.ledger.byModel(),
+        tools: state.toolSpend,
         calls: byStage.reduce((total, stage) => total + stage.calls, 0),
     };
 }
@@ -36,8 +37,6 @@ export function finish(decided, state, latencyMs) {
         rolloutIds: ledger.rolloutIds,
         unattributed: state.unattributed ?? [],
         usage,
-        inputTokens: usage.inputTokens,
-        outputTokens: usage.outputTokens,
         latencyMs,
     };
 }

package/dist/noesis/run/run.js

@@ -10,6 +10,11 @@ const watched = (opts, emit) => ({
     triage: { ...opts.triage, emit },
     stage: { ...opts.stage, emit },
     answer: { ...opts.answer, emit },
+    ...(opts.stages
+        ? {
+            stages: Object.fromEntries(Object.entries(opts.stages).map(([id, one]) => [id, { ...one, emit }])),
+        }
+        : {}),
 });
 export async function run(client, llm, question, options = {}) {
     const startedAt = Date.now();

package/dist/noesis/run/stages/classify.js

@@ -1,8 +1,9 @@
 import { routeFor } from "../../route.js";
 import { invoke as triage } from "../../router/triage/index.js";
 import { nextTask } from "../state.js";
+import { triageOptions } from "../options.js";
 export const classifyStage = (client, llm, question, opts, state) => async () => {
-    const stage = await triage(client, llm, { ...opts.triage, currentTask: state.currentTask, question }, { ...opts.triage });
+    const stage = await triage(client, llm, { ...opts.triage, currentTask: state.currentTask, question }, triageOptions(opts));
     state.estimates = state.ledger.record("0", { ...stage, data: stage.estimates });
     state.routing = routeFor(stage.estimates);
     state.currentTask = nextTask(stage.estimates, state.currentTask);

package/dist/noesis/run/stages/direct.js

@@ -1,6 +1,7 @@
 import { answer } from "../../producers/toulmin/index.js";
+import { answerOptions } from "../options.js";
 export const directStage = (client, llm, question, opts, state) => async () => {
-    const answered = await answer(client, llm, { question, ...state.ledger.artifacts() }, opts.answer ?? {});
+    const answered = await answer(client, llm, { question, ...state.ledger.artifacts() }, answerOptions(opts));
     state.answered = answered;
     state.text = state.ledger.record("6C", { ...answered, data: answered.answer }).claim;
     return state.text;

package/dist/noesis/run/stages/retrieve.js

@@ -1,6 +1,9 @@
 import { execute } from "../../execute/index.js";
 import { answer } from "../../producers/toulmin/index.js";
 import { NoToolsError } from "../errors.js";
+import { answerOptions } from "../options.js";
+import { recorded } from "../../execute/index.js";
+import { recordToolSpend } from "../state.js";
 const DEFAULT_TOOL = "deeprecall";
 const lookup = (question, tool) => ({
     id: "q",
@@ -15,15 +18,16 @@ export const retrieveStage = (client, llm, question, opts, state) => async () =>
     if (!opts.tools)
         throw new NoToolsError();
     const execution = await execute(opts.tools, [lookup(question, opts.retrieve?.tool ?? DEFAULT_TOOL)], { emit: state.emit });
+    recordToolSpend(state, execution.spend);
     state.ledger.record("4", {
-        data: execution,
+        data: recorded(execution),
         rolloutIds: [],
         model: "",
         inputTokens: 0,
         outputTokens: 0,
         latencyMs: execution.toolMs,
     });
-    const answered = await answer(client, llm, { question, ...state.ledger.artifacts() }, opts.answer ?? {});
+    const answered = await answer(client, llm, { question, ...state.ledger.artifacts() }, answerOptions(opts));
     state.answered = answered;
     state.text = state.ledger.record("6C", { ...answered, data: answered.answer }).claim;
     return state.text;

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

@@ -1,3 +1,4 @@
+import { type ToolSpend } from "../execute/spend.js";
 import type { Emit } from "../events.js";
 import type { AnswerResult } from "../producers/toulmin/index.js";
 import type { TriageEstimates } from "../router/triage/index.js";
@@ -5,6 +6,8 @@ import type { Routing } from "../types.js";
 import { type Ledger } from "./ledger.js";
 /** What each branch writes down, since `route()` hands back only its output. */
 export interface RunState {
+    /** What the tools reported they cost, which no stage's tokens include. */
+    toolSpend: ToolSpend;
     /** Every stage's result and what it cost, in one place. */
     ledger: Ledger;
     /** Where the run layer says what it is doing. Undefined when nobody listens. */
@@ -19,6 +22,8 @@ export interface RunState {
     unattributed?: string[];
 }
 export declare const newRunState: (currentTask?: string, emit?: Emit, maxRetries?: number) => RunState;
+/** Adds one execution's tool spend to the run's. A retry refunds nothing. */
+export declare function recordToolSpend(state: RunState, spend: ToolSpend): void;
 /**
  * The open task after triage has read the request: the router's summary when it
  * calls the request new, otherwise the task carried in.

package/dist/noesis/run/state.js

@@ -1,9 +1,14 @@
+import { addToolSpend, NO_TOOL_SPEND } from "../execute/spend.js";
 import { newLedger } from "./ledger.js";
 export const newRunState = (currentTask, emit, maxRetries) => ({
+    toolSpend: NO_TOOL_SPEND,
     ledger: newLedger(maxRetries, emit),
     emit,
     currentTask,
 });
+export function recordToolSpend(state, spend) {
+    state.toolSpend = addToolSpend(state.toolSpend, spend);
+}
 export function nextTask(estimates, current) {
     return estimates.is_new_task ? estimates.summary : (current ?? estimates.summary);
 }

package/dist/noesis/run/verify.js

@@ -7,11 +7,12 @@ 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";
+import { answerOptions, stageOptionsFor } from "./options.js";
 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 questions = state.ledger.record("5A", await coveQuestions(client, llm, { question: drafted, ...opts.context }, stageOptionsFor(opts, "5A")));
     const answers = questions.questions.length
-        ? state.ledger.record("5B", await coveAnswers(client, llm, { question: blind(questions), ...opts.context }, opts.stage))
+        ? state.ledger.record("5B", await coveAnswers(client, llm, { question: blind(questions), ...opts.context }, stageOptionsFor(opts, "5B")))
         : { answers: [] };
     const verification = compare(questions, answers, opts.verify?.confidenceFloor);
     state.emit?.({
@@ -34,7 +35,7 @@ export async function checks(client, llm, opts, state, draft) {
     return `${drafted}\n\n${renderChecks(verification)}`;
 }
 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 looked = state.ledger.record("R", await reflection(client, llm, { question: `${soFar(state, question)}\n\nThe gate said: ${reason}`, ...opts.context }, stageOptionsFor(opts, "R")));
     const redoFrom = parseStage(looked.redo_from_stage) ?? parseStage(hint ?? "");
     state.emit?.({
         type: "reflect.pointed",
@@ -46,7 +47,7 @@ export async function reflect(client, llm, question, opts, state, gate, reason,
     return redoFrom;
 }
 export async function compile(client, llm, question, opts, state) {
-    const answered = await answer(client, llm, { question, ...state.ledger.artifacts() }, opts.answer ?? {});
+    const answered = await answer(client, llm, { question, ...state.ledger.artifacts() }, answerOptions(opts));
     state.answered = answered;
     const loose = unattributed(answered.answer, state.ledger.byStage().map((one) => one.stage));
     state.unattributed = loose;

package/dist/noesis/types.d.ts

@@ -1,10 +1,11 @@
 import type { ToolBus } from "@spendgraph/tools";
+import type { ToolSpend } from "./execute/spend.js";
 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 { Escalation, StageKey, StageUsage } from "./run/ledger.js";
 import type { StageOptions } from "./stage.js";
 import type { Usage } from "./usage.js";
 /**
@@ -78,6 +79,13 @@ export interface NoesisOptions {
     context?: Omit<Asked, "question">;
     /** Model and params for every stage between triage and the answer. */
     stage?: StageOptions;
+    /**
+     * Per-stage overrides, keyed by the stage's key, winning over `stage`.
+     *
+     * `params` is not inherited by a stage that names its own `model`: sampling
+     * knobs are per model, and a body written for one is rejected by another.
+     */
+    stages?: Partial<Record<StageKey, StageOptions>>;
     /**
      * Reached when a stage wants a person before it can go on.
      *
@@ -152,13 +160,17 @@ export interface NoesisResult {
      * 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 {
+    /**
+     * What the tools reported, which the numbers above deliberately exclude.
+     *
+     * A tool call is somebody else's API at somebody else's rates and is no
+     * rollout of ours, so it is never folded into the model spend — but it is
+     * real money, so it is reachable rather than buried in an artifact.
+     */
+    tools: ToolSpend;
     /** Summed over every time the loop ran each stage. */
     byStage: StageUsage[];
     byModel: Record<string, Usage>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spendgraph/workflows",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Ready-made workflows assembled from the spendgraph packages.",
   "license": "MIT",
   "repository": {
@@ -33,10 +33,10 @@
     "README.md"
   ],
   "dependencies": {
-    "@spendgraph/harness": "^0.2.1",
-    "@spendgraph/llms": "^0.2.1",
-    "@spendgraph/prompt": "^0.2.1",
-    "@spendgraph/tools": "^0.2.1"
+    "@spendgraph/harness": "^0.3.1",
+    "@spendgraph/llms": "^0.3.1",
+    "@spendgraph/prompt": "^0.3.1",
+    "@spendgraph/tools": "^0.3.1"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments",
@@ -47,7 +47,7 @@
   },
   "devDependencies": {
     "@locusgraph/client": "^0.8.1",
-    "@spendgraph/evals": "^0.2.1",
+    "@spendgraph/evals": "^0.3.1",
     "typescript": "^5"
   },
   "engines": {