Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.2 KB
Raw Blame
/**
 * The approved spend cap of a foreground `gbrain embed` run (fix wave 13
 * P1.18, from PR #6400). Consent returns an Authorization with `cap_usd`; the
 * run spends under a BudgetTracker holding that cap, so every embedding,
 * multimodal and OCR call reserves before it is sent. The first refused
 * reservation aborts the run's signal before the refusal propagates: the
 * page and batch catches see a shutdown, not a chunk failure (no quarantine
 * strike, no per-chunk fan-out), vectors already installed stay banked, and
 * the CLI exits BUDGET_STOP_EXIT_CODE with the command that resumes.
 */
import type { CapSource } from './consent.ts';
import { BudgetExhausted, BudgetTracker, type PricingOverrides } from './budget/budget-tracker.ts';
import { withBudgetTracker } from './ai/gateway.ts';
import { shellQuote } from './shell-quote.ts';

export interface EmbedCostCap {
  readonly signal: AbortSignal;
  /** The cap's refusal once the run reached it; null while under it. */
  hit(): BudgetExhausted | null;
  /** Dollars the run has spent under the cap so far. */
  spent(): number;
  metered<T>(fn: () => Promise<T>): Promise<T>;
}

export interface EmbedCostStopFields {
  reason?: string;
  /** The tracker's refusal reason: `cost`, or `no_pricing` (a model with no known price under a user cap). */
  budget_reason?: string;
  cap_usd?: number;
  spent_usd?: number;
  resume_command?: string;
}

/**
 * Null when the authorization carries no finite positive cap (nothing to meter).
 * `pricingOverrides` is the brain's `pricing.overrides` (loadPricingOverrides),
 * so an operator-declared rate prices the run the same way a queued embed job does.
 */
export function embedCostCap(capUsd: number | null | undefined, capSource: CapSource | null | undefined, pricingOverrides?: PricingOverrides): EmbedCostCap | null {
  if (typeof capUsd !== 'number' || !Number.isFinite(capUsd) || capUsd <= 0) return null;
  const tracker = new BudgetTracker({ maxCostUsd: capUsd, label: 'embed', ...(capSource ? { capSource } : {}), ...(pricingOverrides ? { pricingOverrides } : {}) });
  const controller = new AbortController();
  let refusal: BudgetExhausted | null = null;
  // The refusal itself (cost, or a model with no price under a user cap) is kept for the verdict.
  const reserve = tracker.reserve.bind(tracker);
  tracker.reserve = estimate => {
    try { return reserve(estimate); } catch (err) { if (err instanceof BudgetExhausted) refusal ??= err; throw err; }
  };
  tracker.onExhausted(() => controller.abort());
  return {
    signal: controller.signal,
    hit: () => refusal ?? (controller.signal.aborted
      ? new BudgetExhausted(`embed reached its $${capUsd.toFixed(2)} cost cap`, { reason: 'cost', spent: tracker.totalSpent, cap: capUsd })
      : null),
    spent: () => tracker.totalSpent,
    metered: fn => withBudgetTracker(tracker, fn),
  };
}

/**
 * Record the stop on `result`. The resume command is the run itself without
 * its approval flags, so the user approves the rest again: a slug run skips
 * chunks that already have vectors, a stale run picks up where this one stopped.
 */
export function noteEmbedCostStop(result: EmbedCostStopFields, refusal: BudgetExhausted, args: readonly string[]): void {
  const resume: string[] = [];
  for (let i = 0; i < args.length; i++) {
    if (args[i] === '--yes' || args[i] === '--json') continue;
    if (args[i] === '--max-usd' || args[i] === '--max-cost') { i++; continue; }
    if (/^--max-(?:usd|cost)=/.test(args[i]!)) continue;
    resume.push(args[i]!);
  }
  result.reason = 'cost_cap';
  result.budget_reason = refusal.reason;
  result.cap_usd = refusal.cap;
  result.spent_usd = refusal.spent;
  result.resume_command = ['gbrain', 'embed', ...resume].map(shellQuote).join(' ');
}

/** The stdout verdict line for a cost-cap stop. */
export function embedCostStopVerdict(result: EmbedCostStopFields, refusal?: BudgetExhausted | null): string {
  const why = result.budget_reason === 'no_pricing' && refusal
    ? refusal.message
    : `the run reached its approved $${result.cap_usd?.toFixed(2)} cost cap after spending $${result.spent_usd?.toFixed(4)}`;
  return `[embed] stopped (reason: cost_cap): ${why}; embeddings already written are kept. `
    + `Resume, after the user approves more spend: ${result.resume_command} --max-usd <usd>`;
}