aura-code 0.6.3 → 0.10.2

package/dist/agent/executive-queue.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Executive queue — a bounded record of recent state-altering tool calls.
+ *
+ * When history is compacted, the model loses the verbatim record of what it
+ * already executed; this queue's digest is injected into the compaction recap
+ * so the model never repeats a write/edit/shell command it already ran.
+ * Deliberately bounded (not an exhaustive ledger): only the most recent
+ * mutations matter for "don't repeat yourself", and a cap keeps the recap
+ * payload and state complexity flat.
+ */
+/** Tools that can change the working tree — the checkpoint trigger set. */
+export declare const MUTATING_TOOLS: Set<string>;
+export declare const EXECUTIVE_QUEUE_MAX = 20;
+export interface ExecutiveEntry {
+    name: string;
+    summary: string;
+    turn: number;
+}
+export declare class ExecutiveQueue {
+    private entries;
+    /** Record a call if it's state-altering; evicts the oldest past the cap. */
+    push(name: string, input: Record<string, unknown>, turn: number): void;
+    get size(): number;
+    /** Digest for the compaction recap; newest last. Empty string when empty. */
+    digest(): string;
+}

package/dist/agent/executive-queue.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * Executive queue — a bounded record of recent state-altering tool calls.
+ *
+ * When history is compacted, the model loses the verbatim record of what it
+ * already executed; this queue's digest is injected into the compaction recap
+ * so the model never repeats a write/edit/shell command it already ran.
+ * Deliberately bounded (not an exhaustive ledger): only the most recent
+ * mutations matter for "don't repeat yourself", and a cap keeps the recap
+ * payload and state complexity flat.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecutiveQueue = exports.EXECUTIVE_QUEUE_MAX = exports.MUTATING_TOOLS = void 0;
+/** Tools that can change the working tree — the checkpoint trigger set. */
+exports.MUTATING_TOOLS = new Set(['write_file', 'edit_file', 'run_shell']);
+exports.EXECUTIVE_QUEUE_MAX = 20;
+/** One-line summary of a call, mirroring how confirmations render them. */
+function summarise(name, input) {
+    if (name === 'run_shell') {
+        const cmd = String(input.command ?? '');
+        return cmd.length > 100 ? `${cmd.slice(0, 100)}…` : cmd;
+    }
+    return String(input.path ?? input.file_path ?? '(unknown target)');
+}
+class ExecutiveQueue {
+    entries = [];
+    /** Record a call if it's state-altering; evicts the oldest past the cap. */
+    push(name, input, turn) {
+        if (!exports.MUTATING_TOOLS.has(name))
+            return;
+        this.entries.push({ name, summary: summarise(name, input), turn });
+        if (this.entries.length > exports.EXECUTIVE_QUEUE_MAX)
+            this.entries.shift();
+    }
+    get size() {
+        return this.entries.length;
+    }
+    /** Digest for the compaction recap; newest last. Empty string when empty. */
+    digest() {
+        if (this.entries.length === 0)
+            return '';
+        const lines = this.entries.map(e => e.name === 'run_shell' ? `run_shell: ${e.summary}` : `${e.name} ${e.summary}`);
+        return [
+            'Recent state-altering actions already executed (do not repeat):',
+            ...lines,
+        ].join('\n');
+    }
+}
+exports.ExecutiveQueue = ExecutiveQueue;
+//# sourceMappingURL=executive-queue.js.map

