minimal-agent 0.18.8 → 0.18.10

package/src/tools/shared/fileActivity.ts

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
-import { readFile, realpath } from 'node:fs/promises';
+import { realpath, stat } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
 import { extname, isAbsolute, relative, resolve, sep } from 'node:path';
 
 import { getWorkingDir } from '../../bootstrap/workingDir.js';
@@ -48,7 +49,15 @@ export async function fileActivityMetadata(
 
   let sha256: string | undefined;
   if (activity !== 'deleted') {
-    try { sha256 = createHash('sha256').update(await readFile(candidate)).digest('hex'); }
+    try {
+      // A range Read must not secretly load/hash a gigabyte for UI metadata.
+      // Hash is optional for sources; committed artifacts use bounded buffers.
+      if (activity !== 'read' || (await stat(candidate)).size <= 8 * 1024 * 1024) {
+        const hash = createHash('sha256');
+        for await (const chunk of createReadStream(candidate)) hash.update(chunk);
+        sha256 = hash.digest('hex');
+      }
+    }
     catch { /* The file activity remains useful even when hashing fails. */ }
   }
   return {

package/src/tools/shared/fileState.js

@@ -16,6 +16,7 @@ export function recordRead(absPath, opts, state = defaultState) {
             && st.size === prev.size;
         const sameRegionUnchanged = sameSnapshot
             && prev.offset === opts?.offset
+            && prev.column === opts?.column
             && prev.limit === opts?.limit;
         const reads = sameRegionUnchanged ? (prev.reads ?? 1) + 1 : 1;
         // A bounded Read may be repeated in several adjacent calls.  Keep the
@@ -64,6 +65,7 @@ export function recordRead(absPath, opts, state = defaultState) {
             truncated: opts?.truncated ?? false,
             partial,
             offset: opts?.offset,
+            column: opts?.column,
             limit: opts?.limit,
             reads,
             ...(opts?.contentHash ? { contentHash: opts.contentHash } : {}),

package/src/tools/shared/fileState.ts

@@ -7,6 +7,7 @@ export interface FileStateEntry {
   truncated: boolean;
   partial: boolean;
   offset?: number;
+  column?: number;
   limit?: number;
   reads?: number;
   /** SHA-256 is recorded only for a complete read. */
@@ -42,6 +43,7 @@ export function recordRead(
     truncated?: boolean;
     partial?: boolean;
     offset?: number;
+    column?: number;
     limit?: number;
     contentHash?: string;
     range?: FileReadRange;
@@ -57,6 +59,7 @@ export function recordRead(
       && st.size === prev.size;
     const sameRegionUnchanged = sameSnapshot
       && prev.offset === opts?.offset
+      && prev.column === opts?.column
       && prev.limit === opts?.limit;
     const reads = sameRegionUnchanged ? (prev.reads ?? 1) + 1 : 1;
 
@@ -107,6 +110,7 @@ export function recordRead(
       truncated: opts?.truncated ?? false,
       partial,
       offset: opts?.offset,
+      column: opts?.column,
       limit: opts?.limit,
       reads,
       ...(opts?.contentHash ? { contentHash: opts.contentHash } : {}),

package/src/tools/shared/readBudget.js

@@ -0,0 +1,12 @@
+/** Conservative chars/token reservation works for mixed code and CJK text.
+ * A response's parallel Read calls share this closure, not separate quotas.
+ */
+export function createReadBudget(remainingTokens) {
+    let available = Math.max(0, Math.floor(remainingTokens * 0.5));
+    const perRead = Math.min(1_000_000, Math.max(1000, Math.floor(available / 2)));
+    return (requested = Math.min(240_000, perRead)) => {
+        const granted = Math.min(Math.max(0, requested), perRead, available);
+        available -= granted;
+        return granted;
+    };
+}

package/src/tools/shared/readBudget.ts

@@ -0,0 +1,12 @@
+/** Conservative chars/token reservation works for mixed code and CJK text.
+ * A response's parallel Read calls share this closure, not separate quotas.
+ */
+export function createReadBudget(remainingTokens: number) {
+  let available = Math.max(0, Math.floor(remainingTokens * 0.5));
+  const perRead = Math.min(1_000_000, Math.max(1000, Math.floor(available / 2)));
+  return (requested = Math.min(240_000, perRead)) => {
+    const granted = Math.min(Math.max(0, requested), perRead, available);
+    available -= granted;
+    return granted;
+  };
+}

package/src/tools/toolPromptGuides.js

@@ -1,3 +1,4 @@
+import { AGENT_TOOL_DESCRIPTION } from '../prompts/delegation.js';
 import { bashShellNotice } from './bash/bash.js';
 import { COMPUTER_USE_TOOL_ACTIONS } from './computeruse/protocol.js';
 export const TOOL_CATEGORY_LABELS = {
@@ -42,7 +43,7 @@ export const BUILTIN_TOOL_PROMPT_GUIDES = {
     BrowserCDP: g('web', '需要现有浏览器工具未覆盖的原始 CDP 能力', '发送精确方法并按事件序列读取结果', '常规网页自动化优先 WebBrowser/BrowserBatch', 'last-resort'),
     Download: g('web', '把已知 URL 的原始资源保存到本机', '给出目标路径并校验下载结果', '只阅读正文时用 WebFetch'),
     ComputerUse: g('desktop', '用户明确要求观察或操作原生应用、系统窗口或桌面界面', '观察当前界面，执行一个动作，再验证结果', '文件、静态图片、Shell 和网页任务优先专用工具', 'last-resort'),
-    Agent: g('agents', '派生独立且边界清晰的子任务', '给出自包含任务书并在返回后核验整合', '不要拆分琐碎或强顺序工作'),
+    Agent: g('agents', '大型多模块调查优先委派独立只读问题', '先定位入口，再同轮派发 explore，核验整合证据', '少量已知文件或强顺序工作直接处理'),
     AgentMessage: g('agents', '向运行中的子 Agent 补充非触发消息', '按稳定 agent id 发送必要上下文', '需要追加新工作使用 AgentFollowup'),
     AgentList: g('agents', '查看子 Agent 状态和稳定 ID', '按任务路径列出后选择目标', '已知目标 ID 时无需调用'),
     AgentWait: g('agents', '等待指定子 Agent 进展或结果', '优先长等待，收到更新后再整合', '忙轮询'),
@@ -58,7 +59,7 @@ export const BUILTIN_TOOL_PROMPT_GUIDES = {
     RecallMemory: g('memory', '当前回答依赖跨会话稳定偏好、决定或背景', '按主题召回并核对证据', '当前消息已足够时不要装饰性召回'),
     MemoryMaintenance: g('memory', '处理学习队列、项目事实冲突及经验反馈', 'status 定位；summaries 按 query 找近期任务线索、按 turnId 查证据；resolve/resolveKnowledge 结清候选；明确跨项目适用条件后 promoteExperience/promoteKnowledge；adopt 后 feedback', '召回不算使用；失败摘要不是已确认事实；不每轮调用'),
     RememberMemory: g('memory', '用户明确要求记住长期有效事实、偏好或决定', '保存原话证据和适用范围', '普通陈述交由已启用的后台提炼，不重复保存'),
-    UpdateMemory: g('memory', '当前用户陈述纠正一条已有记忆', '先 Recall 定位版本，再完整替换', '不要创建冲突副本'),
+    UpdateMemory: g('memory', '纠正用户事实', '读版本后 update/review/confirm', '项目知识/经验走 MemoryMaintenance'),
     ListMemories: g('memory', '用户要查看已保存记忆或需要管理总览', '按范围列出后再决定操作', '正常任务无需全量列出'),
     ForgetMemory: g('memory', '用户明确要求忘记某条记忆', '定位准确 ID 后删除', '不得主动清理'),
     SetPersona: g('memory', '用户明确要求改变长期角色或协作风格', '写入清晰、稳定的人格要求', '一次性语气请求不要持久化'),
@@ -87,7 +88,7 @@ export const BUILTIN_TOOL_PROMPT_GUIDES = {
 //      测试就是从这次真实回归里补的，锁住"压缩后仍要包含这些内容"而不是简单地
 //      锁住某个具体的压缩产物。
 export const CONTRACT_DESCRIPTION_OVERRIDES = {
-    Read: '读取文本、图片、Notebook 或 PDF。文本 offset 从 1 开始；截断后缩小 limit 重读区间，不能跳过未显示内容。PDF 用 pages 指定范围，一次最多 20 页。',
+    Read: '读取文本、图片、Notebook 或 PDF。offset 从 1 开始；大范围阅读可提高 limit/max_chars，实际预算由 Runtime 分配。按回执 offset/column 续读，不能跳过截断行。PDF 用 pages，一次最多 20 页。',
     Edit: '精确替换已有文本。先 Read 最新内容，old_string 必须唯一；多处相同替换传 replace_all=true。new_string 按字面写入。',
     Write: '创建文件或整体覆盖；新文件可直接写入。覆盖已有文件前须完整 Read（一次全量或分段覆盖全部范围）且内容未变化；仅有局部读取时使用 Edit/ApplyPatch。',
     ApplyPatch: '提交 Codex 格式补丁，必须用 *** Begin Patch / *** End Patch 包络，不接受裸 git diff。支持 Add/Update/Delete File、Move to；路径相对工作区。先校验，写入失败尝试回滚，不保证跨文件断电原子性。',
@@ -111,13 +112,13 @@ export const CONTRACT_DESCRIPTION_OVERRIDES = {
     Advisor: '向无工具权限的顾问模型请求一次结构化第二意见。默认 reviewMode=brief 只给重点短评；完整代码审查用 full，并提供范围、基线和证据。full 不扩大上下文或输出预算，材料不足时必须说明未完成。',
     // 保留决策必填条件，与 schema 的 superRefine 一致；不能只概括成“记录决定”。
     AdvisorDecision: '记录主 Agent 对顾问第二意见的 accept、partial 或 reject 判断；是否采纳由主 Agent 决定，登记不是执行许可。partial 同时填 acceptedPoints/rejectedPoints；reject 填 rejectedPoints，列出被拒绝点及依据；evidenceRefs 只引用真实 tool_call_id，没有引用则记录待验证。登记失败不阻止任务继续。',
-    MultiEdit: '同文件有序批量精确替换，先 Read；全部匹配成功才写盘。old_string 非空且唯一，或显式 replace_all。后续匹配前序生成文本会被拒绝，请合并 edits。',
+    MultiEdit: '同文件有序批量精确替换，先 Read 相关范围；全部匹配成功才写盘。old_string 非空且唯一，或显式 replace_all。后续匹配前序生成文本会被拒绝，请合并 edits。操作条数不等于替换次数，diff 预览可能不完整。',
     LSP: '查询定义、引用、类型、符号和诊断。line/character 为 1-based UTF-16；尚未收到诊断不等于没有错误，编辑前读取源码。',
     WebFetch: '读取已知 HTTP(S) URL 的静态文本，HTML 转 Markdown；不执行 JavaScript、不继承登录态。PDF/图片用 Download 后 Read；动态页面用 WebBrowser。',
     WebSearch: 'Tavily 搜索返回标题、URL、片段及可选综合答案，不是完整原文或浏览器。重要结论读取来源正文；按子问题查询，重试改变关键词或来源。recency 控制时效，历史范围用 start_date/end_date，none 关闭自动时效；advanced 更慢，news 偏新闻。需配置 Tavily。',
     PowerShell: '运行宿主 PowerShell 独立进程并检查结果；长任务用 TaskOutput/TaskStop。永久删除用 Trash；不可逆操作先确认，非交互时取消。',
     Download: '下载 HTTP(S) 原始字节到指定路径；相对路径基于工作目录，会覆盖已有文件；失败或中断不保留部分下载。',
-    Agent: '启动隔离上下文子任务并返回 agent_id。explore 只读，general 按 write_scopes 或 worktree 执行。run_in_background 立即返回；resume_agent_id 续接私有历史。context.researchQuestions 定义问题契约，AgentReport.findings 按 ID 回传证据结论；reportMaxChars 限制返回预览，完整交接可由 TaskOutput 获取。',
+    Agent: AGENT_TOOL_DESCRIPTION,
     EnterWorktree: '从已提交 HEAD 创建并进入隔离工作树，不自动复制原工作区未提交修改；后续文件工具使用隔离目录，项目记忆仍属于原工作区。',
     ExitWorktree: '退出隔离工作树：apply 检查并应用补丁到原工作区但不自动提交；keep 保留；discard 有改动则归档保留。实际应用成功后的清理告警不表示应重新应用。',
 };

package/src/tools/toolPromptGuides.ts

@@ -1,4 +1,5 @@
 import type { Tool, ToolCategory, ToolPromptGuide } from '../types.js';
+import { AGENT_TOOL_DESCRIPTION } from '../prompts/delegation.js';
 import { bashShellNotice } from './bash/bash.js';
 import { COMPUTER_USE_TOOL_ACTIONS } from './computeruse/protocol.js';
 
@@ -56,7 +57,7 @@ export const BUILTIN_TOOL_PROMPT_GUIDES: Readonly<Record<string, ToolPromptGuide
 
   ComputerUse: g('desktop', '用户明确要求观察或操作原生应用、系统窗口或桌面界面', '观察当前界面，执行一个动作，再验证结果', '文件、静态图片、Shell 和网页任务优先专用工具', 'last-resort'),
 
-  Agent: g('agents', '派生独立且边界清晰的子任务', '给出自包含任务书并在返回后核验整合', '不要拆分琐碎或强顺序工作'),
+  Agent: g('agents', '大型多模块调查优先委派独立只读问题', '先定位入口，再同轮派发 explore，核验整合证据', '少量已知文件或强顺序工作直接处理'),
   AgentMessage: g('agents', '向运行中的子 Agent 补充非触发消息', '按稳定 agent id 发送必要上下文', '需要追加新工作使用 AgentFollowup'),
   AgentList: g('agents', '查看子 Agent 状态和稳定 ID', '按任务路径列出后选择目标', '已知目标 ID 时无需调用'),
   AgentWait: g('agents', '等待指定子 Agent 进展或结果', '优先长等待，收到更新后再整合', '忙轮询'),
@@ -73,7 +74,7 @@ export const BUILTIN_TOOL_PROMPT_GUIDES: Readonly<Record<string, ToolPromptGuide
   RecallMemory: g('memory', '当前回答依赖跨会话稳定偏好、决定或背景', '按主题召回并核对证据', '当前消息已足够时不要装饰性召回'),
   MemoryMaintenance: g('memory', '处理学习队列、项目事实冲突及经验反馈', 'status 定位；summaries 按 query 找近期任务线索、按 turnId 查证据；resolve/resolveKnowledge 结清候选；明确跨项目适用条件后 promoteExperience/promoteKnowledge；adopt 后 feedback', '召回不算使用；失败摘要不是已确认事实；不每轮调用'),
   RememberMemory: g('memory', '用户明确要求记住长期有效事实、偏好或决定', '保存原话证据和适用范围', '普通陈述交由已启用的后台提炼，不重复保存'),
-  UpdateMemory: g('memory', '当前用户陈述纠正一条已有记忆', '先 Recall 定位版本，再完整替换', '不要创建冲突副本'),
+  UpdateMemory: g('memory', '纠正用户事实', '读版本后 update/review/confirm', '项目知识/经验走 MemoryMaintenance'),
   ListMemories: g('memory', '用户要查看已保存记忆或需要管理总览', '按范围列出后再决定操作', '正常任务无需全量列出'),
   ForgetMemory: g('memory', '用户明确要求忘记某条记忆', '定位准确 ID 后删除', '不得主动清理'),
   SetPersona: g('memory', '用户明确要求改变长期角色或协作风格', '写入清晰、稳定的人格要求', '一次性语气请求不要持久化'),
@@ -104,7 +105,7 @@ export const BUILTIN_TOOL_PROMPT_GUIDES: Readonly<Record<string, ToolPromptGuide
 //      测试就是从这次真实回归里补的，锁住"压缩后仍要包含这些内容"而不是简单地
 //      锁住某个具体的压缩产物。
 export const CONTRACT_DESCRIPTION_OVERRIDES: Readonly<Record<string, string | (() => string)>> = {
-  Read: '读取文本、图片、Notebook 或 PDF。文本 offset 从 1 开始；截断后缩小 limit 重读区间，不能跳过未显示内容。PDF 用 pages 指定范围，一次最多 20 页。',
+  Read: '读取文本、图片、Notebook 或 PDF。offset 从 1 开始；大范围阅读可提高 limit/max_chars，实际预算由 Runtime 分配。按回执 offset/column 续读，不能跳过截断行。PDF 用 pages，一次最多 20 页。',
   Edit: '精确替换已有文本。先 Read 最新内容，old_string 必须唯一；多处相同替换传 replace_all=true。new_string 按字面写入。',
   Write: '创建文件或整体覆盖；新文件可直接写入。覆盖已有文件前须完整 Read（一次全量或分段覆盖全部范围）且内容未变化；仅有局部读取时使用 Edit/ApplyPatch。',
   ApplyPatch: '提交 Codex 格式补丁，必须用 *** Begin Patch / *** End Patch 包络，不接受裸 git diff。支持 Add/Update/Delete File、Move to；路径相对工作区。先校验，写入失败尝试回滚，不保证跨文件断电原子性。',
@@ -129,13 +130,13 @@ export const CONTRACT_DESCRIPTION_OVERRIDES: Readonly<Record<string, string | ((
   Advisor: '向无工具权限的顾问模型请求一次结构化第二意见。默认 reviewMode=brief 只给重点短评；完整代码审查用 full，并提供范围、基线和证据。full 不扩大上下文或输出预算，材料不足时必须说明未完成。',
   // 保留决策必填条件，与 schema 的 superRefine 一致；不能只概括成“记录决定”。
   AdvisorDecision: '记录主 Agent 对顾问第二意见的 accept、partial 或 reject 判断；是否采纳由主 Agent 决定，登记不是执行许可。partial 同时填 acceptedPoints/rejectedPoints；reject 填 rejectedPoints，列出被拒绝点及依据；evidenceRefs 只引用真实 tool_call_id，没有引用则记录待验证。登记失败不阻止任务继续。',
-  MultiEdit: '同文件有序批量精确替换，先 Read；全部匹配成功才写盘。old_string 非空且唯一，或显式 replace_all。后续匹配前序生成文本会被拒绝，请合并 edits。',
+  MultiEdit: '同文件有序批量精确替换，先 Read 相关范围；全部匹配成功才写盘。old_string 非空且唯一，或显式 replace_all。后续匹配前序生成文本会被拒绝，请合并 edits。操作条数不等于替换次数，diff 预览可能不完整。',
   LSP: '查询定义、引用、类型、符号和诊断。line/character 为 1-based UTF-16；尚未收到诊断不等于没有错误，编辑前读取源码。',
   WebFetch: '读取已知 HTTP(S) URL 的静态文本，HTML 转 Markdown；不执行 JavaScript、不继承登录态。PDF/图片用 Download 后 Read；动态页面用 WebBrowser。',
   WebSearch: 'Tavily 搜索返回标题、URL、片段及可选综合答案，不是完整原文或浏览器。重要结论读取来源正文；按子问题查询，重试改变关键词或来源。recency 控制时效，历史范围用 start_date/end_date，none 关闭自动时效；advanced 更慢，news 偏新闻。需配置 Tavily。',
   PowerShell: '运行宿主 PowerShell 独立进程并检查结果；长任务用 TaskOutput/TaskStop。永久删除用 Trash；不可逆操作先确认，非交互时取消。',
   Download: '下载 HTTP(S) 原始字节到指定路径；相对路径基于工作目录，会覆盖已有文件；失败或中断不保留部分下载。',
-  Agent: '启动隔离上下文子任务并返回 agent_id。explore 只读，general 按 write_scopes 或 worktree 执行。run_in_background 立即返回；resume_agent_id 续接私有历史。context.researchQuestions 定义问题契约，AgentReport.findings 按 ID 回传证据结论；reportMaxChars 限制返回预览，完整交接可由 TaskOutput 获取。',
+  Agent: AGENT_TOOL_DESCRIPTION,
   EnterWorktree: '从已提交 HEAD 创建并进入隔离工作树，不自动复制原工作区未提交修改；后续文件工具使用隔离目录，项目记忆仍属于原工作区。',
   ExitWorktree: '退出隔离工作树：apply 检查并应用补丁到原工作区但不自动提交；keep 保留；discard 有改动则归档保留。实际应用成功后的清理告警不表示应重新应用。',
 };

package/src/tools/types.js

@@ -11,11 +11,7 @@ export const DEFAULT_MAX_RESULT_SIZE_CHARS = 30_000;
 /** Read 工具默认行数上限（与 kakadeai 主仓库一致） */
 export const MAX_LINES_TO_READ = 2000;
 /**
- * Read 工具默认字节上限（防止超大文件灌进上下文）。
- * 基于 200K 上下文窗口设计：
- * - system prompt + 工具定义 ≈ 30KB
- * - 对话历史 ≈ 100KB
- * - 单次读取安全上限 ≈ 256KB（~64K tokens）
- * 超过此限制请用 offset/limit 分段读。
+ * Text input IO ceiling, independent of the model's returned-content budget.
+ * Read windows are bounded separately and can reserve runtime context capacity.
  */
 export const MAX_FILE_SIZE_BYTES = 1024 * 1024 * 1024; // 1 GiB; returned content remains independently bounded

package/src/tools/types.ts

@@ -14,11 +14,7 @@ export const DEFAULT_MAX_RESULT_SIZE_CHARS = 30_000;
 export const MAX_LINES_TO_READ = 2000;
 
 /**
- * Read 工具默认字节上限（防止超大文件灌进上下文）。
- * 基于 200K 上下文窗口设计：
- * - system prompt + 工具定义 ≈ 30KB
- * - 对话历史 ≈ 100KB
- * - 单次读取安全上限 ≈ 256KB（~64K tokens）
- * 超过此限制请用 offset/limit 分段读。
+ * Text input IO ceiling, independent of the model's returned-content budget.
+ * Read windows are bounded separately and can reserve runtime context capacity.
  */
 export const MAX_FILE_SIZE_BYTES = 1024 * 1024 * 1024; // 1 GiB; returned content remains independently bounded

package/src/types.ts

@@ -291,8 +291,8 @@ export interface FilePatchSummary {
   unifiedDiff?: string;
   beforeHash?: string;
   afterHash: string;
-  additions: number;
-  deletions: number;
+  additions?: number;
+  deletions?: number;
   truncated: boolean;
   omittedReason?: 'too_large';
 }
@@ -570,6 +570,8 @@ export type ToolResult = { problem?: ToolProblemOutcome; observation?: ReadObser
  * 避免按工具名写特判分支。
  */
 export interface ToolCallContext {
+  /** Shared per-model-response read allowance; reservations happen before IO. */
+  reserveReadChars?: (requested?: number) => number;
   /** Host presentation only; cannot grant tools to a delegated agent. */
   output?: import('./runtime/outputContract.js').OutputContract;
   /** Live effective catalog, including per-turn restrictions. */