@mafdet/cli 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -6,6 +6,99 @@ The version is the contract for the JSON output shapes and the exit codes.
 Being 0.x, semver still permits a break in a minor bump; the intent is not to
 use that latitude, and the promise becomes binding at 1.0.0.
 
+## 0.4.4 - 2026-08-11
+
+A security fix and twenty-one other corrections, all from an external audit of
+the 0.4.3 release.
+
+**Session ids are now checked before they become paths.** `mafdet sessions
+show`, `usage`, `delete` and `--resume` each joined whatever you typed onto
+the sessions directory, and `join` resolves `..` - so an id like
+`../../../something` reached outside the store. Reading it leaked another
+directory's contents, and `sessions delete ../../../something --yes` removed
+that directory's files. This was present from 0.3.0. It requires you (or a
+script running as you) to pass such a path - the agent has no way to invoke
+these commands - but it was a real destructive defect and it is fixed.
+
+**Resuming a conversation now honours what it says.** Blockers were computed
+and printed and then ignored, so a session whose workspace had been deleted,
+or whose model your key can no longer call, continued anyway - and it
+continued in your _current_ directory rather than the recorded one, which with
+`--allow-write` meant carrying one project's conversation into another
+project's files. A resumed session now runs where it was recorded, on the
+model it was recorded with, and refuses when it cannot.
+
+**Deleting reports what happened.** Every failure used to be swallowed and
+"deleted" printed regardless. It now takes the session lock first and only
+claims success when the directory is gone.
+
+**`--read-only` works in the interactive session.** It existed only in `mafdet
+agent`, so `mafdet --allow-write --read-only` was read-only there and
+write-enabled here.
+
+**Streams have limits.** The request timeout was cleared when the response
+headers arrived, which for a stream is the beginning: a gateway that then went
+quiet hung the CLI indefinitely. There is now a per-chunk idle deadline and a
+byte cap, and both close the connection.
+
+**Terminal control sequences.** A model's reply and a session's title, model
+and workspace are stripped of escape sequences when a terminal is reading
+them. Redirected output still receives exact bytes.
+
+**Context compaction covers conversations without tools**, and when nothing
+can safely be dropped the run stops and says so instead of sending a request
+that is over the window.
+
+**An unpriced request is no longer recorded as costing zero** - unknown and
+free are different claims.
+
+**`approvalMode` and `testCommands` are removed from the config.** They were
+accepted, displayed by `config list`, and read by nothing, so setting
+`auto-edit` looked like it turned approval off. They are removed rather than
+implemented because in a project file both would let a cloned repository raise
+its own permission level. Setting one is now an error explaining why.
+
+**A damaged line in the middle of a transcript is reported** rather than
+skipped in silence, and resuming from one is refused.
+
+Also: `mafdet agent` gains `--title` and `--no-history` (`--resume` stays in
+the interactive session and now says so); the model picker highlights the
+default you saved; `sessions` refuses unknown flags and stray arguments
+instead of ignoring them; `--json --plain` prints a usage error rather than a
+stack trace; the resume lock is released on exit; `mafdet help` describes what
+the agent can actually do; and the README states plainly that approving a
+command means allowing that program to run as you - the workspace bounds the
+agent's own tools, not the program, and is not a sandbox.
+
+## 0.4.3 - 2026-08-11
+
+A long agent run no longer walks into the model's context window, a one-shot
+chat can be saved, and the Windows timeout kill now walks the process tree.
+
+**Automatic compaction.** When a run gets close to the model's context window,
+the oldest tool exchanges are dropped from what is sent and you are told it
+happened. The size is measured rather than estimated: every response reports
+how many input tokens it actually cost, which is the provider's own count of
+exactly the conversation we sent. What gets dropped is always a whole exchange
+
+- an assistant tool call and the results answering it are inseparable - and
+  the system prompt and your original goal are never touched. A model whose
+  context length the catalogue does not publish is left alone, because guessing
+  a window would either truncate a conversation that fit or fail to truncate one
+  that did not. Your saved transcript is unaffected; only what is sent gets
+  shorter.
+
+**`mafdet chat "..." --save`** records a one-shot chat, through exactly the
+same store as an interactive session - the same redaction, the same private
+files, the same `mafdet sessions delete`. Chats are still not saved by
+default, `--no-history` still wins over `--save`, and a chat you cancel is not
+saved at all.
+
+**Windows command timeouts** now use `taskkill /T`, then `taskkill /T /F`,
+where POSIX uses SIGTERM then SIGKILL on the process group. Note the standing
+caveat: this path has not been run on a real Windows machine, so a surviving
+grandchild process there remains a known limitation rather than a fixed bug.
+
 ## 0.4.2 - 2026-08-11
 
 Conversations are now saved on this computer, and a session's cost can be