package/dist/agent/executive-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executive-queue.js","sourceRoot":"","sources":["../../src/agent/executive-queue.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAEH,2EAA2E;AAC9D,QAAA,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,YAAY,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;AAEnE,QAAA,mBAAmB,GAAG,EAAE,CAAC;AAQtC,2EAA2E;AAC3E,SAAS,SAAS,CAAC,IAAY,EAAE,KAA8B;IAC7D,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;QACxC,OAAO,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;IAC1D,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,SAAS,IAAI,kBAAkB,CAAC,CAAC;AACrE,CAAC;AAED,MAAa,cAAc;IACjB,OAAO,GAAqB,EAAE,CAAC;IAEvC,4EAA4E;IAC5E,IAAI,CAAC,IAAY,EAAE,KAA8B,EAAE,IAAY;QAC7D,IAAI,CAAC,sBAAc,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO;QACtC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QACnE,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,2BAAmB;YAAE,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACtE,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,6EAA6E;IAC7E,MAAM;QACJ,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CACjC,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,OAAO,EAAE,CAC9E,CAAC;QACF,OAAO;YACL,iEAAiE;YACjE,GAAG,KAAK;SACT,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;CACF;AAzBD,wCAyBC"}

package/dist/agent/generational-flush.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Generational rollover — the "new context window" step. In-place recap
+ * compaction (compactor.ts) can only escalate its trigger threshold so far
+ * (ROLLOVER_AT_GENERATION) before recompacting a recap starts destroying
+ * information no heuristic can recover cheaply. At that point, flush the
+ * whole recap through one LLM call — the same distillation primitive the
+ * cross-session dream pipeline uses (src/dream/dream.ts) — into the dream
+ * store, and replace it with a short pointer. This is "distill, don't
+ * discard" applied mid-session instead of only at process exit, and it
+ * means the flushed content is automatically picked up by the normal
+ * cross-session runReconciliation() pass alongside end-of-session dreams.
+ */
+import type { HistoryMessage, LLMProvider } from '../providers/types.js';
+export interface RolloverResult {
+    flushed: boolean;
+    flushPath?: string;
+}
+/**
+ * Flush the current recap to the dream store and replace it in `history`
+ * with a pointer line + a freshly regenerated executive digest and affect
+ * hint (never the old recap's text — that's what's being flushed). Mutates
+ * `history` in place, matching compactHistory's contract. No-ops if there's
+ * no recap to flush.
+ */
+export declare function maybeRollover(history: HistoryMessage[], sessionRoot: string, provider: LLMProvider, extras?: {
+    executiveDigest?: string;
+    affectHint?: string;
+}): Promise<RolloverResult>;

package/dist/agent/generational-flush.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maybeRollover = maybeRollover;
+const compactor_js_1 = require("./compactor.js");
+const dream_js_1 = require("../dream/dream.js");
+const FLUSH_SYSTEM = [
+    'You distill an in-progress coding session\'s compacted history into durable memory bullets.',
+    'Write ONLY markdown bullet points, one per line, each starting with "- ".',
+    'Each bullet must be a concrete, standalone fact: a decision made, a file touched, a root cause found, or an unresolved thread.',
+    'Be specific — file names, exact behavior, not generic advice. No headers, no prose paragraphs.',
+].join(' ');
+/** Per-process counter for sessionFlushFile's uniqueness suffix. */
+let flushSeq = 0;
+/**
+ * Flush the current recap to the dream store and replace it in `history`
+ * with a pointer line + a freshly regenerated executive digest and affect
+ * hint (never the old recap's text — that's what's being flushed). Mutates
+ * `history` in place, matching compactHistory's contract. No-ops if there's
+ * no recap to flush.
+ */
+async function maybeRollover(history, sessionRoot, provider, extras = {}) {
+    const recapIndex = (0, compactor_js_1.findRecapIndex)(history);
+    if (recapIndex === -1)
+        return { flushed: false };
+    const recap = history[recapIndex];
+    flushSeq++;
+    const flushPath = (0, dream_js_1.sessionFlushFile)(sessionRoot, flushSeq);
+    await (0, dream_js_1.distillText)({
+        systemPrompt: FLUSH_SYSTEM,
+        userContent: recap.content,
+        provider,
+        outPath: flushPath,
+    });
+    const pointer = {
+        role: 'assistant',
+        content: [
+            `[Session context flushed to memory (${flushPath}) — continuing with a fresh context window.]`,
+            ...(extras.affectHint ? [extras.affectHint] : []),
+            ...(extras.executiveDigest ? ['', extras.executiveDigest] : []),
+        ].join('\n'),
+    };
+    // Note: the pointer's content deliberately does NOT start with compactor's
+    // RECAP_MARKER, so getRecapGeneration(history) reads back to 0 next time —
+    // this message is ordinary content from here on, not a growing recap.
+    history.splice(recapIndex, 1, pointer);
+    return { flushed: true, flushPath };
+}
+//# sourceMappingURL=generational-flush.js.map

