@vincentbanana/bananacli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BananaCLI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,317 @@
-# Temporary Holding Version
+# 🍌 BananaCLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+终端里的多 provider AI agent：能读写文件、跑命令、搜代码、上网查资料，多轮对话自动保存并随时切换。
+
+```
+   ____                  _
+  | __ )  __ _ _ __   __ _| |__   __ _ _ __
+  |  _ \ / _` | '_ \ / _` | '_ \ / _` | '_ \
+  | |_) | (_| | | | | (_| | |_) | (_| | | | |
+  |____/ \__,_|_| |_|\__,_|_.__/ \__,_|_| |_|
+
+          BananaCLI v0.1.0 · 终端里的多 provider agent
+
+  模型    deepseek/deepseek-chat
+  工作区  D:\BananaCLI
+  工具    11 个 · 权限 shell=ask write=ask network=allow
+  会话    修一下配置向导 · 20261017-203512-ab12
+
+  输入文字开始对话 · /help 查看命令 · /exit 退出 · Ctrl+C 中断请求
+
+🍌 修一下配置向导 [deepseek/deepseek-chat] ›
+```
+
+- **零运行时依赖**：只用 Node 内置模块；源码可直接 `node src/index.ts` 跑，发布版编译到 `dist/`。
+- **手写 agent 循环**：tool-calling 循环、工具注册、权限控制、上下文压缩都在仓库里，可读可改。
+- **多 provider**：OpenAI 兼容协议（DeepSeek / Moonshot / Qwen / Gemini / OpenRouter / Ollama …）和 Anthropic 原生协议都支持，SSE 流式输出。
+- **会话持久化**：每轮自动落盘到 `~/.banana/sessions/`，支持 `/list` `/use` 切换历史对话。
+- **不脆弱**：429/5xx 自动退避重试、上游报上下文超限时自动压缩后重试、网络重试可见。
+- **推理模型友好**：DeepSeek-R1 的 `reasoning_content` 和 Claude extended thinking 都能流式展示。
+- **任务清单**：内置 `todo_write` / `todo_read`，多步骤任务有进度可查，清单随会话保存。
+- **改前先看 diff、改后能回滚**：写文件前展示具体增删行，`/undo` 还原上一轮所有文件改动。
+- **多模态与扩展**：`/image` 附加截图，`.banana/tools/` 放脚本即可注册自定义工具，成本按 token 估算。
+
+## 平台支持
+
+| 平台 | 状态 | 说明 |
+| --- | --- | --- |
+| Windows 10/11 | ✅ | PowerShell / Windows Terminal；`shell` 工具走 `cmd.exe`，超时用 `taskkill /T` 杀进程树 |
+| macOS 12+ | ✅ | `shell` 走 `/bin/sh`，超时按进程组杀 |
+| Linux (glibc/musl) | ✅ | 同上；纯 Node 实现，没有原生依赖 |
+| WSL | ✅ | 装在 WSL 里就是 Linux 行为（推荐，脚本兼容性最好） |
+
+要求：**Node.js >= 20**（推荐 22 LTS 或 24）。`npm install -g @vincentbanana/bananacli` 会自动创建 `banana` 命令（Windows 生成 `.cmd` shim，Unix 生成可执行软链）。
+
+平台差异只在这几处，都已处理：
+
+- 路径全部用 `node:path`，工作区沙箱按真实路径校验（软链/junction 也不例外）
+- `shell` 命令在 Windows 用 `cmd.exe`、Unix 用 `/bin/sh`；中断/超时都会清理子进程
+- 配置文件在 `~/.banana/`（Windows 是 `C:\Users\<你>\.banana`）
+- **CRLF 兼容**：Windows 仓库常见的 `\r\n` 文件，模型用 `\n` 写 `old_string` 也能匹配，替换后保持原文件行尾
+- 老版 conhost 如果 emoji 显示成方块，`chcp 65001` 或改用 Windows Terminal；不影响功能
+
+CI 在 Ubuntu / macOS / Windows × Node 20 / 22 / 24 上跑类型检查、全量测试、打包、从 tarball 全局安装并执行 `banana --version`（见 `.github/workflows/ci.yml`）。
+
+## 快速开始
+
+```bash
+# 安装（包名是 @vincentbanana/bananacli，命令是 banana）
+npm install -g @vincentbanana/bananacli
+
+# 第一次启动会进入配置向导（选服务、贴 key、测连接）
+banana
+
+# 也可以提前用环境变量给 key，跳过向导
+$env:DEEPSEEK_API_KEY = "sk-..."        # PowerShell
+export ANTHROPIC_API_KEY="sk-ant-..."   # macOS / Linux
+
+# 交互式 / 单轮执行
+banana
+banana "看下 src/index.ts 是干什么的"
+banana -c                               # 继续上次对话
+```
+
+不想全局安装可以用 `npx @vincentbanana/bananacli`。
+
+从源码开发：
+
+```bash
+npm install        # 会触发 prepare -> 构建 dist
+npm start          # 等价于 node src/index.ts
+npm test
+npm run build
+```
+
+## 配置向导
+
+第一次启动（无 `~/.banana/config.json` 且检测不到 key）会自动进入向导，也可以用 `banana --setup` 随时重跑：
+
+1. **选服务**：内置 OpenAI / Anthropic / DeepSeek / Moonshot / Qwen / Gemini / OpenRouter / Ollama，或选「自定义」接自建网关、vLLM、LiteLLM。列表里会标出每个服务是「环境变量已就绪」「已保存 key」还是「未配置」。
+2. **填连接信息**：确认或修改 Base URL、模型名。
+3. **填 API key**：输入时显示为 `*`，不会留在终端历史里；已有环境变量或已保存的 key 可以直接沿用。
+4. **选权限**：shell 命令、写文件是否每次都要确认（默认都要）。
+5. **测连接**：真实发一次最小请求；失败会显示上游错误并允许重试，或仍然保存。
+6. 配置写入 `~/.banana/config.json`（POSIX 上尽量设为 `0600`），然后直接进入对话。
+
+> key 默认以明文存在配置文件里。更稳妥的做法是：向导里选择沿用环境变量（`DEEPSEEK_API_KEY` 等），配置文件里就只留 `apiKeyEnv` 引用。
+
+非交互环境也能配置：把答案按顺序逐行喂给 stdin。
+
+```bash
+printf '3\nn\nsk-xxxx\nn\nn\n' | banana --setup
+```
+
+顺序是：provider 序号 → 是否改 Base URL/模型 → API key（本地服务会先问要不要设）→ shell 是否确认 → 写文件是否确认。自定义服务的顺序是：`序号(最后一项)` → 名字 → 协议(1/2) → Base URL → 模型名 → 是否再修改 → key → 两个权限问题。
+
+## 命令行
+
+```
+banana                       进入交互式多轮对话
+banana "帮我跑一下测试"      单轮任务模式（不进入对话）
+
+  -p, --provider <名称>  openai / anthropic / deepseek / moonshot / qwen / gemini / openrouter / ollama
+  -m, --model <模型名>   覆盖模型名
+      --base-url <url>  覆盖 base URL（接自建网关、vLLM、LiteLLM 等）
+      --api-key <key>   直接给 key（不推荐，优先用环境变量）
+  -s, --session <ref>   载入指定对话（序号 / id 前缀 / 标题关键词）
+  -c, --continue        继续上一次对话
+      --list            列出历史对话后退出
+      --cwd <目录>      指定工作区（agent 能访问的目录范围）
+      --allow-outside   允许工具访问工作区之外的路径
+      --yolo            跳过所有确认
+      --system <文本>   覆盖系统提示词
+      --no-tools        不给 agent 任何工具（纯对话）
+      --no-reasoning    不显示推理模型的思考过程
+      --setup           运行/重跑配置向导
+```
+
+## 交互命令
+
+| 命令 | 说明 |
+| --- | --- |
+| `/new [标题]` | 开新对话（当前对话已自动保存） |
+| `/list` | 历史对话列表 |
+| `/use <序号\|id前缀\|标题>` | 切换对话 |
+| `/rename` `/delete` `/clear` | 改名 / 删除 / 清空上下文 |
+| `/undo` | 回滚上一轮的文件修改（恢复/删除） |
+| `/session` `/history` | 当前对话信息 / 消息列表 |
+| `/provider [名]` `/model [名]` | 切换供应商 / 模型 |
+| `/setup` | 会话内重新配置 provider / 模型 / key |
+| `/image <路径\|clear>` | 给下一条消息附加图片（png/jpg/gif/webp） |
+| `/tools [名\|all]` | 查看或启停工具（含插件工具） |
+| `/perm <shell\|write\|network> <ask\|allow\|deny>` | 权限策略 |
+| `/compact` | 手动压缩上下文 |
+| `/cwd [路径]` | 查看/切换工作目录 |
+| `/system [文本]` | 查看/替换系统提示词 |
+| `/cls` `/exit` | 清屏 / 保存退出 |
+
+快捷键：`Ctrl+C` 中断当前请求（连按两次退出），`↑` 翻历史输入，输入末尾加 `\` 可以续行，`@` 后按 `Tab` 补全项目文件。
+
+## 安全网：diff 预览与撤销
+
+- 写文件 / 改文件需要确认时，会先显示 `+新增 / -删除` 的具体行（最多 40 行，中文按两列宽度截断）
+- 每次工具写入前，旧内容会快照到 `~/.banana/backups/<sessionId>/`，每轮一条记录（最多保留 30 轮）
+- `/undo` 回滚最近一轮：被改的文件恢复原内容，新建的文件直接删除
+- 对话记录不会回滚；`shell` 命令和插件工具的副作用也不在撤销范围内（无法可靠追踪）
+
+## 图片输入
+
+```text
+/image screenshot.png
+看看这个报错
+```
+
+图片会编码成 data URL 随下一条消息发送，OpenAI 兼容协议和 Anthropic 协议都支持；单张上限 4MB，支持 png / jpg / gif / webp。`/image` 不带参数查看待发送列表，`/image clear` 清空。
+
+## 插件工具
+
+在 `~/.banana/tools/` 或 `<项目>/.banana/tools/` 放一个 `.mjs`（也支持 `.js` / `.ts`），默认导出工具定义即可，启动时自动加载：
+
+```js
+// ~/.banana/tools/http_status.mjs
+export default {
+  name: 'http_status',
+  description: '检查一个 URL 的 HTTP 状态码',
+  parameters: {
+    type: 'object',
+    properties: { url: { type: 'string', description: '目标地址' } },
+    required: ['url'],
+    additionalProperties: false,
+  },
+  approval: 'network', // never | write | shell | network
+  async run(input) {
+    const response = await fetch(String(input.url), { method: 'HEAD' });
+    return { ok: response.ok, content: `${input.url} -> ${response.status}` };
+  },
+};
+```
+
+名称冲突、缺少 `run`、字段不合法都会在启动时给出提示并跳过该文件。插件以当前 Node 进程权限运行，等同于你自己写的代码，只放可信的脚本。
+
+## 成本估算
+
+按内置价目表（美元 / 百万 token）估算每轮和整会话花费，未知模型不显示。价格会变，可在 provider 配置里覆盖：
+
+```json
+{ "pricing": { "input": 0.27, "output": 1.1 } }
+```
+
+## 界面细节
+
+- 启动头部显示当前模型、工作区、工具数与权限组合、会话 id
+- 等待模型响应时有 `⠋ 等待 … 3.2s` 状态行，首个 token 到达即擦除
+- 工具调用显示为 `⏺ shell command="…"`，成功 `✓ 摘要`、失败 `✗ 错误首行`（最多三行缩进展示）
+- 需要确认的操作标注类别（执行命令 / 写文件 / 访问网络），命令太长时自动换行展示
+- 中文按两列宽计算，`/help`、`/tools`、`/list` 的表格在中文环境下也对齐；命令拼错会提示最接近的命令（`/providr` → `/provider`）
+
+## 工具
+
+| 工具 | 权限类别 | 说明 |
+| --- | --- | --- |
+| `read_file` | – | 读文件，带行号，支持 offset/limit 分段 |
+| `write_file` | write | 新建/覆盖文件 |
+| `edit_file` | write | 精确字符串替换，要求唯一匹配，支持 `replace_all` |
+| `list_dir` | – | 列目录，自动忽略 `node_modules` 等 |
+| `glob` | – | `**/*.ts`、`{a,b}` 风格 glob |
+| `grep` | – | 正则搜代码，返回 `file:line` |
+| `shell` | shell | 执行命令，回传 stdout/stderr/退出码，带超时与输出截断 |
+| `web_search` | network | 优先 Tavily / Brave，回退 DuckDuckGo |
+| `web_fetch` | network | 抓 URL 转纯文本（HTML 去标签去脚本） |
+| `todo_write` | – | 写入/更新任务清单（整表覆盖，随会话保存） |
+| `todo_read` | – | 读取当前任务清单 |
+| 插件工具 | 自定义 | `.banana/tools/` 下的脚本自动注册，权限类别由插件声明 |
+
+路径默认被限制在工作区内，越界会拒绝并告诉模型原因；符号链接也会按其真实位置校验，不能借软链逃出工作区。`--allow-outside` 或配置 `allowOutsideWorkspace` 可放开。
+
+## 配置
+
+全局 `~/.banana/config.json`，项目级 `<工作区>/.banana/config.json` 覆盖全局：
+
+```json
+{
+  "current": "deepseek",
+  "providers": {
+    "deepseek": { "protocol": "openai", "baseUrl": "https://api.deepseek.com/v1", "model": "deepseek-chat", "apiKeyEnv": "DEEPSEEK_API_KEY" },
+    "my-gateway": { "protocol": "openai", "baseUrl": "https://llm.internal/v1", "model": "qwen2.5-coder", "apiKeyEnv": "INTERNAL_KEY", "pricing": { "input": 0.4, "output": 1.2 } }
+  },
+  "permissions": { "shell": "ask", "write": "ask", "network": "allow" },
+  "maxSteps": 40,
+  "maxContextChars": 160000,
+  "allowOutsideWorkspace": false,
+  "showReasoning": true
+}
+```
+
+Anthropic 协议默认给 `system` 和工具定义打 `cache_control: ephemeral`（prompt caching，长对话能省不少钱）；如果你的网关不认这个字段，在对应 provider 里设 `"promptCaching": false`。
+
+环境变量：`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `DEEPSEEK_API_KEY` / `MOONSHOT_API_KEY` / `DASHSCOPE_API_KEY` / `GEMINI_API_KEY` / `OPENROUTER_API_KEY`；搜索可选 `TAVILY_API_KEY` 或 `BRAVE_API_KEY`；临时覆盖用 `BANANA_PROVIDER` / `BANANA_MODEL` / `BANANA_BASE_URL` / `BANANA_SHOW_REASONING` / `BANANA_HOME` / `BANANA_CONFIG`。
+
+`protocol` 只有两个值：`openai`（OpenAI 兼容）和 `anthropic`（Claude 原生）。绝大多数第三方服务都能用 `openai` 协议接进来。
+
+## 代码结构
+
+```
+src/
+  index.ts            入口：参数解析、装配
+  config/config.ts    配置加载/合并、环境变量覆盖、系统提示词
+  providers/
+    types.ts          统一消息格式（UMessage / ToolCall / ToolSchema / 图片）
+    http.ts           fetch 重试退避、上下文超限/stream_options 错误识别
+    pricing.ts        内置价目表与成本估算
+    openai.ts         OpenAI 兼容协议 + SSE 流式 + tool_calls 增量拼接 + reasoning + 图片
+    anthropic.ts      Anthropic Messages API + tool_use / tool_result 角色归并 + prompt caching + 图片
+  agent/
+    loop.ts           agent 主循环：请求 → 工具 → 回灌 → 再请求；断流补偿与超限自愈
+    context.ts        token 估算与历史压缩（保留首条用户消息 + 最近若干轮，不切断工具配对）
+  tools/
+    fs.ts shell.ts web.ts todo.ts   文件 / 命令 / 网络 / 任务清单工具
+    plugins.ts        .banana/tools/ 下的插件加载与校验
+    index.ts          工具注册表、权限判定、执行入口
+  util/diff.ts        零依赖行级 diff（LCS + 大文件降级）
+  session/
+    store.ts          会话落盘、列表、按 id/序号/标题查找
+    backups.ts        每轮文件快照与 /undo
+  cli/
+    repl.ts           交互循环、流式渲染、diff 确认、Ctrl+C 中断、历史输入
+    commands.ts       slash 命令实现
+    completion.ts     @文件 与 slash 命令补全
+    setup.ts          配置向导（终端 raw mode / 可注入 IO）
+    ui.ts             终端输出、颜色、双宽对齐
+test/
+  mock-provider.mjs   内置 mock 模型服务（两种协议 + 故障注入）
+  prompt.test.mjs     掩码输入/退格/粘贴/Ctrl+C 的按键级单元测试
+  ui.test.mjs         双宽字符对齐、banner、启动头部、命令纠错
+  p0.test.mjs         压缩配对、符号链接沙箱、失败退出码
+  features.test.mjs   diff/预览/shell 流式/补全/向导/撤销/成本/插件
+  smoke.mjs           冒烟测试：不需要真实 API key
+```
+
+## 开发
+
+```bash
+npm run typecheck   # tsc --noEmit
+npm test            # 123 项断言，全部基于内置 mock provider
+npm run dev         # node --watch
+npm run build       # 编译到 dist/（发布用）
+```
+
+发布（包名 `@vincentbanana/bananacli`，`prepublishOnly` 会自动 typecheck + 测试 + 构建；scope 包需要 `--access public`）：
+
+```bash
+npm login
+npm publish            # 2FA 账号加 --otp=123456
+npm version patch      # 之后发新版本
+npm publish
+```
+
+覆盖范围：OpenAI / Anthropic 两条协议的工具调用、一轮多个工具、未知工具、工作区越界与软链拦截、会话落盘与 `-c` 续接、stdin 脚本化输入、`ask`/`deny` 权限、todo 清单落盘、429 退避重试、上下文超限自愈、压缩不切断工具配对、推理内容、Anthropic prompt caching、配置向导（含注入 IO）、掩码输入按键、中文双宽对齐、命令纠错、diff 预览、shell 实时输出与超时、`@` 补全、`/undo`、成本估算、图片输入、插件加载与调用。
+
+## 已知边界
+
+- 模型名和 provider baseUrl 是内置默认值，不同服务可能需要 `/model` 或配置改一下。
+- 上下文压缩按字符数估算 token，超长会话建议调小 `maxContextChars`。
+- `web_search` 在没有 Tavily/Brave key 时走 DuckDuckGo HTML 抓取，无外网环境下会失败（会明确报错，不会假装成功）。
+- 图片以 data URL 存进会话 JSON，多张大图会让会话文件变大（模型侧仍受单张 4MB 限制）。
+- `/undo` 只覆盖 `write_file` / `edit_file`；`shell` 命令和插件工具的副作用无法回滚。
+- 插件以当前进程权限运行，等同用户自己的代码，只应放可信脚本。
+- 成本估算用内置价目表，实际账单以服务商为准。

package/dist/agent/context.js

@@ -0,0 +1,99 @@
+const CHARS_PER_TOKEN = 3.2;
+/** 粗略估算 token 数：中文按 ~1.5 字符/token，代码/英文更省，所以用偏保守的系数。 */
+export function estimateTokens(messages) {
+    let chars = 0;
+    for (const message of messages) {
+        chars += message.content.length;
+        for (const call of message.toolCalls ?? []) {
+            chars += call.name.length + JSON.stringify(call.input ?? {}).length;
+        }
+    }
+    return Math.ceil(chars / CHARS_PER_TOKEN);
+}
+export function estimateChars(messages) {
+    let chars = 0;
+    for (const message of messages) {
+        chars += message.content.length + 8;
+        for (const call of message.toolCalls ?? []) {
+            chars += call.name.length + JSON.stringify(call.input ?? {}).length + 8;
+        }
+    }
+    return chars;
+}
+const SUMMARY_INSTRUCTION = [
+    '请把下面这段 AI 编程助手与用户的对话压缩成一份交接摘要，供对话继续进行时使用。',
+    '必须保留：用户的原始目标、已经做出的决定、已修改/新建的文件及其改动要点、关键代码事实（函数名/路径/接口）、工具报错与卡点、下一步待办。',
+    '不要保留无用的寒暄和重复内容。只输出摘要正文，用 Markdown，分「目标 / 进展 / 关键事实 / 下一步」四段。',
+].join('\n');
+/**
+ * 上下文超限时把中间的历史压成一段摘要，保留第一条用户消息和最近若干条消息。
+ * 失败时返回 null，调用方应继续带着原上下文跑（可能只是这次请求会失败）。
+ */
+export async function compactMessages(options) {
+    const { provider, messages, keepRecentChars = 60_000, maxTailMessages = 8, signal, } = options;
+    if (messages.length < 4)
+        return null;
+    const firstUserIndex = messages.findIndex((message) => message.role === 'user');
+    if (firstUserIndex === -1)
+        return null;
+    const firstUser = messages[firstUserIndex];
+    const head = messages.slice(0, firstUserIndex + 1);
+    // 从尾部往前保留，直到用完字符预算或达到条数上限
+    let boundary = messages.length;
+    let used = 0;
+    for (let index = messages.length - 1; index > firstUserIndex; index -= 1) {
+        const size = estimateChars([messages[index]]);
+        const keptCount = messages.length - index;
+        if ((used + size > keepRecentChars && keptCount > 2) || keptCount > maxTailMessages) {
+            boundary = index + 1;
+            break;
+        }
+        used += size;
+        boundary = index;
+    }
+    // 关键：切点不能落在 tool 结果上，否则 tail 会以孤儿 tool_result 开头，
+    // Anthropic 会直接 400（tool_use_id 找不到），部分 OpenAI 兼容服务也会报错。
+    // 往前退到发起调用的 assistant 消息，保证 tool_use / tool_result 成对保留。
+    while (boundary > firstUserIndex + 1 && messages[boundary]?.role === 'tool') {
+        boundary -= 1;
+    }
+    if (boundary <= firstUserIndex + 1)
+        return null;
+    const middle = messages.slice(firstUserIndex + 1, boundary);
+    const tail = messages.slice(boundary);
+    const transcript = middle
+        .map((message) => {
+        const label = message.role === 'assistant' ? '助手' : message.role === 'tool' ? `工具(${message.name ?? ''})` : '用户';
+        const calls = message.toolCalls?.map((call) => `[调用工具 ${call.name}]`).join(' ') ?? '';
+        return `### ${label}\n${message.content}\n${calls}`.trim();
+    })
+        .join('\n\n');
+    try {
+        const result = await provider.generate({
+            messages: [
+                { role: 'user', content: `${SUMMARY_INSTRUCTION}\n\n<对话记录>\n${transcript}\n</对话记录>` },
+            ],
+            system: '你在压缩对话上下文，输出必须简洁、结构化、只保留事实。',
+            tools: [],
+            signal,
+        });
+        const summary = result.message.content.trim();
+        if (!summary)
+            return null;
+        return {
+            messages: [
+                ...head,
+                {
+                    role: 'user',
+                    content: `[上下文已自动压缩] 下面是较早对话的摘要，请基于它继续工作：\n\n${summary}`,
+                },
+                ...tail,
+            ],
+            summary,
+            removed: middle.length,
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/agent/loop.js

@@ -0,0 +1,161 @@
+import { isContextOverflowError } from "../providers/http.js";
+import { permissionFor, runTool, toolMap, toolSchemas, } from "../tools/index.js";
+import { compactMessages, estimateChars, estimateTokens } from "./context.js";
+function mergeUsage(total, next) {
+    return {
+        inputTokens: (total.inputTokens ?? 0) + (next.inputTokens ?? 0) || undefined,
+        outputTokens: (total.outputTokens ?? 0) + (next.outputTokens ?? 0) || undefined,
+    };
+}
+const MAX_TOOL_MESSAGE_CHARS = 6000;
+/**
+ * 历史太短压不动、但上下文已经超限时，先把超长的工具输出截断。
+ * 这是无损信息里最划算的一刀：大文件读取/命令输出通常才是占地方的元凶。
+ */
+export function truncateToolOutputs(messages, maxChars = MAX_TOOL_MESSAGE_CHARS) {
+    let trimmed = 0;
+    for (const message of messages) {
+        if (message.role !== 'tool')
+            continue;
+        if (message.content.length <= maxChars)
+            continue;
+        const head = Math.floor(maxChars * 0.75);
+        const tail = maxChars - head;
+        message.content = `${message.content.slice(0, head)}\n...[历史工具输出已截断，原长 ${message.content.length} 字符]...\n${message.content.slice(-tail)}`;
+        trimmed += 1;
+    }
+    return trimmed;
+}
+/**
+ * 跑完一整轮：请求 -> 工具调用 -> 回灌结果 -> 再请求，直到模型不再要工具。
+ * messages 不会被原地修改，返回的是新数组，方便会话持久化。
+ */
+export async function runTurn(deps, messages, input, images) {
+    const tools = toolMap(deps.tools);
+    const schemas = toolSchemas(deps.tools);
+    const convo = [...messages];
+    if (input) {
+        convo.push({
+            role: 'user',
+            content: input,
+            ...(images?.length ? { images } : {}),
+        });
+    }
+    const usage = {};
+    const todos = deps.todos ?? [];
+    let steps = 0;
+    let compacted = false;
+    let overflowRecovered = false;
+    const toolContext = {
+        workspace: deps.toolsWorkspace,
+        signal: deps.signal,
+        approve: deps.approve,
+        log: deps.onNotice ?? (() => { }),
+        allowOutsideWorkspace: deps.allowOutsideWorkspace,
+        permissions: deps.permissions,
+        todos,
+        onOutput: deps.onToolOutput,
+        recordChange: deps.recordChange,
+    };
+    const tryCompact = async (aggressive) => {
+        deps.onNotice?.(aggressive ? '上游报告上下文超限，正在压缩历史对话后重试…' : '上下文接近上限，正在压缩历史对话…');
+        const result = await compactMessages({
+            provider: deps.provider,
+            messages: convo,
+            keepRecentChars: Math.max(200, Math.floor(deps.maxContextChars * (aggressive ? 0.25 : 0.6))),
+            maxTailMessages: aggressive ? 2 : 8,
+            signal: deps.signal,
+        });
+        if (!result) {
+            const trimmed = truncateToolOutputs(convo);
+            if (trimmed > 0)
+                deps.onNotice?.(`历史太短，已截断 ${trimmed} 条超长工具输出。`);
+            return trimmed > 0;
+        }
+        const before = estimateTokens(convo);
+        convo.length = 0;
+        convo.push(...result.messages);
+        compacted = true;
+        deps.onCompact?.({ removed: result.removed, before, after: estimateTokens(convo) });
+        return true;
+    };
+    while (steps < deps.maxSteps) {
+        if (deps.signal.aborted)
+            return { messages: convo, steps, usage, stopReason: 'aborted', compacted };
+        if (estimateChars(convo) > deps.maxContextChars) {
+            const done = await tryCompact(false);
+            if (!done)
+                deps.onNotice?.('暂时压不动（历史太短），继续用当前上下文尝试。');
+        }
+        let result;
+        try {
+            deps.onStep?.(steps + 1);
+            result = await deps.provider.generate({
+                messages: convo,
+                system: deps.system,
+                tools: schemas,
+                signal: deps.signal,
+                onText: deps.onText,
+                onReasoning: deps.onReasoning,
+                onRetry: deps.onRetry,
+            });
+        }
+        catch (error) {
+            if (deps.signal.aborted)
+                return { messages: convo, steps, usage, stopReason: 'aborted', compacted };
+            const message = error instanceof Error ? error.message : String(error);
+            // 上下文超限：压缩后原地重试一次，不算作一步
+            if (!overflowRecovered && isContextOverflowError(message)) {
+                overflowRecovered = true;
+                if (await tryCompact(true))
+                    continue;
+            }
+            return { messages: convo, steps, usage, stopReason: 'error', error: message, compacted };
+        }
+        steps += 1;
+        Object.assign(usage, mergeUsage(usage, result.usage));
+        convo.push(result.message);
+        const calls = result.message.toolCalls ?? [];
+        if (calls.length === 0) {
+            return { messages: convo, steps, usage, stopReason: 'done', compacted };
+        }
+        for (let index = 0; index < calls.length; index += 1) {
+            const call = calls[index];
+            if (deps.signal.aborted) {
+                // 为所有未执行的 tool_use 补上结果，避免下一轮协议校验失败
+                for (const pending of calls.slice(index)) {
+                    convo.push({
+                        role: 'tool',
+                        toolCallId: pending.id,
+                        name: pending.name,
+                        content: '操作被用户中断。',
+                        isError: true,
+                    });
+                }
+                return { messages: convo, steps, usage, stopReason: 'aborted', compacted };
+            }
+            const input = (call.input && typeof call.input === 'object' ? call.input : {});
+            const tool = tools.get(call.name);
+            if (!tool) {
+                const result = {
+                    ok: false,
+                    content: `未知工具 "${call.name}"。可用工具: ${[...tools.keys()].join(', ')}。请改用已有工具。`,
+                };
+                deps.onToolEnd?.(call.name, result);
+                convo.push({ role: 'tool', toolCallId: call.id, name: call.name, content: result.content, isError: true });
+                continue;
+            }
+            deps.onToolStart?.(call.name, input);
+            const toolResult = await runTool(tool, input, toolContext, permissionFor(deps.permissions, tool));
+            deps.onToolEnd?.(call.name, toolResult);
+            convo.push({
+                role: 'tool',
+                toolCallId: call.id,
+                name: call.name,
+                content: toolResult.content,
+                isError: !toolResult.ok,
+            });
+        }
+    }
+    return { messages: convo, steps, usage, stopReason: 'max_steps', compacted };
+}