package/README.md

@@ -3,7 +3,7 @@
 The official Mafdet AI command line: model calls, account queries, and a
 permissioned local agent.
 
-> **0.4.1.** 中文版见 [README.zh-CN.md](./README.zh-CN.md). The CLI never
+> **0.4.4.** 中文版见 [README.zh-CN.md](./README.zh-CN.md). The CLI never
 > advertises a command it cannot serve, so `mafdet help` always lists exactly
 > what works.
 >
@@ -25,8 +25,8 @@ Or build it from this repository:
 
 ```bash
 pnpm --filter @mafdet/cli build
-cd packages/cli && npm pack          # -> mafdet-cli-0.4.1.tgz
-npm install -g ./mafdet-cli-0.4.1.tgz
+cd packages/cli && npm pack          # -> mafdet-cli-0.4.4.tgz
+npm install -g ./mafdet-cli-0.4.4.tgz
 ```
 
 ## The interactive session
@@ -77,20 +77,20 @@ prompt as an argument, or use `--input <file>`.
 
 ## Commands
 
-| Command                                                                                     | What it does                                                               |
-| ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `mafdet doctor`                                                                             | One pass over key, endpoints, model, tool-calling, balance, workspace, git |
-| `mafdet models list [--surface chat\|embeddings\|speech] [--agent]`                         | Models this key can call, joined with catalogue metadata                   |
-| `mafdet models show <id>`                                                                   | One model in detail, including whether the agent may drive it              |
-| `mafdet chat [prompt] [--model] [--system <file>] [--input <file>] [--no-stream] [--quiet]` | Send a prompt; streams by default                                          |
-| `mafdet agent "<goal>" [--allow-write] [--allow-command "<prefix>"]`                        | Local agent; read-only unless told otherwise                               |
-| `mafdet agent` (no goal, needs a terminal)                                                  | Interactive session                                                        |
-| `mafdet embed [text\|<file>] --model <id> [--output <file>]`                                | Text to vector                                                             |
-| `mafdet speech [text\|<file>] --model <id> --output <file> --voice <name>`                  | Text to an audio file                                                      |
-| `mafdet account balance\|usage\|subscription`                                               | Wallet, spend and plan (needs the `account:read` scope)                    |
-| `mafdet sessions list\|show\|usage\|delete`                                                 | Conversations saved on this computer (never calls a model)                 |
-| `mafdet sessions usage <id> --refresh`                                                      | Replace the local estimate with the billing ledger's figure                |
-| `mafdet config list`                                                                        | The resolved settings and where each came from                             |
+| Command                                                                                              | What it does                                                               |
+| ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `mafdet doctor`                                                                                      | One pass over key, endpoints, model, tool-calling, balance, workspace, git |
+| `mafdet models list [--surface chat\|embeddings\|speech] [--agent]`                                  | Models this key can call, joined with catalogue metadata                   |
+| `mafdet models show <id>`                                                                            | One model in detail, including whether the agent may drive it              |
+| `mafdet chat [prompt] [--model] [--system <file>] [--input <file>] [--no-stream] [--quiet] [--save]` | Send a prompt; streams by default                                          |
+| `mafdet agent "<goal>" [--allow-write] [--allow-command "<prefix>"]`                                 | Local agent; read-only unless told otherwise                               |
+| `mafdet agent` (no goal, needs a terminal)                                                           | Interactive session                                                        |
+| `mafdet embed [text\|<file>] --model <id> [--output <file>]`                                         | Text to vector                                                             |
+| `mafdet speech [text\|<file>] --model <id> --output <file> --voice <name>`                           | Text to an audio file                                                      |
+| `mafdet account balance\|usage\|subscription`                                                        | Wallet, spend and plan (needs the `account:read` scope)                    |
+| `mafdet sessions list\|show\|usage\|delete`                                                          | Conversations saved on this computer (never calls a model)                 |
+| `mafdet sessions usage <id> --refresh`                                                               | Replace the local estimate with the billing ledger's figure                |
+| `mafdet config list`                                                                                 | The resolved settings and where each came from                             |
 
 `--json` on any query command emits one complete JSON document; `--plain`
 emits tab-separated rows with no header, for `cut` and `awk`.
