@iinm/plain-agent 1.13.1 → 1.14.0

package/README.md

@@ -1,7 +1,7 @@
 # Plain Agent
 
 [![CodeQL](https://github.com/iinm/plain-agent/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/iinm/plain-agent/actions/workflows/github-code-scanning/codeql)
-[![Socket Badge](https://badge.socket.dev/npm/package/@iinm/plain-agent/1.13.1)](https://socket.dev/npm/package/@iinm/plain-agent)
+[![Socket Badge](https://badge.socket.dev/npm/package/@iinm/plain-agent/1.14.0)](https://socket.dev/npm/package/@iinm/plain-agent)
 [![install size](https://packagephobia.com/badge?p=@iinm/plain-agent)](https://packagephobia.com/result?p=@iinm/plain-agent)
 
 A lightweight terminal-based coding agent focused on safety and low token cost
@@ -229,7 +229,7 @@ A few design choices keep token usage low:
 
 - Minimal system prompt — the [system prompt](https://github.com/iinm/plain-agent/blob/main/src/prompt.mjs) contains only what the agent needs to function. 
 - Output truncation — when a command or MCP tool produces large output, it is truncated and saved to a file. The agent can then read only the relevant parts.
-- Context compaction — when the context grows large, you can run `/compact` to discard old messages and reload task state from a memory file.
+- Context compaction — run `/compact` to discard old messages and reload task state from a memory file. This also happens automatically when input tokens exceed a configurable soft limit.
 - MCP tool filtering — MCP servers often expose many tools. Use `enabledTools` in the server config to enable only the ones you need, which reduces the number of tool definitions sent to the model.
 
 ### Claude Code Compatibility
@@ -745,6 +745,17 @@ Files are loaded in the following order. Settings in later files override earlie
     }
   },
 
+  // Auto-compact: when input tokens exceed the soft limit after a tool execution,
+  // the agent is prompted to update the memory file and call compact_context.
+  // Reduces noise and token costs before hitting the model's hard limit.
+  "autoCompact": {
+    "softLimit": 120000,
+    // Optional: override per model (prefix match on name+variant)
+    "softLimitPerModelPrefix": {
+      "gemini-2.5-pro": 500000
+    }
+  },
+
   // Override the default notification command
   "notifyCmd": { "command": "plain-notify-desktop", "args": [] }
 }

package/config/config.predefined.json

@@ -1,4 +1,5 @@
 {
+  "autoCompact": { "softLimit": 120000 },
   "autoApproval": {
     "defaultAction": "ask",
     "maxApprovals": 50,
@@ -154,12 +155,18 @@
     "tests": [
       {
         "desc": "find should be denied",
-        "toolUse": { "toolName": "exec_command", "input": { "command": "find" } },
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "find" }
+        },
         "expectedAction": "deny"
       },
       {
         "desc": "grep should be denied",
-        "toolUse": { "toolName": "exec_command", "input": { "command": "grep" } },
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "grep" }
+        },
         "expectedAction": "deny"
       },
       {
@@ -362,7 +369,12 @@
           "toolName": "exec_command",
           "input": {
             "command": "gh",
-            "args": ["api", "--method", "GET", "repos/owner/repo/pulls/123/comments"]
+            "args": [
+              "api",
+              "--method",
+              "GET",
+              "repos/owner/repo/pulls/123/comments"
+            ]
           }
         },
         "expectedAction": "allow"
@@ -371,7 +383,10 @@
         "desc": "gh api without --method should be denied",
         "toolUse": {
           "toolName": "exec_command",
-          "input": { "command": "gh", "args": ["api", "repos/owner/repo/pulls"] }
+          "input": {
+            "command": "gh",
+            "args": ["api", "repos/owner/repo/pulls"]
+          }
         },
         "expectedAction": "deny"
       },
@@ -398,7 +413,10 @@
         "desc": "bash -c with pipe should not match deny pattern",
         "toolUse": {
           "toolName": "exec_command",
-          "input": { "command": "bash", "args": ["-c", "echo hello | grep hello"] }
+          "input": {
+            "command": "bash",
+            "args": ["-c", "echo hello | grep hello"]
+          }
         },
         "expectedAction": null
       },
@@ -406,7 +424,10 @@
         "desc": "bash -c with redirect should not match deny pattern",
         "toolUse": {
           "toolName": "exec_command",
-          "input": { "command": "bash", "args": ["-c", "echo hello > file.txt"] }
+          "input": {
+            "command": "bash",
+            "args": ["-c", "echo hello > file.txt"]
+          }
         },
         "expectedAction": null
       },
@@ -422,7 +443,10 @@
         "desc": "bash -c with semicolon should not match deny pattern",
         "toolUse": {
           "toolName": "exec_command",
-          "input": { "command": "bash", "args": ["-c", "for i in *.txt; do echo $i; done"] }
+          "input": {
+            "command": "bash",
+            "args": ["-c", "for i in *.txt; do echo $i; done"]
+          }
         },
         "expectedAction": null
       },
@@ -470,6 +494,9 @@
           "cache_read_input_tokens": 0.1,
           "cache_creation_input_tokens": 1.25
         }
