Skip to content

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.

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-guard
index 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 iteration
1. 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.md
index 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 ledger
Your 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.ts
index 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.js
index 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.js
index f1c8b70..03b0c54 100755
--- a/tools/loop-context/dist/cli.js
+++ b/tools/loop-context/dist/cli.js
@@ -1,7 +1,9 @@
#!/usr/bin/env node
import { 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 --check
loop-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.sh
Operations (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.ts
index 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.ts
new file mode 100644
index 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.js
new file mode 100644
index 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.json
index 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.json
index 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.ts
index 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: BudgetFromPatternInpu
throw 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.ts
index 41f2c29..51f2161 100644
--- a/tools/loop-context/src/cli.ts
+++ b/tools/loop-context/src/cli.ts
@@ -1,5 +1,6 @@
#!/usr/bin/env node
import { 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 --check
loop-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.sh
Operations (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.ts
index 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.ts
new file mode 100644
index 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.mjs
index 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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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);
+});