aura-code 0.6.3 → 0.10.1

package/README.md

@@ -1,189 +1,72 @@
-<p align="center">
-  <img src="./README-hero.jpg" alt="Aura">
-</p>
+# Aura Code
 
-
-<h1 align="center">Aura Code — Autonomous Coding Agent</h1>
-
-<p align="center">
-  <em>I don't try. I verify.</em>
-</p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/aura-code"><img src="https://img.shields.io/npm/v/aura-code?color=cc0000&label=npm&logo=npm" alt="npm version"></a>
-  <a href="https://github.com/milodule3-debug/aura-code/actions/workflows/ci.yml"><img src="https://github.com/milodule3-debug/aura-code/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
-  <img src="https://img.shields.io/badge/tests-1205%2B-brightgreen" alt="1205+ tests">
-  <a href="https://github.com/milodule3-debug/aura-code/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
-  <img src="https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white" alt="Node.js 18+">
-  <a href="https://github.com/milodule3-debug/aura-code"><img src="https://img.shields.io/github/stars/milodule3-debug/aura-code?style=social" alt="GitHub Stars"></a>
-</p>
-
-<p align="center">
-  <a href="./docs/ARCHITECTURE.md">
-    <img src="./assets/architecture-diagram.png" alt="Architecture Diagram" width="800">
-  </a>
-  <br>
-  <em><a href="./docs/ARCHITECTURE.md">View full architecture documentation →</a></em>
-</p>
-
-<p align="center">
-  <img src="./assets/demo.gif" alt="Aura Code CLI Demo" width="800">
-  <br>
-  <em>CLI demo — help, models, and version overview</em>
-</p>
-
----
-
-## What is Aura Code?
-
-Designed and brought to life by **Dušan Milosavljević** using opencode.  
-Built by agents, for agents — AI-assisted engineering workflows with multiple AI agents contributing to design, implementation, testing, and verification.  
-Model-agnostic: works with Claude, GPT, Gemini, MiMo, and any OpenAI-compatible endpoint.  
-Written in TypeScript — not related to the Ruby programming language.
-
-Built on the **Praktess** framework — from Ancient Greek: *she who acts and executes*.
-
----
-
-## Quick Start
+> Model-agnostic autonomous coding agent. Natural-language task → read codebase → plan → execute → verify → report.
 
 ```bash
 npm install -g aura-code
-aura 'your task here'
+aura 'fix the login bug'
 ```
 
-Set at least one API key before running:
+## Quick Start
 
 ```bash
-export ANTHROPIC_API_KEY="sk-ant-..."   # Claude
-export OPENAI_API_KEY="sk-..."          # GPT
-export GOOGLE_API_KEY="..."             # Gemini
-export XIAOMI_API_KEY="tp-..."          # MiMo
-# Local — no API key needed:
-# ollama pull qwen2.5-coder:1.5b
-```
-
----
-
-## What Aura Does
-
-1. **Reads** your codebase — files, structure, dependencies
-2. **Plans** a strategy — decides what to change and how
-3. **Executes** — writes code, runs commands, makes edits
-4. **Verifies** — runs tests, checks file integrity, confirms changes
-5. **Reports** — summarizes what was done and what passed
-
----
-
-## Modes
-
-| Mode | What it does |
-|------|-------------|
-| `normal` | Single-agent loop: read → plan → execute → verify |
-| `orchestrate` | Multi-agent: Researcher → Coder → Reviewer |
-| `architect` | High-level design and planning before implementation |
-| `verify` | Post-task checks with automatic retry on failure |
-| `analyze` | Scan session history for failure patterns |
+# Install
+npm install -g aura-code
 
-```bash
-aura 'fix the bug'                                      # normal
-aura --orchestrate 'add error handling to all endpoints' # orchestrate
-aura --architect 'design the new auth system'            # architect
-aura --verify --test-command "npm test" 'fix the tests'  # verify
-aura --analyze                                           # analyze
+# Run (requires at least one provider API key)
+export ANTHROPIC_API_KEY=sk-...   # or OPENAI_API_KEY, GOOGLE_API_KEY, etc.
+aura 'add a logout button'
 ```
 