+      },
+      "autoCompact": {
+        "inputTokensKeys": ["input_tokens", "cache_read_input_tokens"]
       }
     },
     {
@@ -497,6 +524,9 @@
           "cache_read_input_tokens": 0.1,
           "cache_creation_input_tokens": 1.25
         }
+      },
+      "autoCompact": {
+        "inputTokensKeys": ["input_tokens", "cache_read_input_tokens"]
       }
     },
     {
@@ -525,6 +555,9 @@
           "cache_read_input_tokens": 0.3,
           "cache_creation_input_tokens": 3.75
         }
+      },
+      "autoCompact": {
+        "inputTokensKeys": ["input_tokens", "cache_read_input_tokens"]
       }
     },
     {
@@ -553,6 +586,9 @@
           "cache_read_input_tokens": 0.3,
           "cache_creation_input_tokens": 3.75
         }
+      },
+      "autoCompact": {
+        "inputTokensKeys": ["input_tokens", "cache_read_input_tokens"]
       }
     },
     {
@@ -581,6 +617,9 @@
           "cache_read_input_tokens": 0.5,
           "cache_creation_input_tokens": 6.25
         }
+      },
+      "autoCompact": {
+        "inputTokensKeys": ["input_tokens", "cache_read_input_tokens"]
       }
     },
     {
@@ -609,6 +648,9 @@
           "cache_read_input_tokens": 0.5,
           "cache_creation_input_tokens": 6.25
         }
+      },
+      "autoCompact": {
+        "inputTokensKeys": ["input_tokens", "cache_read_input_tokens"]
       }
     },
     {
@@ -635,8 +677,11 @@
           "input_tokens": 10,
           "output_tokens": 50,
           "cache_read_input_tokens": 1,
-          "cache_creation_input_tokens": 12.50
+          "cache_creation_input_tokens": 12.5
         }
+      },
+      "autoCompact": {
+        "inputTokensKeys": ["input_tokens", "cache_read_input_tokens"]
       }
     },
     {
@@ -663,8 +708,11 @@
           "input_tokens": 10,
           "output_tokens": 50,
           "cache_read_input_tokens": 1,
-          "cache_creation_input_tokens": 12.50
+          "cache_creation_input_tokens": 12.5
         }
+      },
+      "autoCompact": {
+        "inputTokensKeys": ["input_tokens", "cache_read_input_tokens"]
       }
     },
 
@@ -692,6 +740,9 @@
           "cache_read_input_tokens": 0.1,
           "cache_creation_input_tokens": 1.25
         }
+      },
+      "autoCompact": {
+        "inputTokensKeys": ["input_tokens", "cache_read_input_tokens"]
       }
     },
     {
@@ -718,6 +769,9 @@
           "cache_read_input_tokens": 0.1,
           "cache_creation_input_tokens": 1.25
         }
+      },
+      "autoCompact": {
+        "inputTokensKeys": ["input_tokens", "cache_read_input_tokens"]
       }
     },
     {
@@ -745,6 +799,9 @@
           "cache_read_input_tokens": 0.3,
           "cache_creation_input_tokens": 3.75
         }
+      },
+      "autoCompact": {
+        "inputTokensKeys": ["input_tokens", "cache_read_input_tokens"]
       }
     },
     {
@@ -772,6 +829,9 @@
           "cache_read_input_tokens": 0.3,
           "cache_creation_input_tokens": 3.75
         }