@@ -113,6 +113,16 @@ prefixes: `pnpm test` permits `pnpm test --filter web` but never `pnpm publish`.
 `;`, `&&`, backticks and `$( )` are refused with an explanation rather than
 sanitised.
 
+**What approving a command means.** It means allowing that program to run on
+your machine, as you. The workspace bounds which files the agent's own tools
+may touch; it is not a sandbox, and it does not bound the program. `pnpm test`
+can read your home directory, reach the network, or start something that
+outlives the run - because that is what running a program is. A short list of
+obviously destructive names is refused (`sudo`, `su`, `doas`, `chown`,
+`shutdown`, `reboot`, and invoking a program by path), but treat that as a
+guard against slips rather than as containment. Approve prefixes the way you
+would run the command yourself.
+
 In a session: `/model`, `/permissions`, `/diff`, `/cost`, `/compact`, `/exit`.
 
 ## Configuration
@@ -131,8 +141,8 @@ User config lives at `~/.config/mafdet/config.json` (Linux),
 `~/Library/Application Support/mafdet/config.json` (macOS) or
 `%APPDATA%\mafdet\config.json` (Windows).
 
-A project may carry `.mafdet.json` with `model`, `approvalMode` and
-`testCommands` — and nothing else. Credentials and endpoints in a project file
+A project may carry `.mafdet.json` with `model` — and nothing else.
+Credentials and endpoints in a project file
 are rejected outright: cloning a repository must never change where your key
 is sent.
 
@@ -216,10 +226,16 @@ Turning it off and cleaning up:
 
 ```bash
 mafdet --no-history            # this run is not recorded at all
+mafdet chat "..." --save       # a one-shot chat is saved only when asked
 mafdet sessions list           # what is saved, and the path when nothing is
 mafdet sessions delete <id> --yes
 ```
 
+A single `mafdet chat` is not a conversation anyone resumes, so it is not
+recorded unless `--save` is given. `--no-history` still wins over `--save`, and
+a chat cancelled with Ctrl+C is not saved at all — half a reply is a worse
+record than none.
+
 `--no-history` writes nothing — not an empty directory, not an index entry.
 
 Deleting removes the local messages and this session's usage mapping. It does

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 Mafdet AI 官方命令行：模型调用、账户查询，以及一个受权限约束的本地 Agent。
 
-> **0.4.1。** 英文版见 [README.md](./README.md)。
+> **0.4.4。** 英文版见 [README.md](./README.md)。
 
 ## 环境要求
 
@@ -60,20 +60,20 @@ mafdet doctor
 
 ## 命令
 
