cashclaw 1.6.2 → 1.7.0

package/src/cli/commands/guard.js

@@ -0,0 +1,280 @@
+'use strict';
+
+/**
+ * CashClaw Guard - CLI commands
+ * v1.7.0
+ *
+ *   cashclaw guard init        # write guard-policy.yaml
+ *   cashclaw guard status      # show active policy + recent events
+ *   cashclaw guard test        # dry-run 8 enforcement scenarios
+ *   cashclaw guard kill <id>   # signal kill for running agent
+ *   cashclaw guard logs        # print recent Guard events
+ *   cashclaw guard reload      # reload policy from disk
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { loadConfig, saveConfig } from '../utils/config.js';
+import { Policy } from '../../guard/policy.js';
+import { llm as guardLlm, tool as guardTool, wrap as guardWrap, getRuntime, setRuntime, GuardRuntime } from '../../guard/decorator.js';
+import { BudgetExceeded, RecursionKilled, ToolDenied, RateLimitExceeded } from '../../guard/exceptions.js';
+
+const guard = { llm: guardLlm, tool: guardTool, wrap: guardWrap };
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname  = path.dirname(__filename);
+
+const TEMPLATE_PATH = path.resolve(__dirname, '../../../templates/guard-policy.yaml');
+const HOME_POLICY_PATH = path.join(os.homedir(), '.cashclaw', 'guard-policy.yaml');
+
+function header() {
+  console.log('');
+  console.log(chalk.bold.hex('#7B2CBF')('  CashClaw Guard') + chalk.dim('  v1.7.0'));
+  console.log(chalk.dim('  ──────────────────────────────'));
+}
+
+export function createGuardCommand() {
+  const cmd = new Command('guard')
+    .description('Agent runtime protection (cost cap, recursion kill, tool firewall)');
+
+  cmd
+    .command('init')
+    .description('Create guard-policy.yaml in ~/.cashclaw/')
+    .option('--force', 'Overwrite existing policy')
+    .option('--path <file>', 'Custom output path', HOME_POLICY_PATH)
+    .action(async (opts) => {
+      header();
+      const out = path.resolve(opts.path);
+      const dir = path.dirname(out);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      if (fs.existsSync(out) && !opts.force) {
+        console.log(chalk.yellow(`  ! Already exists: ${out}`));
+        console.log(chalk.dim('    Use --force to overwrite, or --path to write elsewhere.'));
+        return;
+      }
+      if (!fs.existsSync(TEMPLATE_PATH)) {
+        console.log(chalk.red(`  ! Template missing: ${TEMPLATE_PATH}`));
+        process.exitCode = 1;
+        return;
+      }
+      fs.copyFileSync(TEMPLATE_PATH, out);
+      const cfg = (await loadConfig()) || {};
+      cfg.guard = { ...(cfg.guard || {}), policy_path: out, enabled: true };
+      await saveConfig(cfg);
+      console.log(chalk.green(`  ✓ Policy written to ${out}`));
+      console.log(chalk.dim('    Edit the YAML and run `cashclaw guard reload`.'));
+    });
+
+  cmd
+    .command('status')
+    .description('Show active policy + recent Guard events')
+    .action(async () => {
+      header();
+      const cfg = await loadConfig();
+      const policyPath = cfg?.guard?.policy_path || HOME_POLICY_PATH;
+      let policy;
+      try {
+        policy = fs.existsSync(policyPath) ? Policy.fromFile(policyPath) : Policy.default();
+      } catch (err) {
+        console.log(chalk.red(`  ! Failed to load policy: ${err.message}`));
+        return;
+      }
+
+      console.log(`  Policy:           ${policy.sourcePath || chalk.dim('built-in default')}`);
+      console.log(`  Cost/day:         ${chalk.cyan('$' + policy.limits.cost_usd_per_day)}`);
+      console.log(`  Cost/call:        ${chalk.cyan('$' + policy.limits.cost_usd_per_call)}`);
+      console.log(`  Max tokens/call:  ${chalk.cyan(policy.limits.max_tokens_per_call)}`);
+      console.log(`  Max recursion:    ${chalk.cyan(policy.limits.max_recursion_depth)}`);
+      console.log(`  Tool denylist:    ${chalk.yellow(policy.tools.denylist.join(', ') || 'none')}`);
+      console.log(`  Allowlist:        ${policy.tools.allowlist.length === 0 ? chalk.dim('(deny-by-denylist mode)') : chalk.green(policy.tools.allowlist.join(', '))}`);
+
+      const enabled = ['telegram', 'slack', 'discord', 'generic']
+        .filter(c => policy.webhook[c]?.enabled);
+      console.log(`  Webhooks:         ${enabled.length === 0 ? chalk.dim('none') : chalk.green(enabled.join(', '))}`);
+
+      const rt = getRuntime();
+      const events = rt.events.slice(-10);
+      console.log('');
+      console.log(chalk.bold(`  Recent events (last ${events.length}):`));
+      if (events.length === 0) {
+        console.log(chalk.dim('    (none yet — Guard is quiet)'));
+      } else {
+        for (const ev of events) {
+          console.log(`    [${chalk.dim(ev.at)}] ${chalk.red(ev.type)}  ${ev.error?.message || ''}`);
+        }
+      }
+    });
+
+  cmd
+    .command('test')
+    .description('Dry-run 8 enforcement scenarios with mock LLM calls')
+    .action(async () => {
+      header();
+      const policy = Policy.default();
+      const rt = new GuardRuntime({ policy });
+      setRuntime(rt);
+
+      const scenarios = [
+        {
+          name: 'Per-call cost cap',
+          run: async () => {
+            const fn = guard.llm({ maxCostUsd: 0.01, maxTokens: 5_000_000, model: 'gpt-5.5', agentId: 'test-1' })(
+              async () => ({ usage: { prompt_tokens: 100_000, completion_tokens: 100_000 } })
+            );
+            await fn('hello world');
+          },
+          expect: BudgetExceeded,
+        },
+        {
+          name: 'Daily cost cap',
+          run: async () => {
+            // Daily cap = $1 baseline, single call cost ~$1.50 via gpt-5-mini
+            policy.data.limits.cost_usd_per_day = 1;
+            rt.reloadPolicy(policy);
+            const fn = guard.llm({ scope: 'daily-test', maxCostUsd: 1000, maxTokens: 5_000_000, model: 'gpt-5-mini' })(
+              async () => ({ usage: { prompt_tokens: 1_000_000, completion_tokens: 1_000_000 } })
+            );
+            await fn('hi');
+          },
+          expect: BudgetExceeded,
+        },
+        {
+          name: 'Recursion kill',
+          run: async () => {
+            const fn = guard.llm({ scope: 'rec-test', label: 'echo' })(async (p) => ({ usage: { prompt_tokens: 1, completion_tokens: 1 } }));
+            for (let i = 0; i < 10; i++) await fn('same-prompt-same-prompt');
+          },
+          expect: RecursionKilled,
+        },
+        {
+          name: 'Tool denylist',
+          run: async () => { guard.tool('shell', { agentId: 'test-tool', args: { command: 'ls' } }); },
+          expect: ToolDenied,
+        },
+        {
+          name: 'Tool allowlist miss',
+          run: async () => {
+            const p = Policy.default();
+            p.data.tools.allowlist = ['openai.chat.completions.create'];
+            const rt2 = new GuardRuntime({ policy: p });
+            guard.tool('weather.lookup', { runtime: rt2, agentId: 'test-aw' });
+          },
+          expect: ToolDenied,
+        },
+        {
+          name: 'Rate limit',
+          run: async () => {
+            const p = Policy.default();
+            p.data.tools.rate_limits = { 'slack.send': { max_per_minute: 2 } };
+            const rt2 = new GuardRuntime({ policy: p });
+            guard.tool('slack.send', { runtime: rt2, agentId: 't' });
+            guard.tool('slack.send', { runtime: rt2, agentId: 't' });
+            guard.tool('slack.send', { runtime: rt2, agentId: 't' });
+          },
+          expect: RateLimitExceeded,
+        },
+        {
+          name: 'YAML policy load',
+          run: async () => {
+            const p = Policy.fromYaml('limits:\n  cost_usd_per_call: 0.001\n');
+            if (p.limits.cost_usd_per_call !== 0.001) throw new Error('YAML did not parse');
+          },
+          expect: null, // should succeed
+        },
+        {
+          name: 'Default pricing fallback',
+          run: async () => {
+            const fn = guard.llm({ scope: 'pricing-test', maxCostUsd: 100, model: 'unknown-model-xyz' })(
+              async () => ({ usage: { prompt_tokens: 1, completion_tokens: 1 }, model: 'unknown-model-xyz' })
+            );
+            const r = await fn('hi');
+            if (!r) throw new Error('no result');
+          },
+          expect: null,
+        },
+      ];
+
+      let pass = 0, fail = 0;
+      for (const s of scenarios) {
+        try {
+          await s.run();
+          if (s.expect) {
+            console.log(`  ${chalk.red('✗')} ${s.name} ${chalk.dim('(expected ' + s.expect.name + ')')}`);
+            fail++;
+          } else {
+            console.log(`  ${chalk.green('✓')} ${s.name}`);
+            pass++;
+          }
+        } catch (err) {
+          if (s.expect && err instanceof s.expect) {
+            console.log(`  ${chalk.green('✓')} ${s.name} ${chalk.dim('(' + err.name + ')')}`);
+            pass++;
+          } else {
+            console.log(`  ${chalk.red('✗')} ${s.name}: ${err.message}`);
+            fail++;
+          }
+        }
+      }
+
+      console.log('');
+      console.log(`  ${chalk.bold('Summary:')} ${chalk.green(pass + ' pass')} / ${chalk.red(fail + ' fail')}`);
+      if (fail > 0) process.exitCode = 1;
+    });
+
+  cmd
+    .command('kill <agentId>')
+    .description('Emit a kill signal for a running agent (writes flag file)')
+    .action((agentId) => {
+      header();
+      const dir = path.join(os.homedir(), '.cashclaw', 'guard');
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      const flag = path.join(dir, `kill-${agentId}.flag`);
+      fs.writeFileSync(flag, JSON.stringify({ agentId, at: new Date().toISOString() }), 'utf-8');
+      console.log(chalk.yellow(`  Kill flag written: ${flag}`));
+      console.log(chalk.dim('  Agents check this file at the start of each Guard step.'));
+    });
+
+  cmd
+    .command('logs')
+    .description('Print recent Guard events (in-process ring buffer)')
+    .option('--limit <n>', 'How many events to show', '50')
+    .action((opts) => {
+      header();
+      const rt = getRuntime();
+      const limit = parseInt(opts.limit, 10) || 50;
+      const events = rt.events.slice(-limit);
+      if (events.length === 0) {
+        console.log(chalk.dim('  (no events recorded in this process)'));
+        return;
+      }
+      for (const ev of events) {
+        console.log(`  [${chalk.dim(ev.at)}] ${chalk.red(ev.type)}  scope=${ev.scope || '-'}  ${ev.error?.message || ''}`);
+      }
+    });
+
+  cmd
+    .command('reload')
+    .description('Reload the YAML policy from disk into the current runtime')
+    .action(async () => {
+      header();
+      const cfg = await loadConfig();
+      const policyPath = cfg?.guard?.policy_path || HOME_POLICY_PATH;
+      if (!fs.existsSync(policyPath)) {
+        console.log(chalk.red(`  ! No policy at ${policyPath}. Run \`cashclaw guard init\` first.`));
+        process.exitCode = 1;
+        return;
+      }
+      const policy = Policy.fromFile(policyPath);
+      const rt = getRuntime();
+      rt.reloadPolicy(policy);
+      console.log(chalk.green('  ✓ Policy reloaded into runtime.'));
+    });
+
+  return cmd;
+}
+
+export default createGuardCommand;

package/src/cli/index.js

@@ -10,6 +10,7 @@ import { listMissions, createMission, startMission, completeMission, cancelMissi
 import { getTotal, getMonthly, getWeekly, getToday, getHistory, getByService } from '../engine/earnings-tracker.js';
 import { listInstalledSkills, listAvailableSkills, installSkills } from '../integrations/openclaw-bridge.js';
 import { createHyrveCommand } from './commands/hyrve.js';
+import { createGuardCommand } from './commands/guard.js';
 import Table from 'cli-table3';
 import fs from 'fs-extra';
 import path from 'path';
@@ -568,6 +569,9 @@ program
 // ─── cashclaw hyrve ───────────────────────────────────────────────────
 program.addCommand(createHyrveCommand());
 
+// ─── cashclaw guard ───────────────────────────────────────────────────
+program.addCommand(createGuardCommand());
+
 // ─── Default action (no command) ───────────────────────────────────────
 program.action(() => {
   showBanner();

package/src/dashboard/public/index.html

@@ -13,7 +13,7 @@
     <header class="header">
       <div class="header-left">
         <span class="logo">CashClaw</span>
-        <span class="version" id="appVersion">v1.6.1</span>
+        <span class="version" id="appVersion">v1.7.0</span>
       </div>
       <div class="header-right">
         <span class="agent-name" id="agentName">Loading...</span>
@@ -164,7 +164,7 @@
 
     <!-- Footer -->
     <footer class="footer">
-      <span id="footerVersion">CashClaw v1.6.1</span>
+      <span id="footerVersion">CashClaw v1.7.0</span>
       <span class="footer-sep">|</span>
       <a href="https://cashclawai.com" target="_blank">cashclawai.com</a>
       <span class="footer-sep">|</span>

package/src/guard/cost-tracker.js

@@ -0,0 +1,138 @@
+/**
+ * CashClaw Guard - Cost tracking
+ * v1.7.0
+ *
+ * Tracks token usage and converts to USD using a pricing table.
+ * Holds per-agent/per-scope counters in memory and persists them
+ * via the optional `persistFn` callback (typically writes to disk).
+ *
+ * Daily counters reset at UTC midnight.
+ */
+
+import { BudgetExceeded, TokenLimitExceeded } from './exceptions.js';
+
+// USD per 1M tokens. Prices reflect public 2026-05 list rates and are
+// editable via policy.pricing override.
+export const DEFAULT_PRICING = {
+  // OpenAI
+  'gpt-5.5':          { input: 5.00,  output: 15.00 },
+  'gpt-5.5-pro':      { input: 30.00, output: 90.00 },
+  'gpt-5':            { input: 2.50,  output: 10.00 },
+  'gpt-5-mini':       { input: 0.30,  output: 1.20 },
+  'gpt-5-nano':       { input: 0.10,  output: 0.40 },
+  'gpt-4o':           { input: 2.50,  output: 10.00 },
+  'gpt-4o-mini':      { input: 0.15,  output: 0.60 },
+  // Anthropic
+  'claude-opus-4-7':  { input: 15.00, output: 75.00 },
+  'claude-opus-4-6':  { input: 15.00, output: 75.00 },
+  'claude-sonnet-4-6':{ input: 3.00,  output: 15.00 },
+  'claude-haiku-4-5': { input: 0.80,  output: 4.00 },
+  // Google
+  'gemini-3.1-pro':   { input: 1.25,  output: 5.00 },
+  'gemini-3-flash':   { input: 0.075, output: 0.30 },
+  // Moonshot Kimi
+  'kimi-k2.6':        { input: 0.60,  output: 2.50 },
+  'kimi-k2.5':        { input: 0.60,  output: 2.50 },
+  // Fallback
+  'default':          { input: 2.00,  output: 8.00 },
+};
+
+function utcDayKey(date = new Date()) {
+  return date.toISOString().slice(0, 10); // YYYY-MM-DD
+}
+
+export class CostTracker {
+  constructor({ pricing = DEFAULT_PRICING, persistFn = null, now = () => new Date() } = {}) {
+    this.pricing = { ...DEFAULT_PRICING, ...pricing };
+    this.persistFn = persistFn;
+    this.now = now;
+    // counters[scope][day] = { usd, tokens, calls }
+    this.counters = {};
+  }
+
+  _bucket(scope) {
+    const day = utcDayKey(this.now());
+    if (!this.counters[scope]) this.counters[scope] = {};
+    if (!this.counters[scope][day]) {
+      this.counters[scope][day] = { usd: 0, tokens: 0, calls: 0 };
+    }
+    return this.counters[scope][day];
+  }
+
+  /**
+   * Estimate cost of a single LLM call.
+   * @param {object} usage { model, inputTokens, outputTokens }
+   * @returns {number} USD
+   */
+  estimate({ model = 'default', inputTokens = 0, outputTokens = 0 }) {
+    const price = this.pricing[model] || this.pricing.default;
+    const inUsd = (inputTokens / 1_000_000) * price.input;
+    const outUsd = (outputTokens / 1_000_000) * price.output;
+    return inUsd + outUsd;
+  }
+
+  /**
+   * Record an LLM call and enforce caps.
+   * Throws BudgetExceeded or TokenLimitExceeded when limits hit.
+   * @param {object} opts
+   *   - scope: counter key (agentId, workflowId, "global", etc.)
+   *   - usage: { model, inputTokens, outputTokens }
+   *   - limits: { costUsdPerDay, costUsdPerCall, maxTokensPerCall }
+   *   - agentId: for error reporting
+   * @returns {{ usd, tokens, scopeTotal }}
+   */
+  record({ scope, usage, limits = {}, agentId = scope }) {
+    const usd = this.estimate(usage);
+    const tokens = (usage.inputTokens || 0) + (usage.outputTokens || 0);
+
+    if (limits.maxTokensPerCall && tokens > limits.maxTokensPerCall) {
+      throw new TokenLimitExceeded({ tokens, limit: limits.maxTokensPerCall, agentId });
+    }
+    if (limits.costUsdPerCall && usd > limits.costUsdPerCall) {
+      throw new BudgetExceeded({
+        spent: usd.toFixed(4),
+        limit: limits.costUsdPerCall,
+        agentId,
+        scope: 'per-call',
+      });
+    }
+
+    const bucket = this._bucket(scope);
+    const projected = bucket.usd + usd;
+
+    if (limits.costUsdPerDay && projected > limits.costUsdPerDay) {
+      throw new BudgetExceeded({
+        spent: projected.toFixed(4),
+        limit: limits.costUsdPerDay,
+        agentId,
+        scope: `daily:${scope}`,
+      });
+    }
+
+    bucket.usd = projected;
+    bucket.tokens += tokens;
+    bucket.calls += 1;
+
+    if (this.persistFn) {
+      try { this.persistFn(this.counters); } catch { /* ignore persistence errors */ }
+    }
+
+    return { usd, tokens, scopeTotal: bucket };
+  }
+
+  /**
+   * Get current spend snapshot.
+   */
+  snapshot(scope) {
+    return this._bucket(scope);
+  }
+
+  /**
+   * Reset all counters (useful for tests).
+   */
+  reset() {
+    this.counters = {};
+  }
+}
+
+export default CostTracker;