+      },
+      "autoCompact": {
+        "inputTokensKeys": ["input_tokens", "cache_read_input_tokens"]
       }
     },
     {
@@ -799,6 +859,9 @@
           "cache_read_input_tokens": 0.5,
           "cache_creation_input_tokens": 6.25
         }
+      },
+      "autoCompact": {
+        "inputTokensKeys": ["input_tokens", "cache_read_input_tokens"]
       }
     },
     {
@@ -826,6 +889,9 @@
           "cache_read_input_tokens": 0.5,
           "cache_creation_input_tokens": 6.25
         }
+      },
+      "autoCompact": {
+        "inputTokensKeys": ["input_tokens", "cache_read_input_tokens"]
       }
     },
     {
@@ -851,8 +917,11 @@
           "input_tokens": 10,
           "output_tokens": 50,
           "cache_read_input_tokens": 1,
-          "cache_creation_input_tokens": 12.50
+          "cache_creation_input_tokens": 12.5
         }
+      },
+      "autoCompact": {
+        "inputTokensKeys": ["input_tokens", "cache_read_input_tokens"]
       }
     },
     {
@@ -878,8 +947,11 @@
           "input_tokens": 10,
           "output_tokens": 50,
           "cache_read_input_tokens": 1,
-          "cache_creation_input_tokens": 12.50
+          "cache_creation_input_tokens": 12.5
         }
+      },
+      "autoCompact": {
+        "inputTokensKeys": ["input_tokens", "cache_read_input_tokens"]
       }
     },
 