-| 命令                                                                                        | 作用                                                                |
-| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| `mafdet doctor`                                                                             | 一次检查 Node、两个端点、Key、工作区、git、模型与工具调用能力、余额 |
-| `mafdet models list [--surface chat\|embeddings\|speech] [--agent]`                         | 这把 Key 能调用的模型，并附上目录元数据                             |
-| `mafdet models show <id>`                                                                   | 单个模型详情，含 Agent 是否可以驱动它                               |
-| `mafdet chat [提示词] [--model] [--system <文件>] [--input <文件>] [--no-stream] [--quiet]` | 发一次对话，默认流式                                                |
-| `mafdet embed [文本\|<文件>] --model <id> [--output <文件>]`                                | 文本转向量                                                          |
-| `mafdet speech [文本\|<文件>] --model <id> --output <文件> --voice <音色>`                  | 文本转音频                                                          |
-| `mafdet agent "<目标>" [--allow-write] [--allow-command "<前缀>"]`                          | 本地 Agent，默认只读                                                |
-| `mafdet agent`（不带目标，需终端）                                                          | 交互会话                                                            |
-| `mafdet account balance\|usage\|subscription`                                               | 钱包、用量、套餐（需 `account:read` scope）                         |
-| `mafdet sessions list\|show\|usage\|delete`                                                 | 保存在这台电脑上的会话（不会调用模型）                              |
-| `mafdet sessions usage <id> --refresh`                                                      | 用账单账本的权威金额替换本地估算                                    |
-| `mafdet config list`                                                                        | 当前生效的配置及其来源                                              |
+| 命令                                                                                                 | 作用                                                                |
+| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `mafdet doctor`                                                                                      | 一次检查 Node、两个端点、Key、工作区、git、模型与工具调用能力、余额 |
+| `mafdet models list [--surface chat\|embeddings\|speech] [--agent]`                                  | 这把 Key 能调用的模型，并附上目录元数据                             |
+| `mafdet models show <id>`                                                                            | 单个模型详情，含 Agent 是否可以驱动它                               |
+| `mafdet chat [提示词] [--model] [--system <文件>] [--input <文件>] [--no-stream] [--quiet] [--save]` | 发一次对话，默认流式                                                |
+| `mafdet embed [文本\|<文件>] --model <id> [--output <文件>]`                                         | 文本转向量                                                          |
+| `mafdet speech [文本\|<文件>] --model <id> --output <文件> --voice <音色>`                           | 文本转音频                                                          |
+| `mafdet agent "<目标>" [--allow-write] [--allow-command "<前缀>"]`                                   | 本地 Agent，默认只读                                                |
+| `mafdet agent`（不带目标，需终端）                                                                   | 交互会话                                                            |
+| `mafdet account balance\|usage\|subscription`                                                        | 钱包、用量、套餐（需 `account:read` scope）                         |
+| `mafdet sessions list\|show\|usage\|delete`                                                          | 保存在这台电脑上的会话（不会调用模型）                              |
+| `mafdet sessions usage <id> --refresh`                                                               | 用账单账本的权威金额替换本地估算                                    |
+| `mafdet config list`                                                                                 | 当前生效的配置及其来源                                              |
 
 查询类命令都支持 `--json`（输出一份完整 JSON 文档）与 `--plain`（无表头的 TSV，方便
 `cut`、`awk` 处理）。
@@ -94,6 +94,13 @@ mafdet doctor
 **没有 shell**：命令被切成 argv 直接执行，所以管道、重定向、`;`、`&&`、反引号、`$( )`
 一律被拒绝并说明原因，而不是尝试"消毒"。
 
+**批准一条命令意味着什么。** 意味着允许那个程序在你的机器上、以你的身份运行。
+工作区限定的是 **Agent 自己的工具**能碰哪些文件，它**不是沙箱**，也约束不了那个程序。
+`pnpm test` 可以读你的家目录、可以联网、可以起一个比这次运行活得更久的进程——
+因为那就是"运行一个程序"的含义。我们会拒绝一小份明显破坏性的名字
+（`sudo`、`su`、`doas`、`chown`、`shutdown`、`reboot`，以及按路径调用），
+但请把它当作**防手滑的护栏，而不是隔离**。批准前缀时，请按"我自己会不会直接敲这条命令"来判断。
+
 会话内命令：`/model`、`/permissions`、`/diff`、`/cost`、`/compact`、`/exit`。
 
 ## 配置
@@ -111,7 +118,7 @@ mafdet doctor
 用户配置位置：Linux `~/.config/mafdet/config.json`、macOS
 `~/Library/Application Support/mafdet/config.json`、Windows `%APPDATA%\mafdet\config.json`。
 
-项目可以放一个 `.mafdet.json`，但**只允许** `model`、`approvalMode`、`testCommands` 三项。
+项目可以放一个 `.mafdet.json`，但**只允许 `model` 一项**。
 里面出现凭据或端点会**直接报错**：克隆一个仓库绝不该改变你的 Key 发往哪里。
 
 ## 退出码
@@ -186,10 +193,15 @@ Linux 与 macOS 上文件权限 `0600`、目录 `0700`；**Windows 没有等价
 
 ```bash
 mafdet --no-history            # 这一次运行完全不记录
+mafdet chat "..." --save       # 一次性对话只有明确要求时才保存
 mafdet sessions list           # 已保存的会话；没有时会告诉你路径
 mafdet sessions delete <id> --yes
 ```
 
