@sweny-ai/core 0.1.157 → 0.1.159

package/dist/budget.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Spend budgets (#449): token and cost ceilings per node and per run.
+ *
+ * Pure and browser-safe. `budget: { tokens, cost_usd }` on a node caps one visit
+ * to that node (every retry attempt included); on the workflow it caps the whole
+ * run, and is the ceiling for every node. The CLI's `--max-tokens` and
+ * `--max-cost` tighten the run ceiling further (the lowest wins).
+ *
+ * Tokens are input + output tokens as the harness reports them (cache reads and
+ * writes are not counted, matching the run receipt). Cost is the harness's own
+ * reported USD, never estimated. Only agent node runs are counted: judge,
+ * routing and retry-reflection completions report no usage and are not metered.
+ *
+ * Enforcement, per unit the harness can report:
+ * - live: the harness calls `onUsage` during the node; crossing a limit aborts
+ *   the attempt's signal, which stops the agent (harness cancel).
+ * - between nodes: usage on the finished result is checked; a crossing fails the
+ *   node, and the run halts before the next node starts.
+ */
+import type { NodeUsage } from "./types.js";
+/** The `budget` field of a node or workflow. */
+export interface Budget {
+    /** Max input + output tokens. */
+    tokens?: number;
+    /** Max reported cost in USD. */
+    cost_usd?: number;
+}
+/** Spend limits in the units the executor works in. Absent = unlimited. */
+export interface SpendLimits {
+    tokens?: number;
+    costUsd?: number;
+}
+export interface Spend {
+    tokens: number;
+    costUsd: number;
+}
+export type BudgetUnit = "tokens" | "cost_usd";
+/** Recorded on the node whose spend crossed a budget (`NodeResult.budget`). */
+export interface BudgetOverrun {
+    /** Which ceiling was crossed: the node's own, or the run's. */
+    scope: "node" | "run";
+    unit: BudgetUnit;
+    limit: number;
+    /** Spend at the moment of the stop (live) or at the end of the node. */
+    spent: number;
+}
+export declare function toLimits(b: Budget | undefined): SpendLimits;
+/** The tighter of two limit sets, per unit. */
+export declare function minLimits(a: SpendLimits, b: SpendLimits): SpendLimits;
+export declare function hasLimits(l: SpendLimits): boolean;
+/** Tokens and cost a usage report carries. A field the harness did not report stays undefined. */
+export declare function spendOf(u: NodeUsage | undefined): {
+    tokens?: number;
+    costUsd?: number;
+};
+/** One line for the log, the node's `data.error` and the receipt. */
+export declare function describeOverrun(o: BudgetOverrun, nodeId?: string): string;
+/**
+ * Tracks spend for one run. `node()` opens a visit to a node; `attempt()` opens
+ * one agent run inside it. Spend is committed when an attempt finishes.
+ */
+export declare class BudgetGuard {
+    readonly runLimits: SpendLimits;
+    private spent;
+    constructor(runLimits: SpendLimits);
+    get totals(): Spend;
+    /** True when any limit exists at all, so the executor can skip the machinery. */
+    active(nodeLimits: SpendLimits): boolean;
+    /** The run ceiling is already reached: no further attempt may start. */
+    runExhausted(): BudgetOverrun | undefined;
+    node(nodeLimits: SpendLimits): NodeBudget;
+    /** @internal */
+    commit(s: Spend): void;
+}
+export declare class NodeBudget {
+    private readonly guard;
+    readonly limits: SpendLimits;
+    private spent;
+    constructor(guard: BudgetGuard, limits: SpendLimits);
+    /** A limit is already reached before the next attempt (a retry after a spend-heavy attempt, or a spent run). */
+    exhausted(): BudgetOverrun | undefined;
+    attempt(outer?: AbortSignal): BudgetAttempt;
+    /** @internal */
+    get committed(): Spend;
+    /** @internal */
+    commit(s: Spend): void;
+}
+/** One agent run. Its `signal` is the caller's signal plus a budget stop. */
+export declare class BudgetAttempt {
+    private readonly guard;
+    private readonly node;
+    private readonly outer?;
+    private readonly controller;
+    private live;
+    private liveUsage;
+    private stopped;
+    private readonly onOuterAbort;
+    constructor(guard: BudgetGuard, node: NodeBudget, outer?: AbortSignal | undefined);
+    get signal(): AbortSignal;
+    /** The breach that stopped this attempt live, if any. */
+    get breach(): BudgetOverrun | undefined;
+    /** Latest usage the harness reported during the run (cumulative for the attempt). */
+    get lastUsage(): NodeUsage | undefined;
+    /** Handed to the harness as `onUsage`. Reports are cumulative for this attempt. */
+    readonly onUsage: (u: NodeUsage) => void;
+    private check;
+    /**
+     * The attempt is over. Commit its spend (the larger of what the result
+     * reports and what was seen live) and return the breach, if any: the live
+     * stop, else a crossing visible only in the final usage.
+     */
+    finish(finalUsage: NodeUsage | undefined): BudgetOverrun | undefined;
+    /** Release the outer-signal listener when the run threw before `finish`. */
+    dispose(): void;
+}

package/dist/budget.js

@@ -0,0 +1,191 @@
+/**
+ * Spend budgets (#449): token and cost ceilings per node and per run.
+ *
+ * Pure and browser-safe. `budget: { tokens, cost_usd }` on a node caps one visit
+ * to that node (every retry attempt included); on the workflow it caps the whole
+ * run, and is the ceiling for every node. The CLI's `--max-tokens` and
+ * `--max-cost` tighten the run ceiling further (the lowest wins).
+ *
+ * Tokens are input + output tokens as the harness reports them (cache reads and
+ * writes are not counted, matching the run receipt). Cost is the harness's own
+ * reported USD, never estimated. Only agent node runs are counted: judge,
+ * routing and retry-reflection completions report no usage and are not metered.
+ *
+ * Enforcement, per unit the harness can report:
+ * - live: the harness calls `onUsage` during the node; crossing a limit aborts
+ *   the attempt's signal, which stops the agent (harness cancel).
+ * - between nodes: usage on the finished result is checked; a crossing fails the
+ *   node, and the run halts before the next node starts.
+ */
+const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+export function toLimits(b) {
+    return {
+        ...(b?.tokens !== undefined ? { tokens: b.tokens } : {}),
+        ...(b?.cost_usd !== undefined ? { costUsd: b.cost_usd } : {}),
+    };
+}
+/** The tighter of two limit sets, per unit. */
+export function minLimits(a, b) {
+    const pick = (x, y) => (x === undefined ? y : y === undefined ? x : Math.min(x, y));
+    const tokens = pick(a.tokens, b.tokens);
+    const costUsd = pick(a.costUsd, b.costUsd);
+    return { ...(tokens !== undefined ? { tokens } : {}), ...(costUsd !== undefined ? { costUsd } : {}) };
+}
+export function hasLimits(l) {
+    return l.tokens !== undefined || l.costUsd !== undefined;
+}
+/** Tokens and cost a usage report carries. A field the harness did not report stays undefined. */
+export function spendOf(u) {
+    if (!u)
+        return {};
+    const tokens = isNum(u.inputTokens) || isNum(u.outputTokens) ? (u.inputTokens ?? 0) + (u.outputTokens ?? 0) : undefined;
+    return { ...(tokens !== undefined ? { tokens } : {}), ...(isNum(u.costUsd) ? { costUsd: u.costUsd } : {}) };
+}
+function over(spent, limit, strictlyOver) {
+    if (limit === undefined)
+        return false;
+    return strictlyOver ? spent > limit : spent >= limit;
+}
+function breachOf(scope, limits, spent, strictlyOver) {
+    if (over(spent.tokens, limits.tokens, strictlyOver)) {
+        return { scope, unit: "tokens", limit: limits.tokens, spent: spent.tokens };
+    }
+    if (over(spent.costUsd, limits.costUsd, strictlyOver)) {
+        return { scope, unit: "cost_usd", limit: limits.costUsd, spent: spent.costUsd };
+    }
+    return undefined;
+}
+/** One line for the log, the node's `data.error` and the receipt. */
+export function describeOverrun(o, nodeId) {
+    const fmt = (n) => o.unit === "cost_usd" ? `$${n < 0.01 ? n.toFixed(4) : n.toFixed(2)}` : String(Math.round(n));
+    const what = o.scope === "run" ? "run budget" : `node budget${nodeId ? ` for '${nodeId}'` : ""}`;
+    return `${what} exceeded: ${o.unit} ${fmt(o.spent)} of ${fmt(o.limit)}`;
+}
+/**
+ * Tracks spend for one run. `node()` opens a visit to a node; `attempt()` opens
+ * one agent run inside it. Spend is committed when an attempt finishes.
+ */
+export class BudgetGuard {
+    runLimits;
+    spent = { tokens: 0, costUsd: 0 };
+    constructor(runLimits) {
+        this.runLimits = runLimits;
+    }
+    get totals() {
+        return { ...this.spent };
+    }
+    /** True when any limit exists at all, so the executor can skip the machinery. */
+    active(nodeLimits) {
+        return hasLimits(this.runLimits) || hasLimits(nodeLimits);
+    }
+    /** The run ceiling is already reached: no further attempt may start. */
+    runExhausted() {
+        return breachOf("run", this.runLimits, this.spent, false);
+    }
+    node(nodeLimits) {
+        return new NodeBudget(this, nodeLimits);
+    }
+    /** @internal */
+    commit(s) {
+        this.spent = { tokens: this.spent.tokens + s.tokens, costUsd: this.spent.costUsd + s.costUsd };
+    }
+}
+export class NodeBudget {
+    guard;
+    limits;
+    spent = { tokens: 0, costUsd: 0 };
+    constructor(guard, limits) {
+        this.guard = guard;
+        this.limits = limits;
+    }
+    /** A limit is already reached before the next attempt (a retry after a spend-heavy attempt, or a spent run). */
+    exhausted() {
+        return breachOf("node", this.limits, this.spent, false) ?? this.guard.runExhausted();
+    }
+    attempt(outer) {
+        return new BudgetAttempt(this.guard, this, outer);
+    }
+    /** @internal */
+    get committed() {
+        return this.spent;
+    }
+    /** @internal */
+    commit(s) {
+        this.spent = { tokens: this.spent.tokens + s.tokens, costUsd: this.spent.costUsd + s.costUsd };
+        this.guard.commit(s);
+    }
+}
+/** One agent run. Its `signal` is the caller's signal plus a budget stop. */
+export class BudgetAttempt {
+    guard;
+    node;
+    outer;
+    controller = new AbortController();
+    live = { tokens: 0, costUsd: 0 };
+    liveUsage;
+    stopped;
+    onOuterAbort = () => this.controller.abort();
+    constructor(guard, node, outer) {
+        this.guard = guard;
+        this.node = node;
+        this.outer = outer;
+        if (outer?.aborted)
+            this.controller.abort();
+        else
+            outer?.addEventListener("abort", this.onOuterAbort, { once: true });
+    }
+    get signal() {
+        return this.controller.signal;
+    }
+    /** The breach that stopped this attempt live, if any. */
+    get breach() {
+        return this.stopped;
+    }
+    /** Latest usage the harness reported during the run (cumulative for the attempt). */
+    get lastUsage() {
+        return this.liveUsage;
+    }
+    /** Handed to the harness as `onUsage`. Reports are cumulative for this attempt. */
+    onUsage = (u) => {
+        if (this.stopped)
+            return;
+        this.liveUsage = { ...this.liveUsage, ...u };
+        const s = spendOf(u);
+        // Reports are cumulative; never let a partial report move spend backwards.
+        this.live = {
+            tokens: Math.max(this.live.tokens, s.tokens ?? 0),
+            costUsd: Math.max(this.live.costUsd, s.costUsd ?? 0),
+        };
+        const b = this.check(this.live);
+        if (b) {
+            this.stopped = b;
+            this.controller.abort();
+        }
+    };
+    check(attempt) {
+        const n = this.node.committed;
+        const r = this.guard.totals;
+        return (breachOf("node", this.node.limits, { tokens: n.tokens + attempt.tokens, costUsd: n.costUsd + attempt.costUsd }, true) ??
+            breachOf("run", this.guard.runLimits, { tokens: r.tokens + attempt.tokens, costUsd: r.costUsd + attempt.costUsd }, true));
+    }
+    /**
+     * The attempt is over. Commit its spend (the larger of what the result
+     * reports and what was seen live) and return the breach, if any: the live
+     * stop, else a crossing visible only in the final usage.
+     */
+    finish(finalUsage) {
+        this.outer?.removeEventListener("abort", this.onOuterAbort);
+        const f = spendOf(finalUsage);
+        const spent = {
+            tokens: Math.max(this.live.tokens, f.tokens ?? 0),
+            costUsd: Math.max(this.live.costUsd, f.costUsd ?? 0),
+        };
+        const b = this.stopped ?? this.check(spent);
+        this.node.commit(spent);
+        return b;
+    }
+    /** Release the outer-signal listener when the run threw before `finish`. */
+    dispose() {
+        this.outer?.removeEventListener("abort", this.onOuterAbort);
+    }
+}

package/dist/cli/comment-output.d.ts

@@ -8,7 +8,7 @@
  */
 import type { ExecutionTrace, NodeResult, Workflow } from "../types.js";
 import { type RunSummary } from "./run-output.js";
-export declare const RUN_COMMENT_FOOTER = "Run with [SWEny](https://sweny.ai): `npx @sweny-ai/core new`";
+export declare const RUN_COMMENT_FOOTER = "Run with [SWEny](https://github.com/swenyai/sweny): `npx @sweny-ai/core new`";
 export interface RunCommentOptions {
     trace?: ExecutionTrace;
     /** Per-node wall-clock duration in ms, keyed by node id. Missing entries render as "-". */

package/dist/cli/comment-output.js

@@ -10,7 +10,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { toMermaidBlock } from "../mermaid.js";
 import { STEP_SUMMARY_CLASS_DEFS, formatReceipt, formatReceiptDuration, nodeStates, } from "./run-output.js";
-export const RUN_COMMENT_FOOTER = "Run with [SWEny](https://sweny.ai): `npx @sweny-ai/core new`";
+export const RUN_COMMENT_FOOTER = "Run with [SWEny](https://github.com/swenyai/sweny): `npx @sweny-ai/core new`";
 /** Hidden marker the poster searches for to update the comment in place. */
 export function runCommentMarker(workflowId) {
     const safe = workflowId.replace(/[^A-Za-z0-9._-]+/g, "_").replace(/-{2,}/g, "-") || "workflow";

package/dist/cli/main.d.ts

@@ -9,6 +9,8 @@ export declare function workflowRunAction(file: string | undefined, options: Rec
     verbose?: boolean;
     timeout?: string;
     maxSteps?: string;
+    maxTokens?: string;
+    maxCost?: string;
     yes?: boolean;
 }): Promise<void>;
 export declare function workflowExportAction(name: string): void;

package/dist/cli/main.js

@@ -20,7 +20,7 @@ import { buildAutoMcpServers, buildSkillMcpServers, buildProviderContext } from
 import { loadAdditionalContext } from "../templates.js";
 import { loadAndValidateWorkflow } from "../loader.js";
 import { validateRuntimeInput } from "../inputs.js";
-import { mergeDryRunIntoInput, parseInputFlag, parseRunBudgetFlags } from "./workflow-input.js";
+import { mergeDryRunIntoInput, parseInputFlag, parseRunBudgetFlags, parseSpendFlags } from "./workflow-input.js";
 import { stringify as stringifyYaml } from "yaml";
 import { buildWorkflow, refineWorkflow } from "../workflow-builder.js";
 import { toMermaidBlock } from "../mermaid.js";
@@ -82,7 +82,7 @@ const program = new Command()
 // ── sweny new ─────────────────────────────────────────────────────────
 program
     .command("new [id]")
-    .description("Create a new workflow. With no id, opens the interactive picker. With an id, uses that built-in template, or installs it from the marketplace (swenyai/workflows).")
+    .description("Create a new workflow. With no id, opens the interactive picker. With an id, uses that built-in template.")
     .option("--template <id>", "Use a built-in template without the picker")
     .option("-y, --yes", "Skip every prompt (never overwrites existing files)")
     .action(async (id, options) => {
@@ -730,8 +730,10 @@ export async function workflowRunAction(file, options) {
     // Reject junk --timeout/--max-steps up front (both paths) instead of
     // silently falling back to a default.
     let budget;
+    let spendBudget;
     try {
         budget = parseRunBudgetFlags(options.timeout, options.maxSteps, DEFAULT_WORKFLOW_TIMEOUT_MS);
+        spendBudget = parseSpendFlags(options.maxTokens, options.maxCost);
     }
     catch (err) {
         console.error(chalk.red(`\n  ${err instanceof Error ? err.message : String(err)}\n`));
@@ -1000,6 +1002,8 @@ export async function workflowRunAction(file, options) {
             signal,
             max_steps: wfMaxSteps,
             stageOutputs: options.stage === true,
+            ...(spendBudget ? { budget: spendBudget } : {}),
+            harnessPolicy: resolveHarnessPolicy(process.env, typeof options.harnessPolicy === "string" ? options.harnessPolicy : undefined, runLogger),
         }), wfTimeoutMs, `Workflow ${workflow.name}`);
         const wfDurationMs = Date.now() - runStart;
         const wfHasFailed = [...results.values()].some((r) => r.status === "failed");

package/dist/cli/marketplace.js

@@ -27,7 +27,7 @@ export async function fetchMarketplaceWorkflow(id) {
         throw err;
     }
     if (res.status === 404) {
-        const err = new Error(`Workflow "${id}" not found in ${MARKETPLACE_REPO}. See https://marketplace.sweny.ai for available workflows.`);
+        const err = new Error(`Workflow "${id}" not found in ${MARKETPLACE_REPO}.`);
         err.kind = "not-found";
         throw err;
     }

package/dist/cli/new.js

@@ -625,12 +625,9 @@ export async function runNew(options) {
             const entries = await fetchMarketplaceIndex({ timeoutMs: 3000 });
             if (Array.isArray(entries) && entries.length > 0)
                 marketplaceEntries = entries;
-            else
-                p.log.info("Marketplace has no workflows yet. Showing built-in templates.");
         }
-        catch (err) {
-            const reason = err instanceof Error ? err.message : String(err);
-            p.log.info(`Marketplace unavailable (${reason}). Showing built-in templates.`);
+        catch {
+            // No reachable index: built-in templates only, and nothing about a marketplace is shown.
         }
         templateChoice = await p.select({
             message: "What do you want to do?",

package/dist/cli/run-output.d.ts

@@ -25,6 +25,14 @@ export interface RunSummary {
      * (`max_turns`, `egress allowlist`, `deny [write]`). Absent when none.
      */
     degraded?: string[];
+    /** The spend budget a node crossed (#449). Absent when none was. */
+    budget?: {
+        node: string;
+        scope: "node" | "run";
+        unit: "tokens" | "cost_usd";
+        limit: number;
+        spent: number;
+    };
 }
 /** The short key of a `degraded` entry: the text before its first colon. */
 export declare function degradedKey(entry: string): string;
@@ -33,6 +41,8 @@ export declare function summarizeRun(results: Map<string, NodeResult>, durationM
 export declare function formatReceiptDuration(ms: number): string;
 export declare function formatTokenCount(n: number): string;
 export declare function formatCost(usd: number): string;
+/** `budget exceeded: tokens 52k of 50k (run, at node gather)`. */
+export declare function formatBudgetOverrun(b: NonNullable<RunSummary["budget"]>): string;
 /**
  * One plain line: `✓ 3/3 nodes · 41 tool calls · 2m10s · 12k tokens · $0.18`.
  * Token and cost segments are omitted when the SDK reported none. A harness

package/dist/cli/run-output.js

@@ -24,8 +24,11 @@ export function summarizeRun(results, durationMs, crashed = false) {
     let costUsd;
     let harness;
     const degraded = new Set();
+    let budget;
     const isNum = (v) => typeof v === "number" && Number.isFinite(v);
-    for (const r of results.values()) {
+    for (const [nodeId, r] of results) {
+        if (r.budget && !budget)
+            budget = { node: nodeId, ...r.budget };
         harness ??= r.harness?.id;
         for (const d of r.degraded ?? [])
             degraded.add(degradedKey(d));
@@ -57,6 +60,7 @@ export function summarizeRun(results, durationMs, crashed = false) {
         ...(costUsd !== undefined ? { costUsd } : {}),
         ...(harness !== undefined ? { harness } : {}),
         ...(degraded.size > 0 ? { degraded: [...degraded] } : {}),
+        ...(budget ? { budget } : {}),
     };
 }
 export function formatReceiptDuration(ms) {
@@ -81,6 +85,12 @@ export function formatCost(usd) {
         return "<$0.01";
     return `$${usd.toFixed(2)}`;
 }
+/** `budget exceeded: tokens 52k of 50k (run, at node gather)`. */
+export function formatBudgetOverrun(b) {
+    const amount = (n) => b.unit === "cost_usd" ? (n < 0.01 ? `$${n.toFixed(4)}` : formatCost(n)) : formatTokenCount(n);
+    const unit = b.unit === "cost_usd" ? "cost" : "tokens";
+    return `budget exceeded: ${unit} ${amount(b.spent)} of ${amount(b.limit)} (${b.scope}, at node ${b.node})`;
+}
 /**
  * One plain line: `✓ 3/3 nodes · 41 tool calls · 2m10s · 12k tokens · $0.18`.
  * Token and cost segments are omitted when the SDK reported none. A harness
@@ -98,6 +108,7 @@ export function formatReceipt(s) {
         ...(s.costUsd !== undefined ? [formatCost(s.costUsd)] : []),
         ...(s.harness !== undefined && s.harness !== "claude-code" ? [s.harness] : []),
         ...(s.degraded && s.degraded.length > 0 ? [`degraded: ${s.degraded.join(", ")}`] : []),
+        ...(s.budget ? [formatBudgetOverrun(s.budget)] : []),
     ];
     return parts.join(" · ");
 }
@@ -193,6 +204,14 @@ export const WORKFLOW_RUN_OPTIONS = [
         "--max-steps <n>",
         "Hard cap on total node executions for a single workflow file, including eval-failure retries (default: 200)",
     ],
+    [
+        "--max-tokens <n>",
+        "Run-wide token budget (input plus output) for a single workflow file. The lowest of this and the workflow's budget.tokens wins. A crossing stops the agent, fails the node and halts the run",
+    ],
+    [
+        "--max-cost <usd>",
+        "Run-wide cost budget in US dollars for a single workflow file, from harness-reported cost (never estimated). The lowest of this and the workflow's budget.cost_usd wins",
+    ],
     ["-y, --yes", "Skip the batch confirmation prompt (for CI)"],
     [
         "--dry-run",

package/dist/cli/workflow-input.d.ts

@@ -39,6 +39,15 @@ export declare function parseRunBudgetFlags(timeout: string | undefined, maxStep
     timeoutMs: number;
     maxSteps: number | undefined;
 };
+/**
+ * Parse `--max-tokens <n>` and `--max-cost <usd>` (#449) into a run budget.
+ * Both are optional; junk is rejected up front instead of silently running
+ * with no ceiling. Returns `undefined` when neither flag is set.
+ */
+export declare function parseSpendFlags(maxTokens: string | undefined, maxCost: string | undefined): {
+    tokens?: number;
+    cost_usd?: number;
+} | undefined;
 /**
  * Parse the `--input` flag (#339). The old catch printed only "--input must be
  * valid JSON" and dropped the parser's reason, so a stray quote from shell

package/dist/cli/workflow-input.js

@@ -54,6 +54,27 @@ export function parseRunBudgetFlags(timeout, maxSteps, defaultTimeoutMs) {
         maxSteps: maxSteps === undefined ? undefined : parse(maxSteps, "--max-steps", 1),
     };
 }
+/**
+ * Parse `--max-tokens <n>` and `--max-cost <usd>` (#449) into a run budget.
+ * Both are optional; junk is rejected up front instead of silently running
+ * with no ceiling. Returns `undefined` when neither flag is set.
+ */
+export function parseSpendFlags(maxTokens, maxCost) {
+    const parse = (raw, flag, integer) => {
+        const t = raw.trim();
+        const n = t === "" ? Number.NaN : Number(t);
+        if (!Number.isFinite(n) || n <= 0 || (integer && !Number.isInteger(n))) {
+            throw new Error(`${flag} must be a positive ${integer ? "integer" : "number"}, got "${raw}"` +
+                (integer ? " (input plus output tokens)" : " (US dollars, for example 2.50)"));
+        }
+        return n;
+    };
+    const tokens = maxTokens === undefined ? undefined : parse(maxTokens, "--max-tokens", true);
+    const cost = maxCost === undefined ? undefined : parse(maxCost, "--max-cost", false);
+    if (tokens === undefined && cost === undefined)
+        return undefined;
+    return { ...(tokens !== undefined ? { tokens } : {}), ...(cost !== undefined ? { cost_usd: cost } : {}) };
+}
 /**
  * Parse the `--input` flag (#339). The old catch printed only "--input must be
  * valid JSON" and dropped the parser's reason, so a stray quote from shell

package/dist/executor.d.ts

@@ -13,7 +13,9 @@
  * This replaces ~8k lines of engine + recipe step code.
  */
 import type { Workflow, Skill, Tool, Claude, Observer, Logger, ExecutionResult } from "./types.js";
+import type { HarnessPolicyMode } from "./harness/policy.js";
 import type { AgentHarness } from "./harness/types.js";
+import type { Budget } from "./budget.js";
 import { type ActorInfo } from "./safe-outputs.js";
 export interface ExecuteOptions {
     /** Registered skills (id → Skill) */
@@ -85,6 +87,16 @@ export interface ExecuteOptions {
      * association in the `GITHUB_EVENT_PATH` payload.
      */
     actor?: ActorInfo;
+    /**
+     * Run-wide spend ceiling (#449), tightening `workflow.budget` (the lowest of
+     * the two wins per unit). CLI: `--max-tokens`, `--max-cost`. Default: none.
+     */
+    budget?: Budget;
+    /**
+     * `strict` refuses a node whose spend budget the harness cannot enforce at
+     * all (cost on Codex). Default: {@link resolveHarnessPolicy} from the run env.
+     */
+    harnessPolicy?: HarnessPolicyMode;
 }
 /**
  * Default workflow-level step budget. Counts total node executions across the