@@ -912,7 +984,8 @@
           "cachedContentTokenCount": -1.35,
           "candidatesTokenCount": 9
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["promptTokenCount"] }
     },
     {
       "name": "gemini-3.5-flash",
@@ -943,7 +1016,8 @@
           "cachedContentTokenCount": -1.35,
           "candidatesTokenCount": 9
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["promptTokenCount"] }
     },
     {
       "name": "gemini-3.1-pro-preview",
@@ -974,7 +1048,8 @@
           "cachedContentTokenCount": -1.8,
           "candidatesTokenCount": 12
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["promptTokenCount"] }
     },
     {
       "name": "gemini-3.1-pro-preview",
@@ -1005,7 +1080,8 @@
           "cachedContentTokenCount": -1.8,
           "candidatesTokenCount": 12
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["promptTokenCount"] }
     },
 
     {
@@ -1036,7 +1112,8 @@
           "cachedContentTokenCount": -1.35,
           "candidatesTokenCount": 9
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["promptTokenCount"] }
     },
     {
       "name": "gemini-3.5-flash",
@@ -1066,7 +1143,8 @@
           "cachedContentTokenCount": -1.35,
           "candidatesTokenCount": 9
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["promptTokenCount"] }
     },
     {
       "name": "gemini-3.1-pro-preview",
@@ -1096,7 +1174,8 @@
           "cachedContentTokenCount": -1.8,
           "candidatesTokenCount": 12
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["promptTokenCount"] }
     },
     {
       "name": "gemini-3.1-pro-preview",
@@ -1126,7 +1205,8 @@
           "cachedContentTokenCount": -1.8,
           "candidatesTokenCount": 12
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["promptTokenCount"] }
     },
 
     {
@@ -1154,7 +1234,8 @@
           "input_tokens_details.cached_tokens": -0.675,
           "output_tokens": 4.5
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["input_tokens"] }
     },
     {
       "name": "gpt-5.4-mini",
@@ -1181,7 +1262,8 @@
           "input_tokens_details.cached_tokens": -0.675,
           "output_tokens": 4.5
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["input_tokens"] }
     },
     {
       "name": "gpt-5.4-mini",
@@ -1208,7 +1290,8 @@
           "input_tokens_details.cached_tokens": -0.675,
           "output_tokens": 4.5
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["input_tokens"] }
     },
     {
       "name": "gpt-5.5",
@@ -1235,7 +1318,8 @@
           "input_tokens_details.cached_tokens": -4.5,
           "output_tokens": 30
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["input_tokens"] }
     },
     {
       "name": "gpt-5.5",
@@ -1262,7 +1346,8 @@
           "input_tokens_details.cached_tokens": -4.5,
           "output_tokens": 30
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["input_tokens"] }
     },
     {
       "name": "gpt-5.5",
@@ -1289,7 +1374,8 @@
           "input_tokens_details.cached_tokens": -4.5,
           "output_tokens": 30
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["input_tokens"] }
     },
 
     {
@@ -1316,7 +1402,8 @@
           "input_tokens_details.cached_tokens": -0.675,
           "output_tokens": 4.5
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["input_tokens"] }
     },
     {
       "name": "gpt-5.4-mini",
@@ -1342,7 +1429,8 @@
           "input_tokens_details.cached_tokens": -0.675,
           "output_tokens": 4.5
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["input_tokens"] }
     },
     {
       "name": "gpt-5.4-mini",
@@ -1368,7 +1456,8 @@
           "input_tokens_details.cached_tokens": -0.675,
           "output_tokens": 4.5
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["input_tokens"] }
     },
     {
       "name": "gpt-5.5",
@@ -1394,7 +1483,8 @@
           "input_tokens_details.cached_tokens": -4.5,
           "output_tokens": 30
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["input_tokens"] }
     },
     {
       "name": "gpt-5.5",
@@ -1420,7 +1510,8 @@
           "input_tokens_details.cached_tokens": -4.5,
           "output_tokens": 30
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["input_tokens"] }
     },
     {
       "name": "gpt-5.5",
@@ -1446,7 +1537,8 @@
           "input_tokens_details.cached_tokens": -4.5,
           "output_tokens": 30
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["input_tokens"] }
     },
 
     {
@@ -1468,9 +1560,10 @@
         "prices": {
           "prompt_tokens": 0.15,
           "prompt_tokens_details.cached_tokens": -0.14,
-          "completion_tokens": 0.6 
+          "completion_tokens": 0.6
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["prompt_tokens"] }
     },
 
     {
@@ -1494,7 +1587,8 @@
           "completion_tokens": 3.2,
           "prompt_tokens_details.cached_tokens": -0.9
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["prompt_tokens"] }
     },
     {
       "name": "glm-5",
@@ -1517,7 +1611,8 @@
           "prompt_tokens": 1,
           "completion_tokens": 3.2
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["prompt_tokens"] }
     },
 
     {
@@ -1541,7 +1636,8 @@
           "prompt_tokens_details.cached_tokens": -1.14,
           "completion_tokens": 4.4
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["prompt_tokens"] }
     },
 
     {
@@ -1557,7 +1653,8 @@
           "model": "Kimi-K2.6",
           "reasoning_effort": "high"
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["prompt_tokens"] }
     },
     {
       "name": "kimi-k2.7-code",
@@ -1580,7 +1677,8 @@
           "prompt_tokens_details.cached_tokens": -0.76,
           "completion_tokens": 4
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["prompt_tokens"] }
     },
 
     {
@@ -1604,7 +1702,8 @@
           "prompt_tokens_details.cached_tokens": -1.6,
           "completion_tokens": 3.48
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["prompt_tokens"] }
     },
     {
       "name": "deepseek-v4-pro",
@@ -1619,7 +1718,8 @@
           "model": "DeepSeek-V4-Pro",
           "reasoning_effort": "high"
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["prompt_tokens"] }
     },
 
     {
@@ -1643,7 +1743,8 @@
           "prompt_tokens_details.cached_tokens": -0.24,
           "completion_tokens": 1.2
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["prompt_tokens"] }
     },
 
     {
@@ -1667,7 +1768,8 @@
           "prompt_tokens_details.cached_tokens": -0.32,
           "completion_tokens": 1.6
         }
-      }
+      },
+      "autoCompact": { "inputTokensKeys": ["prompt_tokens"] }
     },
 
     {
@@ -1689,6 +1791,9 @@
             }
           }
         }
+      },
+      "autoCompact": {
+        "inputTokensKeys": ["inputTokens", "cacheReadInputTokens"]
       }
     },
     {
@@ -1713,6 +1818,9 @@
             }
           }
         }
+      },
+      "autoCompact": {
+        "inputTokensKeys": ["inputTokens", "cacheReadInputTokens"]
       }
     }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iinm/plain-agent",