----
-
-## Providers
+## Providers (model-agnostic)
 
 | Provider | Models |
 |----------|--------|
-| **Claude** (Anthropic) | Opus, Sonnet, Haiku |
-| **GPT** (OpenAI) | gpt-4o, gpt-4o-mini |
-| **Gemini** (Google) | gemini-2.5-pro, gemini-2.5-flash |
-| **MiMo** (Xiaomi) | mimo-v2.5-pro, mimo-v2.5 |
-| **DeepSeek** (OpenRouter) | deepseek-v4-pro, deepseek-v4-flash:free |
-| **Ollama** (Local) | Any local model — no API key needed |
-
-Any OpenAI-compatible endpoint also works via `openrouter/<model>`.
-
----
-
-## Testing
-
-```bash
-npm install
-npm run build      # compiles TypeScript, zero errors expected
-npm test           # runs the full suite (vitest)
-```
-
-For local development:
-
-```bash
-npm run test:watch     # re-runs tests on file changes
-npm run test:coverage  # generates a coverage report
-```
+| Claude (Anthropic) | Opus, Sonnet, Haiku |
+| GPT (OpenAI) | gpt-4o, gpt-4o-mini |
+| Gemini (Google) | gemini-2.5-pro, gemini-2.5-flash |
+| GLM (Zhipu / Z.ai) | glm-5.2, glm-5.1, glm-5 |
+| MiMo (Xiaomi) | mimo-v2.5-pro, mimo-v2.5 |
+| Ollama | any local model |
+| OpenCode Go | Anthropic-compatible endpoint |
 
-The suite currently runs 1000+ tests across 60+ files, covering the agent
-loop, all provider integrations, the tool registry, safety/permissions, the
-orchestration and self-improvement layers, and the dashboard generator.
+Run `aura` without arguments for the interactive setup wizard.
 
-Contributions should keep `npm run build` and `npm test` clean before
-opening a pull request.
+## Features
 
----
+- **Autonomous execution** — reads files, edits code, runs commands, verifies results
+- **Multi-provider fallback** — resilient API handling with circuit breakers
+- **TUI mode** — full terminal UI with command palette, diff view, markdown rendering
+- **Telegram bot** — voice replies, PC control, file sending
+- **Benchmark harness** — reproducible coding tasks with verified outcomes
+- **Context compaction** — adaptive memory for long sessions
 
-## Known Limitations
+## CLI Flags
 
-- **Self-improvement routing (RubyAlternator) is implemented but inactive.**
-  Episode recording and competence scoring both work and are visible in the
-  dashboard's Learning tab, but the routing logic that would actually use
-  competence scores to pick models isn't wired into the main agent loop yet.
-  Today, model selection doesn't change based on what Aura has learned.
-
-- **Provider behavior varies by model.** Tool-calling support, context
-  window handling, and error message quality differ across providers —
-  some of this is normalized (see CHANGELOG for cross-provider config
-  fixes), but not all of it. If a model behaves unexpectedly with tools,
-  check whether the provider documents function-calling support before
-  assuming it's a bug in Aura.
-
-- **Large refactors still need verification.** `--verify` and `--test-command`
-  catch regressions Aura's own changes introduce, but they don't replace
-  review for changes spanning many files or with subtle behavioral intent.
-
-- **Conversation compaction is new.** Long sessions now auto-summarize older
-  turns to stay within context limits; this is recently added and still
-  being hardened against edge cases in unusual tool-call sequences.
-
----
-
-## Stats
-
-| Metric | Value |
-|--------|-------|
-| Tests | 1205+ passing, 0 failures |
-| Version | v0.6.2 |
-| Language | TypeScript (strict) |
-| License | MIT |
-
----
-
-## Repository
+| Flag | Description |
+|------|-------------|
+| `--auto` | Fully autonomous (no confirmations) |
+| `--model <id>` | Specific model (e.g. `claude-sonnet-4`) |
+| `--provider <name>` | Force provider |
+| `--orchestrate` | Multi-agent mode (Researcher → Coder → Reviewer) |
+| `--verify` | Post-task checks with auto-retry |
+| `--readonly` | Read-only analysis |
+| `--doctor` | Run self-diagnostic checks |
 
