@gethelio/proxy 0.10.0 → 0.11.0

package/dist/cli.js

@@ -49,7 +49,7 @@ var upstreamSchema = z.object({
   request_timeout: durationSchema.default("30s"),
   forward_headers: z.array(z.string().min(1)).default([]),
   headers: z.record(z.string(), z.string()).default({})
-}).refine((data) => data.transport !== "stdio" || data.command !== void 0, {
+}).strict().refine((data) => data.transport !== "stdio" || data.command !== void 0, {
   message: '"command" is required when transport is "stdio"',
   path: ["command"]
 }).superRefine((data, ctx) => {
@@ -82,7 +82,7 @@ var upstreamSchema = z.object({
 var listenSchema = z.object({
   port: z.number().int().min(1).max(65535).default(3e3),
   host: z.string().default("127.0.0.1")
-});
+}).strict();
 function isLoopbackHost(host) {
   return host === "127.0.0.1" || host === "localhost" || host === "::1";
 }
@@ -96,7 +96,7 @@ var dashboardSchema = z.object({
   api_secret: z.string().optional(),
   allow_open_mode: z.boolean().default(false),
   sse_heartbeat_interval: durationSchema.default("30s")
-});
+}).strict();
 var inputConditionSchema = z.object({
   eq: z.unknown().optional(),
   neq: z.unknown().optional(),
@@ -226,12 +226,27 @@ var policiesSchema = z.object({
    */
   hot_reload: z.boolean().optional()
 }).strict();
-var budgetContributorSchema = z.object({
+var budgetContributorMatchSchema = z.object({
   tool: z.string().min(1),
   // picomatch glob, same engine as match.tool
+  // Same operators and AND-combination as rule `match.input`. Other rule
+  // matchers (annotations, environment, metadata) stay strict-rejected
+  // until the budget charge context can actually evaluate them.
+  input: z.record(z.string(), inputConditionSchema).optional()
+}).strict();
+var modernBudgetContributorSchema = z.object({
+  match: budgetContributorMatchSchema,
   field: z.string().min(1)
   // dot-path into tool arguments, e.g. "$.amount"
 }).strict();
+var budgetContributorSchema = z.unknown().superRefine((raw, ctx) => {
+  if (raw !== null && typeof raw === "object" && "tool" in raw) {
+    ctx.addIssue({
+      code: "custom",
+      message: 'contributor "tool" moved under "match" in v0.11.0 \u2014 write { match: { tool: "<glob>" }, field: "<path>" }'
+    });
+  }
+}).pipe(modernBudgetContributorSchema);
 var budgetSchema = z.object({
   // The name is embedded in bucket keys (`budget:<name>:<scope>`) and, later,
   // ledger rows — constrain it so keys stay parseable and scope classification
@@ -290,17 +305,17 @@ var slackChannelSchema = z.object({
   bot_token: z.string(),
   signing_secret: z.string(),
   channel: z.string()
-});
+}).strict();
 var webhookChannelSchema = z.object({
   type: z.literal("webhook"),
   name: z.string().min(1).optional(),
   url: z.string(),
   secret: z.string().optional()
-});
+}).strict();
 var dashboardChannelSchema = z.object({
   type: z.literal("dashboard"),
   name: z.string().min(1).optional()
-});
+}).strict();
 var approvalChannelSchema = z.discriminatedUnion("type", [
   slackChannelSchema,
   webhookChannelSchema,
@@ -310,13 +325,13 @@ var approvalSchema = z.object({
   timeout: durationSchema.default("300s"),
   default_on_timeout: z.enum(["deny", "allow"]).default("deny"),
   channels: z.array(approvalChannelSchema).default([])
-});
+}).strict();
 var auditSchema = z.object({
   storage: z.enum(["sqlite"]).default("sqlite"),
   path: z.string().default("./helio-audit.db"),
   retention: durationSchema.default("90d"),
   include_responses: z.boolean().default(true)
-});
+}).strict();
 var sdkSchema = z.object({
   enabled: z.boolean().default(false),
   port: z.number().int().min(1).max(65535).default(3200),
@@ -328,12 +343,11 @@ var sdkSchema = z.object({
    * decided-allowed call from the trail.
    */
   evaluation_ttl: durationSchema.default("10m")
-});
+}).strict();
 var helioConfigBaseSchema = z.object({
   version: z.literal("1"),
   upstream: upstreamSchema,
   listen: listenSchema.prefault({}),
-  dashboard: dashboardSchema.prefault({}),
   environment: z.string().optional(),
   policies: policiesSchema.prefault({}),
   // Budgets sit beside policies deliberately: they are the second half of the
@@ -341,9 +355,18 @@ var helioConfigBaseSchema = z.object({
   budgets: z.array(budgetSchema).default([]),
   approval: approvalSchema.prefault({}),
   audit: auditSchema.prefault({}),
+  // Dashboard follows audit deliberately: an operator surface, not part of
+  // the request path (canonical section order, #89/#163).
+  dashboard: dashboardSchema.prefault({}),
   sdk: sdkSchema.prefault({})
-});
-var helioConfigSchema = helioConfigBaseSchema.superRefine((cfg, ctx) => {
+}).strict();
+function stripRootExtensionKeys(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return value;
+  return Object.fromEntries(
+    Object.entries(value).filter(([key]) => !key.startsWith("x-"))
+  );
+}
+var helioConfigRefinedSchema = helioConfigBaseSchema.superRefine((cfg, ctx) => {
   const hasConfiguredEnvironment = typeof cfg.environment === "string" && cfg.environment.trim().length > 0;
   const requiresSecret = cfg.policies.flag_destructive === "require_approval" || cfg.policies.on_tool_drift === "require_approval" || cfg.policies.rules.some((rule) => rule.action === "require_approval") || cfg.budgets.some((budget) => budget.on_exceed === "require_approval");
   const hasSecret = hasDashboardApiSecret(cfg.dashboard.api_secret);
@@ -458,6 +481,22 @@ var helioConfigSchema = helioConfigBaseSchema.superRefine((cfg, ctx) => {
       message: "dashboard.enabled must be true when approval.channels includes a webhook channel. Webhook notifications require the dashboard sideband approval API."
     });
   }
+  if (!cfg.dashboard.enabled) {
+    if (cfg.policies.flag_destructive === "require_approval") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["policies", "flag_destructive"],
+        message: 'policies.flag_destructive: require_approval routes its escalation tickets to the dashboard channel, but dashboard.enabled is false \u2014 the tickets could never be resolved and would always time out. Enable the dashboard or use "log".'
+      });
+    }
+    if (cfg.policies.on_tool_drift === "require_approval") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["policies", "on_tool_drift"],
+        message: 'policies.on_tool_drift: require_approval routes its escalation tickets to the dashboard channel, but dashboard.enabled is false \u2014 the tickets could never be resolved and would always time out. Enable the dashboard or use "block" or "log".'
+      });
+    }
+  }
   for (const [ruleIndex, rule] of cfg.policies.rules.entries()) {
     if (rule.match.environment !== void 0 && !hasConfiguredEnvironment) {
       ctx.addIssue({
@@ -513,6 +552,28 @@ var helioConfigSchema = helioConfigBaseSchema.superRefine((cfg, ctx) => {
         message: `Unknown approval channel "${channel}". Add it to approval.channels (type or name), or use "dashboard".`
       });
     }
+    if (rule.action === "require_approval" && !cfg.dashboard.enabled && rule.match.metadata === void 0) {
+      const effectiveChannel = rule.approval?.channel ?? "dashboard";
+      if (resolvesToDashboard(effectiveChannel)) {
+        ctx.addIssue({
+          code: "custom",
+          path: rule.approval?.channel !== void 0 ? ["policies", "rules", ruleIndex, "approval", "channel"] : ["policies", "rules", ruleIndex, "action"],
+          message: "This rule routes approvals to the dashboard channel, but dashboard.enabled is false \u2014 the ticket could never be resolved and would always time out. Enable the dashboard or route approval.channel to a Slack channel."
+        });
+      }
+      const escalationAfterMs = rule.approval?.escalation_after !== void 0 ? parseDuration(rule.approval.escalation_after) : void 0;
+      const effectiveTimeoutMs = parseDuration(rule.approval?.timeout ?? cfg.approval.timeout);
+      const escalationCanFire = escalationAfterMs !== void 0 && escalationAfterMs > 0 && escalationAfterMs < effectiveTimeoutMs;
+      for (const [delegateIndex, delegate] of (rule.approval?.delegates ?? []).entries()) {
+        if (escalationCanFire && knownChannelKeys.has(delegate) && resolvesToDashboard(delegate)) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["policies", "rules", ruleIndex, "approval", "delegates", delegateIndex],
+            message: "This rule escalates approvals to a dashboard channel, but dashboard.enabled is false \u2014 the delegate could never resolve the ticket. Enable the dashboard or delegate to a Slack channel."
+          });
+        }
+      }
+    }
     const delegates = rule.approval?.delegates;
     if (!delegates) continue;
     for (const [delegateIndex, delegate] of delegates.entries()) {
@@ -526,6 +587,7 @@ var helioConfigSchema = helioConfigBaseSchema.superRefine((cfg, ctx) => {
     }
   }
 });