-  "version": "1.13.1",
+  "version": "1.14.0",
   "description": "A lightweight terminal-based coding agent focused on safety and low token cost",
   "license": "MIT",
   "type": "module",

package/src/agent.d.ts

@@ -61,4 +61,8 @@ export type AgentConfig = {
   };
   /** When provided, the agent restores its state from this snapshot. */
   initialState?: SessionState | null;
+  /** Soft limit on input tokens; triggers auto-compact prompt when exceeded. */
+  contextSoftLimit?: number;
+  /** Keys in providerTokenUsage to sum for input token count. */
+  inputTokensKeys?: string[];
 };

package/src/agent.mjs

@@ -34,6 +34,8 @@ export function createAgent({
   modelCostConfig,
   sessionMetadata,
   initialState,
+  contextSoftLimit,
+  inputTokensKeys,
 }) {
   /** @type {UserEventEmitter} */
   const userEventEmitter = new EventEmitter();
@@ -195,6 +197,8 @@ export function createAgent({
     toolUseApprover,
     subagentManager,
     pauseSignal,
+    contextSoftLimit,
+    inputTokensKeys,
   });
 
   userEventEmitter.on("userInput", agentLoop.handleUserInput);

package/src/agentLoop.mjs

@@ -7,6 +7,8 @@
  */
 
 import { styleText } from "node:util";
+import { buildCompactPrompt } from "./prompt.mjs";
+import { extractInputTokenCount } from "./tokenUsage.mjs";
 import { compactContextToolName } from "./tools/compactContext.mjs";
 
 /**
@@ -55,6 +57,8 @@ function applyCompactContextIfCalled(stateManager, toolUseParts, toolResults) {
  * @property {ToolUseApprover} toolUseApprover - Tool use approval checker
  * @property {SubagentManager} subagentManager - Subagent manager instance
  * @property {PauseSignal} pauseSignal - Signal to pause auto-approve after current tool completes
+ * @property {number} [contextSoftLimit] - Soft limit on input tokens for auto-compact
+ * @property {string[]} [inputTokensKeys] - Keys in providerTokenUsage to sum for input token count
  */
 
 /**
@@ -74,6 +78,8 @@ export function createAgentLoop({
   toolUseApprover,
   subagentManager,
   pauseSignal,
+  contextSoftLimit,
+  inputTokensKeys,
 }) {
   const inputHandler = createInputHandler({
     stateManager,
@@ -102,7 +108,7 @@ export function createAgentLoop({
   async function runTurnLoop() {
     let thinkingLoops = 0;
     const maxThinkingLoops = 5;
-
+    let turnsAfterCompactPrompt = -1;
     while (true) {
       // Check if auto-approve was paused by Ctrl-C during tool execution
       if (pauseSignal.isPaused()) {
@@ -240,6 +246,7 @@ export function createAgentLoop({
       if (
         applyCompactContextIfCalled(stateManager, toolUseParts, toolResults)
       ) {
+        turnsAfterCompactPrompt = -1;
         continue;
       }
 
@@ -254,6 +261,40 @@ export function createAgentLoop({
       } else {
         stateManager.appendMessages([{ role: "user", content: toolResults }]);
       }
+
+      // Auto-compact: insert prompt if context exceeds soft limit
+      if (contextSoftLimit && inputTokensKeys && providerTokenUsage) {
+        const inputTokens = extractInputTokenCount(
+          providerTokenUsage,
+          inputTokensKeys,
+        );
+        if (inputTokens !== undefined && inputTokens > contextSoftLimit) {
+          if (0 <= turnsAfterCompactPrompt && turnsAfterCompactPrompt < 3) {
+            turnsAfterCompactPrompt += 1;
+          } else {
+            stateManager.appendMessages([
+              {
+                role: "user",
+                content: [
+                  {
+                    type: "text",
+                    text: buildCompactPrompt({
+                      isSubagent: subagentManager.isSubagentActive(),
+                    }),
+                  },
+                ],
+              },
+            ]);
+            turnsAfterCompactPrompt = 0;
+            console.error(
+              styleText(
+                "yellow",
+                `\nContext exceeded soft limit (${inputTokens.toLocaleString()} / ${contextSoftLimit.toLocaleString()} tokens). Auto-compact prompt inserted.`,
+              ),
+            );
+          }
+        }
+      }
     }
   }
 

package/src/cli/commands.mjs

@@ -8,7 +8,10 @@ import { styleText } from "node:util";
 import { loadAgentRoles } from "../context/loadAgentRoles.mjs";
 import { loadPrompts } from "../context/loadPrompts.mjs";
 import { loadUserMessageContext } from "../context/loadUserMessageContext.mjs";
-import { CLAUDE_CODE_COMPATIBILITY_NOTES } from "../prompt.mjs";
+import {
+  buildCompactPrompt,
+  CLAUDE_CODE_COMPATIBILITY_NOTES,
+} from "../prompt.mjs";
 import { parseFileRange } from "../utils/parseFileRange.mjs";
 import { readFileRange } from "../utils/readFileRange.mjs";
 import { toOneLine } from "../utils/toOneLine.mjs";
@@ -140,14 +143,10 @@ export function createCommandHandler({
 
     // /compact [reason]
     if (/^\/compact( |$)/i.test(inputTrimmed)) {
-      const invocation = inputTrimmed;
-      const message = [
-        `System: This prompt was invoked as "${invocation}".`,
-        "",
-        "Compact the conversation context:",
-        "1. Update the memory file for the current task so it fully captures the task overview, progress, decisions, and next steps in a self-contained way.",
-        '2. Then call the "compact_context" tool alone with that memory file path and a brief reason.',
-      ].join("\n");
+      const message = buildCompactPrompt({
+        invocation: inputTrimmed,
+        isSubagent: agentCommands.getActiveSubagent() !== null,
+      });
       userEventEmitter.emit("userInput", [{ type: "text", text: message }]);
       return "continue";
     }

package/src/config.d.ts

@@ -87,6 +87,10 @@ export type AppConfig = {
   };
   mcpServers?: Record<string, MCPServerConfig>;
   notifyCmd?: { command: string; args?: string[] };
+  autoCompact?: {
+    softLimit?: number;
+    softLimitPerModelPrefix?: Record<string, number>;
+  };
   claudeCodePlugins?: ClaudeCodePluginRepo[];
 };
 

package/src/config.mjs

@@ -124,6 +124,16 @@ export async function loadAppConfig(options = {}) {
         ...(merged.mcpServers ?? {}),
         ...(config.mcpServers ?? {}),
       },
+      autoCompact: config.autoCompact
+        ? {
+            softLimit:
+              config.autoCompact.softLimit ?? merged.autoCompact?.softLimit,
+            softLimitPerModelPrefix: {
+              ...(merged.autoCompact?.softLimitPerModelPrefix ?? {}),
+              ...(config.autoCompact.softLimitPerModelPrefix ?? {}),
+            },
+          }
+        : merged.autoCompact,
       notifyCmd: config.notifyCmd ?? merged.notifyCmd,
       claudeCodePlugins: [
         ...(merged.claudeCodePlugins ?? []),
@@ -223,3 +233,21 @@ async function trustConfigHash(hash) {
   await fs.mkdir(TRUSTED_CONFIG_HASHES_DIR, { recursive: true });
   await fs.writeFile(path.join(TRUSTED_CONFIG_HASHES_DIR, hash), "");
 }
+
+/**
+ * Resolve the effective context soft limit for the given model.
+ *
+ * @param {AppConfig["autoCompact"]} autoCompact
+ * @param {string} modelNameWithVariant - e.g. "claude-sonnet-4-6+thinking-high"
+ * @returns {number | undefined}
+ */
+export function resolveContextSoftLimit(autoCompact, modelNameWithVariant) {
+  if (!autoCompact) return undefined;
+  const perPrefix = autoCompact.softLimitPerModelPrefix;
+  const matched = perPrefix
+    ? Object.entries(perPrefix).find(([prefix]) =>
+        modelNameWithVariant.startsWith(prefix),
+      )?.[1]
+    : undefined;
+  return matched ?? autoCompact.softLimit ?? undefined;
+}

package/src/main.mjs

@@ -16,7 +16,7 @@ import { startBatchSession } from "./cli/batch.mjs";
 import { runCostCommand } from "./cli/cost.mjs";
 import { startInteractiveSession } from "./cli/interactive.mjs";
 import { runTestApprovalCommand } from "./cli/testApproval.mjs";
-import { loadAppConfig } from "./config.mjs";
+import { loadAppConfig, resolveContextSoftLimit } from "./config.mjs";
 import { loadAgentRoles } from "./context/loadAgentRoles.mjs";
 import { loadPrompts } from "./context/loadPrompts.mjs";
 import { AGENT_PROJECT_METADATA_DIR, USER_NAME } from "./env.mjs";
@@ -428,6 +428,12 @@ export async function main(argv = process.argv) {
     },
   });
 
