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): add tool + release wiring (closes #125 path)

Cobus Greyling61aa376e030e
diff --git a/.github/workflows/release-loop-context.yml b/.github/workflows/release-loop-context.yml
new file mode 100644
index 0000000..a259427
--- /dev/null
+++ b/.github/workflows/release-loop-context.yml
@@ -0,0 +1,47 @@
+name: Release loop-context
+
+on:
+ push:
+ tags:
+ - 'loop-context-v*'
+ workflow_dispatch:
+ inputs:
+ tag:
+ description: 'Tag to publish (e.g. loop-context-v1.0.0)'
+ required: true
+ type: string
+
+permissions:
+ contents: read
+ id-token: write
+
+jobs:
+ test-and-publish:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ ref: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/{0}', github.event.inputs.tag) || github.ref }}
+
+ - uses: actions/setup-node@v6
+ with:
+ node-version: '22'
+ registry-url: 'https://registry.npmjs.org'
+ cache: 'npm'
+ cache-dependency-path: tools/loop-context/package-lock.json
+
+ - name: Ensure npm supports trusted publishing (OIDC)
+ run: npm install -g npm@latest
+
+ - name: Install, build, test
+ working-directory: tools/loop-context
+ run: |
+ npm ci
+ npm run build
+ npm test
+
+ - name: Publish to npm
+ working-directory: tools/loop-context
+ run: npm publish --access public --provenance
+ env:
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index b1b965b..ff1a8f7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -31,6 +31,7 @@ build/
!tools/loop-cost/dist/
!tools/loop-init/dist/
!tools/mcp-server/dist/
+!tools/loop-context/dist/
!tools/goal-audit/dist/
*.egg-info/
diff --git a/README.md b/README.md
index 28d64a3..aa0bdbb 100644
--- a/README.md
+++ b/README.md
@@ -88,6 +88,7 @@ For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agent
| [loop-init](tools/loop-init/) | Scaffold starters + budget/run-log + constraints (v1.2) — `npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok` |
| [loop-cost](tools/loop-cost/) | Token spend estimator — `npx @cobusgreyling/loop-cost` |
| [loop-sync](tools/loop-sync/) | Drift detection between `STATE.md` and `LOOP.md` — `npx @cobusgreyling/loop-sync .` |
+| [loop-context](tools/loop-context/) | Stateful memory manager + circuit breaker for long runs — `npx @cobusgreyling/loop-context --check --ledger run.json` |
| [loop-mcp-server](tools/mcp-server/) | MCP runtime lookup for patterns, skills, state — `node tools/mcp-server/dist/index.js` (repo v1; npm pending) |
| [Goal Engineering](https://github.com/cobusgreyling/goal-engineering) | **Companion:** loops discover, goals finish — `/goal` + [stack cookbook](https://github.com/cobusgreyling/goal-engineering/blob/main/docs/stack-cookbook.md) (`npx @cobusgreyling/goal doctor .`) |
| [Stories](stories/) | Real wins and honest failures |
diff --git a/docs/RELEASE.md b/docs/RELEASE.md
index a09a10d..2ac578c 100644
--- a/docs/RELEASE.md
+++ b/docs/RELEASE.md
@@ -1,6 +1,6 @@
# Release playbook — npm packages
-This repo ships four public npm packages from `tools/`:
+This repo ships five public npm packages from `tools/`:
| Package | Directory | Release tag |
|---------|-----------|-------------|
@@ -8,6 +8,7 @@ This repo ships four public npm packages from `tools/`:
| `@cobusgreyling/loop-init` | `tools/loop-init` | `loop-init-v*` |
| `@cobusgreyling/loop-cost` | `tools/loop-cost` | `loop-cost-v*` |
| `@cobusgreyling/loop-sync` | `tools/loop-sync` | `loop-sync-v*` |
+| `@cobusgreyling/loop-context` | `tools/loop-context` | `loop-context-v*` |
## One-time setup (trusted publishing — recommended)
@@ -19,6 +20,7 @@ Link npm to GitHub, then for **each package** on [npmjs.com](https://www.npmjs.c
| `@cobusgreyling/loop-init` | `cobusgreyling/loop-engineering` | `release-loop-init.yml` |
| `@cobusgreyling/loop-cost` | `cobusgreyling/loop-engineering` | `release-loop-cost.yml` |
| `@cobusgreyling/loop-sync` | `cobusgreyling/loop-engineering` | `release-loop-sync.yml` |
+| `@cobusgreyling/loop-context` | `cobusgreyling/loop-engineering` | `release-loop-context.yml` |
Names must match **exactly** (case-sensitive). No `NPM_TOKEN` secret is required when trusted publishing is configured.
@@ -52,9 +54,13 @@ git push origin loop-cost-v1.0.0
# loop-sync (drift detection between STATE.md and LOOP.md)
git tag loop-sync-v1.0.0
git push origin loop-sync-v1.0.0
+
+# loop-context (stateful memory manager + circuit breaker)
+git tag loop-context-v1.0.0
+git push origin loop-context-v1.0.0
```
-Workflows: `.github/workflows/release-loop-audit.yml`, `.github/workflows/release-loop-init.yml`, `.github/workflows/release-loop-cost.yml`, `.github/workflows/release-loop-sync.yml`.
+Workflows: `.github/workflows/release-loop-audit.yml`, `.github/workflows/release-loop-init.yml`, `.github/workflows/release-loop-cost.yml`, `.github/workflows/release-loop-sync.yml`, `.github/workflows/release-loop-context.yml`.
## Verify after publish
@@ -63,6 +69,7 @@ npx @cobusgreyling/loop-audit --help
npx @cobusgreyling/loop-init --help
npx @cobusgreyling/loop-cost --help
npx @cobusgreyling/loop-sync --help
+npx @cobusgreyling/loop-context --help
mkdir /tmp/loop-init-test && cd /tmp/loop-init-test
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok --dry-run
diff --git a/package.json b/package.json
index 9fd7ccc..e66c7c1 100644
--- a/package.json
+++ b/package.json
@@ -9,9 +9,10 @@
"test:loop-init": "cd tools/loop-init && npm test",
"test:loop-cost": "cd tools/loop-cost && npm test",
"test:loop-sync": "cd tools/loop-sync && npm test",
+ "test:loop-context": "cd tools/loop-context && npm test",
"test:mcp-server": "cd tools/mcp-server && npm test",
- "test:tools": "npm run test:loop-audit && npm run test:loop-init && npm run test:loop-cost && npm run test:loop-sync && npm run test:mcp-server",
- "build:tools": "cd tools/loop-audit && npm run build && cd ../loop-init && npm run build && cd ../loop-cost && npm run build && cd ../loop-sync && npm run build && cd ../mcp-server && npm run build"
+ "test:tools": "npm run test:loop-audit && npm run test:loop-init && npm run test:loop-cost && npm run test:loop-sync && npm run test:loop-context && npm run test:mcp-server",
+ "build:tools": "cd tools/loop-audit && npm run build && cd ../loop-init && npm run build && cd ../loop-cost && npm run build && cd ../loop-sync && npm run build && cd ../loop-context && npm run build && cd ../mcp-server && npm run build"
},
"devDependencies": {
"ajv": "^8.17.1",
diff --git a/scripts/ci-validate-gates.sh b/scripts/ci-validate-gates.sh
index 70214cc..1255542 100755
--- a/scripts/ci-validate-gates.sh
+++ b/scripts/ci-validate-gates.sh
@@ -39,6 +39,11 @@ cd ../loop-sync
npm ci
npm test
+echo "Building and testing loop-context…"
+cd ../loop-context
+npm ci
+npm test
+
echo "Building and testing mcp-server…"
cd ../mcp-server
npm ci
diff --git a/tools/loop-context/README.md b/tools/loop-context/README.md
new file mode 100644
index 0000000..d5e8c14
--- /dev/null
+++ b/tools/loop-context/README.md
@@ -0,0 +1,130 @@
+# loop-context
+
+**Stateful memory manager for agent loops.** Keeps the context window clean and stops runaway loops before they burn tokens.
+
+Long-running agent loops fail in two classic ways the [loop-engineering docs](../../docs/) warn about:
+
+- **Context overflow & rot** — conversation history and error logs grow until the model loses the original goal or drowns in stale stack traces.
+- **Stagnant / no-progress loops** — the agent retries the same failing action forever, quietly blowing the token budget.
+
+`loop-context` sits between the agent and its durable memory (`STATE.md`, run logs) and, before each iteration, does three things:
+
+1. **Summarize** what has been tried and what failed.
+2. **Prune** verbose stack traces, collapse repeated errors, and drop stale attempts outside a recent window.
+3. **Inject** only the essentials into the next prompt.
+
+A **circuit breaker** watches iteration count, token spend, stagnation (same error N× in a row), and no-progress (too many consecutive failures) — and escalates to a human instead of looping in vain.
+
+Everything is **deterministic and dependency-free**: no LLM call is needed to summarize or prune, so it is cheap enough to run on every iteration.
+
+## Install / run
+
+```bash
+npx @cobusgreyling/loop-context --help
+# or from this repo:
+cd tools/loop-context && npm install && npm test
+```
+
+## The ledger
+
+The tool reads a **run ledger** — a JSON record of the loop's goal and its attempts:
+
+```json
+{
+ "goal": "Get the failing migration test to pass",
+ "attempts": [
+ { "iteration": 1, "action": "run migration", "outcome": "failure",
+ "error": "Error: connect ECONNREFUSED 127.0.0.1:5432", "tokensUsed": 1500 },
+ { "iteration": 2, "action": "run migration again", "outcome": "failure",
+ "error": "Error: connect ECONNREFUSED 127.0.0.1:5432", "tokensUsed": 1400 }
+ ]
+}
+```
+
+`outcome` is `success | failure | noop`. `error` and `tokensUsed` are optional.
+
+## Usage
+
+```bash
+# Circuit breaker — exit 0 = continue, 2 = escalate (wire into a loop's control flow)
+loop-context --check --ledger run.json
+
+# Compact context block for the next prompt
+loop-context --inject --ledger run.json
+
+# Factual rollup of the run
+loop-context --summary --ledger run.json --json
+
+# Pruned ledger (recent window, trimmed traces, collapsed repeats)
+loop-context --prune --ledger run.json
+
+# Pipe on stdin
+cat run.json | loop-context --check
+```
+
+### Options
+
+| Flag | Default | Meaning |
+|------|---------|---------|
+| `--max-iterations <n>` | 10 | Hard iteration cap |
+| `--stagnation <n>` | 3 | Escalate when the same error repeats N× in a row |
+| `--no-progress <n>` | 5 | Escalate after N consecutive failures |
+| `--token-budget <n>` | none | Escalate when cumulative tokens reach the cap |
+| `--window <n>` | 5 | Attempts kept when pruning |
+| `--max-trace-lines <n>` | 8 | Stack-trace lines kept when pruning |
+
+Exit codes: `0` continue · `2` escalate · `1` error.
+
+## Populating the ledger
+
+Your loop control script appends one object per iteration to `run.json` (or pipes the same shape on stdin):
+
+```bash
+# after each agent iteration — append attempt, then gate the next one
+node -e "
+const fs = require('fs');
+const ledger = JSON.parse(fs.readFileSync('run.json', 'utf8'));
+ledger.attempts.push({
+ iteration: ledger.attempts.length + 1,
+ action: 'run migration tests',
+ outcome: 'failure',
+ error: process.argv[1],
+ tokensUsed: Number(process.argv[2] || 0),
+});
+fs.writeFileSync('run.json', JSON.stringify(ledger, null, 2));
+" \"\$ERROR_MSG\" \"\$TOKENS\"
+loop-context --check --ledger run.json || { loop-context --inject --ledger run.json; exit 2; }
+```
+
+Initialize once at loop start: `{ \"goal\": \"Get CI green on main\", \"attempts\": [] }`.
+
+## In a loop
+
+```bash
+# inside your loop's control script, before each iteration:
+if ! loop-context --check --ledger run.json; then
+ loop-context --inject --ledger run.json > escalation.md # hand a clean summary to the human
+ exit 0 # stop instead of retrying
+fi
+```
+
+## Library API
+
+```ts
+import {
+ checkCircuitBreaker,
+ pruneLedger,
+ summarizeAttempts,
+ buildContextInjection,
+} from '@cobusgreyling/loop-context';
+
+const decision = checkCircuitBreaker(ledger);
+if (decision.escalate) escalateToHuman(decision.reason);
+else runNextIteration(buildContextInjection(ledger));
+```
+
+## Where it fits
+
+This is the **Memory / State** primitive of loop engineering made dynamic: `STATE.md` stores state statically; `loop-context` manages it across iterations. See [docs/primitives.md](../../docs/primitives.md) and the [operating & safety](../../docs/) guides.
+
+MIT · part of [loop-engineering](https://github.com/cobusgreyling/loop-engineering) by Cobus Greyling.
diff --git a/tools/loop-context/dist/cli.d.ts b/tools/loop-context/dist/cli.d.ts
new file mode 100644
index 0000000..b798801
--- /dev/null
+++ b/tools/loop-context/dist/cli.d.ts
@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};
diff --git a/tools/loop-context/dist/cli.js b/tools/loop-context/dist/cli.js
new file mode 100644
index 0000000..e04cf63
--- /dev/null
+++ b/tools/loop-context/dist/cli.js
@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { buildContextInjection, checkCircuitBreaker, pruneLedger, summarizeAttempts, DEFAULT_BREAKER, DEFAULT_PRUNE, } from './context-manager.js';
+function parseArgs(argv) {
+ const breaker = { ...DEFAULT_BREAKER };
+ const prune = { ...DEFAULT_PRUNE };
+ let op = 'status';
+ let ledger;
+ let json = false;
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i];
+ if (a === '--help' || a === '-h')
+ return { help: true, op, json, breaker, prune };
+ else if (a === '--ledger' || a === '-f')
+ ledger = argv[++i];
+ else if (a === '--check')
+ op = 'check';
+ else if (a === '--prune')
+ op = 'prune';
+ else if (a === '--inject')
+ op = 'inject';
+ else if (a === '--summary')
+ op = 'summary';
+ else if (a === '--status')
+ op = 'status';
+ else if (a === '--json')
+ json = true;
+ else if (a === '--max-iterations')
+ breaker.maxIterations = Number(argv[++i]);
+ else if (a === '--stagnation')
+ breaker.stagnationThreshold = Number(argv[++i]);
+ else if (a === '--no-progress')
+ breaker.noProgressThreshold = Number(argv[++i]);
+ else if (a === '--token-budget')
+ breaker.tokenBudget = Number(argv[++i]);
+ else if (a === '--window')
+ prune.window = Number(argv[++i]);
+ else if (a === '--max-trace-lines')
+ prune.maxTraceLines = Number(argv[++i]);
+ }
+ return { help: false, op, ledger, json, breaker, prune };
+}
+async function readLedger(pathArg) {
+ const raw = pathArg
+ ? await readFile(pathArg, 'utf8')
+ : await readStdin();
+ if (!raw.trim()) {
+ throw new Error('No ledger provided. Pass --ledger <file.json> or pipe JSON on stdin.');
+ }
+ const parsed = JSON.parse(raw);
+ if (typeof parsed.goal !== 'string' || !Array.isArray(parsed.attempts)) {
+ throw new Error('Invalid ledger: expected { goal: string, attempts: Attempt[] }.');
+ }
+ return parsed;
+}
+function readStdin() {
+ return new Promise((resolve, reject) => {
+ let data = '';
+ process.stdin.setEncoding('utf8');
+ process.stdin.on('data', (c) => (data += c));
+ process.stdin.on('end', () => resolve(data));
+ process.stdin.on('error', reject);
+ });
+}
+const HELP = `loop-context — stateful memory manager for agent loops
+
+Keeps a loop's context window clean and stops runaway loops. Reads a run ledger
+(JSON) and summarizes, prunes, injects, or applies the circuit breaker.
+
+Usage:
+ loop-context [operation] [--ledger <file.json>] [options]
+ cat ledger.json | loop-context --check
+
+Operations (default: --status):
+ --check Run the circuit breaker. Exit 0 = continue, 2 = escalate.
+ --prune Emit a pruned ledger (recent window, trimmed traces, collapsed).
+ --inject Emit the compact context block for the next prompt.
+ --summary Emit a factual rollup of the run.
+ --status Human-readable overview (summary + breaker decision).
+
+Options:
+ -f, --ledger <file> Ledger JSON file (default: stdin)
+ --json Machine-readable output where applicable
+ --max-iterations <n> Iteration cap (default: ${DEFAULT_BREAKER.maxIterations})
+ --stagnation <n> Same-error repeat limit (default: ${DEFAULT_BREAKER.stagnationThreshold})
+ --no-progress <n> Consecutive-failure limit (default: ${DEFAULT_BREAKER.noProgressThreshold})
+ --token-budget <n> Total token cap (default: none)
+ --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
+
+Ledger shape:
+ { "goal": "...", "attempts": [ { "iteration": 1, "action": "...",
+ "outcome": "failure", "error": "...", "tokensUsed": 1200 } ] }
+
+Exit codes: 0 continue · 2 escalate · 1 error
+`;
+async function main() {
+ const args = parseArgs(process.argv.slice(2));
+ if (args.help) {
+ console.log(HELP);
+ return;
+ }
+ const ledger = await readLedger(args.ledger);
+ switch (args.op) {
+ case 'check': {
+ const decision = checkCircuitBreaker(ledger, args.breaker);
+ 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;
+ return;
+ }
+ case 'prune':
+ console.log(JSON.stringify(pruneLedger(ledger, args.prune), null, 2));
+ return;
+ case 'summary': {
+ const summary = summarizeAttempts(ledger);
+ if (args.json)
+ console.log(JSON.stringify(summary, null, 2));
+ else
+ console.log(formatSummary(summary));
+ return;
+ }
+ case 'inject':
+ console.log(buildContextInjection(ledger, args.breaker, args.prune));
+ return;
+ case 'status':
+ default: {
+ const summary = summarizeAttempts(ledger);
+ const decision = checkCircuitBreaker(ledger, args.breaker);
+ console.log(formatSummary(summary));
+ console.log('');
+ console.log(`Circuit breaker: ${decision.escalate ? 'ESCALATE' : 'CONTINUE'} [${decision.trigger}]`);
+ console.log(` ${decision.reason}`);
+ process.exitCode = decision.escalate ? 2 : 0;
+ return;
+ }
+ }
+}
+function formatSummary(s) {
+ const lines = [];
+ lines.push(`Attempts: ${s.totalAttempts} (${s.successes} ok · ${s.failures} failed · ${s.noops} no-op)`);
+ if (s.tokensUsed)
+ lines.push(`Tokens used: ${s.tokensUsed}`);
+ if (s.distinctErrors.length) {
+ lines.push('Distinct errors (most frequent first):');
+ for (const g of s.distinctErrors)
+ lines.push(` (${g.count}×) ${g.sample}`);
+ }
+ if (s.actionsTried.length) {
+ lines.push('Actions tried:');
+ for (const a of s.actionsTried)
+ lines.push(` - ${a}`);
+ }
+ return lines.join('\n');
+}
+main().catch((err) => {
+ const msg = err instanceof Error ? err.message : String(err);
+ console.error('loop-context failed:', msg);
+ process.exit(1);
+});
diff --git a/tools/loop-context/dist/context-manager.d.ts b/tools/loop-context/dist/context-manager.d.ts
new file mode 100644
index 0000000..19f5e5a
--- /dev/null
+++ b/tools/loop-context/dist/context-manager.d.ts
@@ -0,0 +1,119 @@
+/**
+ * Stateful Memory Manager — Context Manager, Pruner, and Circuit Breaker.
+ *
+ * Sits between an agent loop and its durable memory (STATE.md, run logs).
+ * Before each new iteration it can: summarize what has been tried, prune stale
+ * or verbose context (long stack traces, repeated errors), and inject only the
+ * essentials into the next prompt — keeping the context window clean and focused.
+ *
+ * The circuit breaker detects the two classic loop failures the docs warn about:
+ * - stagnant runs (retrying the same error N times)
+ * - no-progress loops (repeated failures with no success)
+ * and, together with iteration and token caps, escalates to a human instead of
+ * burning tokens in a hopeless loop.
+ *
+ * All logic here is deterministic and dependency-free — no LLM call is required
+ * to summarize or prune, so it is cheap to run on every iteration and easy to test.
+ */
+export type Outcome = 'success' | 'failure' | 'noop';
+export interface Attempt {
+ /** 1-based iteration number within the run. */
+ iteration: number;
+ /** ISO timestamp of the attempt (optional). */
+ timestamp?: string;
+ /** What the agent tried this iteration (a short description). */
+ action: string;
+ /** Result of the attempt. */
+ outcome: Outcome;
+ /** Raw error message or stack trace, if the attempt failed. */
+ error?: string;
+ /** Tokens spent on this iteration, if tracked. */
+ tokensUsed?: number;
+ /** Set by the pruner when consecutive identical failures are collapsed. */
+ repeated?: number;
+}
+export interface Ledger {
+ /** The loop's original goal — the anchor the agent must not lose. */
+ goal: string;
+ /** ISO timestamp when the run started (optional). */
+ startedAt?: string;
+ /** Ordered list of attempts, oldest first. */
+ attempts: Attempt[];
+}
+export interface CircuitBreakerConfig {
+ /** Hard cap on total iterations before escalating. */
+ maxIterations: number;
+ /** Escalate when the same error signature repeats this many times in a row. */
+ stagnationThreshold: number;
+ /** Escalate after this many consecutive failures with no success in between. */
+ noProgressThreshold: number;
+ /** Optional hard cap on cumulative tokens across the run. */
+ tokenBudget?: number;
+}
+export interface PruneConfig {
+ /** Max lines to keep from any single stack trace. */
+ maxTraceLines: number;
+ /** Number of most-recent attempts to retain in the pruned ledger. */
+ window: number;
+}
+export declare const DEFAULT_BREAKER: CircuitBreakerConfig;
+export declare const DEFAULT_PRUNE: PruneConfig;
+/**
+ * Reduce a raw error / stack trace to a stable signature so that "the same
+ * error" can be recognized across iterations even when volatile details
+ * (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 interface BreakerDecision {
+ /** Whether the loop is cleared to run another iteration. */
+ shouldContinue: boolean;
+ /** Whether the loop must hand off to a human. */
+ escalate: boolean;
+ /** Which condition fired (or 'ok'). */
+ trigger: BreakerTrigger;
+ /** Human-readable explanation. */
+ reason: string;
+ iterations: number;
+ tokensUsed: number;
+}
+/**
+ * Decide whether the loop may continue. Checks the most specific and cheapest-
+ * to-fix conditions first (stagnation, then no-progress) before the absolute
+ * caps (token budget, iteration count), so the reported reason is the most
+ * actionable one when several conditions hold.
+ */
+export declare function checkCircuitBreaker(ledger: Ledger, config?: CircuitBreakerConfig): BreakerDecision;
+/** Truncate a stack trace to its most useful head, noting how much was dropped. */
+export declare function pruneStackTrace(trace: string, maxLines: number): string;
+/**
+ * Produce a lean ledger for injection: keep only the most-recent `window`
+ * attempts, prune verbose traces, and collapse consecutive identical failures
+ * into a single entry with a repeat count. The full ledger is untouched — this
+ * returns a new object.
+ */
+export declare function pruneLedger(ledger: Ledger, config?: PruneConfig): Ledger;
+export interface ErrorGroup {
+ signature: string;
+ count: number;
+ sample: string;
+}
+export interface AttemptSummary {
+ totalAttempts: number;
+ successes: number;
+ failures: number;
+ noops: number;
+ tokensUsed: number;
+ /** Distinct error signatures, most frequent first. */
+ distinctErrors: ErrorGroup[];
+ /** Unique actions the agent has already tried. */
+ actionsTried: string[];
+}
+/** Deterministic factual rollup of the whole run — no LLM required. */
+export declare function summarizeAttempts(ledger: Ledger): AttemptSummary;
+/**
+ * Build the compact context block to prepend to the next prompt. Contains only
+ * what the agent needs to make progress: the goal, what has already been tried
+ * (so it does not repeat itself), the last pruned error, and the breaker status.
+ */
+export declare function buildContextInjection(ledger: Ledger, breaker?: CircuitBreakerConfig, prune?: PruneConfig): string;
diff --git a/tools/loop-context/dist/context-manager.js b/tools/loop-context/dist/context-manager.js
new file mode 100644
index 0000000..a229f70
--- /dev/null
+++ b/tools/loop-context/dist/context-manager.js
@@ -0,0 +1,248 @@
+/**
+ * Stateful Memory Manager — Context Manager, Pruner, and Circuit Breaker.
+ *
+ * Sits between an agent loop and its durable memory (STATE.md, run logs).
+ * Before each new iteration it can: summarize what has been tried, prune stale
+ * or verbose context (long stack traces, repeated errors), and inject only the
+ * essentials into the next prompt — keeping the context window clean and focused.
+ *
+ * The circuit breaker detects the two classic loop failures the docs warn about:
+ * - stagnant runs (retrying the same error N times)
+ * - no-progress loops (repeated failures with no success)
+ * and, together with iteration and token caps, escalates to a human instead of
+ * burning tokens in a hopeless loop.
+ *
+ * All logic here is deterministic and dependency-free — no LLM call is required
+ * to summarize or prune, so it is cheap to run on every iteration and easy to test.
+ */
+export const DEFAULT_BREAKER = {
+ maxIterations: 10,
+ stagnationThreshold: 3,
+ noProgressThreshold: 5,
+};
+export const DEFAULT_PRUNE = {
+ maxTraceLines: 8,
+ window: 5,
+};
+// ── Error normalization ────────────────────────────────────────────
+/**
+ * Reduce a raw error / stack trace to a stable signature so that "the same
+ * error" can be recognized across iterations even when volatile details
+ * (line numbers, addresses, timestamps, ports, temp paths) differ.
+ */
+export function errorSignature(error) {
+ const firstLine = error.split('\n').find((l) => l.trim().length > 0) ?? '';
+ return firstLine
+ .trim()
+ .replace(/\b\d{4}-\d{2}-\d{2}[T ][\d:.]+Z?\b/g, '<ts>') // ISO timestamps
+ .replace(/0x[0-9a-fA-F]+/g, '<addr>') // hex addresses
+ .replace(/[A-Za-z]:[\\/][^\s:]+|(?:[\\/][^\s:/\\]+)+/g, (p) => {
+ const parts = p.split(/[\\/]/);
+ return parts[parts.length - 1] || p; // collapse paths to basename
+ })
+ .replace(/:\d+(:\d+)?/g, '') // line:col suffixes
+ .replace(/\b\d+\b/g, '#') // any remaining numbers (ports, ids, counts)
+ .replace(/\s+/g, ' ')
+ .trim();
+}
+function totalTokens(ledger) {
+ return ledger.attempts.reduce((sum, a) => sum + (a.tokensUsed ?? 0), 0);
+}
+/** Length of the trailing run of failures (since the last non-failure). */
+function trailingFailureRun(attempts) {
+ const run = [];
+ for (let i = attempts.length - 1; i >= 0; i--) {
+ if (attempts[i].outcome !== 'failure')
+ break;
+ run.unshift(attempts[i]);
+ }
+ return run;
+}
+/**
+ * Decide whether the loop may continue. Checks the most specific and cheapest-
+ * to-fix conditions first (stagnation, then no-progress) before the absolute
+ * caps (token budget, iteration count), so the reported reason is the most
+ * actionable one when several conditions hold.
+ */
+export function checkCircuitBreaker(ledger, config = DEFAULT_BREAKER) {
+ const iterations = ledger.attempts.length;
+ const tokensUsed = totalTokens(ledger);
+ const base = { iterations, tokensUsed };
+ const failRun = trailingFailureRun(ledger.attempts);
+ // Stagnation: the same error signature repeated at the tail.
+ if (failRun.length >= config.stagnationThreshold) {
+ const lastSig = errorSignature(failRun[failRun.length - 1].error ?? '');
+ let same = 0;
+ for (let i = failRun.length - 1; i >= 0; i--) {
+ if (errorSignature(failRun[i].error ?? '') === lastSig)
+ same++;
+ else
+ break;
+ }
+ if (same >= config.stagnationThreshold) {
+ return {
+ ...base,
+ shouldContinue: false,
+ escalate: true,
+ trigger: 'stagnation',
+ reason: `Same error repeated ${same}× in a row (threshold ${config.stagnationThreshold}): "${lastSig}". Escalating instead of retrying.`,
+ };
+ }
+ }
+ // No-progress: many consecutive failures without a success.
+ if (failRun.length >= config.noProgressThreshold) {
+ return {
+ ...base,
+ shouldContinue: false,
+ escalate: true,
+ trigger: 'no-progress',
+ reason: `${failRun.length} consecutive failures with no progress (threshold ${config.noProgressThreshold}). Escalating.`,
+ };
+ }
+ // Token budget: absolute spend cap.
+ if (config.tokenBudget !== undefined && tokensUsed >= config.tokenBudget) {
+ return {
+ ...base,
+ shouldContinue: false,
+ escalate: true,
+ trigger: 'token-budget',
+ reason: `Token budget reached (${tokensUsed} ≥ ${config.tokenBudget}). Escalating to avoid cost blowup.`,
+ };
+ }
+ // Iteration cap: absolute count.
+ if (iterations >= config.maxIterations) {
+ return {
+ ...base,
+ shouldContinue: false,
+ escalate: true,
+ trigger: 'max-iterations',
+ reason: `Iteration cap reached (${iterations} ≥ ${config.maxIterations}). Escalating.`,
+ };
+ }
+ return {
+ ...base,
+ shouldContinue: true,
+ escalate: false,
+ trigger: 'ok',
+ reason: 'Within limits — cleared to continue.',
+ };
+}
+// ── Pruning ────────────────────────────────────────────────────────
+/** Truncate a stack trace to its most useful head, noting how much was dropped. */
+export function pruneStackTrace(trace, maxLines) {
+ const lines = trace.split('\n');
+ if (lines.length <= maxLines)
+ return trace.trim();
+ const kept = lines.slice(0, maxLines).join('\n').trimEnd();
+ const omitted = lines.length - maxLines;
+ return `${kept}\n … (${omitted} more line${omitted === 1 ? '' : 's'} pruned)`;
+}
+/**
+ * Produce a lean ledger for injection: keep only the most-recent `window`
+ * attempts, prune verbose traces, and collapse consecutive identical failures
+ * into a single entry with a repeat count. The full ledger is untouched — this
+ * returns a new object.
+ */
+export function pruneLedger(ledger, config = DEFAULT_PRUNE) {
+ const recent = ledger.attempts.slice(-config.window);
+ const collapsed = [];
+ for (const attempt of recent) {
+ const pruned = {
+ ...attempt,
+ ...(attempt.error !== undefined
+ ? { error: pruneStackTrace(attempt.error, config.maxTraceLines) }
+ : {}),
+ };
+ const prev = collapsed[collapsed.length - 1];
+ const sameFailure = prev !== undefined &&
+ prev.outcome === 'failure' &&
+ pruned.outcome === 'failure' &&
+ errorSignature(prev.error ?? '') === errorSignature(pruned.error ?? '');
+ if (sameFailure) {
+ prev.repeated = (prev.repeated ?? 1) + 1;
+ prev.iteration = pruned.iteration; // advance to the latest iteration
+ }
+ else {
+ collapsed.push(pruned);
+ }
+ }
+ return { goal: ledger.goal, startedAt: ledger.startedAt, attempts: collapsed };
+}
+/** Deterministic factual rollup of the whole run — no LLM required. */
+export function summarizeAttempts(ledger) {
+ const groups = new Map();
+ const actions = new Set();
+ let successes = 0;
+ let failures = 0;
+ let noops = 0;
+ for (const a of ledger.attempts) {
+ actions.add(a.action);
+ if (a.outcome === 'success')
+ successes++;
+ else if (a.outcome === 'noop')
+ noops++;
+ else {
+ failures++;
+ if (a.error) {
+ const sig = errorSignature(a.error);
+ const existing = groups.get(sig);
+ if (existing)
+ existing.count++;
+ else
+ groups.set(sig, { signature: sig, count: 1, sample: a.error.split('\n')[0].trim() });
+ }
+ }
+ }
+ return {
+ totalAttempts: ledger.attempts.length,
+ successes,
+ failures,
+ noops,
+ tokensUsed: totalTokens(ledger),
+ distinctErrors: [...groups.values()].sort((a, b) => b.count - a.count),
+ actionsTried: [...actions],
+ };
+}
+// ── Injection ──────────────────────────────────────────────────────
+/**
+ * Build the compact context block to prepend to the next prompt. Contains only
+ * what the agent needs to make progress: the goal, what has already been tried
+ * (so it does not repeat itself), the last pruned error, and the breaker status.
+ */
+export function buildContextInjection(ledger, breaker = DEFAULT_BREAKER, prune = DEFAULT_PRUNE) {
+ const summary = summarizeAttempts(ledger);
+ const decision = checkCircuitBreaker(ledger, breaker);
+ const pruned = pruneLedger(ledger, prune);
+ const lines = [];
+ lines.push('## Loop Context (managed)');
+ lines.push('');
+ lines.push(`**Goal:** ${ledger.goal}`);
+ lines.push(`**Progress:** iteration ${summary.totalAttempts} · ${summary.successes} ok · ${summary.failures} failed` +
+ (summary.tokensUsed ? ` · ${summary.tokensUsed} tokens` : ''));
+ lines.push('');
+ if (summary.actionsTried.length > 0) {
+ lines.push('**Already tried (do NOT repeat):**');
+ for (const action of summary.actionsTried)
+ lines.push(`- ${action}`);
+ lines.push('');
+ }
+ if (summary.distinctErrors.length > 0) {
+ lines.push('**Failure patterns:**');
+ for (const g of summary.distinctErrors) {
+ lines.push(`- (${g.count}×) ${g.sample}`);
+ }
+ lines.push('');
+ }
+ const lastFail = [...pruned.attempts].reverse().find((a) => a.outcome === 'failure');
+ if (lastFail?.error) {
+ lines.push('**Most recent error (pruned):**');
+ lines.push('```');
+ lines.push(lastFail.error);
+ lines.push('```');
+ lines.push('');
+ }
+ lines.push(decision.escalate
+ ? `> STOP — circuit breaker tripped (${decision.trigger}). ${decision.reason}`
+ : `> Circuit breaker: OK (${decision.iterations}/${breaker.maxIterations} iterations used).`);
+ return lines.join('\n');
+}
diff --git a/tools/loop-context/package-lock.json b/tools/loop-context/package-lock.json
new file mode 100644
index 0000000..b6db3e1
--- /dev/null
+++ b/tools/loop-context/package-lock.json
@@ -0,0 +1,54 @@
+{
+ "name": "@cobusgreyling/loop-context",
+ "version": "1.0.0",
+ "lockfileVersion": 3,
+ "requires": true,
+ "packages": {
+ "": {
+ "name": "@cobusgreyling/loop-context",
+ "version": "1.0.0",
+ "license": "MIT",
+ "bin": {
+ "loop-context": "dist/cli.js"
+ },
+ "devDependencies": {
+ "@types/node": "^20.0.0",
+ "typescript": "^5.0.0"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@types/node": {
+ "version": "20.19.43",
+ "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.43.tgz",
+ "integrity": "sha512-6oYBAi5ikg4Pl+kGsoYtawUMBT2zZMCvPNF7pVLnHZfd1zf38DRiWn/gT01RYCdUqkv7Fhr+C9ot4/tb+2sVvA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "undici-types": "~6.21.0"
+ }
+ },
+ "node_modules/typescript": {
+ "version": "5.9.3",
+ "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+ "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "bin": {
+ "tsc": "bin/tsc",
+ "tsserver": "bin/tsserver"
+ },
+ "engines": {
+ "node": ">=14.17"
+ }
+ },
+ "node_modules/undici-types": {
+ "version": "6.21.0",
+ "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
+ "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
+ "dev": true,
+ "license": "MIT"
+ }
+ }
+}
diff --git a/tools/loop-context/package.json b/tools/loop-context/package.json
new file mode 100644
index 0000000..03c9f73
--- /dev/null
+++ b/tools/loop-context/package.json
@@ -0,0 +1,55 @@
+{
+ "name": "@cobusgreyling/loop-context",
+ "version": "1.0.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",
+ "exports": {
+ ".": "./dist/context-manager.js"
+ },
+ "bin": {
+ "loop-context": "dist/cli.js"
+ },
+ "files": [
+ "dist",
+ "README.md"
+ ],
+ "scripts": {
+ "build": "tsc && chmod +x dist/cli.js",
+ "test": "npm run build && node --test test/context-manager.test.mjs",
+ "prepublishOnly": "npm test",
+ "start": "node dist/cli.js"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "keywords": [
+ "loop-engineering",
+ "ai-agents",
+ "coding-agents",
+ "context-management",
+ "circuit-breaker",
+ "memory",
+ "claude-code",
+ "grok",
+ "devtools"
+ ],
+ "author": "Cobus Greyling",
+ "license": "MIT",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/cobusgreyling/loop-engineering.git",
+ "directory": "tools/loop-context"
+ },
+ "homepage": "https://cobusgreyling.github.io/loop-engineering/",
+ "bugs": {
+ "url": "https://github.com/cobusgreyling/loop-engineering/issues"
+ },
+ "publishConfig": {
+ "access": "public"
+ },
+ "devDependencies": {
+ "@types/node": "^20.0.0",
+ "typescript": "^5.0.0"
+ }
+}
diff --git a/tools/loop-context/src/cli.ts b/tools/loop-context/src/cli.ts
new file mode 100644
index 0000000..d9dbc87
--- /dev/null
+++ b/tools/loop-context/src/cli.ts
@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import {
+ buildContextInjection,
+ checkCircuitBreaker,
+ pruneLedger,
+ summarizeAttempts,
+ DEFAULT_BREAKER,
+ DEFAULT_PRUNE,
+ type Ledger,
+ type CircuitBreakerConfig,
+ type PruneConfig,
+} from './context-manager.js';
+
+type Op = 'check' | 'prune' | 'inject' | 'summary' | 'status';
+
+interface Args {
+ help: boolean;
+ op: Op;
+ ledger?: string;
+ json: boolean;
+ breaker: CircuitBreakerConfig;
+ prune: PruneConfig;
+}
+
+function parseArgs(argv: string[]): Args {
+ const breaker: CircuitBreakerConfig = { ...DEFAULT_BREAKER };
+ const prune: PruneConfig = { ...DEFAULT_PRUNE };
+ let op: Op = 'status';
+ let ledger: string | undefined;
+ let json = false;
+
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i];
+ if (a === '--help' || a === '-h') return { help: true, op, json, breaker, prune };
+ else if (a === '--ledger' || a === '-f') ledger = argv[++i];
+ else if (a === '--check') op = 'check';
+ else if (a === '--prune') op = 'prune';
+ else if (a === '--inject') op = 'inject';
+ else if (a === '--summary') op = 'summary';
+ else if (a === '--status') op = 'status';
+ else if (a === '--json') json = true;
+ else if (a === '--max-iterations') breaker.maxIterations = Number(argv[++i]);
+ else if (a === '--stagnation') breaker.stagnationThreshold = Number(argv[++i]);
+ else if (a === '--no-progress') breaker.noProgressThreshold = Number(argv[++i]);
+ else if (a === '--token-budget') breaker.tokenBudget = Number(argv[++i]);
+ else if (a === '--window') prune.window = Number(argv[++i]);
+ else if (a === '--max-trace-lines') prune.maxTraceLines = Number(argv[++i]);
+ }
+
+ return { help: false, op, ledger, json, breaker, prune };
+}
+
+async function readLedger(pathArg?: string): Promise<Ledger> {
+ const raw = pathArg
+ ? await readFile(pathArg, 'utf8')
+ : await readStdin();
+ if (!raw.trim()) {
+ throw new Error('No ledger provided. Pass --ledger <file.json> or pipe JSON on stdin.');
+ }
+ const parsed = JSON.parse(raw) as Ledger;
+ if (typeof parsed.goal !== 'string' || !Array.isArray(parsed.attempts)) {
+ throw new Error('Invalid ledger: expected { goal: string, attempts: Attempt[] }.');
+ }
+ return parsed;
+}
+
+function readStdin(): Promise<string> {
+ return new Promise((resolve, reject) => {
+ let data = '';
+ process.stdin.setEncoding('utf8');
+ process.stdin.on('data', (c) => (data += c));
+ process.stdin.on('end', () => resolve(data));
+ process.stdin.on('error', reject);
+ });
+}
+
+const HELP = `loop-context — stateful memory manager for agent loops
+
+Keeps a loop's context window clean and stops runaway loops. Reads a run ledger
+(JSON) and summarizes, prunes, injects, or applies the circuit breaker.
+
+Usage:
+ loop-context [operation] [--ledger <file.json>] [options]
+ cat ledger.json | loop-context --check
+
+Operations (default: --status):
+ --check Run the circuit breaker. Exit 0 = continue, 2 = escalate.
+ --prune Emit a pruned ledger (recent window, trimmed traces, collapsed).
+ --inject Emit the compact context block for the next prompt.
+ --summary Emit a factual rollup of the run.
+ --status Human-readable overview (summary + breaker decision).
+
+Options:
+ -f, --ledger <file> Ledger JSON file (default: stdin)
+ --json Machine-readable output where applicable
+ --max-iterations <n> Iteration cap (default: ${DEFAULT_BREAKER.maxIterations})
+ --stagnation <n> Same-error repeat limit (default: ${DEFAULT_BREAKER.stagnationThreshold})
+ --no-progress <n> Consecutive-failure limit (default: ${DEFAULT_BREAKER.noProgressThreshold})
+ --token-budget <n> Total token cap (default: none)
+ --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
+
+Ledger shape:
+ { "goal": "...", "attempts": [ { "iteration": 1, "action": "...",
+ "outcome": "failure", "error": "...", "tokensUsed": 1200 } ] }
+
+Exit codes: 0 continue · 2 escalate · 1 error
+`;
+
+async function main() {
+ const args = parseArgs(process.argv.slice(2));
+ if (args.help) {
+ console.log(HELP);
+ return;
+ }
+
+ const ledger = await readLedger(args.ledger);
+
+ switch (args.op) {
+ case 'check': {
+ const decision = checkCircuitBreaker(ledger, args.breaker);
+ 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;
+ return;
+ }
+ case 'prune':
+ console.log(JSON.stringify(pruneLedger(ledger, args.prune), null, 2));
+ return;
+ case 'summary': {
+ const summary = summarizeAttempts(ledger);
+ if (args.json) console.log(JSON.stringify(summary, null, 2));
+ else console.log(formatSummary(summary));
+ return;
+ }
+ case 'inject':
+ console.log(buildContextInjection(ledger, args.breaker, args.prune));
+ return;
+ case 'status':
+ default: {
+ const summary = summarizeAttempts(ledger);
+ const decision = checkCircuitBreaker(ledger, args.breaker);
+ console.log(formatSummary(summary));
+ console.log('');
+ console.log(`Circuit breaker: ${decision.escalate ? 'ESCALATE' : 'CONTINUE'} [${decision.trigger}]`);
+ console.log(` ${decision.reason}`);
+ process.exitCode = decision.escalate ? 2 : 0;
+ return;
+ }
+ }
+}
+
+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)`);
+ if (s.tokensUsed) lines.push(`Tokens used: ${s.tokensUsed}`);
+ if (s.distinctErrors.length) {
+ lines.push('Distinct errors (most frequent first):');
+ for (const g of s.distinctErrors) lines.push(` (${g.count}×) ${g.sample}`);
+ }
+ if (s.actionsTried.length) {
+ lines.push('Actions tried:');
+ for (const a of s.actionsTried) lines.push(` - ${a}`);
+ }
+ return lines.join('\n');
+}
+
+main().catch((err: unknown) => {
+ const msg = err instanceof Error ? err.message : String(err);
+ console.error('loop-context failed:', msg);
+ process.exit(1);
+});
diff --git a/tools/loop-context/src/context-manager.ts b/tools/loop-context/src/context-manager.ts
new file mode 100644
index 0000000..376ac6e
--- /dev/null
+++ b/tools/loop-context/src/context-manager.ts
@@ -0,0 +1,369 @@
+/**
+ * Stateful Memory Manager — Context Manager, Pruner, and Circuit Breaker.
+ *
+ * Sits between an agent loop and its durable memory (STATE.md, run logs).
+ * Before each new iteration it can: summarize what has been tried, prune stale
+ * or verbose context (long stack traces, repeated errors), and inject only the
+ * essentials into the next prompt — keeping the context window clean and focused.
+ *
+ * The circuit breaker detects the two classic loop failures the docs warn about:
+ * - stagnant runs (retrying the same error N times)
+ * - no-progress loops (repeated failures with no success)
+ * and, together with iteration and token caps, escalates to a human instead of
+ * burning tokens in a hopeless loop.
+ *
+ * All logic here is deterministic and dependency-free — no LLM call is required
+ * to summarize or prune, so it is cheap to run on every iteration and easy to test.
+ */
+
+export type Outcome = 'success' | 'failure' | 'noop';
+
+export interface Attempt {
+ /** 1-based iteration number within the run. */
+ iteration: number;
+ /** ISO timestamp of the attempt (optional). */
+ timestamp?: string;
+ /** What the agent tried this iteration (a short description). */
+ action: string;
+ /** Result of the attempt. */
+ outcome: Outcome;
+ /** Raw error message or stack trace, if the attempt failed. */
+ error?: string;
+ /** Tokens spent on this iteration, if tracked. */
+ tokensUsed?: number;
+ /** Set by the pruner when consecutive identical failures are collapsed. */
+ repeated?: number;
+}
+
+export interface Ledger {
+ /** The loop's original goal — the anchor the agent must not lose. */
+ goal: string;
+ /** ISO timestamp when the run started (optional). */
+ startedAt?: string;
+ /** Ordered list of attempts, oldest first. */
+ attempts: Attempt[];
+}
+
+export interface CircuitBreakerConfig {
+ /** Hard cap on total iterations before escalating. */
+ maxIterations: number;
+ /** Escalate when the same error signature repeats this many times in a row. */
+ stagnationThreshold: number;
+ /** Escalate after this many consecutive failures with no success in between. */
+ noProgressThreshold: number;
+ /** Optional hard cap on cumulative tokens across the run. */
+ tokenBudget?: number;
+}
+
+export interface PruneConfig {
+ /** Max lines to keep from any single stack trace. */
+ maxTraceLines: number;
+ /** Number of most-recent attempts to retain in the pruned ledger. */
+ window: number;
+}
+
+export const DEFAULT_BREAKER: CircuitBreakerConfig = {
+ maxIterations: 10,
+ stagnationThreshold: 3,
+ noProgressThreshold: 5,
+};
+
+export const DEFAULT_PRUNE: PruneConfig = {
+ maxTraceLines: 8,
+ window: 5,
+};
+
+// ── Error normalization ────────────────────────────────────────────
+
+/**
+ * Reduce a raw error / stack trace to a stable signature so that "the same
+ * error" can be recognized across iterations even when volatile details
+ * (line numbers, addresses, timestamps, ports, temp paths) differ.
+ */
+export function errorSignature(error: string): string {
+ const firstLine = error.split('\n').find((l) => l.trim().length > 0) ?? '';
+ return firstLine
+ .trim()
+ .replace(/\b\d{4}-\d{2}-\d{2}[T ][\d:.]+Z?\b/g, '<ts>') // ISO timestamps
+ .replace(/0x[0-9a-fA-F]+/g, '<addr>') // hex addresses
+ .replace(/[A-Za-z]:[\\/][^\s:]+|(?:[\\/][^\s:/\\]+)+/g, (p) => {
+ const parts = p.split(/[\\/]/);
+ return parts[parts.length - 1] || p; // collapse paths to basename
+ })
+ .replace(/:\d+(:\d+)?/g, '') // line:col suffixes
+ .replace(/\b\d+\b/g, '#') // any remaining numbers (ports, ids, counts)
+ .replace(/\s+/g, ' ')
+ .trim();
+}
+
+// ── Circuit breaker ────────────────────────────────────────────────
+
+export type BreakerTrigger =
+ | 'ok'
+ | 'stagnation'
+ | 'no-progress'
+ | 'token-budget'
+ | 'max-iterations';
+
+export interface BreakerDecision {
+ /** Whether the loop is cleared to run another iteration. */
+ shouldContinue: boolean;
+ /** Whether the loop must hand off to a human. */
+ escalate: boolean;
+ /** Which condition fired (or 'ok'). */
+ trigger: BreakerTrigger;
+ /** Human-readable explanation. */
+ reason: string;
+ iterations: number;
+ tokensUsed: number;
+}
+
+function totalTokens(ledger: Ledger): number {
+ return ledger.attempts.reduce((sum, a) => sum + (a.tokensUsed ?? 0), 0);
+}
+
+/** Length of the trailing run of failures (since the last non-failure). */
+function trailingFailureRun(attempts: Attempt[]): Attempt[] {
+ const run: Attempt[] = [];
+ for (let i = attempts.length - 1; i >= 0; i--) {
+ if (attempts[i].outcome !== 'failure') break;
+ run.unshift(attempts[i]);
+ }
+ return run;
+}
+
+/**
+ * Decide whether the loop may continue. Checks the most specific and cheapest-
+ * to-fix conditions first (stagnation, then no-progress) before the absolute
+ * caps (token budget, iteration count), so the reported reason is the most
+ * actionable one when several conditions hold.
+ */
+export function checkCircuitBreaker(
+ ledger: Ledger,
+ config: CircuitBreakerConfig = DEFAULT_BREAKER,
+): BreakerDecision {
+ const iterations = ledger.attempts.length;
+ const tokensUsed = totalTokens(ledger);
+ const base = { iterations, tokensUsed };
+
+ const failRun = trailingFailureRun(ledger.attempts);
+
+ // Stagnation: the same error signature repeated at the tail.
+ if (failRun.length >= config.stagnationThreshold) {
+ const lastSig = errorSignature(failRun[failRun.length - 1].error ?? '');
+ let same = 0;
+ for (let i = failRun.length - 1; i >= 0; i--) {
+ if (errorSignature(failRun[i].error ?? '') === lastSig) same++;
+ else break;
+ }
+ if (same >= config.stagnationThreshold) {
+ return {
+ ...base,
+ shouldContinue: false,
+ escalate: true,
+ trigger: 'stagnation',
+ reason: `Same error repeated ${same}× in a row (threshold ${config.stagnationThreshold}): "${lastSig}". Escalating instead of retrying.`,
+ };
+ }
+ }
+
+ // No-progress: many consecutive failures without a success.
+ if (failRun.length >= config.noProgressThreshold) {
+ return {
+ ...base,
+ shouldContinue: false,
+ escalate: true,
+ trigger: 'no-progress',
+ reason: `${failRun.length} consecutive failures with no progress (threshold ${config.noProgressThreshold}). Escalating.`,
+ };
+ }
+
+ // Token budget: absolute spend cap.
+ if (config.tokenBudget !== undefined && tokensUsed >= config.tokenBudget) {
+ return {
+ ...base,
+ shouldContinue: false,
+ escalate: true,
+ trigger: 'token-budget',
+ reason: `Token budget reached (${tokensUsed} ≥ ${config.tokenBudget}). Escalating to avoid cost blowup.`,
+ };
+ }
+
+ // Iteration cap: absolute count.
+ if (iterations >= config.maxIterations) {
+ return {
+ ...base,
+ shouldContinue: false,
+ escalate: true,
+ trigger: 'max-iterations',
+ reason: `Iteration cap reached (${iterations} ≥ ${config.maxIterations}). Escalating.`,
+ };
+ }
+
+ return {
+ ...base,
+ shouldContinue: true,
+ escalate: false,
+ trigger: 'ok',
+ reason: 'Within limits — cleared to continue.',
+ };
+}
+
+// ── Pruning ────────────────────────────────────────────────────────
+
+/** Truncate a stack trace to its most useful head, noting how much was dropped. */
+export function pruneStackTrace(trace: string, maxLines: number): string {
+ const lines = trace.split('\n');
+ if (lines.length <= maxLines) return trace.trim();
+ const kept = lines.slice(0, maxLines).join('\n').trimEnd();
+ const omitted = lines.length - maxLines;
+ return `${kept}\n … (${omitted} more line${omitted === 1 ? '' : 's'} pruned)`;
+}
+
+/**
+ * Produce a lean ledger for injection: keep only the most-recent `window`
+ * attempts, prune verbose traces, and collapse consecutive identical failures
+ * into a single entry with a repeat count. The full ledger is untouched — this
+ * returns a new object.
+ */
+export function pruneLedger(ledger: Ledger, config: PruneConfig = DEFAULT_PRUNE): Ledger {
+ const recent = ledger.attempts.slice(-config.window);
+
+ const collapsed: Attempt[] = [];
+ for (const attempt of recent) {
+ const pruned: Attempt = {
+ ...attempt,
+ ...(attempt.error !== undefined
+ ? { error: pruneStackTrace(attempt.error, config.maxTraceLines) }
+ : {}),
+ };
+
+ const prev = collapsed[collapsed.length - 1];
+ const sameFailure =
+ prev !== undefined &&
+ prev.outcome === 'failure' &&
+ pruned.outcome === 'failure' &&
+ errorSignature(prev.error ?? '') === errorSignature(pruned.error ?? '');
+
+ if (sameFailure) {
+ prev.repeated = (prev.repeated ?? 1) + 1;
+ prev.iteration = pruned.iteration; // advance to the latest iteration
+ } else {
+ collapsed.push(pruned);
+ }
+ }
+
+ return { goal: ledger.goal, startedAt: ledger.startedAt, attempts: collapsed };
+}
+
+// ── Summarization ──────────────────────────────────────────────────
+
+export interface ErrorGroup {
+ signature: string;
+ count: number;
+ sample: string;
+}
+
+export interface AttemptSummary {
+ totalAttempts: number;
+ successes: number;
+ failures: number;
+ noops: number;
+ tokensUsed: number;
+ /** Distinct error signatures, most frequent first. */
+ distinctErrors: ErrorGroup[];
+ /** Unique actions the agent has already tried. */
+ actionsTried: string[];
+}
+
+/** Deterministic factual rollup of the whole run — no LLM required. */
+export function summarizeAttempts(ledger: Ledger): AttemptSummary {
+ const groups = new Map<string, ErrorGroup>();
+ const actions = new Set<string>();
+ let successes = 0;
+ let failures = 0;
+ let noops = 0;
+
+ for (const a of ledger.attempts) {
+ actions.add(a.action);
+ if (a.outcome === 'success') successes++;
+ else if (a.outcome === 'noop') noops++;
+ else {
+ failures++;
+ if (a.error) {
+ const sig = errorSignature(a.error);
+ const existing = groups.get(sig);
+ if (existing) existing.count++;
+ else groups.set(sig, { signature: sig, count: 1, sample: a.error.split('\n')[0].trim() });
+ }
+ }
+ }
+
+ return {
+ totalAttempts: ledger.attempts.length,
+ successes,
+ failures,
+ noops,
+ tokensUsed: totalTokens(ledger),
+ distinctErrors: [...groups.values()].sort((a, b) => b.count - a.count),
+ actionsTried: [...actions],
+ };
+}
+
+// ── Injection ──────────────────────────────────────────────────────
+
+/**
+ * Build the compact context block to prepend to the next prompt. Contains only
+ * what the agent needs to make progress: the goal, what has already been tried
+ * (so it does not repeat itself), the last pruned error, and the breaker status.
+ */
+export function buildContextInjection(
+ ledger: Ledger,
+ breaker: CircuitBreakerConfig = DEFAULT_BREAKER,
+ prune: PruneConfig = DEFAULT_PRUNE,
+): string {
+ const summary = summarizeAttempts(ledger);
+ const decision = checkCircuitBreaker(ledger, breaker);
+ const pruned = pruneLedger(ledger, prune);
+ const lines: string[] = [];
+
+ lines.push('## Loop Context (managed)');
+ lines.push('');
+ lines.push(`**Goal:** ${ledger.goal}`);
+ lines.push(
+ `**Progress:** iteration ${summary.totalAttempts} · ${summary.successes} ok · ${summary.failures} failed` +
+ (summary.tokensUsed ? ` · ${summary.tokensUsed} tokens` : ''),
+ );
+ lines.push('');
+
+ if (summary.actionsTried.length > 0) {
+ lines.push('**Already tried (do NOT repeat):**');
+ for (const action of summary.actionsTried) lines.push(`- ${action}`);
+ lines.push('');
+ }
+
+ if (summary.distinctErrors.length > 0) {
+ lines.push('**Failure patterns:**');
+ for (const g of summary.distinctErrors) {
+ lines.push(`- (${g.count}×) ${g.sample}`);
+ }
+ lines.push('');
+ }
+
+ const lastFail = [...pruned.attempts].reverse().find((a) => a.outcome === 'failure');
+ if (lastFail?.error) {
+ lines.push('**Most recent error (pruned):**');
+ lines.push('```');
+ lines.push(lastFail.error);
+ lines.push('```');
+ lines.push('');
+ }
+
+ lines.push(
+ decision.escalate
+ ? `> STOP — circuit breaker tripped (${decision.trigger}). ${decision.reason}`
+ : `> Circuit breaker: OK (${decision.iterations}/${breaker.maxIterations} iterations used).`,
+ );
+
+ return lines.join('\n');
+}
diff --git a/tools/loop-context/test/context-manager.test.mjs b/tools/loop-context/test/context-manager.test.mjs
new file mode 100644
index 0000000..43b3c95
--- /dev/null
+++ b/tools/loop-context/test/context-manager.test.mjs
@@ -0,0 +1,199 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+ errorSignature,
+ checkCircuitBreaker,
+ pruneStackTrace,
+ pruneLedger,
+ summarizeAttempts,
+ buildContextInjection,
+ DEFAULT_BREAKER,
+ DEFAULT_PRUNE,
+} from '../dist/context-manager.js';
+
+function attempt(iteration, outcome, opts = {}) {
+ return { iteration, action: opts.action ?? `try ${iteration}`, outcome, ...opts };
+}
+
+function ledger(attempts, goal = 'make the build green') {
+ return { goal, attempts };
+}
+
+// ── errorSignature ─────────────────────────────────────────────────
+
+test('errorSignature normalizes volatile details to a stable key', () => {
+ const a = errorSignature('TypeError: cannot read x at /home/u/app/foo.js:12:5');
+ const b = errorSignature('TypeError: cannot read x at /tmp/build/foo.js:88:9');
+ assert.equal(a, b);
+});
+
+test('errorSignature collapses ports and addresses', () => {
+ const a = errorSignature('Error: connect ECONNREFUSED 127.0.0.1:5432');
+ const b = errorSignature('Error: connect ECONNREFUSED 127.0.0.1:5433');
+ assert.equal(a, b);
+});
+
+test('errorSignature keeps genuinely different errors distinct', () => {
+ const a = errorSignature('TypeError: undefined is not a function');
+ const b = errorSignature('ReferenceError: foo is not defined');
+ assert.notEqual(a, b);
+});
+
+// ── circuit breaker: stagnation ────────────────────────────────────
+
+test('breaker trips on stagnation (same error 3× in a row)', () => {
+ const err = 'Error: connect ECONNREFUSED 127.0.0.1:5432';
+ const l = ledger([
+ attempt(1, 'failure', { error: err }),
+ attempt(2, 'failure', { error: err }),
+ attempt(3, 'failure', { error: err }),
+ ]);
+ const d = checkCircuitBreaker(l);
+ assert.equal(d.escalate, true);
+ assert.equal(d.trigger, 'stagnation');
+ assert.equal(d.shouldContinue, false);
+});
+
+test('breaker does not trip when errors differ each time', () => {
+ const l = ledger([
+ attempt(1, 'failure', { error: 'TypeError: a' }),
+ attempt(2, 'failure', { error: 'ReferenceError: b' }),
+ ]);
+ const d = checkCircuitBreaker(l);
+ assert.equal(d.escalate, false);
+ assert.equal(d.trigger, 'ok');
+});
+
+test('breaker stagnation resets after a success', () => {
+ const err = 'Error: boom';
+ const l = ledger([
+ attempt(1, 'failure', { error: err }),
+ attempt(2, 'failure', { error: err }),
+ attempt(3, 'success'),
+ attempt(4, 'failure', { error: err }),
+ ]);
+ const d = checkCircuitBreaker(l);
+ assert.equal(d.escalate, false, 'trailing failure run is only 1 after the success');
+});
+
+// ── circuit breaker: no-progress ───────────────────────────────────
+
+test('breaker trips on no-progress (consecutive failures, distinct errors)', () => {
+ const l = ledger([
+ attempt(1, 'failure', { error: 'e1' }),
+ attempt(2, 'failure', { error: 'e2' }),
+ attempt(3, 'failure', { error: 'e3' }),
+ attempt(4, 'failure', { error: 'e4' }),
+ attempt(5, 'failure', { error: 'e5' }),
+ ]);
+ const d = checkCircuitBreaker(l, { ...DEFAULT_BREAKER, stagnationThreshold: 99 });
+ assert.equal(d.escalate, true);
+ assert.equal(d.trigger, 'no-progress');
+});
+
+// ── circuit breaker: caps ──────────────────────────────────────────
+
+test('breaker trips on token budget', () => {
+ const l = ledger([
+ attempt(1, 'noop', { tokensUsed: 600 }),
+ attempt(2, 'noop', { tokensUsed: 600 }),
+ ]);
+ const d = checkCircuitBreaker(l, { ...DEFAULT_BREAKER, tokenBudget: 1000 });
+ assert.equal(d.trigger, 'token-budget');
+ assert.equal(d.tokensUsed, 1200);
+});
+
+test('breaker trips on iteration cap', () => {
+ const attempts = [];
+ for (let i = 1; i <= 10; i++) attempts.push(attempt(i, 'noop'));
+ const d = checkCircuitBreaker(ledger(attempts), { ...DEFAULT_BREAKER, maxIterations: 10 });
+ assert.equal(d.trigger, 'max-iterations');
+});
+
+test('breaker clears an empty ledger', () => {
+ const d = checkCircuitBreaker(ledger([]));
+ assert.equal(d.shouldContinue, true);
+ assert.equal(d.iterations, 0);
+});
+
+// ── pruning ────────────────────────────────────────────────────────
+
+test('pruneStackTrace keeps head and notes omissions', () => {
+ const trace = Array.from({ length: 20 }, (_, i) => `line ${i}`).join('\n');
+ const pruned = pruneStackTrace(trace, 5);
+ assert.ok(pruned.includes('line 0'));
+ assert.ok(pruned.includes('15 more lines pruned'));
+ assert.ok(!pruned.includes('line 19'));
+});
+
+test('pruneStackTrace leaves short traces intact', () => {
+ const trace = 'line 0\nline 1';
+ assert.equal(pruneStackTrace(trace, 5), trace);
+});
+
+test('pruneLedger keeps only the recent window', () => {
+ const attempts = [];
+ for (let i = 1; i <= 12; i++) attempts.push(attempt(i, 'noop'));
+ const pruned = pruneLedger(ledger(attempts), { ...DEFAULT_PRUNE, window: 3 });
+ assert.equal(pruned.attempts.length, 3);
+ assert.equal(pruned.attempts[2].iteration, 12);
+});
+
+test('pruneLedger collapses consecutive identical failures with a count', () => {
+ const err = 'Error: same thing';
+ const l = ledger([
+ attempt(1, 'failure', { error: err }),
+ attempt(2, 'failure', { error: err }),
+ attempt(3, 'failure', { error: err }),
+ ]);
+ const pruned = pruneLedger(l, { ...DEFAULT_PRUNE, window: 5 });
+ assert.equal(pruned.attempts.length, 1);
+ assert.equal(pruned.attempts[0].repeated, 3);
+ assert.equal(pruned.attempts[0].iteration, 3);
+});
+
+test('pruneLedger does not mutate the input ledger', () => {
+ const l = ledger([attempt(1, 'failure', { error: 'x'.repeat(10) + '\n'.repeat(20) })]);
+ const before = JSON.stringify(l);
+ pruneLedger(l);
+ assert.equal(JSON.stringify(l), before);
+});
+
+// ── summarization ──────────────────────────────────────────────────
+
+test('summarizeAttempts groups errors by signature, most frequent first', () => {
+ const l = ledger([
+ attempt(1, 'failure', { error: 'Error: connect ECONNREFUSED 127.0.0.1:5432', action: 'run migration' }),
+ attempt(2, 'failure', { error: 'Error: connect ECONNREFUSED 127.0.0.1:5433', action: 'run migration' }),
+ attempt(3, 'failure', { error: 'TypeError: x', action: 'patch code' }),
+ attempt(4, 'success', { action: 'patch code' }),
+ ]);
+ const s = summarizeAttempts(l);
+ assert.equal(s.totalAttempts, 4);
+ assert.equal(s.failures, 3);
+ assert.equal(s.successes, 1);
+ assert.equal(s.distinctErrors[0].count, 2, 'ECONNREFUSED collapses to one group of 2');
+ assert.deepEqual(s.actionsTried, ['run migration', 'patch code']);
+});
+
+// ── injection ──────────────────────────────────────────────────────
+
+test('buildContextInjection includes goal, tried actions, and breaker status', () => {
+ const err = 'Error: boom';
+ const l = ledger([
+ attempt(1, 'failure', { error: err, action: 'approach A' }),
+ attempt(2, 'failure', { error: err, action: 'approach A' }),
+ attempt(3, 'failure', { error: err, action: 'approach A' }),
+ ]);
+ const block = buildContextInjection(l);
+ assert.ok(block.includes('make the build green'));
+ assert.ok(block.includes('approach A'));
+ assert.ok(block.includes('do NOT repeat'));
+ assert.ok(block.includes('STOP'), 'stagnation should surface a STOP directive');
+});
+
+test('buildContextInjection shows OK status for a healthy run', () => {
+ const l = ledger([attempt(1, 'noop'), attempt(2, 'success')]);
+ const block = buildContextInjection(l);
+ assert.ok(block.includes('Circuit breaker: OK'));
+});
diff --git a/tools/loop-context/tsconfig.json b/tools/loop-context/tsconfig.json
new file mode 100644
index 0000000..ef0f184
--- /dev/null
+++ b/tools/loop-context/tsconfig.json
@@ -0,0 +1,13 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "NodeNext",
+ "moduleResolution": "NodeNext",
+ "outDir": "dist",
+ "rootDir": "src",
+ "strict": true,
+ "skipLibCheck": true,
+ "declaration": true
+ },
+ "include": ["src/**/*"]
+}