package/dist/agent/generational-flush.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generational-flush.js","sourceRoot":"","sources":["../../src/agent/generational-flush.ts"],"names":[],"mappings":";;AAsCA,sCAmCC;AA5DD,iDAAgD;AAChD,gDAAkE;AAElE,MAAM,YAAY,GAAG;IACnB,6FAA6F;IAC7F,2EAA2E;IAC3E,gIAAgI;IAChI,gGAAgG;CACjG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAEZ,oEAAoE;AACpE,IAAI,QAAQ,GAAG,CAAC,CAAC;AAOjB;;;;;;GAMG;AACI,KAAK,UAAU,aAAa,CACjC,OAAyB,EACzB,WAAmB,EACnB,QAAqB,EACrB,SAA4D,EAAE;IAE9D,MAAM,UAAU,GAAG,IAAA,6BAAc,EAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,UAAU,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAEjD,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,CAA2C,CAAC;IAC5E,QAAQ,EAAE,CAAC;IACX,MAAM,SAAS,GAAG,IAAA,2BAAgB,EAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IAE1D,MAAM,IAAA,sBAAW,EAAC;QAChB,YAAY,EAAE,YAAY;QAC1B,WAAW,EAAE,KAAK,CAAC,OAAO;QAC1B,QAAQ;QACR,OAAO,EAAE,SAAS;KACnB,CAAC,CAAC;IAEH,MAAM,OAAO,GAAmB;QAC9B,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE;YACP,uCAAuC,SAAS,8CAA8C;YAC9F,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACjD,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SAChE,CAAC,IAAI,CAAC,IAAI,CAAC;KACb,CAAC;IAEF,2EAA2E;IAC3E,2EAA2E;IAC3E,sEAAsE;IACtE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;IAEvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AACtC,CAAC"}

package/dist/agent/loop-profile.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Task classification for turn-budget sizing.
+ *
+ * Cheap heuristics only — no LLM call. Spending a model turn to decide
+ * how many turns to allow defeats the purpose. This is pattern matching
+ * on the task string, nothing more.
+ */
+export type TaskShape = 'single-file' | 'multi-file' | 'exploratory';
+export interface LoopProfile {
+    maxTurns: number;
+    shape: TaskShape;
+    /** How many identical consecutive turn-signatures count as a stall. */
+    stallThreshold: number;
+    /**
+     * One-time budget upgrade: if the run hits maxTurns while still making
+     * progress (not stalled), widen once to this ceiling instead of ending
+     * with a resume hint. Absent for shapes already at the top tier and
+     * whenever the user passed an explicit --max-turns (a hard ceiling).
+     */
+    widenTo?: number;
+}
+/**
+ * Classify a task string into a rough shape. Defaults to 'single-file'
+ * when nothing matches — the common case (fix X, add Y to file Z).
+ */
+export declare function classifyTask(task: string): TaskShape;
+/**
+ * Get the loop profile for a task.
+ *
+ * @param task     The task prompt.
+ * @param override Explicit maxTurns from CLI flag or config — always wins,
+ *                 and is a hard ceiling (no adaptive widening past it).
+ */
+export declare function getLoopProfile(task: string, override?: number): LoopProfile;
+export type StallKind = 'repeat' | 'cycle';
+/**
+ * Detect a stalled run from the sequence of per-turn tool-call signatures.
+ *
+ * - 'repeat': the last `threshold` signatures are identical (A A A) — the
+ *   agent retrying the same call verbatim.
+ * - 'cycle':  the last `2 * threshold` signatures alternate between two
+ *   distinct signatures (A B A B A B) — the agent bouncing between two
+ *   equally-wrong edits. Requires `threshold` full repetitions of the pair,
+ *   so it is strictly harder to trigger than 'repeat'.
+ *
+ * Exact-match only, deliberately conservative: a false stop on a run that
+ * was making slow progress is worse than a few wasted turns, since a human
+ * can always resume a stopped session.
+ */
+export declare function detectStall(signatures: string[], threshold: number): StallKind | null;

