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.

6.0 KB
Raw Blame
/**
 * 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 when the agent attempts semantically similar actions this many times in a row. */
    frustrationThreshold: 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;
    /** Float 0.0-1.0. If consecutive errors are this similar, they count as stagnant. */
    similarityThreshold: 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;
    /** Float 0.0-1.0. If consecutive errors are this similar, they are collapsed. */
    similarityThreshold: number;
}
export declare const DEFAULT_BREAKER: CircuitBreakerConfig;
export declare const DEFAULT_PRUNE: PruneConfig;
/** Throw unless value is a similarity threshold: a fraction in (0, 1]. */
export declare function assertSimilarityThreshold(value: unknown, label?: string): asserts value is number;
/** Throw if any rule in the config could never fire (or would fire on nothing). */
export declare function validateBreakerConfig(config: CircuitBreakerConfig): void;
export declare function validatePruneConfig(config: PruneConfig): void;
/**
 * 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 declare function calculateSimilarity(a: string, b: string): number;
export type BreakerTrigger = 'ok' | 'stagnation' | 'frustration' | 'no-progress' | 'token-budget' | 'daily-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, similarityThreshold?: number): 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;