package/src/guard/decorator.js

@@ -0,0 +1,175 @@
+/**
+ * CashClaw Guard - SDK surface
+ * v1.7.0
+ *
+ * Higher-order wrappers used by application code:
+ *   - guard.llm({ ... })(fn)   → wraps a single LLM call
+ *   - guard.tool(name, args)   → tool firewall check
+ *   - guard.wrap(fn, options)  → one-shot inline wrap
+ *
+ * Each helper uses a shared Guard runtime instance so policy
+ * counters are aggregated across the whole process.
+ */
+
+import { Policy } from './policy.js';
+import { CostTracker } from './cost-tracker.js';
+import { RecursionDetector } from './recursion-detector.js';
+import { ToolFirewall } from './tool-firewall.js';
+import { WebhookDispatcher } from './webhook.js';
+import { GuardError } from './exceptions.js';
+
+export class GuardRuntime {
+  constructor({ policy = Policy.default(), logger = null } = {}) {
+    this.policy = policy;
+    this.logger = logger || (() => {});
+    this.cost = new CostTracker({ pricing: policy.pricing });
+    this.recursion = new RecursionDetector({
+      fingerprintWindowSeconds: policy.recursion.fingerprint_window_seconds,
+      killAfterRepeats: policy.recursion.kill_after_repeats,
+      maxRecursionDepth: policy.limits.max_recursion_depth,
+    });
+    this.firewall = new ToolFirewall({
+      allowlist: policy.tools.allowlist,
+      denylist: policy.tools.denylist,
+      rateLimits: policy.tools.rate_limits,
+    });
+    this.webhook = new WebhookDispatcher({ config: policy.webhook, logger });
+    this.events = []; // recent events ring buffer
+  }
+
+  reloadPolicy(policy) {
+    this.policy = policy;
+    this.cost.pricing = { ...this.cost.pricing, ...(policy.pricing || {}) };
+    this.recursion = new RecursionDetector({
+      fingerprintWindowSeconds: policy.recursion.fingerprint_window_seconds,
+      killAfterRepeats: policy.recursion.kill_after_repeats,
+      maxRecursionDepth: policy.limits.max_recursion_depth,
+    });
+    this.firewall.update({
+      allowlist: policy.tools.allowlist,
+      denylist: policy.tools.denylist,
+      rateLimits: policy.tools.rate_limits,
+    });
+    this.webhook.update(policy.webhook);
+  }
+
+  _eventTypeFromError(err) {
+    if (err?.code === 'BUDGET_EXCEEDED') return 'budget_exceeded';
+    if (err?.code === 'TOKEN_LIMIT_EXCEEDED') return 'token_limit_exceeded';
+    if (err?.code === 'RECURSION_KILLED') return 'recursion_killed';
+    if (err?.code === 'TOOL_DENIED') return 'tool_denied';
+    if (err?.code === 'RATE_LIMIT_EXCEEDED') return 'rate_limit_exceeded';
+    return 'guard_error';
+  }
+
+  async _fireEvent(err, { scope, agentId } = {}) {
+    const event = {
+      type: this._eventTypeFromError(err),
+      error: err instanceof GuardError ? err.toJSON() : { message: err?.message, code: err?.code },
+      scope,
+      agentId,
+      metadata: {},
+    };
+    this.events.push({ ...event, at: new Date().toISOString() });
+    if (this.events.length > 500) this.events.shift();
+    try { await this.webhook.dispatch(event); }
+    catch (e) { this.logger({ level: 'warn', msg: 'webhook dispatch failed', err: e.message }); }
+  }
+}
+
+let _defaultRuntime = null;
+export function getRuntime() {
+  if (!_defaultRuntime) _defaultRuntime = new GuardRuntime();
+  return _defaultRuntime;
+}
+export function setRuntime(rt) { _defaultRuntime = rt; }
+export function resetRuntime() { _defaultRuntime = null; }
+
+/**
+ * Wrap an LLM-calling function with cost/recursion enforcement.
+ *
+ * @param {object} opts
+ *   - maxCostUsd     hard per-call cost cap (overrides policy.cost_usd_per_call)
+ *   - maxTokens      hard per-call token cap
+ *   - maxRecursion   max times this signature can repeat in window
+ *   - agentId        scope/agent id for counters & alerts
+ *   - scope          counter scope (defaults to agentId)
+ *   - model          model id for cost estimation
+ *   - label          extra fingerprint label
+ *   - usageOf        function(result) → { inputTokens, outputTokens, model }
+ *   - runtime        explicit GuardRuntime (defaults to module singleton)
+ */
+export function llm(opts = {}) {
+  const rt = opts.runtime || getRuntime();
+
+  return function decorate(fn) {
+    return async function guardedLlm(...args) {
+      const scope = opts.scope || opts.agentId || 'default';
+      const sig = {
+        model: opts.model,
+        label: opts.label || fn.name || 'llm',
+        prompt: args[0],
+      };
+
+      try {
+        rt.recursion.track(sig, opts.agentId || scope);
+      } catch (err) {
+        await rt._fireEvent(err, { scope, agentId: opts.agentId });
+        throw err;
+      }
+
+      const result = await fn(...args);
+
+      // Extract usage. The caller can provide a custom extractor; otherwise
+      // we assume the result already exposes `.usage` like OpenAI/Anthropic.
+      let usage = { model: opts.model || sig.model, inputTokens: 0, outputTokens: 0 };
+      if (typeof opts.usageOf === 'function') {
+        usage = { ...usage, ...(opts.usageOf(result) || {}) };
+      } else if (result && result.usage) {
+        usage.inputTokens  = result.usage.prompt_tokens     || result.usage.input_tokens  || 0;
+        usage.outputTokens = result.usage.completion_tokens || result.usage.output_tokens || 0;
+        if (result.model) usage.model = result.model;
+      }
+
+      const limits = {
+        costUsdPerDay:  opts.policy?.limits?.cost_usd_per_day  || rt.policy.limits.cost_usd_per_day,
+        costUsdPerCall: opts.maxCostUsd ?? rt.policy.limits.cost_usd_per_call,
+        maxTokensPerCall: opts.maxTokens ?? rt.policy.limits.max_tokens_per_call,
+      };
+
+      try {
+        rt.cost.record({ scope, usage, limits, agentId: opts.agentId || scope });
+      } catch (err) {
+        await rt._fireEvent(err, { scope, agentId: opts.agentId });
+        throw err;
+      }
+
+      return result;
+    };
+  };
+}
+
+/**
+ * One-shot inline wrap: runs `fn`, records usage, throws if limits crossed.
+ * Returns the function result on success.
+ */
+export async function wrap(fn, opts = {}) {
+  const wrapped = llm(opts)(fn);
+  return wrapped();
+}
+
+/**
+ * Check a tool invocation against the firewall.
+ * Throws ToolDenied or RateLimitExceeded.
+ */
+export function tool(name, ctx = {}) {
+  const rt = ctx.runtime || getRuntime();
+  try {
+    return rt.firewall.check(name, ctx);
+  } catch (err) {
+    rt._fireEvent(err, { scope: ctx.scope, agentId: ctx.agentId });
+    throw err;
+  }
+}
+
+export default { llm, wrap, tool, GuardRuntime, getRuntime, setRuntime, resetRuntime };