@sweny-ai/core 0.1.156 → 0.1.158

package/dist/executor.js

@@ -23,7 +23,8 @@ import { validateWorkflow } from "./schema.js";
 import { resolveAgentAccess } from "./agent-env.js";
 import { fenceUntrusted } from "./untrusted.js";
 import { asClaude } from "./harness/compat.js";
-import { isToolClass, policyGate } from "./harness/policy.js";
+import { budgetGate, isToolClass, policyGate, resolveHarnessPolicy } from "./harness/policy.js";
+import { BudgetGuard, describeOverrun, minLimits, toLimits } from "./budget.js";
 import { buildNodePolicy, resolveNodePermissions } from "./node-policy.js";
 import { applySafeOutputs, createEmitOutputTool, createWriteStageState, resolveActor, safeOutputsInstruction, unresolvedOutputs, SAFE_OUTPUT_SCREEN_INSTRUCTION, } from "./safe-outputs.js";
 /**
@@ -82,6 +83,10 @@ export async function execute(workflow, input, options) {
     const actor = usesOutputs ? resolveActor(runEnv, options.actor) : {};
     // The run input, for `number: { input }` issue pins on outputs.
     const runInput = input && typeof input === "object" ? input : undefined;
+    // 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)));
+    const harnessPolicy = options.harnessPolicy ?? resolveHarnessPolicy(runEnv);
     // Build an eval-time alias table from the loaded skills. Each skill owns
     // its own mapping between skill-tool names and equivalent MCP names. Core
     // stays vendor-neutral; this call just unions what the skills declare.
@@ -206,14 +211,22 @@ export async function execute(workflow, input, options) {
         // (a Record<name, EvalResult> for downstream lookup like
         // `priorNode.evals.tests_run_clean.pass`). This namespace is reserved
         // for runtime verdicts; an agent-provided `data.evals` never overrides it.
-        const context = {
+        // `requires` always reads this full map: it is a deterministic gate, not
+        // a prompt, so it costs no tokens and keeps every declared path working.
+        const requiresContext = {
             input,
             ...Object.fromEntries([...results.entries()].map(([k, v]) => [k, buildPriorNodeContext(v)])),
         };
+        // What the model sees (#337): only nodes this one can depend on, and a
+        // schema'd node's declared fields instead of its prose. `context_mode:
+        // full` keeps the old everything-prior map.
+        const context = workflow.context_mode === "full"
+            ? requiresContext
+            : buildBoundedContext(workflow, currentId, results, input, resolvedInstruction);
         // Pre-condition gate: evaluate `requires` against the cross-node context
         // BEFORE invoking the LLM. Failure either marks the node failed (on_fail
         // default) or skipped (on_fail: "skip") and skips execution entirely.
-        const requiresError = evaluateRequires(node.requires, context);
+        const requiresError = evaluateRequires(node.requires, requiresContext);
         if (requiresError) {
             const onFail = node.requires?.on_fail ?? "fail";
             const result = onFail === "skip"
@@ -304,39 +317,98 @@ export async function execute(workflow, input, options) {
         const gate = nodePolicy && options.harness
             ? policyGate(options.harness.capabilities, { ...nodePolicy, egress: [] })
             : undefined;
+        // Spend budgets (#449): this node's own limits plus what is left of the
+        // 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));
+        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;
+        let previous;
         while (true) {
-            if (gate?.refuse) {
+            const refusal = gate?.refuse ?? budgetCheck?.refuse;
+            if (refusal) {
                 // Not an agent failure: fail_soft never softens a policy refusal.
-                logger.warn(`  harness refused the node: ${gate.refuse}`, { node: currentId });
+                logger.warn(`  harness refused the node: ${refusal}`, { node: currentId });
                 result = {
                     status: "failed",
-                    data: { error: gate.refuse, refused: true },
+                    data: { error: refusal, refused: true },
                     toolCalls: [],
-                    degraded: gate.degraded,
+                    degraded: [...(gate?.degraded ?? []), ...(budgetCheck?.degraded ?? [])],
                 };
                 break;
             }
+            // No attempt may start once a ceiling is reached (the run's budget spent
+            // by earlier nodes, or this node's by an earlier attempt).
+            const spent = budgetOn ? nodeBudget.exhausted() : undefined;
+            if (spent) {
+                const error = describeOverrun(spent, currentId);
+                logger.warn(`  ${error}; not starting the node`, { node: currentId });
+                result = {
+                    ...(previous ?? { toolCalls: [] }),
+                    status: "failed",
+                    data: { ...(previous?.data ?? {}), error, budget_exceeded: true },
+                    budget: spent,
+                };
+                agentRunFailed = true;
+                budgetStop = spent;
+                break;
+            }
             // Only the final attempt's intents may be applied.
             intents.length = 0;
-            result = await claude.run({
-                instruction: currentInstruction,
-                context,
-                tools: trackedTools,
-                outputSchema: node.output,
-                maxTurns: node.max_turns,
-                disallowedTools: node.disallowed_tools,
-                ...(denyClasses.length > 0 ? { deny: denyClasses } : {}),
-                model: nodeModel,
-                signal,
-                timeoutMs,
-                agentAccess,
-                ...(nodePolicy ? { policy: nodePolicy } : {}),
-                ...(readOnlyNode ? {} : { mcpServers: skillMcpServers }),
-                ...(readOnlyNode ? { readOnly: true } : {}),
-                onProgress: (message) => {
-                    safeObserve(observer, { type: "node:progress", node: currentId, message }, logger);
-                },
-            });
+            const attemptBudget = budgetOn ? nodeBudget.attempt(signal) : undefined;
+            try {
+                result = await claude.run({
+                    instruction: currentInstruction,
+                    context,
+                    tools: trackedTools,
+                    outputSchema: node.output,
+                    maxTurns: node.max_turns,
+                    disallowedTools: node.disallowed_tools,
+                    ...(denyClasses.length > 0 ? { deny: denyClasses } : {}),
+                    model: nodeModel,
+                    signal: attemptBudget?.signal ?? signal,
+                    timeoutMs,
+                    agentAccess,
+                    ...(nodePolicy ? { policy: nodePolicy } : {}),
+                    ...(readOnlyNode ? {} : { mcpServers: skillMcpServers }),
+                    ...(readOnlyNode ? { readOnly: true } : {}),
+                    ...(attemptBudget ? { onUsage: attemptBudget.onUsage } : {}),
+                    onProgress: (message) => {
+                        safeObserve(observer, { type: "node:progress", node: currentId, message }, logger);
+                    },
+                });
+            }
+            finally {
+                attemptBudget?.dispose();
+            }
+            previous = result;
+            if (budgetCheck && budgetCheck.degraded.length > 0) {
+                result = { ...result, degraded: [...new Set([...(result.degraded ?? []), ...budgetCheck.degraded])] };
+            }
+            if (attemptBudget) {
+                // Commit this attempt's spend; a live stop, or a crossing visible only
+                // in the final usage, fails the node whatever else it did.
+                const breach = attemptBudget.finish(result.usage);
+                if (breach) {
+                    const error = describeOverrun(breach, currentId);
+                    logger.warn(`  ${error}`, { node: currentId });
+                    const usage = result.usage ?? attemptBudget.lastUsage;
+                    result = {
+                        ...result,
+                        status: "failed",
+                        data: { ...result.data, error, budget_exceeded: true },
+                        ...(usage ? { usage } : {}),
+                        budget: breach,
+                    };
+                    agentRunFailed = true;
+                    budgetStop = breach;
+                    break;
+                }
+            }
             // Opinions the harness could not honor natively: said once per node, never silently dropped.
             if (!degradedLogged && result.degraded && result.degraded.length > 0) {
                 degradedLogged = true;
@@ -442,7 +514,7 @@ export async function execute(workflow, input, options) {
         // observers. Eval failures never take this path (agentRunFailed guards it).
         // A strict-policy refusal (#331) is not an agent failure: fail_soft never softens it.
         const refused = result.data?.refused === true;
-        if (agentRunFailed && result.status === "failed" && node.fail_soft === true && !refused) {
+        if (agentRunFailed && result.status === "failed" && node.fail_soft === true && !refused && !budgetStop) {
             const failError = result.data?.error;
             logger.warn(`  fail_soft: node failed (${String(failError ?? "unknown error")}); continuing with partial output`, {
                 node: currentId,
@@ -508,9 +580,10 @@ export async function execute(workflow, input, options) {
         // the back of a failure. The failed result stays in `results`, so the run
         // surfaces as failed to callers (CLI exit code, cloud status). Authors who
         // want the legacy fall-through opt in per-node with `on_fail: "continue"`.
-        if (result.status === "failed" && (node.on_fail ?? "halt") === "halt") {
-            logger.warn(`  node failed; halting workflow (on_fail: halt)`, { node: currentId });
-            safeObserve(observer, { type: "route", from: currentId, to: "(end)", reason: "node failed (on_fail: halt)" }, logger);
+        if (result.status === "failed" && ((node.on_fail ?? "halt") === "halt" || budgetStop)) {
+            const why = budgetStop ? "budget exceeded" : "on_fail: halt";
+            logger.warn(`  node failed; halting workflow (${why})`, { node: currentId });
+            safeObserve(observer, { type: "route", from: currentId, to: "(end)", reason: `node failed (${why})` }, logger);
             break;
         }
         // Dry run gate + routing — shared with requires path via advanceFromNode helper.
@@ -653,9 +726,9 @@ function buildPriorNodeContext(result) {
  * evaluator. When no schema is declared we fall back to the full data
  * (back-compat for workflows without structured outputs).
  *
- * The downstream node prompt is untouched: nodes still see the full prior
- * `data` including any prose `summary`, so workflows that consume the
- * narrative in subsequent steps keep working.
+ * Downstream node prompts get a similar projection (see
+ * `buildBoundedNodeEntry`), minus the null-fill, unless the workflow sets
+ * `context_mode: full`.
  */
 function buildRouteEvalEntry(result, sourceNode) {
     const fullData = (result.data ?? {});
@@ -714,6 +787,77 @@ function getDeclaredOutputProperties(output) {
         return null;
     return new Set(keys);
 }
+// ─── Bounded node context (#337) ─────────────────────────────────
+//
+// Full mode hands every node the whole results map: node N re-sends nodes
+// 1..N-1 including each one's prose `summary`, so prompt bytes per run grow
+// quadratically and one verbose node inflates every later prompt. Bounded
+// mode (the default) keeps the same keys a node can depend on, and sends a
+// schema'd node's declared fields only.
+/** Keys the executor itself writes into data; kept when a view is projected. */
+const RUNTIME_DATA_KEYS = ["error", "fail_soft", "skipped_reason"];
+/**
+ * The prompt-context entry for one prior node in bounded mode. A successful
+ * node with a declared `output.properties` block contributes those fields
+ * (plus executor-written error/fail_soft keys); everything else, including
+ * the free-text `summary`, is dropped. Nodes without a schema, and nodes
+ * that did not succeed, keep the full `buildPriorNodeContext` entry. The
+ * trusted `evals` and `safe_outputs` namespaces always come from the runtime.
+ */
+function buildBoundedNodeEntry(result, sourceNode) {
+    const full = buildPriorNodeContext(result);
+    const declared = getDeclaredOutputProperties(sourceNode?.output);
+    if (!declared || result.status !== "success")
+        return full;
+    const keep = new Set([...declared, ...RUNTIME_DATA_KEYS, "evals", "safe_outputs"]);
+    return Object.fromEntries(Object.entries(full).filter(([k]) => keep.has(k)));
+}
+/** First segment of a requires path (`any:triage.findings[*].x` -> `triage`). */
+function pathRoot(path) {
+    return /^(?:all:|any:)?([^.[\]]+)/.exec(path)?.[1];
+}
+function mentionsNode(text, nodeId) {
+    const escaped = nodeId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(?<![A-Za-z0-9_-])${escaped}(?![A-Za-z0-9_-])`).test(text);
+}
+/**
+ * Node ids whose results `nodeId` may read: its graph ancestors (every node
+ * with an edge path into it, itself included when it sits on a cycle), any
+ * node a `requires` path names, and any node id its instruction mentions.
+ */
+function contextDependencies(workflow, nodeId, instruction = "") {
+    const deps = new Set();
+    const stack = [nodeId];
+    for (let id = stack.pop(); id !== undefined; id = stack.pop()) {
+        for (const e of workflow.edges) {
+            if (e.to === id && !deps.has(e.from)) {
+                deps.add(e.from);
+                stack.push(e.from);
+            }
+        }
+    }
+    const requires = workflow.nodes[nodeId]?.requires;
+    for (const p of [...(requires?.output_required ?? []), ...(requires?.output_matches ?? []).map((m) => m.path)]) {
+        const root = pathRoot(p);
+        if (root && root !== "input")
+            deps.add(root);
+    }
+    for (const id of Object.keys(workflow.nodes)) {
+        if (id !== nodeId && mentionsNode(instruction, id))
+            deps.add(id);
+    }
+    return deps;
+}
+/** The bounded prompt context for one node: `input` plus its dependencies' entries. */
+function buildBoundedContext(workflow, nodeId, results, input, instruction) {
+    const deps = contextDependencies(workflow, nodeId, instruction);
+    return {
+        input,
+        ...Object.fromEntries([...results.entries()]
+            .filter(([k]) => deps.has(k))
+            .map(([k, v]) => [k, buildBoundedNodeEntry(v, workflow.nodes[k])])),
+    };
+}
 /**
  * Return the declared `required` field names for a node's output schema,
  * or an empty array when no required block is declared. Tolerant of

package/dist/harness/acp.js

@@ -437,8 +437,10 @@ export class AcpHarness {
                     // `used` and `size` are context window occupancy, not billed tokens: not mapped.
                     const cost = u.cost;
                     if (isObj(cost) && typeof cost.amount === "number" && Number.isFinite(cost.amount)) {
-                        if (typeof cost.currency === "string" && cost.currency.toUpperCase() === "USD")
+                        if (typeof cost.currency === "string" && cost.currency.toUpperCase() === "USD") {
                             out.costUsd = cost.amount;
+                            o.onUsage?.({ costUsd: cost.amount });
+                        }
                         else if (!costWarned) {
                             costWarned = true;
                             this.logger.debug(`[acp] usage_update cost is in ${String(cost.currency)}, not USD: not recorded`);
@@ -789,6 +791,7 @@ export class AcpHarness {
                     signal: req.signal,
                     maxToolCalls: maxTurns,
                     onProgress: req.onProgress,
+                    onUsage: req.onUsage,
                 });
             }
             finally {

package/dist/harness/capabilities.d.ts

@@ -3,7 +3,12 @@
  * them without pulling in an agent SDK.
  */
 import type { HarnessCapabilities } from "./types.js";
-/** Claude Code enforces every sweny opinion natively, so `policyGate` never degrades or refuses it. */
+/**
+ * Claude Code enforces every sweny opinion natively, so `policyGate` never degrades or refuses it.
+ * usage: tokens live (per assistant message, a lower bound until the terminal
+ * `result` message gives the authoritative total); cost only at the end of the
+ * node (the SDK prices the run in `total_cost_usd` on `result`).
+ */
 export declare const CLAUDE_CODE_CAPABILITIES: HarnessCapabilities;
 /**
  * Codex (`codex exec --json`), declared from the openai/codex source at
@@ -81,9 +86,10 @@ export declare const PI_CAPABILITIES: HarnessCapabilities;
  * - readOnly none: modes are agent-defined. `policyGate` counts read-only as
  *   enforced only with the wrapper's read-only mount.
  * - turnLimit watchdog: no turn limit in the protocol; sweny counts tool calls.
- * - usage costUsd only: `usage_update {used, size, cost?}` is the stable
- *   usage. `used` and `size` are context window occupancy, not billed tokens,
- *   so they are not mapped; `cost` (cumulative, ISO 4217 currency) is, when it
+ * - usage costUsd only, live: `usage_update {used, size, cost?}` is the stable
+ *   usage and arrives while the turn runs, so a cost budget stops the agent
+ *   mid-node. `used` and `size` are context window occupancy, not billed
+ *   tokens, so they are not mapped; `cost` (cumulative, ISO 4217 currency) is, when it
  *   is USD. Per-turn token usage is behind an unstable flag.
  * - cancel rpc: `session/cancel`, then kill.
  * - resume false: sweny starts a fresh session per node.

package/dist/harness/capabilities.js

@@ -2,7 +2,12 @@
  * Declared capabilities per adapter. No runtime imports, so the executor can use
  * them without pulling in an agent SDK.
  */
-/** Claude Code enforces every sweny opinion natively, so `policyGate` never degrades or refuses it. */
+/**
+ * Claude Code enforces every sweny opinion natively, so `policyGate` never degrades or refuses it.
+ * usage: tokens live (per assistant message, a lower bound until the terminal
+ * `result` message gives the authoritative total); cost only at the end of the
+ * node (the SDK prices the run in `total_cost_usd` on `result`).
+ */
 export const CLAUDE_CODE_CAPABILITIES = {
     structuredOutput: "native",
     toolTrace: "full",
@@ -11,7 +16,7 @@ export const CLAUDE_CODE_CAPABILITIES = {
     sandbox: { fs: true, network: true },
     readOnly: "native",
     turnLimit: "native",
-    usage: { tokens: true, costUsd: true, live: false },
+    usage: { tokens: true, costUsd: true, live: true, liveUnits: ["tokens"] },
     cancel: "signal",
     resume: false,
 };
@@ -115,9 +120,10 @@ export const PI_CAPABILITIES = {
  * - readOnly none: modes are agent-defined. `policyGate` counts read-only as
  *   enforced only with the wrapper's read-only mount.
  * - turnLimit watchdog: no turn limit in the protocol; sweny counts tool calls.
- * - usage costUsd only: `usage_update {used, size, cost?}` is the stable
- *   usage. `used` and `size` are context window occupancy, not billed tokens,
- *   so they are not mapped; `cost` (cumulative, ISO 4217 currency) is, when it
+ * - usage costUsd only, live: `usage_update {used, size, cost?}` is the stable
+ *   usage and arrives while the turn runs, so a cost budget stops the agent
+ *   mid-node. `used` and `size` are context window occupancy, not billed
+ *   tokens, so they are not mapped; `cost` (cumulative, ISO 4217 currency) is, when it
  *   is USD. Per-turn token usage is behind an unstable flag.
  * - cancel rpc: `session/cancel`, then kill.
  * - resume false: sweny starts a fresh session per node.
@@ -130,7 +136,7 @@ export const ACP_CAPABILITIES = {
     sandbox: { fs: false, network: false },
     readOnly: "none",
     turnLimit: "watchdog",
-    usage: { tokens: false, costUsd: true, live: false },
+    usage: { tokens: false, costUsd: true, live: true, liveUnits: ["costUsd"] },
     cancel: "rpc",
     resume: false,
 };

package/dist/harness/claude-code.js

@@ -315,7 +315,7 @@ export class ClaudeCodeHarness {
         return { ...result, harness: this.info(), degraded: gate.degraded };
     }
     async runQuery(opts) {
-        const { instruction, context, tools, outputSchema, onProgress, maxTurns, model, timeoutMs, signal, readOnly, agentAccess, } = opts;
+        const { instruction, context, tools, outputSchema, onProgress, maxTurns, model, timeoutMs, signal, readOnly, agentAccess, onUsage, } = opts;
         // Dry run (#380): external MCP servers cannot be classified per tool, so
         // they are unknown, and unknown means write. Drop them, and disallow the
         // built-ins that can change the workspace or shell out.
@@ -361,6 +361,11 @@ export class ClaudeCodeHarness {
         // why FIFO-by-name is wrong.
         const toolCalls = [];
         const pendingByUseId = new Map();
+        // Live token tally (#449). Each assistant message carries its API
+        // message's usage; the SDK repeats one API message across its content
+        // blocks, so keep the latest per message id and sum. A lower bound until
+        // the terminal `result` message, whose total is authoritative.
+        const liveByMessage = new Map();
         // Convert core tools to SDK MCP tools. The wrapper invokes the user's
         // handler and returns `content` via the MCP transport. We do not push
         // to toolCalls from the wrapper - the stream's tool_result is the sole
@@ -468,6 +473,25 @@ export class ClaudeCodeHarness {
                     // Tool_use blocks start a ToolCall record. Status + output are
                     // filled in when the matching user tool_result arrives.
                     const am = message;
+                    if (onUsage) {
+                        const u = am.message?.usage;
+                        if (u && typeof u === "object") {
+                            const key = typeof am.message?.id === "string" ? am.message.id : `#${liveByMessage.size}`;
+                            const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+                            const prev = liveByMessage.get(key);
+                            liveByMessage.set(key, {
+                                input: Math.max(prev?.input ?? 0, num(u.input_tokens)),
+                                output: Math.max(prev?.output ?? 0, num(u.output_tokens)),
+                            });
+                            let inputTokens = 0;
+                            let outputTokens = 0;
+                            for (const v of liveByMessage.values()) {
+                                inputTokens += v.input;
+                                outputTokens += v.output;
+                            }
+                            onUsage({ inputTokens, outputTokens });
+                        }
+                    }
                     if (am.message?.content && Array.isArray(am.message.content)) {
                         for (const block of am.message.content) {
                             if (block.type === "tool_use") {

package/dist/harness/index.d.ts

@@ -8,7 +8,7 @@ import { AcpHarness, type AcpHarnessOptions } from "./acp.js";
 import { PiHarness, type PiHarnessOptions } from "./pi.js";
 export { claudeCompat, asClaude } from "./compat.js";
 export type { AgentHarness, HarnessCapabilities, HarnessCompleteRequest, HarnessId, HarnessInfo, HarnessRunRequest, HarnessRunResult, NodePolicy, PolicyGateResult, PolicyWrappers, ToolClass, } from "./types.js";
-export { policyGate, nativeDenyClasses, resolveHarnessPolicy, isToolClass, TOOL_CLASSES } from "./policy.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 { ClaudeCodeHarness, CLAUDE_CODE_CAPABILITIES } from "./claude-code.js";

package/dist/harness/index.js

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

package/dist/harness/policy.d.ts

@@ -12,6 +12,7 @@
  * - wrapped: sweny keeps the opinion itself, but not natively (for example a
  *   watchdog in place of a native turn limit). Reported, never refused.
  */
+import type { SpendLimits } from "../budget.js";
 import type { HarnessCapabilities, NodePolicy, PolicyGateResult, PolicyWrappers, ToolClass } from "./types.js";
 /** `strict` refuses a node whose opinions the harness cannot honor; `warn` runs it and reports `degraded`. */
 export type HarnessPolicyMode = "strict" | "warn";
@@ -30,3 +31,15 @@ export declare function isToolClass(name: string): name is ToolClass;
 /** The tool classes a harness can deny natively. */
 export declare function nativeDenyClasses(caps: HarnessCapabilities): ToolClass[];
 export declare function policyGate(caps: HarnessCapabilities, policy: NodePolicy, wrappers?: PolicyWrappers): PolicyGateResult;
+/**
+ * budgetGate (#449): can this harness keep a spend budget? Pure; the executor
+ * calls it once per node that has a token or cost limit (node or run).
+ *
+ * Per budgeted unit:
+ * - the harness cannot report the unit at all (Codex has no cost): nothing can
+ *   be enforced. Reported as `budget_<unit>`; `strict` refuses the node.
+ * - the harness reports it only when the node ends: enforced between nodes, so
+ *   one node can overrun before it is stopped. Reported as `budget_live`,
+ *   never refused.
+ */
+export declare function budgetGate(caps: HarnessCapabilities, limits: SpendLimits, strict: boolean): PolicyGateResult;

package/dist/harness/policy.js

@@ -111,3 +111,40 @@ export function policyGate(caps, policy, wrappers = {}) {
     }
     return { degraded };
 }
+/**
+ * budgetGate (#449): can this harness keep a spend budget? Pure; the executor
+ * calls it once per node that has a token or cost limit (node or run).
+ *
+ * Per budgeted unit:
+ * - the harness cannot report the unit at all (Codex has no cost): nothing can
+ *   be enforced. Reported as `budget_<unit>`; `strict` refuses the node.
+ * - the harness reports it only when the node ends: enforced between nodes, so
+ *   one node can overrun before it is stopped. Reported as `budget_live`,
+ *   never refused.
+ */
+export function budgetGate(caps, limits, strict) {
+    const unenforced = [];
+    const wrapped = [];
+    const units = [
+        { unit: "tokens", key: "tokens", limit: limits.tokens, reports: caps.usage.tokens },
+        { unit: "cost_usd", key: "costUsd", limit: limits.costUsd, reports: caps.usage.costUsd },
+    ];
+    const notLive = [];
+    for (const u of units) {
+        if (u.limit === undefined)
+            continue;
+        if (!u.reports) {
+            unenforced.push(`budget_${u.unit}: harness cannot report ${u.unit === "tokens" ? "token" : "cost"} usage, so this budget is not enforced`);
+        }
+        else if (!caps.usage.live || (caps.usage.liveUnits !== undefined && !caps.usage.liveUnits.includes(u.key))) {
+            notLive.push(u.unit);
+        }
+    }
+    if (notLive.length > 0) {
+        wrapped.push(`budget_live: harness reports ${notLive.join(" and ")} only when a node ends; the budget is enforced between nodes, so a node can overrun before it is stopped`);
+    }
+    const degraded = [...unenforced, ...wrapped];
+    if (unenforced.length > 0 && strict)
+        return { degraded, refuse: `strict policy: ${unenforced.join("; ")}` };
+    return { degraded };
+}

package/dist/harness/types.d.ts

@@ -36,10 +36,17 @@ export interface HarnessCapabilities {
     };
     readOnly: "native" | "tool-allowlist" | "none";
     turnLimit: "native" | "watchdog" | "none";
+    /**
+     * What the harness reports. `live`: usage arrives while the node runs (through
+     * `HarnessRunRequest.onUsage`), so a spend budget stops the agent mid-node.
+     * `liveUnits` narrows which of the reported units arrive live; absent means
+     * every reported unit. Without `live`, budgets are enforced between nodes.
+     */
     usage: {
         tokens: boolean;
         costUsd: boolean;
         live: boolean;
+        liveUnits?: Array<"tokens" | "costUsd">;
     };
     cancel: "signal" | "rpc" | "kill";
     resume: boolean;

package/dist/index.d.ts

@@ -27,6 +27,8 @@ export { EVALUATOR_KINDS, EVAL_POLICIES, REQUIRES_ON_FAIL, NODE_ON_FAIL, MCP_TRA
 export { consoleLogger } from "./types.js";
 export { execute, RouteEvaluationError } from "./executor.js";
 export type { ExecuteOptions } from "./executor.js";
+export { BudgetGuard, describeOverrun, minLimits, toLimits } from "./budget.js";
+export type { Budget, BudgetOverrun, BudgetUnit, SpendLimits } from "./budget.js";
 export { resolveNodePermissions, buildNodePolicy } from "./node-policy.js";
 export type { ResolvedPermissions } from "./node-policy.js";
 export { applySafeOutputs, createEmitOutputTool, resolveActor, EMIT_OUTPUT_TOOL } from "./safe-outputs.js";

package/dist/index.js

@@ -28,6 +28,7 @@ export { consoleLogger } from "./types.js";
 // Executor
 export { execute, RouteEvaluationError } from "./executor.js";
 // Least-privilege nodes and safe outputs (#365)
+export { BudgetGuard, describeOverrun, minLimits, toLimits } from "./budget.js";
 export { resolveNodePermissions, buildNodePolicy } from "./node-policy.js";
 export { applySafeOutputs, createEmitOutputTool, resolveActor, EMIT_OUTPUT_TOOL } from "./safe-outputs.js";
 // Agent harness (the seam) and its adapters: Claude Code, Codex and pi