@sweny-ai/core 0.1.157 → 0.1.158

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

package/dist/schema.d.ts

@@ -848,6 +848,26 @@ export declare const nodePermissionsZ: z.ZodUnion<[z.ZodEnum<["read", "write"]>,
     deny?: ("shell" | "write" | "edit" | "net" | "subagent")[] | undefined;
     access?: "write" | "read" | undefined;
 }>]>;
+/**
+ * Spend ceiling (#449): input + output tokens and/or reported USD. The object
+ * must declare at least one of the two.
+ */
+export declare const budgetZ: z.ZodEffects<z.ZodObject<{
+    tokens: z.ZodOptional<z.ZodNumber>;
+    cost_usd: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    tokens?: number | undefined;
+    cost_usd?: number | undefined;
+}, {
+    tokens?: number | undefined;
+    cost_usd?: number | undefined;
+}>, {
+    tokens?: number | undefined;
+    cost_usd?: number | undefined;
+}, {
+    tokens?: number | undefined;
+    cost_usd?: number | undefined;
+}>;
 /** One typed write intent a node may emit (#365). */
 export declare const safeOutputDeclarationZ: z.ZodObject<{
     type: z.ZodEnum<["comment", "issue", "pr", "label", "issue_state"]>;
@@ -940,6 +960,22 @@ export declare const nodeZ: z.ZodObject<{
     skills: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     output: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     max_turns: z.ZodOptional<z.ZodNumber>;
+    budget: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        tokens: z.ZodOptional<z.ZodNumber>;
+        cost_usd: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    }, {
+        tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    }>, {
+        tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    }, {
+        tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    }>>;
     disallowed_tools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     tools: z.ZodOptional<z.ZodEffects<z.ZodObject<{
         allow: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -1426,6 +1462,10 @@ export declare const nodeZ: z.ZodObject<{
     model?: string | undefined;
     on_fail?: "halt" | "continue" | undefined;
     max_turns?: number | undefined;
+    budget?: {
+        tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    } | undefined;
     disallowed_tools?: string[] | undefined;
     fail_soft?: boolean | undefined;
     permissions?: "write" | "read" | {
@@ -1540,6 +1580,10 @@ export declare const nodeZ: z.ZodObject<{
     on_fail?: "halt" | "continue" | undefined;
     skills?: string[] | undefined;
     max_turns?: number | undefined;
+    budget?: {
+        tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    } | undefined;
     disallowed_tools?: string[] | undefined;
     fail_soft?: boolean | undefined;
     permissions?: "write" | "read" | {
@@ -1698,6 +1742,22 @@ export declare const workflowZ: z.ZodObject<{
         skills: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         output: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         max_turns: z.ZodOptional<z.ZodNumber>;
+        budget: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+            tokens: z.ZodOptional<z.ZodNumber>;
+            cost_usd: z.ZodOptional<z.ZodNumber>;
+        }, "strict", z.ZodTypeAny, {
+            tokens?: number | undefined;
+            cost_usd?: number | undefined;
+        }, {
+            tokens?: number | undefined;
+            cost_usd?: number | undefined;
+        }>, {
+            tokens?: number | undefined;
+            cost_usd?: number | undefined;
+        }, {
+            tokens?: number | undefined;
+            cost_usd?: number | undefined;
+        }>>;
         disallowed_tools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         tools: z.ZodOptional<z.ZodEffects<z.ZodObject<{
             allow: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -2184,6 +2244,10 @@ export declare const workflowZ: z.ZodObject<{
         model?: string | undefined;
         on_fail?: "halt" | "continue" | undefined;
         max_turns?: number | undefined;
+        budget?: {
+            tokens?: number | undefined;
+            cost_usd?: number | undefined;
+        } | undefined;
         disallowed_tools?: string[] | undefined;
         fail_soft?: boolean | undefined;
         permissions?: "write" | "read" | {
@@ -2298,6 +2362,10 @@ export declare const workflowZ: z.ZodObject<{
         on_fail?: "halt" | "continue" | undefined;
         skills?: string[] | undefined;
         max_turns?: number | undefined;
+        budget?: {
+            tokens?: number | undefined;
+            cost_usd?: number | undefined;
+        } | undefined;
         disallowed_tools?: string[] | undefined;
         fail_soft?: boolean | undefined;
         permissions?: "write" | "read" | {
@@ -2547,6 +2615,22 @@ export declare const workflowZ: z.ZodObject<{
     judge_model: z.ZodOptional<z.ZodString>;
     model: z.ZodOptional<z.ZodString>;
     judge_budget: z.ZodOptional<z.ZodNumber>;
+    budget: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        tokens: z.ZodOptional<z.ZodNumber>;
+        cost_usd: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    }, {
+        tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    }>, {
+        tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    }, {
+        tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    }>>;
     context_mode: z.ZodOptional<z.ZodEnum<["bounded", "full"]>>;
     inputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
         type: z.ZodEnum<["string", "number", "boolean", "string[]"]>;
@@ -2658,6 +2742,10 @@ export declare const workflowZ: z.ZodObject<{
         model?: string | undefined;
         on_fail?: "halt" | "continue" | undefined;
         max_turns?: number | undefined;
+        budget?: {
+            tokens?: number | undefined;
+            cost_usd?: number | undefined;
+        } | undefined;
         disallowed_tools?: string[] | undefined;
         fail_soft?: boolean | undefined;
         permissions?: "write" | "read" | {
@@ -2762,6 +2850,10 @@ export declare const workflowZ: z.ZodObject<{
     }[];
     entry: string;
     model?: string | undefined;
+    budget?: {
+        tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    } | undefined;
     permissions?: "write" | "read" | {
         strict?: boolean | undefined;
         deny?: ("shell" | "write" | "edit" | "net" | "subagent")[] | undefined;
@@ -2824,6 +2916,10 @@ export declare const workflowZ: z.ZodObject<{
         on_fail?: "halt" | "continue" | undefined;
         skills?: string[] | undefined;
         max_turns?: number | undefined;
+        budget?: {
+            tokens?: number | undefined;
+            cost_usd?: number | undefined;
+        } | undefined;
         disallowed_tools?: string[] | undefined;
         fail_soft?: boolean | undefined;
         permissions?: "write" | "read" | {
@@ -2942,6 +3038,10 @@ export declare const workflowZ: z.ZodObject<{
             env?: Record<string, string> | undefined;
         } | undefined;
     }> | undefined;
+    budget?: {
+        tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    } | undefined;
     permissions?: "write" | "read" | {
         strict?: boolean | undefined;
         deny?: ("shell" | "write" | "edit" | "net" | "subagent")[] | undefined;
@@ -3032,6 +3132,10 @@ export declare function parseWorkflow(raw: unknown): {
         model?: string | undefined;
         on_fail?: "halt" | "continue" | undefined;
         max_turns?: number | undefined;
+        budget?: {
+            tokens?: number | undefined;
+            cost_usd?: number | undefined;
+        } | undefined;
         disallowed_tools?: string[] | undefined;
         fail_soft?: boolean | undefined;
         permissions?: "write" | "read" | {
@@ -3136,6 +3240,10 @@ export declare function parseWorkflow(raw: unknown): {
     }[];
     entry: string;
     model?: string | undefined;
+    budget?: {
+        tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    } | undefined;
     permissions?: "write" | "read" | {
         strict?: boolean | undefined;
         deny?: ("shell" | "write" | "edit" | "net" | "subagent")[] | undefined;
@@ -3178,7 +3286,7 @@ export declare function parseWorkflow(raw: unknown): {
     } | undefined;
 };
 export interface WorkflowError {
-    code: "MISSING_ENTRY" | "UNKNOWN_EDGE_SOURCE" | "UNKNOWN_EDGE_TARGET" | "UNREACHABLE_NODE" | "UNKNOWN_SKILL" | "SELF_LOOP" | "UNBOUNDED_CYCLE" | "AMBIGUOUS_EDGES" | "UNSUPPORTED_EVAL_POLICY" | "INVALID_INLINE_SKILL" | "EDGE_ITERATIONS_EXCEEDED" | "RETRY_MAX_EXCEEDED" | "PERMISSION_CEILING" | "OUTPUT_NOT_ALLOWED" | "DUPLICATE_OUTPUT" | "UNSUPPORTED_OUTPUT";
+    code: "MISSING_ENTRY" | "UNKNOWN_EDGE_SOURCE" | "UNKNOWN_EDGE_TARGET" | "UNREACHABLE_NODE" | "UNKNOWN_SKILL" | "SELF_LOOP" | "UNBOUNDED_CYCLE" | "AMBIGUOUS_EDGES" | "UNSUPPORTED_EVAL_POLICY" | "INVALID_INLINE_SKILL" | "EDGE_ITERATIONS_EXCEEDED" | "RETRY_MAX_EXCEEDED" | "PERMISSION_CEILING" | "BUDGET_CEILING" | "OUTPUT_NOT_ALLOWED" | "DUPLICATE_OUTPUT" | "UNSUPPORTED_OUTPUT";
     message: string;
     nodeId?: string;
 }
@@ -3438,6 +3546,24 @@ export declare const workflowJsonSchema: {
                 };
             }];
         };
+        readonly Budget: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly minProperties: 1;
+            readonly description: "A spend ceiling. 'tokens' counts input plus output tokens as the harness reports them; 'cost_usd' is the harness-reported cost (never estimated). A crossing stops the agent and fails the node; the run halts.";
+            readonly properties: {
+                readonly tokens: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly description: "Max input plus output tokens.";
+                };
+                readonly cost_usd: {
+                    readonly type: "number";
+                    readonly exclusiveMinimum: 0;
+                    readonly description: "Max reported cost in USD.";
+                };
+            };
+        };
         readonly SafeOutput: {
             readonly type: "object";
             readonly required: readonly ["type"];
@@ -3614,6 +3740,10 @@ export declare const workflowJsonSchema: {
             readonly minimum: 0;
             readonly description: "Soft cap on expected judge calls per workflow run. Executor warns at load time if exceeded; not a hard runtime cap in v1.";
         };
+        readonly budget: {
+            readonly $ref: "#/$defs/Budget";
+            readonly description: "Spend ceiling for the whole run and for every node. A node's own budget may only narrow it. The CLI's --max-tokens and --max-cost tighten it further.";
+        };
         readonly context_mode: {
             readonly type: "string";
             readonly enum: readonly ["bounded", "full"];
@@ -3779,6 +3909,10 @@ export declare const workflowJsonSchema: {
                         readonly minimum: 1;
                         readonly description: "Max AI model turns for this node. When absent, the executor's default applies.";
                     };
+                    readonly budget: {
+                        readonly $ref: "#/$defs/Budget";
+                        readonly description: "Spend ceiling for one visit to this node, retry attempts included. Never above the workflow's budget. Crossing it stops the agent and fails the node (fail_soft and on_fail: continue do not apply) and the run halts.";
+                    };
                     readonly disallowed_tools: {
                         readonly type: "array";
                         readonly items: {

package/dist/schema.js

@@ -262,6 +262,19 @@ export const nodePermissionsZ = z.union([
         message: "permissions must declare at least one of access, deny, strict",
     }),
 ]);
+/**
+ * Spend ceiling (#449): input + output tokens and/or reported USD. The object
+ * must declare at least one of the two.
+ */
+export const budgetZ = z
+    .object({
+    tokens: z.number().int().min(1).optional(),
+    cost_usd: z.number().positive().optional(),
+})
+    .strict()
+    .refine((b) => b.tokens !== undefined || b.cost_usd !== undefined, {
+    message: "budget must declare at least one of tokens, cost_usd",
+});
 /** One typed write intent a node may emit (#365). */
 export const safeOutputDeclarationZ = z
     .object({
@@ -296,6 +309,7 @@ export const nodeZ = z
     skills: z.array(z.string()).default([]),
     output: jsonSchemaZ.optional(),
     max_turns: z.number().int().min(1).optional(),
+    budget: budgetZ.optional(),
     disallowed_tools: z.array(z.string().min(1)).optional(),
     tools: nodeToolsZ.optional(),
     fail_soft: z.boolean().optional(),
@@ -353,6 +367,7 @@ export const workflowZ = z.object({
     judge_model: z.string().min(1).optional(),
     model: z.string().min(1).optional(),
     judge_budget: z.number().int().min(0).optional(),
+    budget: budgetZ.optional(),
     context_mode: z.enum(CONTEXT_MODES).optional(),
     inputs: workflowInputsZ.optional(),
     permissions: nodePermissionsZ.optional(),
@@ -611,6 +626,27 @@ export function validateWorkflow(workflow, knownSkills) {
                 nodeId,
             });
         }
+        // Budgets (#449): the workflow's `budget` is the ceiling for every node.
+        const wfBudget = workflow.budget;
+        const nodeBudget = node.budget;
+        if (wfBudget && nodeBudget) {
+            if (wfBudget.tokens !== undefined && nodeBudget.tokens !== undefined && nodeBudget.tokens > wfBudget.tokens) {
+                errors.push({
+                    code: "BUDGET_CEILING",
+                    message: `Node "${nodeId}" declares budget.tokens ${nodeBudget.tokens}, above the workflow's budget.tokens ${wfBudget.tokens}`,
+                    nodeId,
+                });
+            }
+            if (wfBudget.cost_usd !== undefined &&
+                nodeBudget.cost_usd !== undefined &&
+                nodeBudget.cost_usd > wfBudget.cost_usd) {
+                errors.push({
+                    code: "BUDGET_CEILING",
+                    message: `Node "${nodeId}" declares budget.cost_usd ${nodeBudget.cost_usd}, above the workflow's budget.cost_usd ${wfBudget.cost_usd}`,
+                    nodeId,
+                });
+            }
+        }
         const seenTypes = new Set();
         for (const out of node.outputs ?? []) {
             if (seenTypes.has(out.type)) {
@@ -844,6 +880,16 @@ export const workflowJsonSchema = {
                 },
             ],
         },
+        Budget: {
+            type: "object",
+            additionalProperties: false,
+            minProperties: 1,
+            description: "A spend ceiling. 'tokens' counts input plus output tokens as the harness reports them; 'cost_usd' is the harness-reported cost (never estimated). A crossing stops the agent and fails the node; the run halts.",
+            properties: {
+                tokens: { type: "integer", minimum: 1, description: "Max input plus output tokens." },
+                cost_usd: { type: "number", exclusiveMinimum: 0, description: "Max reported cost in USD." },
+            },
+        },
         SafeOutput: {
             type: "object",
             required: ["type"],
@@ -984,6 +1030,10 @@ export const workflowJsonSchema = {
             // applies the soft-cap default at use-time. See judge_model above.
             description: "Soft cap on expected judge calls per workflow run. Executor warns at load time if exceeded; not a hard runtime cap in v1.",
         },
+        budget: {
+            $ref: "#/$defs/Budget",
+            description: "Spend ceiling for the whole run and for every node. A node's own budget may only narrow it. The CLI's --max-tokens and --max-cost tighten it further.",
+        },
         context_mode: {
             type: "string",
             enum: [...CONTEXT_MODES],
@@ -1100,6 +1150,10 @@ export const workflowJsonSchema = {
                         minimum: 1,
                         description: "Max AI model turns for this node. When absent, the executor's default applies.",
                     },
+                    budget: {
+                        $ref: "#/$defs/Budget",
+                        description: "Spend ceiling for one visit to this node, retry attempts included. Never above the workflow's budget. Crossing it stops the agent and fails the node (fail_soft and on_fail: continue do not apply) and the run halts.",
+                    },
                     disallowed_tools: {
                         type: "array",
                         items: { type: "string", minLength: 1 },