+一次 `mafdet chat` 不是有人会去恢复的对话，所以**不带 `--save` 就不保存**。
+`--no-history` 仍然压过 `--save`；被 Ctrl+C 取消的对话**完全不保存**——
+半个回复是比没有更糟的记录。
+
 `--no-history` 什么都不留——不留空目录，也不留索引条目。
 
 删除会移除本地消息和这个会话的用量映射。它**不会**移除 API 用量、账单记录或扣费：

package/dist/agent/context-budget.d.ts

@@ -0,0 +1,69 @@
+import type { ChatMessage } from "./loop.js";
+/**
+ * Fraction of the usable window at which we start shortening.
+ *
+ * Not 1.0, and the gap is not caution for its own sake: the request that
+ * measured `prompt_tokens` is smaller than the next one will be, because the
+ * assistant reply, its tool results and the next user message all land in
+ * between and none of them are counted yet.
+ */
+export declare const COMPACT_AT = 0.75;
+/** Room left for the reply, which shares the window with the input. */
+export declare function replyReserve(contextLength: number): number;
+/** Tool exchanges kept whatever happens, so the recent work stays intact. */
+export declare const KEEP_RECENT_EXCHANGES = 2;
+/**
+ * Is the conversation close enough to the window to shorten it?
+ *
+ * `lastPromptTokens` is what the provider counted for the previous request in
+ * this run. Zero means nothing has been measured yet, and an unknown window
+ * means we have nothing to compare against.
+ */
+export declare function shouldCompact(contextLength: number | undefined, lastPromptTokens: number): boolean;
+export interface PruneResult {
+    /** Messages removed from the array. */
+    readonly removed: number;
+    /** Complete tool exchanges dropped. */
+    readonly exchanges: number;
+}
+/**
+ * Drop the oldest complete tool exchanges, in place.
+ *
+ * The system prompt and the opening goal are never touched - without the goal
+ * the model no longer knows what it is doing, which is a worse failure than
+ * running out of context.
+ */
+export declare function pruneToolExchanges(history: ChatMessage[], keepRecent?: number): PruneResult;
+/**
+ * F-008 · Drop the oldest whole turns.
+ *
+ * The exchange-based prune above cannot help a conversation with no tools in
+ * it - a long back-and-forth of plain questions removed nothing and carried on
+ * requesting, so "a long run no longer walks into the context window" was only
+ * true for tool-using runs.
+ *
+ * A turn starts at a user message and runs to just before the next one, so
+ * cutting on that boundary can never orphan a tool result or leave a tool call
+ * unanswered: CLI-014's rule holds by construction. The system prompt and the
+ * first user message - the goal - always stay.
+ */
+export declare function dropOldestTurns(history: ChatMessage[], keepTurns: number): number;
+export interface CompactionResult extends PruneResult {
+    /** Whole turns dropped, when exchanges were not enough. */
+    readonly turns: number;
+    /** True when nothing could be dropped and the history is still too big. */
+    readonly exhausted: boolean;
+}
+/**
+ * Shorten the history as much as can be done safely.
+ *
+ * Tool exchanges go first because they are the bulk of a long agent run and
+ * the least useful to keep. Only when there are none left does it start
+ * dropping turns, which costs the model more context.
+ *
+ * `exhausted` is the honest outcome when neither helped: the caller must stop
+ * rather than send a request that is over the window, which would fail
+ * upstream and be billed for the attempt.
+ */
+export declare function compactForBudget(history: ChatMessage[], keepRecent?: number): CompactionResult;
+//# sourceMappingURL=context-budget.d.ts.map

package/dist/agent/context-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget.d.ts","sourceRoot":"","sources":["../../src/agent/context-budget.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,OAAO,CAAC;AAE/B,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,6EAA6E;AAC7E,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAKT;AAED,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAsCD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,WAAW,EAAE,EACtB,UAAU,GAAE,MAA8B,GACzC,WAAW,CAkBb;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,WAAW,EAAE,EACtB,SAAS,EAAE,MAAM,GAChB,MAAM,CAuBR;AAED,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,WAAW,EAAE,EACtB,UAAU,GAAE,MAA8B,GACzC,gBAAgB,CAYlB"}

package/dist/agent/context-budget.js

