@sweny-ai/core 0.1.157 → 0.1.159

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 },

package/dist/types.d.ts

@@ -3,6 +3,7 @@ export type { WorkflowInputs, WorkflowInputField, WorkflowInputType, InputValida
 export { WORKFLOW_INPUT_TYPES } from "./inputs.js";
 import type { Source as _Source, ResolvedSource as _ResolvedSource } from "./sources.js";
 import type { ToolClass } from "./harness/types.js";
+import type { Budget, BudgetOverrun } from "./budget.js";
 export type JSONSchema = Record<string, unknown>;
 /** Context passed to tool handlers at execution time */
 export interface ToolContext {
@@ -294,6 +295,12 @@ export interface Node {
     output?: JSONSchema;
     /** Max AI model turns for this node. When absent, the executor's default applies. */
     max_turns?: number;
+    /**
+     * Spend ceiling for one visit to this node (all retry attempts included),
+     * in input + output tokens and/or reported USD. Never above the workflow's
+     * `budget`. A crossing stops the agent and fails the node (see `budget.ts`).
+     */
+    budget?: Budget;
     /** Per-node directives. Additive by default; set `{ only: true, sources: [...] }` to block cascade. */
     rules?: NodeSources;
     /** Per-node background knowledge. Additive by default; set `{ only: true, sources: [...] }` to block cascade. */
@@ -523,6 +530,11 @@ export interface Workflow {
     model?: string;
     /** Soft cap on expected judge calls per workflow run. Warning at load time when exceeded. */
     judge_budget?: number;
+    /**
+     * Spend ceiling for the whole run and for every node (#449). A node's own
+     * `budget` may only narrow it. The CLI's `--max-tokens` / `--max-cost` tighten it.
+     */
+    budget?: Budget;
     /**
      * What prior results a node's prompt receives (#337). `bounded` (default):
      * only nodes it can depend on (graph ancestors, nodes named by `requires`
@@ -612,6 +624,12 @@ export interface NodeResult {
     degraded?: string[];
     /** Safe outputs (#365): what the write stage did with each intent. Absent when the node declares none. */
     outputs?: SafeOutputReceipt[];
+    /**
+     * Set when this node's spend crossed a token or cost budget (#449), or when
+     * the run's budget was already spent before it could start. The node is
+     * `failed`, `fail_soft` and `on_fail: continue` do not apply, and the run halts.
+     */
+    budget?: BudgetOverrun;
 }
 export interface ToolCall {
     tool: string;
@@ -780,6 +798,13 @@ export interface Claude {
          * carry the same read-only and native-deny intent.
          */
         policy?: import("./harness/types.js").NodePolicy;
+        /**
+         * Live spend (#449): a harness that declares `capabilities.usage.live`
+         * calls this with the run's cumulative usage as it grows. The executor
+         * aborts `signal` when a budget is crossed. Harnesses that report usage
+         * only at the end never call it.
+         */
+        onUsage?: (usage: NodeUsage) => void;
     }): Promise<NodeResult>;
     /**
      * Evaluate a routing condition — pick one of N choices.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sweny-ai/core",
-  "version": "0.1.157",
+  "version": "0.1.159",
   "type": "module",
   "bin": {
     "sweny": "./dist/cli/main.js"