+  // Resolve context soft limit from autoCompact config
+  const contextSoftLimit = resolveContextSoftLimit(
+    appConfig.autoCompact,
+    modelNameWithVariant,
+  );
+
   const { userEventEmitter, agentEventEmitter, agentCommands } = createAgent({
     callModel: agentCallModel,
     prompt,
@@ -442,6 +448,8 @@ export async function main(argv = process.argv) {
       startTime,
     },
     initialState: resumedState,
+    contextSoftLimit,
+    inputTokensKeys: modelDef.autoCompact?.inputTokensKeys,
   });
 
   const sessionOptions = {

package/src/modelDefinition.d.ts

@@ -10,6 +10,12 @@ export type ModelDefinition = {
   platform: PlatformConfig;
   model: ModelConfig;
   cost?: CostConfig;
+  autoCompact?: ModelAutoCompactConfig;
+};
+
+export type ModelAutoCompactConfig = {
+  /** Keys in providerTokenUsage whose values are summed to get the input token count. */
+  inputTokensKeys: string[];
 };
 
 export type PlatformConfig =

package/src/prompt.mjs

@@ -105,3 +105,42 @@ export const CLAUDE_CODE_COMPATIBILITY_NOTES = `# Environment Constraints
 - Subagents cannot run in parallel. Switch to them one at a time.
 - Use AGENTS.md instead when CLAUDE.md is absent.
 - If instructed to use "haiku agent", "sonnet agent", or "opus agent", use "worker" instead.`;
+
+/**
+ * Build the compact context prompt message text.
+ *
+ * Shared between the interactive `/compact` command and the automatic
+ * soft-limit prompt insertion in the agent loop.
+ *
+ * @param {object} [options]
+ * @param {string} [options.invocation] - The invocation string (e.g., "/compact reason").
+ *   When omitted, a generic auto-compact preamble is used instead.
+ * @param {boolean} [options.isSubagent] - When true, instructs the model to
+ *   return to the main agent via `switch_to_main_agent` before compacting.
+ * @returns {string}
+ */
+export function buildCompactPrompt(options) {
+  const { invocation, isSubagent } = options ?? {};
+
+  const preamble = invocation
+    ? `System: This prompt was invoked as "${invocation}".`
+    : "System: Context is approaching the soft limit.";
+
+  if (isSubagent) {
+    return [
+      preamble,
+      "",
+      "The context is growing large. Wrap up your current work:",
+      "1. Summarize your progress and findings so far in the memory file.",
+      '2. Call "switch_to_main_agent" to hand back control to the main agent.',
+    ].join("\n");
+  }
+
+  return [
+    preamble,
+    "",
+    "Compact the conversation context:",
+    "1. Update the memory file for the current task so it fully captures the task overview, progress, decisions, and next steps in a self-contained way.",
+    '2. Then call the "compact_context" tool alone with that memory file path and a brief reason.',
+  ].join("\n");
+}

package/src/tokenUsage.mjs

@@ -0,0 +1,28 @@
+/**
+ * @import { ProviderTokenUsage } from "./model"
+ */
+
+/**
+ * Extract the input (prompt/context) token count from a single turn's
+ * provider token usage object by summing the values of the specified keys.
+ *
+ * Returns `undefined` when no specified key yields a positive number.
+ *
+ * @param {ProviderTokenUsage} usage
+ * @param {string[]} inputTokensKeys - Keys whose numeric values are summed.
+ * @returns {number | undefined}
+ */
+export function extractInputTokenCount(usage, inputTokensKeys) {
+  let total = 0;
+  let found = false;
+
+  for (const key of inputTokensKeys) {
+    const value = usage[key];
+    if (typeof value === "number" && value > 0) {
+      total += value;
+      found = true;
+    }
+  }
+
+  return found ? total : undefined;
+}