@@ -0,0 +1,169 @@
+// §7.4 · Keeping a long run inside the model's context window.
+//
+// The plan asks for "总上下文按模型窗口设置预算，接近上限时压缩历史". Two decisions
+// shape what that can honestly be:
+//
+// The size of the history is *measured*, not estimated. Every response carries
+// `prompt_tokens` for the request that produced it, which is the provider's own
+// count of exactly the conversation we sent. Estimating instead would mean
+// shipping a tokenizer per provider - CLI-000B already found the gateway's own
+// reservation under-counts badly because it cannot see the tool schema, and a
+// second wrong estimate here would be no better.
+//
+// And what gets dropped is whole tool exchanges, never individual messages.
+// CLI-014 established the rule the hard way: an assistant message carrying
+// `tool_calls` and the `tool` results answering them are inseparable, because
+// the API rejects a tool result with no matching call and a call with no
+// result. So the unit of removal is the pair, or nothing.
+//
+// When the model's context length is unknown, nothing happens at all. A guess
+// at the window would either truncate a conversation that fit, or fail to
+// truncate one that did not.
+/**
+ * Fraction of the usable window at which we start shortening.
+ *
+ * Not 1.0, and the gap is not caution for its own sake: the request that
+ * measured `prompt_tokens` is smaller than the next one will be, because the
+ * assistant reply, its tool results and the next user message all land in
+ * between and none of them are counted yet.
+ */
+export const COMPACT_AT = 0.75;
+/** Room left for the reply, which shares the window with the input. */
+export function replyReserve(contextLength) {
+    return Math.min(4096, Math.floor(contextLength / 8));
+}
+/** Tool exchanges kept whatever happens, so the recent work stays intact. */
+export const KEEP_RECENT_EXCHANGES = 2;
+/**
+ * Is the conversation close enough to the window to shorten it?
+ *
+ * `lastPromptTokens` is what the provider counted for the previous request in
+ * this run. Zero means nothing has been measured yet, and an unknown window
+ * means we have nothing to compare against.
+ */
+export function shouldCompact(contextLength, lastPromptTokens) {
+    if (contextLength === undefined || contextLength <= 0)
+        return false;
+    if (lastPromptTokens <= 0)
+        return false;
+    const usable = contextLength - replyReserve(contextLength);
+    return usable > 0 && lastPromptTokens >= usable * COMPACT_AT;
+}
+/**
+ * The assistant-with-tool_calls messages and the tool results that answer them.
+ *
+ * An exchange is only counted when every one of its calls has a result: a
+ * partial one is the tail of a run still in progress, and removing half of it
+ * is precisely the shape the API refuses.
+ */
+function exchangesIn(history) {
+    const found = [];
+    for (let i = 0; i < history.length; i += 1) {
+        const message = history[i];
+        if (message === undefined)
+            continue;
+        const calls = message.role === "assistant" ? message.tool_calls : undefined;
+        if (calls === undefined || calls.length === 0)
+            continue;
+        const answered = new Set();
+        let end = i + 1;
+        while (end < history.length && history[end]?.role === "tool") {
+            const id = history[end]?.tool_call_id;
+            if (typeof id === "string")
+                answered.add(id);
+            end += 1;
+        }
+        if (calls.every((call) => answered.has(call.id))) {
+            found.push({ start: i, end });
+        }
+        i = end - 1;
+    }
+    return found;
+}
+/**
+ * Drop the oldest complete tool exchanges, in place.
+ *
+ * The system prompt and the opening goal are never touched - without the goal
+ * the model no longer knows what it is doing, which is a worse failure than
+ * running out of context.
+ */
+export function pruneToolExchanges(history, keepRecent = KEEP_RECENT_EXCHANGES) {
+    const exchanges = exchangesIn(history);
+    const droppable = exchanges.slice(0, Math.max(0, exchanges.length - keepRecent));
+    if (droppable.length === 0)
+        return { removed: 0, exchanges: 0 };
+    const drop = new Set();
+    for (const exchange of droppable) {
+        for (let i = exchange.start; i < exchange.end; i += 1)
+            drop.add(i);
+    }
+    const kept = history.filter((_, index) => !drop.has(index));
+    const removed = history.length - kept.length;
+    history.length = 0;
+    history.push(...kept);
+    return { removed, exchanges: droppable.length };
+}
+/**
+ * F-008 · Drop the oldest whole turns.
+ *
+ * The exchange-based prune above cannot help a conversation with no tools in
+ * it - a long back-and-forth of plain questions removed nothing and carried on
+ * requesting, so "a long run no longer walks into the context window" was only
+ * true for tool-using runs.
+ *
+ * A turn starts at a user message and runs to just before the next one, so
+ * cutting on that boundary can never orphan a tool result or leave a tool call
+ * unanswered: CLI-014's rule holds by construction. The system prompt and the
+ * first user message - the goal - always stay.
+ */
+export function dropOldestTurns(history, keepTurns) {
+    const userAt = [];
+    for (let i = 0; i < history.length; i += 1) {
+        if (history[i]?.role === "user")
+            userAt.push(i);
+    }
+    // The first user message is the goal and is not a droppable turn, so there
+    // have to be more than `keepTurns` turns after it before anything can go.
+    if (userAt.length <= keepTurns + 1)
+        return 0;
+    const cut = userAt[userAt.length - keepTurns];
+    if (cut === undefined)
+        return 0;
+    const kept = [];
+    if (history[0]?.role === "system")
+        kept.push(history[0]);
+    const goal = history[userAt[0]];
+    if (goal !== undefined && userAt[0] !== cut)
+        kept.push(goal);
+    kept.push(...history.slice(cut));
+    const removed = history.length - kept.length;
+    if (removed <= 0)
+        return 0;
+    history.length = 0;
+    history.push(...kept);
+    return removed;
+}
+/**
+ * Shorten the history as much as can be done safely.
+ *
+ * Tool exchanges go first because they are the bulk of a long agent run and
+ * the least useful to keep. Only when there are none left does it start
+ * dropping turns, which costs the model more context.
+ *
+ * `exhausted` is the honest outcome when neither helped: the caller must stop
+ * rather than send a request that is over the window, which would fail
+ * upstream and be billed for the attempt.
+ */
+export function compactForBudget(history, keepRecent = KEEP_RECENT_EXCHANGES) {
+    const pruned = pruneToolExchanges(history, keepRecent);
+    if (pruned.exchanges > 0) {
+        return { ...pruned, turns: 0, exhausted: false };
+    }
+    const turnsRemoved = dropOldestTurns(history, keepRecent);
+    return {
+        removed: turnsRemoved,
+        exchanges: 0,
+        turns: turnsRemoved > 0 ? 1 : 0,
+        exhausted: turnsRemoved === 0,
+    };
+}