+var helioConfigSchema = z.preprocess(stripRootExtensionKeys, helioConfigRefinedSchema);
 
 // src/config/loader.ts
 import { readFile } from "fs/promises";
@@ -588,7 +650,9 @@ async function loadConfig(filePath, env) {
   const interpolated = interpolateEnvVars(parsed, env);
   const result = helioConfigSchema.safeParse(interpolated);
   if (!result.success) {
-    const details = formatZodErrors(result.error);
+    const details = formatZodErrors(result.error).map(
+      (d) => d.path === "" ? { ...d, path: "(top level)" } : d
+    );
     const count = details.length;
     throw new ConfigError(
       `Invalid configuration (${String(count)} error${count === 1 ? "" : "s"})`,
@@ -808,7 +872,7 @@ function compileToolMatcher(pattern, ruleIndex, ruleName) {
     throw new PolicyParseError(`invalid glob pattern "${pattern}": ${message}`, ruleIndex, ruleName);
   }
 }
-function flattenInputConditions(input, ruleIndex, ruleName) {
+function flattenInputConditionsWith(input, makeError) {
   const conditions = [];
   for (const [path, conditionObj] of Object.entries(input)) {
     for (const op of INPUT_OPERATORS) {
@@ -816,17 +880,11 @@ function flattenInputConditions(input, ruleIndex, ruleName) {
       if (value === void 0) continue;
       if (op === "regex") {
         if (typeof value !== "string") {
-          throw new PolicyParseError(
-            `regex value for input path "${path}" must be a string`,
-            ruleIndex,
-            ruleName
-          );
+          throw makeError(`regex value for input path "${path}" must be a string`);
         }
         if (!safeRegex(value)) {
-          throw new PolicyParseError(
-            `catastrophic regex "${value}" for input path "${path}": pattern is vulnerable to ReDoS and has been rejected. Rewrite with bounded quantifiers (e.g. {1,100}) or split into simpler rules.`,
-            ruleIndex,
-            ruleName
+          throw makeError(
+            `catastrophic regex "${value}" for input path "${path}": pattern is vulnerable to ReDoS and has been rejected. Rewrite with bounded quantifiers (e.g. {1,100}) or split into simpler rules.`
           );
         }
         let compiledRegex;
@@ -834,11 +892,7 @@ function flattenInputConditions(input, ruleIndex, ruleName) {
           compiledRegex = new RegExp(value);
         } catch (err) {
           const msg = err instanceof Error ? err.message : String(err);
-          throw new PolicyParseError(
-            `invalid regex "${value}" for input path "${path}": ${msg}`,
-            ruleIndex,
-            ruleName
-          );
+          throw makeError(`invalid regex "${value}" for input path "${path}": ${msg}`);
         }
         conditions.push({ path, operator: op, value, regex: compiledRegex });
       } else {
@@ -848,6 +902,12 @@ function flattenInputConditions(input, ruleIndex, ruleName) {
   }
   return conditions;
 }
+function flattenInputConditions(input, ruleIndex, ruleName) {
+  return flattenInputConditionsWith(
+    input,
+    (message) => new PolicyParseError(message, ruleIndex, ruleName)
+  );
+}
 function flattenMetadataConditions(metadata, ruleIndex, ruleName) {
   const conditions = [];
   for (const [key, raw] of Object.entries(metadata)) {
@@ -981,21 +1041,30 @@ function compileBudgets(budgets) {
     onExceed: budget.on_exceed,
     ...budget.approval !== void 0 && { approval: compileApproval(budget.approval) },
     contributors: budget.contributors.map(
-      (contributor) => compileContributor(contributor, budget.name)
+      (contributor, index) => compileContributor(contributor, budget.name, index)
     )
   }));
 }
-function compileContributor(contributor, budgetName) {
+function compileContributor(contributor, budgetName, index) {
+  let tool;
   try {
-    const test = picomatch2(contributor.tool, { dot: true });
-    return { tool: { pattern: contributor.tool, test }, field: contributor.field };
+    const test = picomatch2(contributor.match.tool, { dot: true });
+    tool = { pattern: contributor.match.tool, test };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     throw new BudgetParseError(
-      `invalid contributor glob "${contributor.tool}": ${message}`,
+      `invalid contributor glob "${contributor.match.tool}": ${message}`,
       budgetName
     );
   }
+  const input = contributor.match.input !== void 0 ? flattenInputConditionsWith(
+    contributor.match.input,
+    (message) => new BudgetParseError(`contributor ${String(index)}: ${message}`, budgetName)
+  ) : void 0;
+  return {
+    match: { tool, ...input !== void 0 && { input } },
+    field: contributor.field
+  };
 }
 
 // src/config/watcher.ts
@@ -1003,6 +1072,7 @@ var ConfigWatcher = class {
   configPath;
   onReload;
   onError;
+  onReady;
   initialConfig;
   env;
   debounceMs;
@@ -1012,6 +1082,7 @@ var ConfigWatcher = class {
     this.configPath = options.configPath;
     this.onReload = options.onReload;
     this.onError = options.onError;
+    this.onReady = options.onReady;
     this.initialConfig = options.initialConfig;
     this.env = options.env;
     this.debounceMs = options.debounceMs ?? 200;
@@ -1027,6 +1098,9 @@ var ConfigWatcher = class {
     this.watcher.on("change", () => {
       this.scheduleReload();
     });
+    this.watcher.on("ready", () => {
+      if (this.watcher && this.onReady) this.onReady();
+    });
   }
   /** Stop watching and clean up resources. */
   close() {
@@ -3116,11 +3190,9 @@ function extractTools(body) {
 
 // src/feedback/self-repair.ts
 function ruleInfo(rule) {
-  const index = rule?.index ?? null;
   return {
     rule: rule?.name ?? null,
-    ruleIndex: index,
-    rule_index: index
+    rule_index: rule?.index ?? null
   };
 }
 function buildPolicyDeniedFeedback(decision) {
@@ -4598,29 +4670,33 @@ var GovernedForwarder = class {
           if (this.spendLimiter && decision.matchedRule?.limits?.maxSpend) {
             const maxSpend = decision.matchedRule.limits.maxSpend;
             const rawAmount = resolvePath(maxSpend.field, toolArguments ?? {});
-            if (typeof rawAmount === "number") {
-              if (!Number.isFinite(rawAmount) || rawAmount < 0) {
-                console.error(
-                  `[helio] Warning: spend limit field "${maxSpend.field}" resolved to invalid amount (${String(rawAmount)}) for tool "${toolName}" in dry-run, denying`
-                );
-                wouldForward = false;
-                limitsOk = false;
-              } else {
-                const key = this.buildSpendLimitKey(
-                  maxSpend.key,
-                  toolName,
-                  request,
-                  decision.matchedRule.index
-                );
-                const peekResult = this.spendLimiter.peek({
-                  key,
-                  amount: rawAmount,
-                  limit: maxSpend.limit,
-                  windowMs: maxSpend.windowMs
-                });
-                wouldForward = peekResult.allowed;
-                limitsOk = peekResult.allowed;
-              }
+            if (typeof rawAmount !== "number") {
+              console.error(
+                `[helio] Warning: spend limit field "${maxSpend.field}" did not resolve to a number for tool "${toolName}" (got ${typeof rawAmount}) in dry-run, denying`
+              );
+              wouldForward = false;
+              limitsOk = false;
+            } else if (!Number.isFinite(rawAmount) || rawAmount < 0) {
+              console.error(
+                `[helio] Warning: spend limit field "${maxSpend.field}" resolved to invalid amount (${String(rawAmount)}) for tool "${toolName}" in dry-run, denying`
+              );
+              wouldForward = false;
+              limitsOk = false;
+            } else {
+              const key = this.buildSpendLimitKey(
+                maxSpend.key,
+                toolName,
+                request,
+                decision.matchedRule.index
+              );
+              const peekResult = this.spendLimiter.peek({
+                key,
+                amount: rawAmount,
+                limit: maxSpend.limit,
+                windowMs: maxSpend.windowMs
+              });
+              wouldForward = peekResult.allowed;
+              limitsOk = peekResult.allowed;
             }
           }
           break;
@@ -6612,6 +6688,7 @@ var GovernanceService = class {
     let wire;
     const plans = [];
     let limitsBlock;
+    let ruleLimitOk = true;
     const reservedThisCall = [];
     const reserve = (key) => {
       const preexisting = this.senderKeys.has(key);
@@ -6625,6 +6702,15 @@ var GovernanceService = class {
     const senderId = senderIdOf(req.metadata);
     if (pipeline.isDryRun) {
       wire = "dry_run";
+      if (decision.action === "rate_limit") {
+        const planned = this.planRate(decision, toolName, req.session_id, senderId);
+        if (planned?.block) limitsBlock = { rate: planned.block };
+        ruleLimitOk = planned?.allowed ?? true;
+      } else if (decision.action === "spend_limit") {
+        const planned = this.planSpend(decision, toolName, req.session_id, req.arguments, senderId);
+        if (planned?.block) limitsBlock = { spend: planned.block };
+        ruleLimitOk = planned?.allowed ?? true;
+      }
     } else if (decision.action === "deny") {
       wire = "deny";
     } else if (decision.action === "require_approval") {
@@ -6749,9 +6835,9 @@ var GovernanceService = class {
     if (limitsBlock) responseBody["limits"] = limitsBlock;
     if (wire === "dry_run") {
       responseBody["dry_run"] = {
-        would_forward: decision.action === "allow" && !pipeline.evidenceBlocked && budgetDryRunOk,
+        would_forward: (decision.action === "allow" || (decision.action === "rate_limit" || decision.action === "spend_limit") && ruleLimitOk) && !pipeline.evidenceBlocked && budgetDryRunOk,
         evidence_satisfied: !pipeline.evidenceBlocked,
-        limits_ok: budgetDryRunOk
+        limits_ok: ruleLimitOk && budgetDryRunOk
       };
     }
     if (pipeline.driftEvent) {
@@ -6773,7 +6859,11 @@ var GovernanceService = class {
         flaggedDestructive: pipeline.flaggedDestructive,
         dryRun: wire === "dry_run",
         recordKind: "tool_call",
-        limitsChain: limitsBlock
+        // A CLONE, for the same reason budgetsAtEvaluate is one below:
+        // limitsBlock is also the response's `limits`, and the audit writer
+        // buffers records by reference until flush — a direct embedder
+        // editing the returned body must not be able to rewrite evidence.
+        limitsChain: limitsBlock ? structuredClone(limitsBlock) : void 0
       });
       this.tombstones.set(evaluationId, {
         auditRecordId: auditId,
@@ -7275,6 +7365,7 @@ var GovernanceService = class {
         this.approvalRouter?.resolveNativeTicket(entry.approvalTicketId, "timeout");
         this.snapshotTicketResolution(entry);
       }
+      const committed = entry.commitState;
       const resolution = entry.ticketResolution;
       const approvalContext = entry.approvalTicketId && resolution && (resolution.denialReason || resolution.escalatedAt) ? {
         ticket_id: entry.approvalTicketId,
@@ -7285,6 +7376,7 @@ var GovernanceService = class {
         } : {}
       } : void 0;
       const auditId = this.writeAudit({
+        ...committed ? { id: committed.auditId } : {},
         timestampIso: entry.timestampIso,
         origin: entry.origin,
         agentId: entry.agentId,
@@ -7302,8 +7394,9 @@ var GovernanceService = class {
         approvalStatus: resolution?.status ?? null,
         approvedBy: resolution?.resolvedBy ?? null,
         approvalContext,
-        limitsChain: !entry.commitState && entry.budgetsAtEvaluate ? { budgets: entry.budgetsAtEvaluate } : void 0,
-        sidebandUnreported: true
+        limitsChain: committed ? committed.limitsChain : entry.budgetsAtEvaluate ? { budgets: entry.budgetsAtEvaluate } : void 0,
+        sidebandUnreported: true,
+        sidebandCommitted: committed !== void 0
       });
       this.discardPending(entry);
       this.tombstones.set(entry.evaluationId, {
@@ -7313,7 +7406,7 @@ var GovernanceService = class {
         expiresAtMs: now + this.ttlMs
       });
       console.error(
-        `[helio] Sideband evaluation ${entry.evaluationId} expired without /audit (origin=${entry.origin}, tool=${entry.toolName}) \u2014 recorded as evaluation_expired`
+        committed ? `[helio] Sideband evaluation ${entry.evaluationId} expired after a failed /audit finalization (origin=${entry.origin}, tool=${entry.toolName}) \u2014 recorded as evaluation_expired under the committed audit id` : `[helio] Sideband evaluation ${entry.evaluationId} expired without /audit (origin=${entry.origin}, tool=${entry.toolName}) \u2014 recorded as evaluation_expired`
       );
       return "expired";
     }
@@ -7495,7 +7588,13 @@ var GovernanceService = class {
     const blockReason = deriveBlockReason(args);
     let evidenceChain = args.limitsChain ?? null;
     if (args.sidebandUnreported) {
-      evidenceChain = { ...evidenceChain ?? {}, sideband: { unreported: true } };
+      evidenceChain = {
+        ...evidenceChain ?? {},
+        sideband: {
+          unreported: true,
+          ...args.sidebandCommitted ? { committed: true } : {}
+        }
+      };
     }
     if (args.approvalContext) {
       evidenceChain = { ...evidenceChain ?? {}, approval: { ...args.approvalContext } };
@@ -8747,16 +8846,26 @@ var BudgetEngine = class {
   /**
    * Resolve which budgets a call feeds and how much it charges each.
    *
-   * A budget participates when any contributor glob matches the tool name;
-   * the FIRST matching contributor (config order) supplies the amount field.
-   * A missing, non-numeric, negative, or non-finite amount fails closed as a
-   * `failures` entry — the caller must deny the call.
+   * A contributor participates when its tool glob matches the tool name AND
+   * every `match.input` condition holds (absent conditions means the glob
+   * alone decides); the FIRST participating contributor (config order, over
+   * that combined predicate) supplies the amount field. A call that matches
+   * the glob but not the conditions simply does not feed the budget — no
+   * charge, no failure. Once a contributor is selected, a missing,
+   * non-numeric, negative, or non-finite amount fails closed as a `failures`
+   * entry — the caller must deny the call.
    */
   resolveCharges(ctx) {
     const charges = [];
     const failures = [];
+    const matchCtx = {
+      toolName: ctx.toolName,
+      ...ctx.toolArguments !== void 0 && { toolArguments: ctx.toolArguments }
+    };
     for (const budget of this.budgets.values()) {
-      const contributor = budget.contributors.find((c) => c.tool.test(ctx.toolName));
+      const contributor = budget.contributors.find(
+        (c) => c.match.tool.test(ctx.toolName) && (c.match.input === void 0 || matchInput(c.match.input, matchCtx))
+      );
       if (!contributor) continue;
       const raw = resolvePath(contributor.field, ctx.toolArguments ?? {});
       if (typeof raw !== "number" || !Number.isFinite(raw) || raw < 0) {
@@ -9490,6 +9599,24 @@ var BudgetLedger = class {
     const { total } = this.countEventsStmt.get(budgetName);
     return { events, total };
   }
+  /**
+   * A budget's spend history for bulk export (issue #155). Unlike
+   * {@link listEvents}, which enforces the dashboard's page clamp, this path
+   * allows up to `EXPORT_MAX_RECORDS` in a single call. Newest first — the
+   * listing's own order, and the opposite of the audit export's oldest-first:
+   * the export takes no time filters, so a capped export must keep the most
+   * recent spend reachable (older rows age out via retention). Same
+   * unknown-name and epoch-spanning posture as the listing.
+   */
+  listEventsForExport(budgetName, limit) {
+    const clamped = Math.min(
+      Math.max(Math.trunc(limit ?? EXPORT_MAX_RECORDS), 1),
+      EXPORT_MAX_RECORDS
+    );
+    const events = this.listEventsStmt.all(budgetName, clamped, 0);
+    const { total } = this.countEventsStmt.get(budgetName);
+    return { events, total };
+  }
   // -------------------------------------------------------------------------
   // Retention
   // -------------------------------------------------------------------------
@@ -9509,17 +9636,6 @@ var BudgetLedger = class {
   }
 };
 
-// src/dashboard/api.ts
-import { readFileSync } from "fs";
-import { join } from "path";
-import { randomUUID as randomUUID8 } from "crypto";
-import { Hono as Hono8 } from "hono";
-import { HTTPException as HTTPException2 } from "hono/http-exception";
-import { z as z8 } from "zod";
-import { cors } from "hono/cors";
-import { serveStatic } from "@hono/node-server/serve-static";
-import { streamSSE } from "hono/streaming";
-
 // src/audit/csv.ts
 var CSV_HEADERS = [
   "id",
@@ -9578,6 +9694,49 @@ function recordsToCsv(records) {
   return lines.join("\n");
 }
 
+// src/budget/csv.ts
+var BUDGET_EVENT_CSV_HEADERS = [
+  "id",
+  "budget_name",
+  "bucket_key",
+  "kind",
+  "amount",
+  "currency",
+  "tool_name",
+  "origin",
+  "audit_record_id",
+  "timestamp",
+  "timestamp_ms",
+  "created_at"
+];
+function eventToRow(event) {
+  return BUDGET_EVENT_CSV_HEADERS.map((h) => {
+    const val = event[h];
+    if (val === null || val === void 0) return "";
+    if (typeof val === "number") return String(val);
+    if (typeof val === "string") return csvEscape(val);
+    return "";
+  }).join(",");
+}
+function budgetEventsToCsv(events) {
+  const lines = [BUDGET_EVENT_CSV_HEADERS.join(",")];
+  for (const e of events) {
+    lines.push(eventToRow(e));
+  }
+  return lines.join("\n");
+}
+
+// src/dashboard/api.ts
+import { readFileSync } from "fs";
+import { join } from "path";
+import { randomUUID as randomUUID8 } from "crypto";
+import { Hono as Hono8 } from "hono";
+import { HTTPException as HTTPException2 } from "hono/http-exception";
+import { z as z8 } from "zod";
+import { cors } from "hono/cors";
+import { serveStatic } from "@hono/node-server/serve-static";
+import { streamSSE } from "hono/streaming";
+
 // src/dashboard/session.ts
 import { createHash as createHash3, createHmac as createHmac3, randomBytes, timingSafeEqual as timingSafeEqual3 } from "crypto";
 var DashboardSessionStore = class {
@@ -9735,6 +9894,10 @@ var budgetEventsQuerySchema = z8.object({
   limit: clampedQueryInt(50, 1, LIST_MAX_PAGE_SIZE),
   offset: clampedQueryInt(0, 0, Number.MAX_SAFE_INTEGER)
 });
+var budgetEventsExportQuerySchema = z8.object({
+  format: z8.preprocess((value) => value === "csv" ? "csv" : "json", z8.enum(["json", "csv"])),
+  limit: clampedQueryInt(EXPORT_MAX_RECORDS, 1, EXPORT_MAX_RECORDS)
+});
 var analyticsQuerySchema = z8.object({
   from: optionalQueryString,
   to: optionalQueryString
@@ -10046,6 +10209,27 @@ function createDashboardAppWithLifecycle(deps, options) {
       offset: query.offset
     });
   });
+  app.get("/api/budgets/:name/events/export", (c) => {
+    const query = budgetEventsExportQuerySchema.parse(c.req.query());
+    const name = c.req.param("name");
+    const page = budgets?.listEventsForExport(name, query.limit) ?? { events: [], total: 0 };
+    const safeName = name.replace(/[^A-Za-z0-9_-]/g, "").slice(0, 64);
+    const filename = safeName ? `helio-budget-${safeName}-events` : "helio-budget-events";
+    if (query.format === "csv") {
+      return new Response(budgetEventsToCsv(page.events), {
+        headers: {
+          "content-type": "text/csv; charset=utf-8",
+          "content-disposition": `attachment; filename="${filename}.csv"`
+        }
+      });
+    }
+    return new Response(JSON.stringify(page.events, null, 2), {
+      headers: {
+        "content-type": "application/json",
+        "content-disposition": `attachment; filename="${filename}.json"`
+      }
+    });
+  });
   app.get("/api/analytics", (c) => {
     const query = analyticsQuerySchema.parse(c.req.query());
     const now = /* @__PURE__ */ new Date();
@@ -10355,11 +10539,29 @@ upstream:
 #   port: 3000
 #   host: 127.0.0.1
 
+# environment: production
+
 # policies:
 #   default: allow
 #   dry_run: false
 #   rules: []
 
+# budgets:
+#   # One depleting pot shared by every tool that spends.
+#   - name: agent-payments
+#     limit: 50
+#     currency: USD
+#     window: session
+#     key: session
+#     on_exceed: deny # or require_approval for a break-glass ticket
+#     contributors:
+#       - match:
+#           tool: 'stripe_*'
+#         field: '$.amount'
+#       - match:
+#           tool: 'paypal_*'
+#         field: '$.total'
+
 # approval:
 #   timeout: 300s
 #   default_on_timeout: deny
@@ -10376,7 +10578,7 @@ upstream:
 # front. dashboard.api_secret is the manual dashboard login secret and also
 # supports machine Bearer auth for sideband API clients. Store it safely; it
 # stays valid until you rotate it. Rotate by editing this file and restarting
-# (or hot-reloading) the proxy. Rotation invalidates active dashboard sessions.
+# the proxy. Rotation invalidates active dashboard sessions.
 dashboard:
   enabled: true
   port: 3100
@@ -10392,6 +10594,12 @@ dashboard:
 # the proxy's environment for a stable cross-restart value.
 `;
 }
+function printConfigErrorDetails(error, prefix = "") {
+  if (!error.details) return;
+  for (const detail of error.details) {
+    console.error(`${prefix}  ${detail.path}: ${detail.message}`);
+  }
+}
 var ANNOTATION_PRIME_INITIAL_WAIT_MS = 1500;
 var ANNOTATION_PRIME_RETRY_BASE_MS = 1e3;
 var ANNOTATION_PRIME_RETRY_MAX_MS = 3e4;
@@ -10483,11 +10691,7 @@ async function startCommand(configPath, options) {
   } catch (err) {
     if (err instanceof ConfigError) {
       console.error(`Error: ${err.message}`);
-      if (err.details) {
-        for (const detail of err.details) {
-          console.error(`  ${detail.path}: ${detail.message}`);
-        }
-      }
+      printConfigErrorDetails(err);
       process.exit(1);
     }
     throw err;
@@ -10688,7 +10892,8 @@ async function startCommand(configPath, options) {
         // spend history from the ledger.
         budgets: {
           listStates: () => budgetEngine.listStates(),
-          listEvents: (name, page) => budgetLedger.listEvents(name, page)
+          listEvents: (name, page) => budgetLedger.listEvents(name, page),
+          listEventsForExport: (name, limit) => budgetLedger.listEventsForExport(name, limit)
         }
       },
       {
@@ -10762,6 +10967,9 @@ async function startCommand(configPath, options) {
     configWatcher = new ConfigWatcher({
       configPath,
       initialConfig: config,
+      onReady: () => {
+        console.error(`Watching ${configPath} for policy changes`);
+      },
       onReload: (newPolicy, reloadWarnings, restartRequiredPaths, newBudgets) => {
         const unroutable = findUnroutableApprovalReferences(newPolicy, newBudgets, {
           channelTypes: runtimeChannelTypes,
@@ -10802,10 +11010,12 @@ async function startCommand(configPath, options) {
         console.error(
           `[helio] Config reload failed (keeping current configuration): ${error.message}`
         );
+        if (error instanceof ConfigError) {
+          printConfigErrorDetails(error, "[helio] ");
+        }
       }
     });
     configWatcher.start();
-    console.error(`Watching ${configPath} for policy changes`);
   } else {
     console.error(
       `[helio] Hot-reload disabled \u2014 config changes to ${configPath} will require a restart`
@@ -10861,17 +11071,14 @@ async function validateCommand(configPath) {
       process.exit(1);
     }
     const ruleCount = config.policies.rules.length;
+    const budgetCount = config.budgets.length;
     console.error(
-      `Config is valid: ${configPath} (${String(ruleCount)} policy rule${ruleCount !== 1 ? "s" : ""})`
+      `Config is valid: ${configPath} (${String(ruleCount)} policy rule${ruleCount !== 1 ? "s" : ""}, ${String(budgetCount)} budget${budgetCount !== 1 ? "s" : ""})`
     );
   } catch (err) {
     if (err instanceof ConfigError) {
       console.error(`Invalid config: ${err.message}`);
-      if (err.details) {
-        for (const detail of err.details) {
-          console.error(`  ${detail.path}: ${detail.message}`);
-        }
-      }
+      printConfigErrorDetails(err);
       process.exit(1);
     }
     if (err instanceof PolicyParseError) {
@@ -10891,12 +11098,29 @@ async function exportCommand(opts) {
     process.exit(1);
   }
   const limit = Math.min(parsedLimit, EXPORT_MAX_RECORDS);
+  if (opts.budgets !== void 0) {
+    const conflicting = [
+      ["--tool", opts.tool],
+      ["--decision", opts.decision],
+      ["--reason", opts.reason],
+      ["--session", opts.session],
+      ["--from", opts.from],
+      ["--to", opts.to]
+    ].filter(([, value]) => value !== void 0);
+    if (conflicting.length > 0) {
+      console.error(
+        `Error: --budgets cannot be combined with audit filters (${conflicting.map(([flag]) => flag).join(", ")})`
+      );
+      process.exit(1);
+    }
+  }
   let config;
   try {
     config = await loadConfig(opts.config);
   } catch (err) {
     if (err instanceof ConfigError) {
       console.error(`Error: ${err.message}`);
+      printConfigErrorDetails(err);
       process.exit(1);
     }
     throw err;
@@ -10909,6 +11133,17 @@ async function exportCommand(opts) {
     // No cleanup timer for one-shot CLI
   });
   try {
+    if (opts.budgets !== void 0) {
+      const ledger = new BudgetLedger({ database: store.database });
+      const page = ledger.listEventsForExport(opts.budgets, limit);
+      if (opts.format === "csv") {
+        console.log(budgetEventsToCsv(page.events));
+      } else {
+        console.log(JSON.stringify(page.events, null, 2));
+      }
+      console.error(`Exported ${String(page.events.length)} of ${String(page.total)} records`);
+      return;
+    }
     const result = store.listForExport(
       {
         tool_name: opts.tool,
@@ -10990,5 +11225,5 @@ program.command("start").description("Load config and start the proxy server").o
 );
 program.command("init").description("Scaffold a helio.yaml config file with commented defaults").option("-o, --output <path>", "Output file path", DEFAULT_CONFIG_PATH).option("-f, --force", "Overwrite existing file", false).action((opts) => initCommand(opts.output, opts.force));
 program.command("validate").description("Validate a helio.yaml config file").option("-c, --config <path>", "Path to helio.yaml", DEFAULT_CONFIG_PATH).action((opts) => validateCommand(opts.config));
-program.command("export").description("Export audit records to JSON or CSV").option("-c, --config <path>", "Path to helio.yaml", DEFAULT_CONFIG_PATH).option("-f, --format <format>", "Output format: json or csv", "json").option("--tool <name>", "Filter by tool name").option("--decision <decision>", "Filter by policy decision").option("--reason <reason>", "Filter by block reason").option("--session <id>", "Filter by session ID").option("--from <iso>", "Start time (ISO 8601)").option("--to <iso>", "End time (ISO 8601)").option("--limit <n>", "Max records to export (up to 10000)", "1000").action((opts) => exportCommand(opts));
+program.command("export").description("Export audit records or a budget ledger to JSON or CSV").option("-c, --config <path>", "Path to helio.yaml", DEFAULT_CONFIG_PATH).option("-f, --format <format>", "Output format: json or csv", "json").option("--budgets <name>", "Export the named budget ledger instead of the audit trail").option("--tool <name>", "Filter by tool name").option("--decision <decision>", "Filter by policy decision").option("--reason <reason>", "Filter by block reason").option("--session <id>", "Filter by session ID").option("--from <iso>", "Start time (ISO 8601)").option("--to <iso>", "End time (ISO 8601)").option("--limit <n>", "Max records to export (up to 10000)", "1000").action((opts) => exportCommand(opts));
 program.parse();