package/dist/agent/loop-profile.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Task classification for turn-budget sizing.
+ *
+ * Cheap heuristics only — no LLM call. Spending a model turn to decide
+ * how many turns to allow defeats the purpose. This is pattern matching
+ * on the task string, nothing more.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyTask = classifyTask;
+exports.getLoopProfile = getLoopProfile;
+exports.detectStall = detectStall;
+const MULTI_FILE_SIGNALS = [
+    'all endpoints', 'every file', 'across the', 'throughout the',
+    'all files', 'each file', 'entire codebase', 'orchestrate',
+];
+const EXPLORATORY_SIGNALS = [
+    'explain', 'analyze', 'investigate', 'research', 'understand',
+    'why does', 'why is', 'how does', 'what causes', 'diagnose',
+];
+/**
+ * Classify a task string into a rough shape. Defaults to 'single-file'
+ * when nothing matches — the common case (fix X, add Y to file Z).
+ */
+function classifyTask(task) {
+    const lower = task.toLowerCase();
+    if (MULTI_FILE_SIGNALS.some((s) => lower.includes(s))) {
+        return 'multi-file';
+    }
+    if (EXPLORATORY_SIGNALS.some((s) => lower.includes(s))) {
+        return 'exploratory';
+    }
+    return 'single-file';
+}
+const PROFILES = {
+    'single-file': { maxTurns: 30, stallThreshold: 3, widenTo: 80 },
+    'multi-file': { maxTurns: 150, stallThreshold: 4 },
+    'exploratory': { maxTurns: 80, stallThreshold: 4 },
+};
+/**
+ * Get the loop profile for a task.
+ *
+ * @param task     The task prompt.
+ * @param override Explicit maxTurns from CLI flag or config — always wins,
+ *                 and is a hard ceiling (no adaptive widening past it).
+ */
+function getLoopProfile(task, override) {
+    const shape = classifyTask(task);
+    const base = PROFILES[shape];
+    if (override !== undefined) {
+        return { shape, maxTurns: override, stallThreshold: base.stallThreshold };
+    }
+    return {
+        shape,
+        maxTurns: base.maxTurns,
+        stallThreshold: base.stallThreshold,
+        widenTo: base.widenTo,
+    };
+}
+/**
+ * Detect a stalled run from the sequence of per-turn tool-call signatures.
+ *
+ * - 'repeat': the last `threshold` signatures are identical (A A A) — the
+ *   agent retrying the same call verbatim.
+ * - 'cycle':  the last `2 * threshold` signatures alternate between two
+ *   distinct signatures (A B A B A B) — the agent bouncing between two
+ *   equally-wrong edits. Requires `threshold` full repetitions of the pair,
+ *   so it is strictly harder to trigger than 'repeat'.
+ *
+ * Exact-match only, deliberately conservative: a false stop on a run that
+ * was making slow progress is worse than a few wasted turns, since a human
+ * can always resume a stopped session.
+ */
+function detectStall(signatures, threshold) {
+    const tail = signatures.slice(-threshold);
+    if (tail.length === threshold && tail.every((s) => s === tail[0])) {
+        return 'repeat';
+    }
+    const pairTail = signatures.slice(-2 * threshold);
+    if (pairTail.length === 2 * threshold) {
+        const [a, b] = pairTail;
+        if (a !== b && pairTail.every((s, i) => s === (i % 2 === 0 ? a : b))) {
+            return 'cycle';
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=loop-profile.js.map

package/dist/agent/loop-profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-profile.js","sourceRoot":"","sources":["../../src/agent/loop-profile.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAgCH,oCAUC;AAeD,wCAaC;AAkBD,kCAcC;AApFD,MAAM,kBAAkB,GAAG;IACzB,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB;IAC7D,WAAW,EAAE,WAAW,EAAE,iBAAiB,EAAE,aAAa;CAC3D,CAAC;AAEF,MAAM,mBAAmB,GAAG;IAC1B,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY;IAC7D,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU;CAC5D,CAAC;AAEF;;;GAGG;AACH,SAAgB,YAAY,CAAC,IAAY;IACvC,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IAEjC,IAAI,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACtD,OAAO,YAAY,CAAC;IACtB,CAAC;IACD,IAAI,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,OAAO,aAAa,CAAC;IACvB,CAAC;IACD,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,MAAM,QAAQ,GAAkD;IAC9D,aAAa,EAAG,EAAE,QAAQ,EAAE,EAAE,EAAG,cAAc,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE;IACjE,YAAY,EAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,cAAc,EAAE,CAAC,EAAE;IACpD,aAAa,EAAG,EAAE,QAAQ,EAAE,EAAE,EAAG,cAAc,EAAE,CAAC,EAAE;CACrD,CAAC;AAEF;;;;;;GAMG;AACH,SAAgB,cAAc,CAAC,IAAY,EAAE,QAAiB;IAC5D,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAE7B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC;IAC5E,CAAC;IACD,OAAO;QACL,KAAK;QACL,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC;AACJ,CAAC;AAID;;;;;;;;;;;;;GAaG;AACH,SAAgB,WAAW,CAAC,UAAoB,EAAE,SAAiB;IACjE,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,CAAC;IAC1C,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAClD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,GAAG,SAAS,EAAE,CAAC;QACtC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,QAAQ,CAAC;QACxB,IAAI,CAAC,KAAK,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACrE,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/agent/loop.d.ts

@@ -25,12 +25,20 @@ export interface LoopOptions {
     disableSpawn?: boolean;
     /** Internal: skip post-task verification (used by runWithVerification wrapper). */
     verify?: boolean;
-    /**
-     * Custom confirmation function for destructive operations.
-     * Defaults to terminal-based confirm() from permissions.
-     * Telegram bot overrides this to send approval requests via Telegram messages.
-     */
+    /** Shadow-git checkpoints before mutating tool calls (default: true; no-op outside a git repo). */
+    checkpoints?: boolean;
+    /** Plugin hooks fired around tool execution (PreToolUse can block). */
+    hooks?: import('../plugins/types.js').HookEntry[];
+    /** Optional abort signal — when aborted the loop stops after the current tool turn. */
+    abortSignal?: AbortSignal;
+    /** Confirmation prompt override for needs-confirm tool calls. Defaults to the
+     *  terminal readline confirm — embedded callers (alternator, bots) supply
+     *  their own so confirmation isn't silently impossible off-terminal. */
     confirmFn?: (message: string) => Promise<boolean>;
+    /** Optional shared context-health tracker (e.g. the REPL's). When omitted the
+     *  loop creates an internal one. Passing it in lets a /context command read
+     *  the accumulated compaction history and per-turn snapshots. */
+    healthTracker?: import('../cli/context-health.js').ContextHealthTracker;
 }
 export interface LoopResult {
     success: boolean;
@@ -51,7 +59,9 @@ export interface TokenUsage {
     inputTokens: number;
     outputTokens: number;
     totalTokens: number;
+    cachedTokens: number;
 }
+export declare function costFor(model: string, input: number, output: number, cachedTokens?: number): number;
 export declare function runAgentLoop(opts: LoopOptions): Promise<LoopResult>;
 export declare function runAgentLoopVerified(opts: LoopOptions, config: VerificationConfig, projectRoot: string): Promise<{
     loopResult: LoopResult;