package/dist/agent/loop.d.ts

@@ -12,7 +12,9 @@ export declare const DEFAULT_LIMITS: {
     maxCostMicroUsd: bigint | undefined;
 };
 export type AgentLimits = typeof DEFAULT_LIMITS;
-export type StopReason = "completed" | "max_turns" | "timeout" | "max_cost" | "cancelled" | "rate_limited" | "error";
+export type StopReason = "completed" | "max_turns" | "timeout" | "max_cost" | "cancelled" | "rate_limited"
+/** F-008 · Over the model's window with nothing left that is safe to drop. */
+ | "context_limit" | "error";
 export interface AgentReport {
     stopReason: StopReason;
     /** The model's last text answer, if it produced one. */
@@ -102,10 +104,26 @@ export type AgentEvent = {
     promptTokens: number;
     completionTokens: number;
     costMicroUsd: bigint;
+    /**
+     * F-012 · False when the catalogue had no price for this model, so a
+     * recorder can tell "we could not work it out" from "it was free".
+     */
+    priced: boolean;
 } | {
     type: "rate_limited";
     waitMs: number;
     attempt: number;
+}
+/**
+ * §7.4 · The history was shortened to stay inside the model's window.
+ * Surfaced rather than done quietly: the user is entitled to know that
+ * earlier tool output is no longer being sent.
+ */
+ | {
+    type: "compacted";
+    exchanges: number;
+    messages: number;
+    promptTokens: number;
 };
 export interface ChatMessage {
     role: "system" | "user" | "assistant" | "tool";

package/dist/agent/loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/agent/loop.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/agent/loop.ts"],"names":[],"mappings":"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"}