-GitHub: https://github.com/milodule3-debug/aura-code
-(Repo renamed from milodule3-debug/rubyness — existing clone URLs redirect automatically)
+## Configuration
 
----
+- `.aura.json` — project-level model/provider config
+- Global config via first-run wizard
+- Environment overrides: `AURA_MODEL`, `AURA_FALLBACK_MODEL`, `AURA_MAX_RETRIES`
 
-## Links
+## Development
 
-- [Lean Progress IQ](https://lean-progress-iq-site.vercel.app)
-- [Aura Manifesto](her-rubyness-manifesto.html)
+```bash
+npm run build     # tsc → dist/
+npm run dev       # ts-node src/cli/index.ts
+npm test          # vitest
+```
 
----
+## License
 
-<p align="center">
-  Built by <a href="https://lean-progress-iq-site.vercel.app">Lean Progress IQ</a>
-</p>
+MIT

package/dist/agent/affect.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Lightweight affect heuristic — integrated into the loop, not a standalone
+ * NLU module. A lexical scan of recent user messages; when it detects
+ * frustration it returns one advisory line for the compaction recap.
+ * No LLM call; false positives cost a single recap line.
+ */
+import type { HistoryMessage } from '../providers/types.js';
+/**
+ * Scan the last `lookback` user messages. Requires ≥2 total hits, or ≥1 in
+ * the very last user message, so ordinary bug-fixing vocabulary ("fix this
+ * error") doesn't trip it. Returns an advisory line or null.
+ */
+export declare function detectFrustration(history: HistoryMessage[], lookback?: number): string | null;

package/dist/agent/affect.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectFrustration = detectFrustration;
+// Seeded from the dream reconciler's NEGATIVE_WORDS plus frustration-specific
+// terms. Kept local: the agent core must not depend on src/dream/.
+const FRUSTRATION_WORDS = [
+    'broken', 'fails', 'failing', 'wrong', 'bug', 'error', 'not working',
+    "doesn't work", 'never works', 'stop doing', 'again!!', 'still broken',
+    'still not', 'why does', 'why is this', 'frustrat', 'annoying', 'useless',
+    'wtf', 'terrible',
+];
+function hits(text) {
+    const t = text.toLowerCase();
+    return FRUSTRATION_WORDS.reduce((n, w) => (t.includes(w) ? n + 1 : n), 0);
+}
+/**
+ * Scan the last `lookback` user messages. Requires ≥2 total hits, or ≥1 in
+ * the very last user message, so ordinary bug-fixing vocabulary ("fix this
+ * error") doesn't trip it. Returns an advisory line or null.
+ */
+function detectFrustration(history, lookback = 3) {
+    const userMessages = history.filter(m => m.role === 'user').slice(-lookback);
+    if (userMessages.length === 0)
+        return null;
+    let total = 0;
+    for (const m of userMessages)
+        total += hits(m.content);
+    const lastHit = hits(userMessages[userMessages.length - 1].content) > 0;
+    if (total >= 2 || lastHit) {
+        return 'Note: recent user messages show signs of frustration — prioritize directness, verify before claiming success.';
+    }
+    return null;
+}
+//# sourceMappingURL=affect.js.map

package/dist/agent/affect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"affect.js","sourceRoot":"","sources":["../../src/agent/affect.ts"],"names":[],"mappings":";;AA2BA,8CAYC;AA/BD,8EAA8E;AAC9E,mEAAmE;AACnE,MAAM,iBAAiB,GAAG;IACxB,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,aAAa;IACpE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,SAAS,EAAE,cAAc;IACtE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS;IACzE,KAAK,EAAE,UAAU;CAClB,CAAC;AAEF,SAAS,IAAI,CAAC,IAAY;IACxB,MAAM,CAAC,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IAC7B,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC5E,CAAC;AAED;;;;GAIG;AACH,SAAgB,iBAAiB,CAAC,OAAyB,EAAE,QAAQ,GAAG,CAAC;IACvE,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC7E,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE3C,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,CAAC,IAAI,YAAY;QAAE,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAExE,IAAI,KAAK,IAAI,CAAC,IAAI,OAAO,EAAE,CAAC;QAC1B,OAAO,+GAA+G,CAAC;IACzH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/agent/compactor.d.ts

@@ -1,4 +1,13 @@
 import type { HistoryMessage } from '../providers/types.js';
+export declare const ROLLOVER_AT_GENERATION = 3;
+/** Generation of the current recap (0 if history hasn't been compacted yet). */
+export declare function getRecapGeneration(history: HistoryMessage[]): number;
+/** Index of the current recap message, or -1 if history hasn't been
+ *  compacted yet. Used by generational-flush.ts to locate the recap it's
+ *  about to flush and replace. */
+export declare function findRecapIndex(history: HistoryMessage[]): number;
+/** Tokens for a single string: exact via tokenizer, else char-ratio estimate. */
+export declare function countText(text: string): number;
 /**
  * Provider-independent estimate of how many tokens the *next* prompt will
  * carry, measured directly from the system prompt + current history. This is
@@ -13,14 +22,28 @@ import type { HistoryMessage } from '../providers/types.js';
  * conservative char-ratio estimate. Result is identical in shape either way.
  */
 export declare function estimateContextTokens(system: string, history: HistoryMessage[]): number;
+/** Token estimate for a single history message. */
+export declare function countMessage(msg: HistoryMessage): number;
 /**
- * Compact conversation history when context usage crosses ~70% of the model's
- * window. Keeps the first message (task) and the most recent messages
- * verbatim; replaces the middle with a recap.
+ * Compact conversation history when context usage crosses the escalating
+ * LADDER threshold for the current recap generation (see thresholdRatio).
+ * Keeps the first message (task) and a recent tail of up to RETENTION_RATIO
+ * of the window verbatim; replaces the middle with a recap that can carry an
+ * executive digest and tone hint (see extras). If the middle already
+ * contains a prior recap, it's compressed via compressRecap rather than
+ * blindly truncated, and the new recap's generation increments — once it
+ * would exceed ROLLOVER_AT_GENERATION, callers should flush via
+ * generational-flush.ts instead of calling this again.
  *
  * Mutates `history` in place (clears and re-fills) so callers that hold a
  * shared reference see the compacted version without reassignment.
  *
  * Returns `true` if compaction happened.
  */
-export declare function compactHistory(history: HistoryMessage[], totalTokens: number, model: string): boolean;
+export interface CompactionExtras {
+    /** Digest of recent state-altering tool calls (ExecutiveQueue.digest()). */
+    executiveDigest?: string;
+    /** Advisory tone hint (detectFrustration()). */
+    affectHint?: string;
+}
+export declare function compactHistory(history: HistoryMessage[], totalTokens: number, model: string, extras?: CompactionExtras): boolean;

package/dist/agent/compactor.js

@@ -1,11 +1,54 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROLLOVER_AT_GENERATION = void 0;
+exports.getRecapGeneration = getRecapGeneration;
+exports.findRecapIndex = findRecapIndex;
+exports.countText = countText;
 exports.estimateContextTokens = estimateContextTokens;
+exports.countMessage = countMessage;
 exports.compactHistory = compactHistory;
 const factory_js_1 = require("../providers/factory.js");
-const COMPACTION_THRESHOLD = 0.7;
-const PRESERVE_RECENT = 3;
+/**
+ * Escalating trigger ladder, indexed by "recap generation" (how many times
+ * the current recap has already been through compaction). Later generations
+ * tolerate more fill before firing again — that content is already dense/
+ * pre-summarized, so there's less marginal value in acting early. Held at
+ * the last value once the ladder is exhausted; ROLLOVER_AT_GENERATION caps
+ * how many in-place rounds happen before a full generational flush (see
+ * generational-flush.ts) instead of a further round of lossy recompaction.
+ */
+const LADDER = [0.55, 0.70, 0.85];
+exports.ROLLOVER_AT_GENERATION = 3;
+/** Verbatim recent-history budget kept through compaction, as a share of the
+ *  window. 40% preserves interaction nuance over long sequences. */
+const RETENTION_RATIO = 0.40;
 const DEFAULT_WINDOW = 128_000;
+/** Messages kept when no later user turn exists to anchor the tail. */
+const FALLBACK_KEEP = 3;
+/** Per-tool-result cap applied by the churn guard (see compactHistory). */
+const MAX_RESULT_CHARS = 4_000;
+function thresholdRatio(generation) {
+    return LADDER[Math.min(generation, LADDER.length - 1)];
+}
+/** Marker prefixing every recap message; also carries the generation number. */
+const RECAP_MARKER = '[Earlier conversation compacted';
+function isRecap(msg) {
+    return msg.role === 'assistant' && msg.content.startsWith(RECAP_MARKER);
+}
+/** Generation of the current recap (0 if history hasn't been compacted yet). */
+function getRecapGeneration(history) {
+    const recap = history.find(isRecap);
+    if (!recap)
+        return 0;
+    const match = recap.content.match(/\(gen (\d+)\)/);
+    return match ? parseInt(match[1], 10) : 0;
+}
+/** Index of the current recap message, or -1 if history hasn't been
+ *  compacted yet. Used by generational-flush.ts to locate the recap it's
+ *  about to flush and replace. */
+function findRecapIndex(history) {
+    return history.findIndex(isRecap);
+}
 /** Average characters per token used for the local size estimate. Deliberately
  *  conservative (real ratio is ~4 for English prose, lower for code/JSON) so we
  *  err toward compacting slightly early rather than overflowing. */
@@ -59,25 +102,77 @@ function countText(text) {
  */
 function estimateContextTokens(system, history) {
     let tokens = countText(system);
-    for (const msg of history) {
-        switch (msg.role) {
-            case 'user':
-                tokens += countText(msg.content);
-                break;
-            case 'assistant':
-                tokens += countText(msg.content ?? '');
-                for (const call of msg.toolCalls ?? []) {
-                    tokens += countText(call.name) + countText(JSON.stringify(call.input));
-                }
-                break;
-            case 'tool_result':
-                for (const r of msg.results) {
-                    tokens += countText(r.name) + countText(r.content ?? '');
-                }
-                break;
+    for (const msg of history)
+        tokens += countMessage(msg);
+    return tokens;
+}
+/** Token estimate for a single history message. */
+function countMessage(msg) {
+    switch (msg.role) {
+        case 'user':
+            return countText(msg.content);
+        case 'assistant': {
+            let tokens = countText(msg.content ?? '');
+            for (const call of msg.toolCalls ?? []) {
+                tokens += countText(call.name) + countText(JSON.stringify(call.input));
+            }
+            return tokens;
+        }
+        case 'tool_result': {
+            let tokens = 0;
+            for (const r of msg.results) {
+                tokens += countText(r.name) + countText(r.content ?? '');
+            }
+            return tokens;
         }
     }
-    return tokens;
+}
+/** Generic English + prior-recap boilerplate excluded from term extraction. */
+const RECAP_STOPWORDS = new Set([
+    'the', 'a', 'an', 'is', 'was', 'were', 'be', 'been', 'to', 'of', 'in', 'on',
+    'for', 'and', 'or', 'it', 'this', 'that', 'with', 'not', 'note', 'recent',
+    'user', 'assistant', 'tool', 'results', 'called', 'earlier', 'conversation',
+    'compacted', 'turns', 'removed', 'stay', 'within', 'context', 'limits',
+]);
+/** Top-N most frequent non-stopword tokens across a set of lines. Pure stats,
+ *  no LLM — same style as dream.ts's topicKey / mining/extract.ts. */
+function extractTopTerms(lines, n) {
+    const freq = new Map();
+    for (const line of lines) {
+        const words = line.toLowerCase().replace(/[^a-z0-9\s./_-]/g, ' ').split(/\s+/);
+        for (const w of words) {
+            if (w.length <= 3 || RECAP_STOPWORDS.has(w))
+                continue;
+            freq.set(w, (freq.get(w) ?? 0) + 1);
+        }
+    }
+    return [...freq.entries()].sort((a, b) => b[1] - a[1]).slice(0, n).map(([w]) => w);
+}
+/** First non-empty line, truncated to ~8 words — a cheap topic label. */
+function extractConcept(lines) {
+    const first = lines.find(l => l.trim().length > 0)?.trim() ?? '(no content)';
+    const words = first.split(/\s+/);
+    return words.length > 8 ? words.slice(0, 8).join(' ') + '…' : first;
+}
+/**
+ * Reduce an existing recap to: 1 concept + top 5 terms, plus its LAST body
+ * line preserved verbatim ("last thread, pre-compaction"). Replaces
+ * summariseMessage's blind slice(0,120) for recap messages specifically —
+ * that truncation was destroying the executive digest and prior context on
+ * any second compaction in the same run.
+ */
+function compressRecap(msg) {
+    const lines = msg.content.split('\n').filter(l => l.trim().length > 0);
+    const body = lines.slice(1); // drop the "[Earlier conversation compacted...]" header
+    const lastThread = body.length > 0 ? body[body.length - 1] : '';
+    const rest = body.slice(0, -1);
+    const concept = extractConcept(rest);
+    const terms = extractTopTerms(rest, 5);
+    return [
+        `Concept: ${concept}`,
+        terms.length > 0 ? `Terms: ${terms.join(', ')}` : '',
+        lastThread ? `Last thread: ${lastThread}` : '',
+    ].filter(Boolean).join(' · ');
 }
 function summariseMessage(msg) {
     switch (msg.role) {
@@ -94,56 +189,65 @@ function summariseMessage(msg) {
         }
     }
 }
-/**
- * Compact conversation history when context usage crosses ~70% of the model's
- * window. Keeps the first message (task) and the most recent messages
- * verbatim; replaces the middle with a recap.
- *
- * Mutates `history` in place (clears and re-fills) so callers that hold a
- * shared reference see the compacted version without reassignment.
- *
- * Returns `true` if compaction happened.
- */
-function compactHistory(history, totalTokens, model) {
+function compactHistory(history, totalTokens, model, extras) {
+    const generation = getRecapGeneration(history);
     const window = (0, factory_js_1.getContextWindow)(model) ?? DEFAULT_WINDOW;
-    const threshold = Math.floor(window * COMPACTION_THRESHOLD);
+    const threshold = Math.floor(window * thresholdRatio(generation));
     if (totalTokens < threshold)
         return false;
-    const MIN_KEEP = 2 + PRESERVE_RECENT;
-    if (history.length <= MIN_KEEP)
+    if (history.length <= 3)
         return false;
-    // Prefer preserving the ENTIRE most recent user turn intact — search
-    // backward for the last 'user' message (excluding the original task at
-    // index 0). A forward-only search from an arbitrary message-count
-    // boundary can miss this entirely, since the most recent user turn may
-    // start well before that boundary — confirmed by testing a multi-turn
-    // session where a forward search found nothing and fell through to
-    // collapsing the whole session, discarding a real, recent instruction.
-    let keepFrom = -1;
+    // Keep-boundary by token budget: walk backward accumulating message sizes
+    // until the verbatim tail would exceed RETENTION_RATIO of the window. The
+    // last message is always kept even if it alone busts the budget.
+    const retainBudget = Math.floor(window * RETENTION_RATIO);
+    let acc = 0;
+    let keepFrom = history.length;
     for (let i = history.length - 1; i >= 1; i--) {
+        const cost = countMessage(history[i]);
+        if (acc + cost > retainBudget && keepFrom < history.length)
+            break;
+        acc += cost;
+        keepFrom = i;
+    }
+    if (keepFrom >= history.length)
+        keepFrom = history.length - 1;
+    // Snap the boundary to the start of a user turn when one is nearby, so the
+    // kept slice opens with user context and tool_use/tool_result pairs stay
+    // intact (a user message never sits between a tool_use and its result).
+    let snapped = -1;
+    for (let i = keepFrom; i >= Math.max(1, keepFrom - 6); i--) {
         if (history[i].role === 'user') {
-            keepFrom = i;
+            snapped = i;
             break;
         }
     }
-    if (keepFrom === -1) {
-        // No later user turn exists (e.g. still mid-task, only the original
-        // instruction so far) — fall back to keeping roughly the last
-        // PRESERVE_RECENT messages, walked forward to avoid landing on an
-        // orphaned tool_result or directly after the assistant-role recap.
-        keepFrom = Math.max(1, history.length - PRESERVE_RECENT);
-        while (keepFrom < history.length &&
-            (history[keepFrom].role === 'tool_result' || history[keepFrom].role === 'assistant'))
+    if (snapped !== -1) {
+        keepFrom = snapped;
+    }
+    else {
+        // No user turn nearby (e.g. one long tool-heavy stretch, like the old
+        // FALLBACK_KEEP case) — never let the kept slice START with a
+        // tool_result whose tool_use was compacted away.
+        keepFrom = Math.max(keepFrom, Math.max(1, history.length - FALLBACK_KEEP));
+        while (keepFrom < history.length - 1 &&
+            history[keepFrom].role === 'tool_result')
             keepFrom++;
     }
     const toCompact = history.slice(1, keepFrom);
-    if (toCompact.length === 0)
-        return false;
-    const summaries = toCompact.map(summariseMessage);
+    if (toCompact.length === 0) {
+        // Nothing droppable (the over-budget content IS the recent tail) — the
+        // churn guard is the only lever left.
+        return truncateOversizedResults(history, threshold);
+    }
+    const summaries = toCompact.map(msg => isRecap(msg) ? compressRecap(msg) : summariseMessage(msg));
+    const newGeneration = generation + 1;
     const recap = {
         role: 'assistant',
         content: [
-            `[Earlier conversation compacted: ${toCompact.length} turns removed to stay within context limits.]`,
+            `${RECAP_MARKER} (gen ${newGeneration}): ${toCompact.length} turns removed to stay within context limits.]`,
+            ...(extras?.affectHint ? [extras.affectHint] : []),
+            ...(extras?.executiveDigest ? ['', extras.executiveDigest, ''] : []),
             ...summaries,
         ].join('\n'),
     };
@@ -151,6 +255,33 @@ function compactHistory(history, totalTokens, model) {
     history.length = 0;
     for (const msg of preserved)
         history.push(msg);
+    // Churn guard (see truncateOversizedResults).
+    truncateOversizedResults(history, threshold);
     return true;
 }
+/**
+ * Churn guard: a single oversized tool_result in the kept tail can hold the
+ * estimate above the trigger forever, so compaction would fire every turn
+ * with no shrinkage. If the history is still over threshold, cap result
+ * bodies. Returns true if anything was truncated.
+ */
+function truncateOversizedResults(history, threshold) {
+    let total = 0;
+    for (const msg of history)
+        total += countMessage(msg);
+    if (total < threshold)
+        return false;
+    let truncated = false;
+    for (const msg of history) {
+        if (msg.role !== 'tool_result')
+            continue;
+        for (const r of msg.results) {
+            if (r.content && r.content.length > MAX_RESULT_CHARS) {
+                r.content = r.content.slice(0, MAX_RESULT_CHARS) + '\n[truncated during compaction]';
+                truncated = true;
+            }
+        }
+    }
+    return truncated;
+}
 //# sourceMappingURL=compactor.js.map