Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.
TypeScript agentic-aiai-agentsai-codinganthropicautomationclaudeclaude-codecodexcoding-agentsdevops-automationdevtoolsgithub-actionsgrokllmloop-engineeringmcpprompt-engineering
feat(loop-context): track daily token spend across runs, add --on-exceed hook (#273)
JonyT Agentic1ceeaf7a0381
diff --git a/templates/SKILL.md.loop-guard b/templates/SKILL.md.loop-guardindex d10aefb..d8a700c 100644--- a/templates/SKILL.md.loop-guard+++ b/templates/SKILL.md.loop-guard@@ -52,6 +52,28 @@ npx @cobusgreyling/loop-context --check --ledger loop-ledger.json \--budget-from-pattern ci-sweeper --budget-level L2```+## Track the daily cap across runs (optional)++`--budget-from-pattern` only guards a single run's ledger. `loop-budget.md`'s+daily table ("Max tokens/day") is a cross-run cap — track it with+`--daily-budget-from-pattern`, which accumulates spend into+`.loop-context/daily-spend.<pattern>.json` (resets at UTC midnight) and+escalates with trigger `daily-budget` once the pattern's suggested daily cap+is reached, even if this run's own ledger is nowhere near its per-run budget:++```bash+npx @cobusgreyling/loop-context --check --ledger loop-ledger.json \+ --budget-from-pattern ci-sweeper --budget-level L2 \+ --daily-budget-from-pattern ci-sweeper \+ --on-exceed ./scripts/on-budget-exceed.sh+```++`--on-exceed <script>` turns `loop-budget.md`'s manual "On budget exceed"+checklist into a hook: on any escalate, the decision is piped as JSON to the+script's stdin (fire-and-forget — the script's exit code doesn't change+`--check`'s own). A typical script disables the scheduler, appends to+`loop-run-log.md`, and opens a maintainer issue.+## Before each iteration1. Append the previous attempt to `loop-ledger.json`.@@ -64,7 +86,8 @@ npx @cobusgreyling/loop-context --check --ledger loop-ledger.json \- **0** → continue. Optionally trim the next prompt first:`npx @cobusgreyling/loop-context --inject --ledger loop-ledger.json`- **2** → **STOP.** The breaker tripped — same error N× in a row, too many- consecutive failures, the token budget, or the iteration cap. Do not retry.+ consecutive failures, the per-run or daily token budget, or the+ iteration cap. Do not retry.## On escalate (exit 2)@@ -88,5 +111,6 @@ npx @cobusgreyling/loop-context --check --ledger loop-ledger.json \- `minimal-fix` / `ci-triage` — record each attempt's outcome + error in the ledger.- `loop-verifier` — a verifier rejection is a `failure`; log it so repeats trip the breaker.- `loop-constraints` — honors "escalate after N attempts"; this skill makes it mechanical.-- `loop-budget` — the per-run budget here comes from `--budget-from-pattern`;- loop-budget.md still governs the *daily* cap across runs.+- `loop-budget` — the per-run budget comes from `--budget-from-pattern`, the+ daily cap from `--daily-budget-from-pattern`; `--on-exceed` automates the+ "On budget exceed" steps loop-budget.md otherwise leaves manual.diff --git a/tools/loop-context/README.md b/tools/loop-context/README.mdindex e946e5d..8c082f1 100644--- a/tools/loop-context/README.md+++ b/tools/loop-context/README.md@@ -100,6 +100,37 @@ dependency) — the same resolution `loop-init` already uses for `loop-audit`packages stay independent at the source level; an unknown pattern id surfaces`loop-cost`'s own error instead of failing silently.+## Tracking a daily cap across separate runs++`--budget-from-pattern` only guards one run's ledger. Patterns also have a **daily**+cap (`loop-cost`'s `suggestedDailyCap`) that spans many runs across a day —+`--daily-budget-from-pattern` tracks that:++```bash+loop-context --check --ledger run.json --daily-budget-from-pattern ci-sweeper \+ --budget-level L2 --on-exceed ./scripts/on-budget-exceed.sh+```++| Flag | Default | Meaning |+|------|---------|---------|+| `--daily-budget-from-pattern <id>` | none | Pattern id whose cumulative daily spend to track and cap |+| `--daily-state-dir <dir>` | `.loop-context` | Where `daily-spend.<pattern>.json` is kept |+| `--on-exceed <script>` | none | On any escalate, pipe the `BreakerDecision` as JSON to this script's stdin |++Each `--check` call adds the ledger's newest attempt's `tokensUsed` to a per-pattern+state file (`daily-spend.<pattern-id>.json`, `{ "date": "...", "tokensUsedToday": N }`),+rolling over to zero when the stored date isn't today (UTC). Once the running total+reaches the pattern's suggested daily cap, `--check` escalates with trigger+`daily-budget` — but only if no per-run trigger (stagnation, no-progress, token-budget,+max-iterations) already fired; per-run reasons always take priority. `--budget-level`,+`--budget-cadence`, and `--budget-conservative` (shared with `--budget-from-pattern`)+shape the daily-cap lookup too.++`--on-exceed <script>` fires on **any** escalate, not just `daily-budget` — it's a+generic hook for automating `loop-budget.md`'s "On budget exceed" checklist (pause+schedulers, log the event, notify a human) instead of doing those steps by hand. The+script's exit code is not checked and does not change `--check`'s own exit code.+## Populating the ledgerYour loop control script appends one object per iteration to `run.json` (or pipes the same shape on stdin):diff --git a/tools/loop-context/dist/budget-resolver.d.ts b/tools/loop-context/dist/budget-resolver.d.tsindex 03a4ca0..d81724c 100644--- a/tools/loop-context/dist/budget-resolver.d.ts+++ b/tools/loop-context/dist/budget-resolver.d.ts@@ -12,8 +12,11 @@ export interface BudgetFromPatternInput {export declare function resolveCostCli(): Promise<string | null>;/*** Resolve a token budget from loop-cost's realistic per-pattern estimate- * instead of a hand-typed number. Shells out to loop-cost's built CLI- * (same monorepo-then-installed-dependency resolution loop-init uses for- * loop-audit) so the two tools stay independent at the source level.+ * instead of a hand-typed number.*/export declare function resolveTokenBudgetFromPattern(input: BudgetFromPatternInput): Promise<number>;+/**+ * Resolve a pattern's suggested daily token cap from loop-cost, for+ * cross-run daily spend tracking (see daily-spend.ts).+ */+export declare function resolveDailyBudgetFromPattern(input: BudgetFromPatternInput): Promise<number>;diff --git a/tools/loop-context/dist/budget-resolver.js b/tools/loop-context/dist/budget-resolver.jsindex 7f12e7f..624e1c2 100644--- a/tools/loop-context/dist/budget-resolver.js+++ b/tools/loop-context/dist/budget-resolver.js@@ -46,17 +46,14 @@ function runCostCli(cli, args) {});}/**- * Resolve a token budget from loop-cost's realistic per-pattern estimate- * instead of a hand-typed number. Shells out to loop-cost's built CLI- * (same monorepo-then-installed-dependency resolution loop-init uses for- * loop-audit) so the two tools stay independent at the source level.+ * Shell out to loop-cost's built CLI (same monorepo-then-installed-dependency+ * resolution loop-init uses for loop-audit) and parse its --json estimate.+ * Shared by both the per-run and daily budget resolvers below.*/-export async function resolveTokenBudgetFromPattern(input) {- const scenario = input.scenario ?? 'realistic';- assertValidBudgetScenario(scenario);+async function invokeLoopCost(input) {const cli = await resolveCostCli();if (!cli) {- throw new Error('--budget-from-pattern requires @cobusgreyling/loop-cost. Install it, or run from the loop-engineering monorepo.');+ throw new Error('Resolving a budget from a pattern requires @cobusgreyling/loop-cost. Install it, or run from the loop-engineering monorepo.');}const args = ['--pattern', input.pattern, '--level', input.level ?? 'L1'];if (input.cadence)@@ -70,16 +67,36 @@ export async function resolveTokenBudgetFromPattern(input) {if (!stdout.trim()) {throw new Error('loop-cost produced no output.');}- let parsed;try {- parsed = JSON.parse(stdout);+ return JSON.parse(stdout);}catch {throw new Error('loop-cost produced output that could not be parsed as JSON.');}+}+/**+ * Resolve a token budget from loop-cost's realistic per-pattern estimate+ * instead of a hand-typed number.+ */+export async function resolveTokenBudgetFromPattern(input) {+ const scenario = input.scenario ?? 'realistic';+ assertValidBudgetScenario(scenario);+ const parsed = await invokeLoopCost(input);const tokensPerRun = parsed.scenarios?.[scenario]?.tokensPerRun;if (typeof tokensPerRun !== 'number') {throw new Error(`loop-cost output missing scenarios.${scenario}.tokensPerRun.`);}return tokensPerRun;}+/**+ * Resolve a pattern's suggested daily token cap from loop-cost, for+ * cross-run daily spend tracking (see daily-spend.ts).+ */+export async function resolveDailyBudgetFromPattern(input) {+ const parsed = await invokeLoopCost(input);+ const dailyCap = parsed.suggestedDailyCap;+ if (typeof dailyCap !== 'number') {+ throw new Error('loop-cost output missing suggestedDailyCap.');+ }+ return dailyCap;+}diff --git a/tools/loop-context/dist/cli.js b/tools/loop-context/dist/cli.jsindex f1c8b70..03b0c54 100755--- a/tools/loop-context/dist/cli.js+++ b/tools/loop-context/dist/cli.js@@ -1,7 +1,9 @@#!/usr/bin/env nodeimport { readFile } from 'node:fs/promises';+import { spawn } from 'node:child_process';import { buildContextInjection, checkCircuitBreaker, pruneLedger, summarizeAttempts, DEFAULT_BREAKER, DEFAULT_PRUNE, } from './context-manager.js';-import { resolveTokenBudgetFromPattern, } from './budget-resolver.js';+import { resolveTokenBudgetFromPattern, resolveDailyBudgetFromPattern, } from './budget-resolver.js';+import { recordDailySpend } from './daily-spend.js';/** Reject NaN/0/floats so a bad flag cannot silently disable the breaker. */function parsePositiveIntFlag(raw, flag) {if (raw === undefined || raw === '') {@@ -24,9 +26,13 @@ function parseArgs(argv) {let budgetScenario = 'realistic';let budgetCadence;let budgetConservative = false;+ let dailyBudgetFromPattern;+ let dailyStateDir = '.loop-context';+ let onExceed;const base = () => ({op, json, breaker, prune,budgetFromPattern, budgetLevel, budgetScenario, budgetCadence, budgetConservative,+ dailyBudgetFromPattern, dailyStateDir, onExceed,});for (let i = 0; i < argv.length; i++) {const a = argv[i];@@ -64,6 +70,12 @@ function parseArgs(argv) {budgetCadence = argv[++i];else if (a === '--budget-conservative')budgetConservative = true;+ else if (a === '--daily-budget-from-pattern')+ dailyBudgetFromPattern = argv[++i];+ else if (a === '--daily-state-dir')+ dailyStateDir = argv[++i];+ else if (a === '--on-exceed')+ onExceed = argv[++i];else if (a === '--window')prune.window = parsePositiveIntFlag(argv[++i], '--window');else if (a === '--max-trace-lines')@@ -102,6 +114,7 @@ Usage:loop-context [operation] [--ledger <file.json>] [options]cat ledger.json | loop-context --checkloop-context --check --ledger run.json --budget-from-pattern ci-sweeper --budget-level L2+ loop-context --check --ledger run.json --daily-budget-from-pattern ci-sweeper --on-exceed ./on-exceed.shOperations (default: --status):--check Run the circuit breaker. Exit 0 = continue, 2 = escalate.@@ -126,6 +139,17 @@ Options:Which loop-cost scenario to use (default: realistic)--budget-cadence <spec> Cadence override passed through to loop-cost--budget-conservative Use the slower cadence in a range (loop-cost flag)+ --daily-budget-from-pattern <id>+ Track cumulative daily spend for this pattern+ across separate --check calls/runs and escalate+ (trigger: daily-budget) once it reaches loop-cost's+ suggested daily cap. Ignored if a per-run trigger+ already escalated. Uses --budget-level/-cadence/+ -conservative for the lookup.+ --daily-state-dir <dir> Where daily-spend.<pattern>.json is kept (default: .loop-context)+ --on-exceed <script> On escalate, pipe the decision as JSON to this+ script's stdin (fire-and-forget; its exit code+ is not checked and does not change --check's own).--window <n> Attempts kept when pruning (default: ${DEFAULT_PRUNE.window})--max-trace-lines <n> Stack-trace lines kept (default: ${DEFAULT_PRUNE.maxTraceLines})-h, --help This help@@ -154,7 +178,13 @@ async function main() {const ledger = await readLedger(args.ledger);switch (args.op) {case 'check': {- const decision = checkCircuitBreaker(ledger, args.breaker);+ let decision = checkCircuitBreaker(ledger, args.breaker);+ if (args.dailyBudgetFromPattern) {+ decision = await applyDailyBudget(decision, ledger, args);+ }+ if (decision.escalate && args.onExceed) {+ await runOnExceedHook(args.onExceed, decision);+ }if (args.json)console.log(JSON.stringify(decision, null, 2));else@@ -189,6 +219,49 @@ async function main() {}}}+/**+ * Add the newest attempt's tokensUsed to the pattern's running daily total+ * (rolling over on UTC date change) and, if that total reaches loop-cost's+ * suggested daily cap, override the decision to escalate — but only when no+ * per-run trigger already fired.+ */+async function applyDailyBudget(decision, ledger, args) {+ const pattern = args.dailyBudgetFromPattern;+ const latest = ledger.attempts[ledger.attempts.length - 1];+ const tokensDelta = latest?.tokensUsed ?? 0;+ const state = await recordDailySpend(args.dailyStateDir, pattern, tokensDelta);+ if (decision.escalate)+ return decision;+ const dailyCap = await resolveDailyBudgetFromPattern({+ pattern,+ level: args.budgetLevel,+ cadence: args.budgetCadence,+ conservative: args.budgetConservative,+ });+ if (state.tokensUsedToday >= dailyCap) {+ return {+ ...decision,+ shouldContinue: false,+ escalate: true,+ trigger: 'daily-budget',+ reason: `Daily token spend for pattern "${pattern}" reached ${state.tokensUsedToday} (cap ${dailyCap}). Escalating to avoid cost blowup.`,+ };+ }+ return decision;+}+/** Pipe the escalation decision as JSON to an operator-provided script's stdin. Fire-and-forget. */+function runOnExceedHook(script, decision) {+ return new Promise((resolve) => {+ const child = spawn(script, [], { stdio: ['pipe', 'inherit', 'inherit'], shell: true });+ child.on('error', (err) => {+ console.error(`loop-context: --on-exceed hook failed to start: ${err.message}`);+ resolve();+ });+ child.on('close', () => resolve());+ child.stdin.write(JSON.stringify(decision));+ child.stdin.end();+ });+}function formatSummary(s) {const lines = [];lines.push(`Attempts: ${s.totalAttempts} (${s.successes} ok · ${s.failures} failed · ${s.noops} no-op)`);diff --git a/tools/loop-context/dist/context-manager.d.ts b/tools/loop-context/dist/context-manager.d.tsindex 19f5e5a..39c69e3 100644--- a/tools/loop-context/dist/context-manager.d.ts+++ b/tools/loop-context/dist/context-manager.d.ts@@ -64,7 +64,7 @@ export declare const DEFAULT_PRUNE: PruneConfig;* (line numbers, addresses, timestamps, ports, temp paths) differ.*/export declare function errorSignature(error: string): string;-export type BreakerTrigger = 'ok' | 'stagnation' | 'no-progress' | 'token-budget' | 'max-iterations';+export type BreakerTrigger = 'ok' | 'stagnation' | 'no-progress' | 'token-budget' | 'daily-budget' | 'max-iterations';export interface BreakerDecision {/** Whether the loop is cleared to run another iteration. */shouldContinue: boolean;diff --git a/tools/loop-context/dist/daily-spend.d.ts b/tools/loop-context/dist/daily-spend.d.tsnew file mode 100644index 0000000..2e534d1--- /dev/null+++ b/tools/loop-context/dist/daily-spend.d.ts@@ -0,0 +1,12 @@+export interface DailySpendState {+ date: string;+ tokensUsedToday: number;+}+/** Today's date in UTC, as YYYY-MM-DD — the daily-spend rollover boundary. */+export declare function todayUTC(): string;+/**+ * Add `tokensDelta` to a pattern's running daily total and persist it. Rolls+ * over to a fresh total when the stored date isn't today (UTC) — a stale+ * file from a previous day is treated as if it didn't exist.+ */+export declare function recordDailySpend(dir: string, pattern: string, tokensDelta: number): Promise<DailySpendState>;diff --git a/tools/loop-context/dist/daily-spend.js b/tools/loop-context/dist/daily-spend.jsnew file mode 100644index 0000000..16da555--- /dev/null+++ b/tools/loop-context/dist/daily-spend.js@@ -0,0 +1,32 @@+import path from 'node:path';+import { mkdir, readFile, writeFile } from 'node:fs/promises';+/** Today's date in UTC, as YYYY-MM-DD — the daily-spend rollover boundary. */+export function todayUTC() {+ return new Date().toISOString().slice(0, 10);+}+function statePath(dir, pattern) {+ return path.join(dir, `daily-spend.${pattern}.json`);+}+async function readState(dir, pattern) {+ try {+ const raw = await readFile(statePath(dir, pattern), 'utf8');+ return JSON.parse(raw);+ }+ catch {+ return null;+ }+}+/**+ * Add `tokensDelta` to a pattern's running daily total and persist it. Rolls+ * over to a fresh total when the stored date isn't today (UTC) — a stale+ * file from a previous day is treated as if it didn't exist.+ */+export async function recordDailySpend(dir, pattern, tokensDelta) {+ const today = todayUTC();+ const existing = await readState(dir, pattern);+ const carryOver = existing && existing.date === today ? existing.tokensUsedToday : 0;+ const state = { date: today, tokensUsedToday: carryOver + tokensDelta };+ await mkdir(dir, { recursive: true });+ await writeFile(statePath(dir, pattern), JSON.stringify(state, null, 2));+ return state;+}diff --git a/tools/loop-context/package-lock.json b/tools/loop-context/package-lock.jsonindex 2365c55..dfbc5d3 100644--- a/tools/loop-context/package-lock.json+++ b/tools/loop-context/package-lock.json@@ -1,12 +1,12 @@{"name": "@cobusgreyling/loop-context",- "version": "1.1.0",+ "version": "1.2.0","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "@cobusgreyling/loop-context",- "version": "1.1.0",+ "version": "1.2.0","license": "MIT","dependencies": {"@cobusgreyling/loop-cost": "^1.1.0"diff --git a/tools/loop-context/package.json b/tools/loop-context/package.jsonindex 5e4897b..4bb928d 100644--- a/tools/loop-context/package.json+++ b/tools/loop-context/package.json@@ -1,6 +1,6 @@{"name": "@cobusgreyling/loop-context",- "version": "1.1.0",+ "version": "1.2.0","description": "Stateful memory manager for agent loops — summarize, prune, and inject context, with a circuit breaker that escalates stagnant or no-progress runs instead of burning tokens.","type": "module","main": "dist/context-manager.js",diff --git a/tools/loop-context/src/budget-resolver.ts b/tools/loop-context/src/budget-resolver.tsindex 61628cb..1790703 100644--- a/tools/loop-context/src/budget-resolver.ts+++ b/tools/loop-context/src/budget-resolver.ts@@ -61,20 +61,21 @@ function runCostCli(cli: string, args: string[]): Promise<{ stdout: string; stde});}+interface LoopCostResult {+ suggestedDailyCap?: number;+ scenarios?: Record<string, { tokensPerRun?: number }>;+}+/**- * Resolve a token budget from loop-cost's realistic per-pattern estimate- * instead of a hand-typed number. Shells out to loop-cost's built CLI- * (same monorepo-then-installed-dependency resolution loop-init uses for- * loop-audit) so the two tools stay independent at the source level.+ * Shell out to loop-cost's built CLI (same monorepo-then-installed-dependency+ * resolution loop-init uses for loop-audit) and parse its --json estimate.+ * Shared by both the per-run and daily budget resolvers below.*/-export async function resolveTokenBudgetFromPattern(input: BudgetFromPatternInput): Promise<number> {- const scenario = input.scenario ?? 'realistic';- assertValidBudgetScenario(scenario);-+async function invokeLoopCost(input: BudgetFromPatternInput): Promise<LoopCostResult> {const cli = await resolveCostCli();if (!cli) {throw new Error(- '--budget-from-pattern requires @cobusgreyling/loop-cost. Install it, or run from the loop-engineering monorepo.',+ 'Resolving a budget from a pattern requires @cobusgreyling/loop-cost. Install it, or run from the loop-engineering monorepo.',);}@@ -90,16 +91,38 @@ export async function resolveTokenBudgetFromPattern(input: BudgetFromPatternInputhrow new Error('loop-cost produced no output.');}- let parsed: { scenarios?: Record<string, { tokensPerRun?: number }> };try {- parsed = JSON.parse(stdout);+ return JSON.parse(stdout) as LoopCostResult;} catch {throw new Error('loop-cost produced output that could not be parsed as JSON.');}+}++/**+ * Resolve a token budget from loop-cost's realistic per-pattern estimate+ * instead of a hand-typed number.+ */+export async function resolveTokenBudgetFromPattern(input: BudgetFromPatternInput): Promise<number> {+ const scenario = input.scenario ?? 'realistic';+ assertValidBudgetScenario(scenario);+ const parsed = await invokeLoopCost(input);const tokensPerRun = parsed.scenarios?.[scenario]?.tokensPerRun;if (typeof tokensPerRun !== 'number') {throw new Error(`loop-cost output missing scenarios.${scenario}.tokensPerRun.`);}return tokensPerRun;}++/**+ * Resolve a pattern's suggested daily token cap from loop-cost, for+ * cross-run daily spend tracking (see daily-spend.ts).+ */+export async function resolveDailyBudgetFromPattern(input: BudgetFromPatternInput): Promise<number> {+ const parsed = await invokeLoopCost(input);+ const dailyCap = parsed.suggestedDailyCap;+ if (typeof dailyCap !== 'number') {+ throw new Error('loop-cost output missing suggestedDailyCap.');+ }+ return dailyCap;+}diff --git a/tools/loop-context/src/cli.ts b/tools/loop-context/src/cli.tsindex 41f2c29..51f2161 100644--- a/tools/loop-context/src/cli.ts+++ b/tools/loop-context/src/cli.ts@@ -1,5 +1,6 @@#!/usr/bin/env nodeimport { readFile } from 'node:fs/promises';+import { spawn } from 'node:child_process';import {buildContextInjection,checkCircuitBreaker,@@ -10,12 +11,15 @@ import {type Ledger,type CircuitBreakerConfig,type PruneConfig,+ type BreakerDecision,} from './context-manager.js';import {assertValidBudgetScenario,resolveTokenBudgetFromPattern,+ resolveDailyBudgetFromPattern,type BudgetScenario,} from './budget-resolver.js';+import { recordDailySpend } from './daily-spend.js';type Op = 'check' | 'prune' | 'inject' | 'summary' | 'status';@@ -31,6 +35,9 @@ interface Args {budgetScenario: BudgetScenario;budgetCadence?: string;budgetConservative: boolean;+ dailyBudgetFromPattern?: string;+ dailyStateDir: string;+ onExceed?: string;}/** Reject NaN/0/floats so a bad flag cannot silently disable the breaker. */@@ -56,10 +63,14 @@ function parseArgs(argv: string[]): Args {let budgetScenario: BudgetScenario = 'realistic';let budgetCadence: string | undefined;let budgetConservative = false;+ let dailyBudgetFromPattern: string | undefined;+ let dailyStateDir = '.loop-context';+ let onExceed: string | undefined;const base = () => ({op, json, breaker, prune,budgetFromPattern, budgetLevel, budgetScenario, budgetCadence, budgetConservative,+ dailyBudgetFromPattern, dailyStateDir, onExceed,});for (let i = 0; i < argv.length; i++) {@@ -81,6 +92,9 @@ function parseArgs(argv: string[]): Args {else if (a === '--budget-scenario') budgetScenario = argv[++i] as BudgetScenario;else if (a === '--budget-cadence') budgetCadence = argv[++i];else if (a === '--budget-conservative') budgetConservative = true;+ else if (a === '--daily-budget-from-pattern') dailyBudgetFromPattern = argv[++i];+ else if (a === '--daily-state-dir') dailyStateDir = argv[++i];+ else if (a === '--on-exceed') onExceed = argv[++i];else if (a === '--window') prune.window = parsePositiveIntFlag(argv[++i], '--window');else if (a === '--max-trace-lines') prune.maxTraceLines = parsePositiveIntFlag(argv[++i], '--max-trace-lines');}@@ -121,6 +135,7 @@ Usage:loop-context [operation] [--ledger <file.json>] [options]cat ledger.json | loop-context --checkloop-context --check --ledger run.json --budget-from-pattern ci-sweeper --budget-level L2+ loop-context --check --ledger run.json --daily-budget-from-pattern ci-sweeper --on-exceed ./on-exceed.shOperations (default: --status):--check Run the circuit breaker. Exit 0 = continue, 2 = escalate.@@ -145,6 +160,17 @@ Options:Which loop-cost scenario to use (default: realistic)--budget-cadence <spec> Cadence override passed through to loop-cost--budget-conservative Use the slower cadence in a range (loop-cost flag)+ --daily-budget-from-pattern <id>+ Track cumulative daily spend for this pattern+ across separate --check calls/runs and escalate+ (trigger: daily-budget) once it reaches loop-cost's+ suggested daily cap. Ignored if a per-run trigger+ already escalated. Uses --budget-level/-cadence/+ -conservative for the lookup.+ --daily-state-dir <dir> Where daily-spend.<pattern>.json is kept (default: .loop-context)+ --on-exceed <script> On escalate, pipe the decision as JSON to this+ script's stdin (fire-and-forget; its exit code+ is not checked and does not change --check's own).--window <n> Attempts kept when pruning (default: ${DEFAULT_PRUNE.window})--max-trace-lines <n> Stack-trace lines kept (default: ${DEFAULT_PRUNE.maxTraceLines})-h, --help This help@@ -177,7 +203,13 @@ async function main() {switch (args.op) {case 'check': {- const decision = checkCircuitBreaker(ledger, args.breaker);+ let decision = checkCircuitBreaker(ledger, args.breaker);+ if (args.dailyBudgetFromPattern) {+ decision = await applyDailyBudget(decision, ledger, args);+ }+ if (decision.escalate && args.onExceed) {+ await runOnExceedHook(args.onExceed, decision);+ }if (args.json) console.log(JSON.stringify(decision, null, 2));else console.log(`${decision.escalate ? 'ESCALATE' : 'CONTINUE'} [${decision.trigger}] — ${decision.reason}`);process.exitCode = decision.escalate ? 2 : 0;@@ -209,6 +241,53 @@ async function main() {}}+/**+ * Add the newest attempt's tokensUsed to the pattern's running daily total+ * (rolling over on UTC date change) and, if that total reaches loop-cost's+ * suggested daily cap, override the decision to escalate — but only when no+ * per-run trigger already fired.+ */+async function applyDailyBudget(decision: BreakerDecision, ledger: Ledger, args: Args): Promise<BreakerDecision> {+ const pattern = args.dailyBudgetFromPattern as string;+ const latest = ledger.attempts[ledger.attempts.length - 1];+ const tokensDelta = latest?.tokensUsed ?? 0;+ const state = await recordDailySpend(args.dailyStateDir, pattern, tokensDelta);++ if (decision.escalate) return decision;++ const dailyCap = await resolveDailyBudgetFromPattern({+ pattern,+ level: args.budgetLevel,+ cadence: args.budgetCadence,+ conservative: args.budgetConservative,+ });++ if (state.tokensUsedToday >= dailyCap) {+ return {+ ...decision,+ shouldContinue: false,+ escalate: true,+ trigger: 'daily-budget',+ reason: `Daily token spend for pattern "${pattern}" reached ${state.tokensUsedToday} (cap ${dailyCap}). Escalating to avoid cost blowup.`,+ };+ }+ return decision;+}++/** Pipe the escalation decision as JSON to an operator-provided script's stdin. Fire-and-forget. */+function runOnExceedHook(script: string, decision: BreakerDecision): Promise<void> {+ return new Promise((resolve) => {+ const child = spawn(script, [], { stdio: ['pipe', 'inherit', 'inherit'], shell: true });+ child.on('error', (err) => {+ console.error(`loop-context: --on-exceed hook failed to start: ${err.message}`);+ resolve();+ });+ child.on('close', () => resolve());+ child.stdin.write(JSON.stringify(decision));+ child.stdin.end();+ });+}+function formatSummary(s: ReturnType<typeof summarizeAttempts>): string {const lines: string[] = [];lines.push(`Attempts: ${s.totalAttempts} (${s.successes} ok · ${s.failures} failed · ${s.noops} no-op)`);diff --git a/tools/loop-context/src/context-manager.ts b/tools/loop-context/src/context-manager.tsindex 376ac6e..8e734e6 100644--- a/tools/loop-context/src/context-manager.ts+++ b/tools/loop-context/src/context-manager.ts@@ -103,6 +103,7 @@ export type BreakerTrigger =| 'stagnation'| 'no-progress'| 'token-budget'+ | 'daily-budget'| 'max-iterations';export interface BreakerDecision {diff --git a/tools/loop-context/src/daily-spend.ts b/tools/loop-context/src/daily-spend.tsnew file mode 100644index 0000000..023b054--- /dev/null+++ b/tools/loop-context/src/daily-spend.ts@@ -0,0 +1,45 @@+import path from 'node:path';+import { mkdir, readFile, writeFile } from 'node:fs/promises';++export interface DailySpendState {+ date: string;+ tokensUsedToday: number;+}++/** Today's date in UTC, as YYYY-MM-DD — the daily-spend rollover boundary. */+export function todayUTC(): string {+ return new Date().toISOString().slice(0, 10);+}++function statePath(dir: string, pattern: string): string {+ return path.join(dir, `daily-spend.${pattern}.json`);+}++async function readState(dir: string, pattern: string): Promise<DailySpendState | null> {+ try {+ const raw = await readFile(statePath(dir, pattern), 'utf8');+ return JSON.parse(raw) as DailySpendState;+ } catch {+ return null;+ }+}++/**+ * Add `tokensDelta` to a pattern's running daily total and persist it. Rolls+ * over to a fresh total when the stored date isn't today (UTC) — a stale+ * file from a previous day is treated as if it didn't exist.+ */+export async function recordDailySpend(+ dir: string,+ pattern: string,+ tokensDelta: number,+): Promise<DailySpendState> {+ const today = todayUTC();+ const existing = await readState(dir, pattern);+ const carryOver = existing && existing.date === today ? existing.tokensUsedToday : 0;+ const state: DailySpendState = { date: today, tokensUsedToday: carryOver + tokensDelta };++ await mkdir(dir, { recursive: true });+ await writeFile(statePath(dir, pattern), JSON.stringify(state, null, 2));+ return state;+}diff --git a/tools/loop-context/test/budget-resolver.test.mjs b/tools/loop-context/test/budget-resolver.test.mjsindex 7e8e583..68ea659 100644--- a/tools/loop-context/test/budget-resolver.test.mjs+++ b/tools/loop-context/test/budget-resolver.test.mjs@@ -3,6 +3,7 @@ import assert from 'node:assert/strict';import {resolveCostCli,resolveTokenBudgetFromPattern,+ resolveDailyBudgetFromPattern,} from '../dist/budget-resolver.js';test('resolveCostCli finds the monorepo sibling loop-cost CLI', async () => {@@ -36,3 +37,22 @@ test('resolveTokenBudgetFromPattern rejects an invalid scenario before spawning/Invalid --budget-scenario/,);});++test('resolveDailyBudgetFromPattern returns loop-cost\'s suggested daily cap', async () => {+ const cap = await resolveDailyBudgetFromPattern({ pattern: 'ci-sweeper', level: 'L2' });+ assert.equal(typeof cap, 'number');+ assert.ok(cap > 0);+});++test('resolveDailyBudgetFromPattern is at least the per-run realistic estimate', async () => {+ const perRun = await resolveTokenBudgetFromPattern({ pattern: 'ci-sweeper', level: 'L2' });+ const dailyCap = await resolveDailyBudgetFromPattern({ pattern: 'ci-sweeper', level: 'L2' });+ assert.ok(dailyCap >= perRun, 'a daily cap should cover at least one run');+});++test('resolveDailyBudgetFromPattern rejects an unknown pattern with loop-cost\'s own message', async () => {+ await assert.rejects(+ () => resolveDailyBudgetFromPattern({ pattern: 'not-a-pattern' }),+ /Unknown pattern: not-a-pattern/,+ );+});diff --git a/tools/loop-context/test/cli.test.mjs b/tools/loop-context/test/cli.test.mjsindex 5f048df..f2dcb4b 100644--- a/tools/loop-context/test/cli.test.mjs+++ b/tools/loop-context/test/cli.test.mjs@@ -3,8 +3,17 @@ import assert from 'node:assert/strict';import { spawnSync } from 'node:child_process';import { fileURLToPath } from 'node:url';import path from 'node:path';+import { mkdtemp, readFile, writeFile } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import { resolveDailyBudgetFromPattern } from '../dist/budget-resolver.js';-const cli = path.join(path.dirname(fileURLToPath(import.meta.url)), '../dist/cli.js');+const testDir = path.dirname(fileURLToPath(import.meta.url));+const cli = path.join(testDir, '../dist/cli.js');+const onExceedCaptureScript = path.join(testDir, 'fixtures/on-exceed-capture.mjs');++async function freshDir() {+ return mkdtemp(path.join(tmpdir(), 'loop-context-cli-daily-'));+}const stagnationLedger = JSON.stringify({goal: 'x',@@ -83,3 +92,65 @@ test('cli --budget-from-pattern surfaces loop-cost\'s unknown-pattern error', ()assert.equal(r.status, 1);assert.match(r.stderr, /Unknown pattern: not-a-pattern/);});++test('cli --daily-budget-from-pattern escalates once the daily cap is reached', async () => {+ const dir = await freshDir();+ const dailyCap = await resolveDailyBudgetFromPattern({ pattern: 'ci-sweeper', level: 'L2' });+ // Pre-seed today's spend right at the cap so this run's single-token delta tips it over.+ await writeFile(+ path.join(dir, 'daily-spend.ci-sweeper.json'),+ JSON.stringify({ date: new Date().toISOString().slice(0, 10), tokensUsedToday: dailyCap }),+ );++ const r = runCli(+ [+ '--check', '--daily-budget-from-pattern', 'ci-sweeper', '--budget-level', 'L2',+ '--daily-state-dir', dir, '--json',+ ],+ cheapLedger,+ );+ assert.equal(r.status, 2);+ const decision = JSON.parse(r.stdout);+ assert.equal(decision.trigger, 'daily-budget');+});++test('cli --daily-budget-from-pattern does not override an existing per-run trigger', async () => {+ const dir = await freshDir();+ const dailyCap = await resolveDailyBudgetFromPattern({ pattern: 'ci-sweeper', level: 'L2' });+ await writeFile(+ path.join(dir, 'daily-spend.ci-sweeper.json'),+ JSON.stringify({ date: new Date().toISOString().slice(0, 10), tokensUsedToday: dailyCap * 10 }),+ );++ const r = runCli([+ '--check', '--daily-budget-from-pattern', 'ci-sweeper', '--budget-level', 'L2',+ '--daily-state-dir', dir, '--json',+ ]);+ assert.equal(r.status, 2);+ const decision = JSON.parse(r.stdout);+ assert.equal(decision.trigger, 'stagnation');+});++test('cli --on-exceed pipes the escalation decision to the script as JSON', async () => {+ const dir = await freshDir();+ const outFile = path.join(dir, 'captured.json');++ const r = runCli(['--check', '--on-exceed', `node ${onExceedCaptureScript} ${outFile}`, '--json']);+ assert.equal(r.status, 2);++ const captured = JSON.parse(await readFile(outFile, 'utf8'));+ assert.equal(captured.trigger, 'stagnation');+ assert.equal(captured.escalate, true);+});++test('cli --on-exceed is not invoked when the run continues', async () => {+ const dir = await freshDir();+ const outFile = path.join(dir, 'should-not-exist.json');++ const r = runCli(+ ['--check', '--on-exceed', `node ${onExceedCaptureScript} ${outFile}`, '--json'],+ cheapLedger,+ );+ assert.equal(r.status, 0);+ await assert.rejects(() => readFile(outFile, 'utf8'));+});diff --git a/tools/loop-context/test/daily-spend.test.mjs b/tools/loop-context/test/daily-spend.test.mjsnew file mode 100644index 0000000..cefd66d--- /dev/null+++ b/tools/loop-context/test/daily-spend.test.mjs@@ -0,0 +1,51 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { mkdtemp, readFile, writeFile } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import path from 'node:path';+import { recordDailySpend, todayUTC } from '../dist/daily-spend.js';++async function freshDir() {+ return mkdtemp(path.join(tmpdir(), 'loop-context-daily-spend-'));+}++test('recordDailySpend starts a fresh total when no state file exists', async () => {+ const dir = await freshDir();+ const state = await recordDailySpend(dir, 'ci-sweeper', 1200);+ assert.equal(state.date, todayUTC());+ assert.equal(state.tokensUsedToday, 1200);+});++test('recordDailySpend accumulates across repeated calls on the same day', async () => {+ const dir = await freshDir();+ await recordDailySpend(dir, 'ci-sweeper', 1000);+ await recordDailySpend(dir, 'ci-sweeper', 500);+ const state = await recordDailySpend(dir, 'ci-sweeper', 250);+ assert.equal(state.tokensUsedToday, 1750);+});++test('recordDailySpend tracks separate patterns independently', async () => {+ const dir = await freshDir();+ await recordDailySpend(dir, 'ci-sweeper', 1000);+ const other = await recordDailySpend(dir, 'dependency-sweeper', 300);+ assert.equal(other.tokensUsedToday, 300);+});++test('recordDailySpend rolls over a stale date instead of carrying its total forward', async () => {+ const dir = await freshDir();+ await writeFile(+ path.join(dir, 'daily-spend.ci-sweeper.json'),+ JSON.stringify({ date: '2000-01-01', tokensUsedToday: 999999 }),+ );+ const state = await recordDailySpend(dir, 'ci-sweeper', 400);+ assert.equal(state.date, todayUTC());+ assert.equal(state.tokensUsedToday, 400);+});++test('recordDailySpend persists the state to disk', async () => {+ const dir = await freshDir();+ await recordDailySpend(dir, 'ci-sweeper', 700);+ const raw = await readFile(path.join(dir, 'daily-spend.ci-sweeper.json'), 'utf8');+ const parsed = JSON.parse(raw);+ assert.equal(parsed.tokensUsedToday, 700);+});diff --git a/tools/loop-context/test/fixtures/on-exceed-capture.mjs b/tools/loop-context/test/fixtures/on-exceed-capture.mjsnew file mode 100644index 0000000..a106301--- /dev/null+++ b/tools/loop-context/test/fixtures/on-exceed-capture.mjs@@ -0,0 +1,8 @@+import { writeFileSync } from 'node:fs';++let data = '';+process.stdin.setEncoding('utf8');+process.stdin.on('data', (chunk) => (data += chunk));+process.stdin.on('end', () => {+ writeFileSync(process.argv[2], data);+});