s-app-scoder-agent 0.8.20 → 0.8.21

package/README.md

@@ -50,7 +50,7 @@ export OPENAI_BASE_URL=https://api.openai.com/v1  # optional, for custom endpoin
 # Run a task
 scoder "add a ping function to src/network.ts"
 
-# Interactive REPL (supports /help, /clear, /cost, /model, /skills, /skill, /mcp, /review, /permission)
+# Interactive REPL (supports /help, /clear, /compact, /cost, /model, /skills, /skill, /mcp, /review, /permission)
 scoder
 ```
 
@@ -234,6 +234,7 @@ Read the current diff. Check for: null derefs, injection risks, ...
 |---|---|
 | `/help` | command list |
 | `/clear` | reset conversation + agent context |
+| `/compact` | summarize older history now (manual compaction) |
 | `/cost` | session token usage |
 | `/model` | active model/provider/build |
 | `/skills` | list discovered skills |
@@ -245,6 +246,23 @@ Read the current diff. Check for: null derefs, injection risks, ...
 
 In the TUI, **Tab** completes commands (and `/skill` names, `/mcp <server> <tool>` arguments), **↑/↓** recall sent-message history.
 
+### Context compaction
+
+Long runs are summarized automatically when history reaches `contextWindow × trigger` (default **80%**). Mechanical trimming only starts later, at **95%** of the window, so compaction gets the first chance to preserve task state. `/compact` runs the same summarization immediately (useful mid-session or when auto-compaction is disabled).
+
+```jsonc
+// .scoderrc.json — all fields optional
+"compaction": {
+  "trigger": 0.8,      // fraction of the model window that triggers compaction
+  "keep": 0.15,        // recent-history fraction kept verbatim
+  "buffer": 0.15,      // extra recent-history fraction never summarized
+  "contextWindow": 128000 // override the model-catalog window
+}
+// "compaction": false disables automatic compaction (mechanical trim only)
+```
+
+`/compact` remains available even when automatic compaction is disabled.
+
 ### @file mentions
 
 Prefix any path with `@` in your task to inline its content into the agent's context:
@@ -377,7 +395,7 @@ Features:
 - **Header row 2** — (no longer present; phase breadcrumb + metrics moved into the sidebar / status bar to avoid duplication)
 - **Diff cards** (`✎`) — every file write/edit renders as a unified diff (`+` green / `-` red / `@@` cyan hunk headers); the same diff also flows out of the HTTP SSE stream
 - **Status bar** — model, token usage (input/output/cached), scroll position, keybind hints
-- **Slash commands** — `/help`, `/clear`, `/cost`, `/model`, `/skills`, `/skill`, `/mcp`, `/review`, `/permission`, `/exit` (identical to the REPL)
+- **Slash commands** — `/help`, `/clear`, `/compact`, `/cost`, `/model`, `/skills`, `/skill`, `/mcp`, `/review`, `/permission`, `/exit` (identical to the REPL)
 - **Multi-turn** — keep typing follow-ups after a task finishes; the conversation context carries over (same as the REPL)
 - **Scrollback** — `PgUp`/`PgDn` page in 0.8-viewport steps, `Home`/`End` jump to top/bottom, `Esc` returns to the live tail (press again to abort); rendering is capped at the last 200 items for smooth scrolling on long runs
 - **Keybinds** — `Enter` send · `PgUp`/`PgDn` scroll · `Esc` reset scroll / abort · `Ctrl+C` quit

package/dist/agent.js

@@ -4,13 +4,13 @@ import { AnthropicClient } from "./provider-anthropic.js";
 import { getTool, allToolSpecs, setMaxOutputChars } from "./tools.js";
 import { invalidateFileIndex } from "./tui/at-complete.js";
 import { detectBuildCommand, runBuild } from "./build.js";
-import { trimHistory, summariseOutput, expandMentions } from "./context.js";
+import { trimHistory, summariseOutput, expandMentions, MAX_HISTORY_TOKENS, historyTokenBudget } from "./context.js";
 import { createGuardrailEngine, CHAT_DONE_MARKER } from "./guardrails.js";
 import { PROMPT_VERSION } from "./prompt.js";
 import { buildSystemPrompt, buildEnvInfo, buildSkillsBlock, buildAgentsBlock, buildMcpBlock } from "./prompt-builder.js";
 import { PermissionChecker } from "./permissions.js";
 import { SessionStore, EventSessionStore } from "./session.js";
-import { DEFAULT_COMPACTION, shouldCompact, extractSummaryInput, COMPACTION_INSTRUCTION, applyCompaction } from "./compaction.js";
+import { DEFAULT_COMPACTION, shouldCompact, estimateTokens, findCutIndex, extractSummaryInput, COMPACTION_INSTRUCTION, applyCompaction } from "./compaction.js";
 import { SnapshotManager } from "./snapshot.js";
 import { contextWindowFor } from "./model-catalog.js";
 import { JsonlLogger } from "./logger.js";
@@ -784,6 +784,20 @@ export class Agent {
         await this.connectMcp();
         return this.runLoop(session.steps ?? 0, buildCmd, lastBuild);
     }
+    /**
+     * Resolve compaction settings from config + model catalog (H-10/I-02).
+     * Also used by `/compact`: manual compaction is an explicit user action and
+     * stays available even when auto-compaction is disabled.
+     */
+    compactionSettings() {
+        const catalogWindow = contextWindowFor(this.config.provider, this.config.model);
+        const overrides = this.config.compaction;
+        return {
+            ...DEFAULT_COMPACTION,
+            contextWindow: this.config.contextWindow ?? catalogWindow,
+            ...(overrides && typeof overrides === "object" ? overrides : {}),
+        };
+    }
     /**
      * The shared autonomous loop:
      * LLM plans -> tool calls -> build -> on failure: read error, patch, retry.
@@ -797,14 +811,16 @@ export class Agent {
         // H-10 compaction config (false = disabled → mechanical trim only).
         // I-02: contextWindow từ model catalog (lookup sync, cache/fallback) thay
         // vì default 128k cứng — compaction trigger chính xác theo model.
-        const catalogWindow = contextWindowFor(this.config.provider, this.config.model);
-        const compactionCfg = this.config.compaction === false
-            ? null
-            : {
-                ...DEFAULT_COMPACTION,
-                contextWindow: this.config.contextWindow ?? catalogWindow,
-                ...(this.config.compaction ?? {}),
-            };
+        const compactionCfg = this.config.compaction === false ? null : this.compactionSettings();
+        // Compaction-aware trim: mechanical trim scales with the model window and
+        // starts AFTER compaction (95% vs 80% trigger). Disabled compaction keeps
+        // the legacy conservative 90k cap.
+        const trimBudget = compactionCfg
+            ? historyTokenBudget(compactionCfg.contextWindow)
+            : MAX_HISTORY_TOKENS;
+        // When a run ends early (guardrail finish/build verification) compaction is
+        // skipped, so never leave a near-full window for the next turn.
+        const safeTrimBudget = Math.min(trimBudget, MAX_HISTORY_TOKENS);
         while (steps < this.config.maxSteps && !this.aborted) {
             // ── Safe step boundary: deliver steered user input (H-08) ────────────
             const steered = this.drainSteerInbox();
@@ -980,7 +996,7 @@ export class Agent {
                     lastBuild = await this.checkBuild(buildCmd);
                     if (lastBuild.success) {
                         if (doTrim)
-                            this.messages = trimHistory(this.messages);
+                            this.messages = trimHistory(this.messages, safeTrimBudget);
                         return this.finish(true, steps, buildCmd, a.successSummary);
                     }
                     reminders.push(`${a.failReminder}\n${summariseOutput(lastBuild.output)}\nFix and continue.`);
@@ -992,34 +1008,46 @@ export class Agent {
                     for (const r of reminders)
                         this.messages.push({ role: "user", content: r });
                     if (doTrim)
-                        this.messages = trimHistory(this.messages);
+                        this.messages = trimHistory(this.messages, safeTrimBudget);
                     return this.finish(a.success, steps, buildCmd, a.summary, a.chatOnly ?? false);
                 }
             }
             for (const r of reminders)
                 this.messages.push({ role: "user", content: r });
-            if (doTrim)
-                this.messages = trimHistory(this.messages);
             // H-10: LLM compaction when history approaches the context window.
+            // Runs BEFORE mechanical trim: trim drops whole turns, which could push
+            // the history below the trigger before compaction ever sees it.
             if (compactionCfg && shouldCompact(this.messages, compactionCfg)) {
                 try {
                     ui.info("compaction: summarizing older history…");
+                    const tokensBefore = estimateTokens(this.messages);
                     const summaryInput = extractSummaryInput(this.currentTask, this.messages);
                     const summaryRes = await this.client.chat([
                         ...this.messages,
                         { role: "user", content: `${summaryInput}\n\n${COMPACTION_INSTRUCTION}` },
                     ], [], // no tools for the summarizer call
                     { signal: this.runSignal.signal });
+                    this.recordLlmUsage(summaryRes.usage);
                     this.messages = applyCompaction(this.messages, redactSecrets(summaryRes.message.content ?? "History summarized."), compactionCfg);
-                    this.events.append({ type: "compaction.ran", tokensBefore: 0, summary: (summaryRes.message.content ?? "").slice(0, 2000) });
-                    ui.info(`compaction: done (history now ${this.messages.length} messages)`);
+                    const tokensAfter = estimateTokens(this.messages);
+                    this.events.append({
+                        type: "compaction.ran",
+                        tokensBefore,
+                        tokensAfter,
+                        summary: (summaryRes.message.content ?? "").slice(0, 2000),
+                    });
+                    ui.info(`compaction: done (${tokensBefore} → ${tokensAfter} tokens, history now ${this.messages.length} messages)`);
                 }
                 catch (err) {
                     // Compaction is best-effort — mechanical trim stays as fallback.
                     ui.warn(`compaction failed (${err.message.slice(0, 100)}) — using mechanical trim`);
-                    this.messages = trimHistory(this.messages);
+                    // Fallback uses the legacy conservative cap: the next LLM call must
+                    // not leave a near-full window if summarization failed.
+                    this.messages = trimHistory(this.messages, safeTrimBudget);
                 }
             }
+            if (doTrim)
+                this.messages = trimHistory(this.messages, trimBudget);
             // Persist session state after every step (enables resume after crash/SIGINT)
             this.saveSession(steps, buildCmd, lastBuild);
             this.events.releaseExecution(steps);
@@ -1077,6 +1105,56 @@ export class Agent {
         return res;
     }
     // ── Frontend-facing APIs (REPL/TUI slash commands) ─────────────────────────
+    /**
+     * Manual compaction (`/compact`): summarize older history now, keeping the
+     * system prompt + the most recent turns. Explicit user action — available
+     * even when auto-compaction is disabled via `"compaction": false`.
+     */
+    async compactHistory() {
+        if (this.messages.length === 0) {
+            return { ok: false, message: "nothing to compact — no conversation yet" };
+        }
+        const cfg = this.compactionSettings();
+        const firstContent = this.messages[0]?.role === "system" ? 1 : 0;
+        if (findCutIndex(this.messages, cfg) <= firstContent) {
+            return { ok: false, message: "nothing to compact — conversation is already short" };
+        }
+        const tokensBefore = estimateTokens(this.messages);
+        const messagesBefore = this.messages.length;
+        const summaryInput = extractSummaryInput(this.currentTask, this.messages);
+        ui.info("compaction: summarizing older history…");
+        try {
+            // A previous run interrupted with Esc leaves the shared signal aborted.
+            if (this.runSignal.signal.aborted)
+                this.resetRunSignal();
+            const summaryRes = await this.client.chat([
+                ...this.messages,
+                { role: "user", content: `${summaryInput}\n\n${COMPACTION_INSTRUCTION}` },
+            ], [], // no tools for the summarizer call
+            { signal: this.runSignal.signal });
+            this.recordLlmUsage(summaryRes.usage);
+            const summary = redactSecrets(summaryRes.message.content ?? "History summarized.");
+            this.messages = applyCompaction(this.messages, summary, cfg);
+            const tokensAfter = estimateTokens(this.messages);
+            this.events.append({
+                type: "compaction.ran",
+                tokensBefore,
+                tokensAfter,
+                manual: true,
+                summary: summary.slice(0, 2000),
+            });
+            ui.info(`compaction: done (${tokensBefore} → ${tokensAfter} tokens)`);
+            return {
+                ok: true,
+                message: `compaction done: ${messagesBefore} → ${this.messages.length} messages · ~${tokensBefore} → ~${tokensAfter} tokens`,
+            };
+        }
+        catch (err) {
+            const msg = err.message.slice(0, 200);
+            ui.warn(`compaction failed (${msg})`);
+            return { ok: false, message: `compaction failed: ${msg}` };
+        }
+    }
     /** Skills visible to this project (for /skills). */
     getSkills() {
         return this.skills;

package/dist/context.js

@@ -3,11 +3,22 @@ import { readFileSync, readdirSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 const MAX_MESSAGES = 120; // keep history under control for long runs
 /**
- * Total history token budget (I-10: token-accurate via gpt-tokenizer, thay
- * char heuristic 100k chars ≈ 25k tokens). Conservative: system prompt +
- * tool defs + reply buffer chiếm phần còn lại của contextWindow.
+ * Default history token budget when compaction is disabled (I-10:
+ * token-accurate via gpt-tokenizer, thay char heuristic 100k chars ≈ 25k
+ * tokens). Conservative: system prompt + tool defs + reply buffer chiếm phần
+ * còn lại của contextWindow.
  */
-const MAX_HISTORY_TOKENS = 90_000;
+export const MAX_HISTORY_TOKENS = 90_000;
+/**
+ * Fraction of the model context window where mechanical trim starts when
+ * compaction is enabled. Must stay ABOVE the compaction trigger (default
+ * 0.8) so semantic compaction gets a chance to run first.
+ */
+export const HISTORY_TRIM_FRACTION = 0.95;
+/** Mechanical trim budget for a given context window (floor 2k). */
+export function historyTokenBudget(contextWindow) {
+    return Math.max(2_000, Math.floor(contextWindow * HISTORY_TRIM_FRACTION));
+}
 /** Tool results older than this many recent tool messages get pruned. */
 const KEEP_RECENT_TOOL_RESULTS = 20;
 /** Token count for one message (tool_calls arguments included). Never throws. */
@@ -25,16 +36,19 @@ function messageTokens(m) {
 }
 const historyTokens = (msgs) => msgs.reduce((n, m) => n + messageTokens(m), 0);
 /**
- * Trim message history to stay within token budget. Layered strategy
+ * Trim message history to stay within a token budget. Layered strategy
  * (context engineering — inspired by compaction patterns, from scratch):
  *   1. Message-count cap: keep system + newest MAX_MESSAGES-1.
  *   2. Token budget: drop the OLDEST WHOLE TURNS (from a user message up to
- *      the next user message) until under MAX_HISTORY_TOKENS — dropping whole
+ *      the next user message) until under `maxTokens` — dropping whole
  *      turns never orphans an assistant tool_calls / tool result pair.
  *   3. Old tool results (outside the recent window) are pruned in place to a
  *      short placeholder — their content dominated the budget anyway.
+ *
+ * `maxTokens` defaults to the legacy 90k cap; callers with compaction enabled
+ * pass `historyTokenBudget(contextWindow)` so trim runs *after* compaction.
  */
-export function trimHistory(messages) {
+export function trimHistory(messages, maxTokens = MAX_HISTORY_TOKENS) {
     let out = messages;
     // 1) Message-count cap
     if (out.length > MAX_MESSAGES) {
@@ -43,7 +57,7 @@ export function trimHistory(messages) {
         out = system ? [system, ...rest.slice(-(MAX_MESSAGES - 1))] : rest.slice(-(MAX_MESSAGES - 1));
     }
     // 2) Token budget — drop oldest whole turns, never the system message
-    while (out.length > 2 && historyTokens(out) > MAX_HISTORY_TOKENS) {
+    while (out.length > 2 && historyTokens(out) > maxTokens) {
         const firstIdx = out[0].role === "system" ? 1 : 0;
         if (out[firstIdx]?.role !== "user")
             break; // no clean turn boundary — stop

package/dist/tui/command-registry.js

@@ -55,6 +55,19 @@ export function coreCommands() {
                 notice(formatUsage(host.agent()?.getUsage() ?? { calls: 0, inputTokens: 0, outputTokens: 0, cachedTokens: 0 }));
             },
         },
+        {
+            name: "/compact",
+            description: "summarize older history now (manual compaction)",
+            async run(_slash, host, notice) {
+                const agent = host.agent();
+                if (!agent)
+                    return notice("agent not ready — start a task first", "warn");
+                if (host.isRunning?.())
+                    return notice("agent is running — wait or Esc first", "warn");
+                const r = await agent.compactHistory();
+                notice(r.message, r.ok ? "info" : "warn");
+            },
+        },
         {
             name: "/skills",
             description: "list discovered skills (SKILL.md)",

package/dist/tui/commands.js

@@ -9,6 +9,7 @@ export const SLASH_COMMANDS = [
     { cmd: "/diff", desc: "show diffs: /diff turn | session | branch" },
     { cmd: "/theme", desc: "switch palette: /theme <name> — /theme list (mission|paper|mono|light|high-contrast|solarized)" },
     { cmd: "/clear", desc: "clear the conversation and reset agent context" },
+    { cmd: "/compact", desc: "summarize older history now (manual compaction)" },
     { cmd: "/cost", desc: "token usage of the current session" },
     { cmd: "/model", desc: "show the active model & provider" },
     { cmd: "/skills", desc: "list discovered skills (SKILL.md)" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s-app-scoder-agent",
-  "version": "0.8.20",
+  "version": "0.8.21",
   "description": "Autonomous coding agent CLI — writes, edits, and builds code autonomously until the project compiles without errors.",
   "type": "module",
   "main": "dist/index.js",