@sweny-ai/core 0.1.199 → 0.1.201

package/dist/executor.js

@@ -30,7 +30,7 @@ import { toolRunContext } from "./run-context.js";
 import { fenceUntrusted, fenceUntrustedJson } from "./untrusted.js";
 import { asClaude } from "./harness/compat.js";
 import { budgetGate, isToolClass, policyGate, resolveHarnessPolicy } from "./harness/policy.js";
-import { BudgetGuard, describeOverrun, minLimits, spendOf, toLimits } from "./budget.js";
+import { BudgetGuard, BudgetRefusal, describeOverrun, minLimits, spendOf, toLimits } from "./budget.js";
 import { createRunDecider, wantsDecider } from "./decider.js";
 import { redact, runSecretValues } from "./journal.js";
 import { buildNodePolicy, resolveNodePermissions } from "./node-policy.js";
@@ -90,6 +90,7 @@ export async function execute(workflow, input, options) {
         };
         results.set(at.node, result);
         trace.steps.push({ node: at.node, status: "failed", iteration: at.iteration });
+        at.syncSpend?.();
         safeObserve(options.observer, { type: "node:exit", node: at.node, result }, logger);
         logger.error(`  ${err.message}`, { node: at.node });
         journalDegraded();
@@ -130,6 +131,130 @@ async function executeRun(workflow, input, options, results, trace, at) {
     // Spend budgets (#449): the run ceiling is the lower of the workflow's
     // `budget` and the caller's (`--max-tokens`, `--max-cost`).
     const budgetGuard = new BudgetGuard(minLimits(toLimits(workflow.budget), toLimits(options.budget)));
+    // The executor's own completions (judge, route, retry reflection, safe-output
+    // screen) report usage into the same guard as node runs, under their kind,
+    // and into the journal so a resume keeps them. Every call passes a gate
+    // first: once a ceiling is reached (or a usage record could not be
+    // journaled) the call is refused, not made. `sink` counts one completion's
+    // total and keeps any breach for the caller; it never throws into the
+    // adapter, so a journal failure inside it is held in `meterFault` and
+    // rethrown by the executor at the next step.
+    let meterFault;
+    const throwIfMeterFault = () => {
+        if (meterFault)
+            throw meterFault;
+    };
+    const metered = (refuse, sink) => {
+        const gate = () => {
+            throwIfMeterFault();
+            const stop = refuse();
+            if (stop)
+                throw new BudgetRefusal(stop);
+        };
+        return {
+            defaultJudgeModel: claude.defaultJudgeModel,
+            run: (req) => claude.run(req),
+            evaluate: async (opts) => {
+                gate();
+                return claude.evaluate({ ...opts, onUsage: sink });
+            },
+            ask: async (opts) => {
+                gate();
+                return claude.ask({ ...opts, onUsage: sink });
+            },
+        };
+    };
+    const journalMeter = (kind, node, iteration, u) => {
+        if (!journal?.meter || meterFault)
+            return;
+        try {
+            journal.meter(kind, node, iteration, u);
+        }
+        catch (err) {
+            meterFault = err;
+        }
+    };
+    const syncSpend = () => {
+        if (budgetGuard.hasMeteredCalls)
+            trace.spend = budgetGuard.breakdown();
+    };
+    at.syncSpend = syncSpend;
+    // A route call that crossed the run budget, or was refused because the run
+    // budget was already spent. The next node is then refused at its start; a
+    // route that ends the run fails the node it left.
+    let routeBreach;
+    let routingFrom;
+    const routeClaude = metered(() => (routeBreach ??= budgetGuard.runExhausted()), (u) => {
+        const b = budgetGuard.meter("route", u);
+        if (routingFrom)
+            journalMeter("route", routingFrom.node, routingFrom.iteration, u);
+        syncSpend();
+        if (b) {
+            routeBreach ??= b;
+            logger.warn(`  ${describeOverrun(b)}; the next node does not start`);
+        }
+    });
+    // Routing from `from`. `budgetStop` says the run ended there on the budget:
+    // the caller then writes no route record, so the journal keeps the visit
+    // ended but unrouted. A resume (with a larger cap) then routes a visit that
+    // succeeded again, like a crash between node:end and the route; a visit
+    // that had failed (`on_fail: continue`) is run again.
+    const advance = async (from) => {
+        routeBreach = undefined;
+        routingFrom = { node: from, iteration: nodeRunCounts.get(from) ?? 1 };
+        // No paid routing once the run budget is spent: the decider (an HTTP
+        // model call) is skipped like the agent's route evaluation, which the gate refuses.
+        const spentBeforeRouting = budgetGuard.runExhausted();
+        if (spentBeforeRouting && routing.decider && !trace.deciderOff)
+            trace.deciderOff = "run budget spent";
+        const routeOpts = spentBeforeRouting ? { ...routing, decider: null } : routing;
+        let routed;
+        let refused = false;
+        try {
+            routed = await advanceFromNode(workflow, from, results, input, routeClaude, observer, edgeCounts, logger, trace, routeOpts);
+        }
+        catch (err) {
+            throwIfMeterFault();
+            if (!(err instanceof BudgetRefusal))
+                throw err;
+            logger.warn(`  ${describeOverrun(err.breach)}; not routing from '${from}'`, { node: from });
+            routed = { next: null };
+            refused = true;
+        }
+        finally {
+            routingFrom = undefined;
+        }
+        throwIfMeterFault();
+        const breach = routeBreach;
+        routeBreach = undefined;
+        if (breach && routed.next === null) {
+            // No node is left to refuse: the stop lands on the node the route left.
+            const prior = results.get(from);
+            if (prior && !prior.budget) {
+                const error = describeOverrun(breach, from);
+                // A node that had already failed keeps its own error; the budget reason has its own field.
+                const priorError = prior.data?.error;
+                const amended = {
+                    ...prior,
+                    status: "failed",
+                    data: { ...prior.data, error: priorError ?? error, budget_error: error, budget_exceeded: true },
+                    budget: breach,
+                };
+                results.set(from, amended);
+                // The trace and observers already saw the visit end: they get the amended result as an amendment, not a second exit.
+                const iteration = nodeRunCounts.get(from) ?? 1;
+                const step = [...trace.steps].reverse().find((st) => st.node === from && st.iteration === iteration);
+                if (step)
+                    step.status = "failed";
+                safeObserve(observer, { type: "node:amended", node: from, result: amended }, logger);
+            }
+            // Routing already announced its own end (an invalid target); a refused route announced nothing.
+            if (refused)
+                safeObserve(observer, { type: "route", from, to: "(end)", reason: "budget exceeded" }, logger);
+            return { ...routed, budgetStop: true };
+        }
+        return routed;
+    };
     const harnessPolicy = options.harnessPolicy ?? resolveHarnessPolicy(runEnv);
     // #473: a checkout that persisted a git credential (actions/checkout's
     // default). Each harness masks it for read-only and staged nodes, or reports
@@ -279,8 +404,9 @@ async function executeRun(workflow, input, options, results, trace, at) {
             logger.info(`  replayed from the run journal: ${replay.result.status}`, { node: currentId });
             const from = currentId;
             if (replay.next === undefined) {
-                const routed = await advanceFromNode(workflow, from, results, input, claude, observer, edgeCounts, logger, trace, routing);
-                journal?.route(from, routed.next, routed.rung, decider?.counters);
+                const routed = await advance(from);
+                if (!routed.budgetStop)
+                    journal?.route(from, routed.next, routed.rung, decider?.counters);
                 currentId = routed.next;
             }
             else {
@@ -304,6 +430,27 @@ async function executeRun(workflow, input, options, results, trace, at) {
             continue;
         }
         journal?.nodeStart(currentId, iteration);
+        // The run budget is already spent (by a route call, or by the node before
+        // a skipped one): this node neither starts nor routes on, whatever its
+        // `requires` say, so a skipped node cannot carry the run past the stop.
+        // A checkpointed visit (resume) already ran its agent: its writes still apply.
+        const runSpent = replay?.kind === "checkpoint" ? undefined : budgetGuard.runExhausted();
+        if (runSpent) {
+            const error = describeOverrun(runSpent, currentId);
+            const result = {
+                status: "failed",
+                data: { error, budget_exceeded: true },
+                toolCalls: [],
+                budget: runSpent,
+            };
+            results.set(currentId, result);
+            journal?.nodeEnd(currentId, iteration, result, writeState);
+            trace.steps.push({ node: currentId, status: "failed", iteration });
+            safeObserve(observer, { type: "node:exit", node: currentId, result }, logger);
+            logger.warn(`  ${error}; not starting the node`, { node: currentId });
+            safeObserve(observer, { type: "route", from: currentId, to: "(end)", reason: "node failed (budget exceeded)" }, logger);
+            break;
+        }
         // Gather tools from the node's skills, then apply the node's optional
         // skill-tool filter (`tools.allow` / `tools.deny`). Filtered tools are
         // never registered for the run, so the model cannot see or call them.
@@ -406,8 +553,9 @@ async function executeRun(workflow, input, options, results, trace, at) {
             }
             // Apply normal routing rules (dry run gate + resolveNext).
             // TODO: dedupe with requires path — see advanceFromNode helper below
-            const routed = await advanceFromNode(workflow, currentId, results, input, claude, observer, edgeCounts, logger, trace, routing);
-            journal?.route(currentId, routed.next, routed.rung, decider?.counters);
+            const routed = await advance(currentId);
+            if (!routed.budgetStop)
+                journal?.route(currentId, routed.next, routed.rung, decider?.counters);
             currentId = routed.next;
             continue;
         }
@@ -496,12 +644,40 @@ async function executeRun(workflow, input, options, results, trace, at) {
         // run's. The gate says whether the harness can keep them; a strict policy
         // refuses the node when it cannot report the budgeted unit at all.
         const nodeBudget = budgetGuard.node(toLimits(node.budget));
+        // Resume: this visit's spend before the crash counts against its node
+        // budget again (the run total already has it from the seed), whether the
+        // write stage is replayed or the visit runs again.
+        const visitPrior = replay?.kind === "checkpoint" ? replay.spent : replay ? undefined : journal?.visitSpent?.(currentId, iteration);
+        if (visitPrior)
+            nodeBudget.restore(visitPrior);
         const budgetOn = budgetGuard.active(nodeBudget.limits);
         const budgetCheck = budgetOn && options.harness
             ? budgetGate(options.harness.capabilities, minLimits(nodeBudget.limits, budgetGuard.runLimits), permissions.strict || harnessPolicy === "strict")
             : undefined;
         // A budget stop: fail_soft and on_fail: continue never apply, the run halts.
         let budgetStop;
+        // This visit's own completions (judge scoring, retry reflection, output
+        // screen) count against the node and the run; a crossing is kept here.
+        let meterBreach;
+        const visitId = currentId;
+        const visitClaude = (kind) => metered(
+        // Latched: once refused, every later call of this visit is refused too.
+        () => (meterBreach ??= budgetOn ? nodeBudget.exhausted() : undefined), (u) => {
+            const b = nodeBudget.meter(kind, u);
+            journalMeter(kind, visitId, iteration, u);
+            syncSpend();
+            meterBreach ??= b;
+        });
+        const judgeClaude = visitClaude("judge");
+        const reflectClaude = visitClaude("reflect");
+        const screenClaude = visitClaude("screen");
+        // A ceiling reached before a paid executor call (judges, reflection): the
+        // node fails with the budget reason instead of making the call.
+        const stopAtCeiling = (r, b) => {
+            const error = describeOverrun(b, visitId);
+            logger.warn(`  ${error}`, { node: currentId });
+            return { ...r, status: "failed", data: { ...r.data, error, budget_exceeded: true }, budget: b };
+        };
         let previous;
         while (true) {
             if (replay?.kind === "checkpoint") {
@@ -509,6 +685,8 @@ async function executeRun(workflow, input, options, results, trace, at) {
                 // write intents; the write stage below skips what the journal shows was already applied.
                 ({ result, agentRunFailed, attempt } = replay);
                 intents.push(...replay.intents);
+                // The visit's own spend before the crash counts against its node budget
+                // again (the run total already has it from the seed).
                 break;
             }
             const refusal = gate?.refuse ?? budgetCheck?.refuse;
@@ -562,7 +740,6 @@ async function executeRun(workflow, input, options, results, trace, at) {
             }
             const journalUsage = journal?.usage
                 ? (u) => {
-                    liveUsage = { ...liveUsage, ...u };
                     if (journalFault)
                         return;
                     try {
@@ -574,12 +751,12 @@ async function executeRun(workflow, input, options, results, trace, at) {
                     }
                 }
                 : undefined;
-            const onUsage = attemptBudget || journalUsage
-                ? (u) => {
-                    attemptBudget?.onUsage(u);
-                    journalUsage?.(u);
-                }
-                : undefined;
+            // Live usage is always collected: with no limit it still feeds the split by kind.
+            const onUsage = (u) => {
+                liveUsage = { ...liveUsage, ...u };
+                attemptBudget?.onUsage(u);
+                journalUsage?.(u);
+            };
             try {
                 result = await claude.run({
                     nodeId: currentId,
@@ -597,13 +774,17 @@ async function executeRun(workflow, input, options, results, trace, at) {
                     ...(nodePolicy ? { policy: nodePolicy } : {}),
                     ...(readOnlyNode || stageOutputs ? {} : { mcpServers: skillMcpServers }),
                     ...(readOnlyNode ? { readOnly: true } : {}),
-                    ...(onUsage ? { onUsage } : {}),
+                    onUsage,
                     onProgress: (message) => {
                         safeObserve(observer, { type: "node:progress", node: currentId, message }, logger);
                     },
                 });
                 // Commit the attempt's spend before anything here can throw (#549); `finish` below reads the breach.
-                attemptBudget?.settle(result.usage);
+                if (attemptBudget)
+                    attemptBudget.settle(result.usage);
+                // No limit to enforce: still count the run, so the split by kind is complete.
+                else
+                    budgetGuard.meter("node", attemptSpend(result.usage, liveUsage));
             }
             catch (err) {
                 if (journalFault)
@@ -741,13 +922,37 @@ async function executeRun(workflow, input, options, results, trace, at) {
                 result.evals = [failure];
             }
             else {
-                const evalResults = await evaluateAll(node.eval, result, {
-                    aliases: toolAliases,
-                    claude,
-                    node,
-                    workflow,
-                });
-                result.evals = evalResults;
+                // With a budget on, judges run one at a time, so a crossing (or a
+                // ceiling already reached) refuses the rest instead of all starting at once.
+                let evalResults;
+                try {
+                    evalResults = await evaluateAll(node.eval, result, {
+                        aliases: toolAliases,
+                        claude: judgeClaude,
+                        node,
+                        workflow,
+                        sequential: budgetOn,
+                        ...(signal ? { signal } : {}),
+                        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+                    });
+                }
+                catch (err) {
+                    throwIfMeterFault();
+                    if (!(err instanceof BudgetRefusal))
+                        throw err;
+                }
+                throwIfMeterFault();
+                if (evalResults)
+                    result.evals = evalResults;
+                if (meterBreach || !evalResults) {
+                    // Judge spend crossed a ceiling, or a judge was refused at one (the
+                    // refusal latched it): the node fails whatever the verdicts said.
+                    const stop = meterBreach ?? nodeBudget.exhausted() ?? budgetGuard.runExhausted();
+                    result = stop ? stopAtCeiling(result, stop) : result;
+                    agentRunFailed = true;
+                    budgetStop = stop;
+                    break;
+                }
                 outcome = aggregateEval(evalResults, node.eval_policy ?? "all_pass");
             }
             if (outcome.pass)
@@ -786,13 +991,21 @@ async function executeRun(workflow, input, options, results, trace, at) {
                 evalFailures: outcome.failures,
                 toolCalls: result.toolCalls,
                 nodeInstruction: resolvedInstruction,
-                claude,
+                claude: reflectClaude,
                 logger,
                 context,
                 model: nodeModel,
                 signal,
                 timeoutMs,
             });
+            throwIfMeterFault();
+            // A reflection refused at a ceiling (or one whose spend crossed it): no further attempt.
+            if (meterBreach) {
+                result = stopAtCeiling(result, meterBreach);
+                agentRunFailed = true;
+                budgetStop = meterBreach;
+                break;
+            }
             currentInstruction = `${preamble}\n\n---\n\n${instruction}`;
             safeObserve(observer, { type: "node:retry", node: currentId, attempt: attempt + 1, reason: outcome.error ?? "eval failed", preamble }, logger);
             attempt++;
@@ -840,19 +1053,35 @@ async function executeRun(workflow, input, options, results, trace, at) {
                     state: writeState,
                     logger,
                     input: runInput,
-                    screen: async (writes) => claude.ask({
-                        instruction: SAFE_OUTPUT_SCREEN_INSTRUCTION,
-                        context: { writes },
-                        model: nodeModel,
-                        signal,
-                        timeoutMs,
-                    }),
+                    ...(journal?.reconcile
+                        ? {
+                            reconcile: (sk, tool, args, ctx) => journal.reconcile(visitId, iteration, sk, tool, args, ctx),
+                        }
+                        : {}),
+                    screen: async (writes) => {
+                        const verdict = await screenClaude.ask({
+                            instruction: SAFE_OUTPUT_SCREEN_INSTRUCTION,
+                            context: { writes },
+                            model: nodeModel,
+                            signal,
+                            timeoutMs,
+                        });
+                        // A screen whose spend crossed a ceiling, or whose meter record the
+                        // journal could not write, allows nothing: the writes are vetoed.
+                        return meterBreach || meterFault ? null : verdict;
+                    },
                 });
+                throwIfMeterFault();
                 result = { ...result, outputs: stage.receipts };
                 if (stage.error) {
                     logger.warn(`  ${stage.error}`, { node: currentId });
                     result = { ...result, status: "failed", data: { ...result.data, error: stage.error } };
                 }
+                if (meterBreach && !budgetStop) {
+                    // The screen's spend crossed a ceiling: the node fails and the run halts.
+                    result = stopAtCeiling(result, meterBreach);
+                    budgetStop = meterBreach;
+                }
             }
             else if (intents.length > 0) {
                 result = {
@@ -885,17 +1114,33 @@ async function executeRun(workflow, input, options, results, trace, at) {
         }
         // Dry run gate + routing — shared with requires path via advanceFromNode helper.
         const routedFrom = currentId;
-        const routed = await advanceFromNode(workflow, currentId, results, input, claude, observer, edgeCounts, logger, trace, routing);
-        journal?.route(routedFrom, routed.next, routed.rung, decider?.counters);
+        const routed = await advance(routedFrom);
+        if (!routed.budgetStop)
+            journal?.route(routedFrom, routed.next, routed.rung, decider?.counters);
         currentId = routed.next;
     }
     safeObserve(observer, {
         type: "workflow:end",
         results: Object.fromEntries(results),
     }, logger);
+    syncSpend();
     return { results, trace };
 }
 // ─── Internals ───────────────────────────────────────────────────
+/**
+ * An attempt's spend as usage: per unit, the larger of the final report and
+ * the last live one (what `BudgetAttempt.settle` commits), so the split is the
+ * same with and without a limit. Undefined when neither reported anything.
+ */
+function attemptSpend(final, live) {
+    const f = spendOf(final);
+    const l = spendOf(live);
+    const tokens = f.tokens === undefined && l.tokens === undefined ? undefined : Math.max(f.tokens ?? 0, l.tokens ?? 0);
+    const costUsd = f.costUsd === undefined && l.costUsd === undefined ? undefined : Math.max(f.costUsd ?? 0, l.costUsd ?? 0);
+    if (tokens === undefined && costUsd === undefined)
+        return undefined;
+    return { ...(tokens !== undefined ? { inputTokens: tokens } : {}), ...(costUsd !== undefined ? { costUsd } : {}) };
+}
 /**
  * Thrown when a conditional routing decision could not be made and there is
  * no explicit default (unconditional) edge to fall back to. Fails closed: the

package/dist/harness/acp.js

@@ -51,7 +51,7 @@ import { agentEnvOverlay, applyEnvOverlay, finishAgentEnv, heldCredentials, over
 import { ACP_CAPABILITIES } from "./capabilities.js";
 import { policyGate, resolveHarnessPolicy, TOOL_CLASSES } from "./policy.js";
 import { gitCredentialPolicy } from "../git-credentials.js";
-import { buildNodePrompt } from "./prompts.js";
+import { buildNodePrompt, reportCompletionUsage } from "./prompts.js";
 import { makeAbort } from "./abort.js";
 import { parseToolResultContent, schemaMismatches, summarizeToolError, tryParseJSON } from "./parse.js";
 import { startToolBridge } from "./tool-bridge/server.js";
@@ -937,6 +937,9 @@ export class AcpHarness {
         }
         if (conv.agentVersion)
             this.agentVersion = conv.agentVersion;
+        // A completion that failed was still billed: report before the outcome.
+        if (conv.costUsd !== undefined)
+            reportCompletionUsage(req.onUsage, { costUsd: conv.costUsd }, this.logger);
         if (conv.spawnError)
             return failClosed(`the ACP agent could not start: ${conv.spawnError}`);
         if (conv.abortReason === "timeout")

package/dist/harness/claude-code.d.ts

@@ -8,7 +8,7 @@
  * This is the ONLY supported LLM backend. The whole point of sweny
  * is to use headless Claude Code - never the raw Anthropic API.
  */
-import type { Claude, Tool, ToolContext, Logger, McpServerConfig } from "../types.js";
+import type { Claude, Tool, ToolContext, NodeUsage, Logger, McpServerConfig } from "../types.js";
 import { type HarnessEnvOptions, type SandboxMode } from "../agent-env.js";
 import type { AgentHarness, HarnessCapabilities, HarnessCompleteRequest, HarnessInfo, HarnessRunRequest, HarnessRunResult, NodePolicy, ToolClass } from "./types.js";
 import { type HarnessPolicyMode } from "./policy.js";
@@ -250,6 +250,7 @@ export declare class ClaudeCodeHarness implements Claude, AgentHarness {
         timeoutMs?: number;
         /** Caller-supplied abort signal. Aborting it interrupts the query. */
         signal?: AbortSignal;
+        onUsage?: (usage: NodeUsage) => void;
     }): Promise<string | null>;
     /** Free-text completion. Delegates to core {@link coreAsk} over {@link complete}. */
     ask(opts: {
@@ -260,6 +261,7 @@ export declare class ClaudeCodeHarness implements Claude, AgentHarness {
         timeoutMs?: number;
         /** Caller-supplied abort signal. Aborting it interrupts the query. */
         signal?: AbortSignal;
+        onUsage?: (usage: NodeUsage) => void;
     }): Promise<string>;
 }
 /** @deprecated Use {@link ClaudeCodeHarnessOptions}. */

package/dist/harness/claude-code.js

@@ -16,7 +16,7 @@ import { AGENT_AUTH_VARS, agentEnvOverlay, applyEnvOverlay, finishAgentEnv, over
 import { gitCredentialGap, policyGate } from "./policy.js";
 import { gitCredentialPolicy } from "../git-credentials.js";
 import { CLAUDE_CODE_CAPABILITIES } from "./capabilities.js";
-import { ask as coreAsk, evaluate as coreEvaluate, buildEvaluatePrompt, buildNodePrompt } from "./prompts.js";
+import { ask as coreAsk, evaluate as coreEvaluate, buildEvaluatePrompt, buildNodePrompt, reportCompletionUsage, } from "./prompts.js";
 import { jsonSchemaToZodShape, toolErrorToMcpResult, toolOutputToMcpResult } from "./tool-bridge/protocol.js";
 import { startToolBridge } from "./tool-bridge/server.js";
 import { parseToolResultContent, summarizeToolError, tryParseJSON } from "./parse.js";
@@ -832,6 +832,9 @@ export class ClaudeCodeHarness {
                 if (message.type === "result") {
                     const resultMsg = message;
                     sawResult = true;
+                    // A completion that failed was still billed: report before the outcome.
+                    if (req.onUsage)
+                        reportCompletionUsage(req.onUsage, extractUsage(resultMsg), this.logger);
                     if (resultMsg.subtype === "success" && "result" in resultMsg) {
                         response = resultMsg.result;
                     }

package/dist/harness/codex.js

@@ -32,7 +32,7 @@ import { CODEX_AUTH_VARS, CODEX_ENV_PREFIXES, agentEnvOverlay, applyEnvOverlay,
 import { CODEX_CAPABILITIES } from "./capabilities.js";
 import { policyGate, resolveHarnessPolicy } from "./policy.js";
 import { gitCredentialPolicy } from "../git-credentials.js";
-import { buildNodePrompt } from "./prompts.js";
+import { buildNodePrompt, reportCompletionUsage } from "./prompts.js";
 import { makeAbort } from "./abort.js";
 import { parseToolResultContent, summarizeToolError, tryParseJSON } from "./parse.js";
 import { startToolBridge } from "./tool-bridge/server.js";
@@ -1055,6 +1055,8 @@ export class CodexHarness {
             // Classification calls use no tools; any tool call is over budget.
             maxToolCalls: 0,
         });
+        // A completion that failed was still billed: report before the outcome.
+        reportCompletionUsage(req.onUsage, out.usage, this.logger);
         if (out.spawnError)
             return failClosed(`codex could not start: ${out.spawnError}`);
         if (out.abortReason === "timeout")

package/dist/harness/compat.js

@@ -35,6 +35,7 @@ export function claudeCompat(claude) {
                 model: req.model,
                 timeoutMs: req.timeoutMs,
                 signal: req.signal,
+                ...(req.onUsage ? { onUsage: req.onUsage } : {}),
             });
         },
     };

package/dist/harness/index.d.ts

@@ -10,7 +10,7 @@ export { claudeCompat, asClaude } from "./compat.js";
 export type { AgentHarness, HarnessCapabilities, HarnessCompleteRequest, HarnessId, HarnessInfo, HarnessRunRequest, HarnessRunResult, NodePolicy, PolicyGateResult, PolicyWrappers, ToolClass, } from "./types.js";
 export { policyGate, budgetGate, nativeDenyClasses, resolveHarnessPolicy, isToolClass, TOOL_CLASSES, } from "./policy.js";
 export type { HarnessPolicyMode } from "./policy.js";
-export { ask, evaluate, buildAskPrompt, buildEvaluatePrompt } from "./prompts.js";
+export { ask, evaluate, buildAskPrompt, buildEvaluatePrompt, reportCompletionUsage } from "./prompts.js";
 export { ClaudeCodeHarness, CLAUDE_CODE_CAPABILITIES } from "./claude-code.js";
 export type { ClaudeCodeHarnessOptions } from "./claude-code.js";
 export { CodexHarness, CODEX_CAPABILITIES, MIN_CODEX_VERSION } from "./codex.js";

package/dist/harness/index.js

@@ -9,7 +9,7 @@ import { PiHarness } from "./pi.js";
 import { parseAcpAgent, unsupportedAgentError } from "./agents.js";
 export { claudeCompat, asClaude } from "./compat.js";
 export { policyGate, budgetGate, nativeDenyClasses, resolveHarnessPolicy, isToolClass, TOOL_CLASSES, } from "./policy.js";
-export { ask, evaluate, buildAskPrompt, buildEvaluatePrompt } from "./prompts.js";
+export { ask, evaluate, buildAskPrompt, buildEvaluatePrompt, reportCompletionUsage } from "./prompts.js";
 export { ClaudeCodeHarness, CLAUDE_CODE_CAPABILITIES } from "./claude-code.js";
 export { CodexHarness, CODEX_CAPABILITIES, MIN_CODEX_VERSION } from "./codex.js";
 export { AcpHarness, ACP_CAPABILITIES, ACP_PROTOCOL_VERSION } from "./acp.js";

package/dist/harness/pi.js

@@ -38,7 +38,7 @@ import { PI_AUTH_VARS, PI_ENV_PREFIXES, PI_NON_SECRET_VARS, agentEnvOverlay, app
 import { PI_CAPABILITIES } from "./capabilities.js";
 import { policyGate, resolveHarnessPolicy } from "./policy.js";
 import { gitCredentialPolicy } from "../git-credentials.js";
-import { buildNodePrompt } from "./prompts.js";
+import { buildNodePrompt, reportCompletionUsage } from "./prompts.js";
 import { makeAbort } from "./abort.js";
 import { parseToolResultContent, summarizeToolError, tryParseJSON } from "./parse.js";
 import { startToolBridge } from "./tool-bridge/server.js";
@@ -1006,6 +1006,8 @@ export class PiHarness {
                 // Classification calls use no tools; any tool call is over budget.
                 maxToolCalls: 0,
             });
+            // A completion that failed was still billed: report before the outcome.
+            reportCompletionUsage(req.onUsage, out.usage, this.logger);
             if (out.spawnError)
                 return failClosed(`pi could not start: ${out.spawnError}`);
             if (out.abortReason === "timeout")

package/dist/harness/prompts.d.ts

@@ -4,8 +4,16 @@
  * `ClaudeClient.ask` / `ClaudeClient.evaluate` built before the harness seam
  * (#330); prompts.test.ts pins them against the old builders.
  */
-import type { Claude, JSONSchema, Logger } from "../types.js";
+import type { Claude, JSONSchema, Logger, NodeUsage } from "../types.js";
 import type { AgentHarness } from "./types.js";
+/**
+ * Hand a completion's usage to the caller's `onUsage`, once, before the
+ * adapter looks at whether the completion succeeded (a failed one was still
+ * billed). A hook that throws is logged and ignored: it never changes the
+ * completion's result, so a good answer is never turned into a failure (and
+ * a judge or route call is never repeated because of it).
+ */
+export declare function reportCompletionUsage(onUsage: ((usage: NodeUsage) => void) | undefined, usage: NodeUsage | undefined, logger?: Logger): void;
 /** @internal Registers the legacy object behind a compat harness. */
 export declare function registerLegacyClaude(harness: AgentHarness, claude: Claude): void;
 /** @internal The legacy `Claude` behind a compat harness, if any. */
@@ -48,6 +56,7 @@ export declare function ask(harness: AgentHarness, opts: {
     model?: string;
     timeoutMs?: number;
     signal?: AbortSignal;
+    onUsage?: (usage: NodeUsage) => void;
 }): Promise<string>;
 /**
  * Route evaluation: pick one of N choices. Fails closed: null when the
@@ -62,4 +71,5 @@ export declare function evaluate(harness: AgentHarness, opts: {
     }[];
     timeoutMs?: number;
     signal?: AbortSignal;
+    onUsage?: (usage: NodeUsage) => void;
 }, logger?: Logger): Promise<string | null>;

package/dist/harness/prompts.js

@@ -6,6 +6,23 @@
  */
 import { consoleLogger } from "../types.js";
 import { fenceUntrustedJson } from "../untrusted.js";
+/**
+ * Hand a completion's usage to the caller's `onUsage`, once, before the
+ * adapter looks at whether the completion succeeded (a failed one was still
+ * billed). A hook that throws is logged and ignored: it never changes the
+ * completion's result, so a good answer is never turned into a failure (and
+ * a judge or route call is never repeated because of it).
+ */
+export function reportCompletionUsage(onUsage, usage, logger) {
+    if (!onUsage || !usage)
+        return;
+    try {
+        onUsage(usage);
+    }
+    catch (err) {
+        (logger ?? consoleLogger).warn(`usage hook failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 /** Legacy `Claude` objects wrapped by `claudeCompat()`, so their own ask/evaluate still win. */
 const LEGACY = new WeakMap();
 /** @internal Registers the legacy object behind a compat harness. */
@@ -76,13 +93,14 @@ export async function ask(harness, opts) {
     const legacy = legacyClaudeOf(harness);
     if (legacy)
         return legacy.ask(opts);
-    const { instruction, context, model, timeoutMs, signal } = opts;
+    const { instruction, context, model, timeoutMs, signal, onUsage } = opts;
     const response = await harness.complete({
         prompt: buildAskPrompt(instruction, context),
         model,
         timeoutMs,
         signal,
         purpose: "ask",
+        ...(onUsage ? { onUsage } : {}),
     });
     return (response ?? "").trim();
 }
@@ -95,12 +113,13 @@ export async function evaluate(harness, opts, logger) {
     if (legacy)
         return legacy.evaluate(opts);
     const log = logger ?? harness.logger ?? consoleLogger;
-    const { question, context, choices, timeoutMs, signal } = opts;
+    const { question, context, choices, timeoutMs, signal, onUsage } = opts;
     const response = await harness.complete({
         prompt: buildEvaluatePrompt(question, context, choices),
         timeoutMs,
         signal,
         purpose: "evaluate",
+        ...(onUsage ? { onUsage } : {}),
     });
     // The adapter already logged why; fail closed with no decision.
     if (response === null)