mocode-ai 0.4.7 → 0.4.9

package/dist/tools/builtins/codegraph.js

@@ -10,8 +10,9 @@ import { MAX_OUTPUT } from '../constants.js';
 function hasCodegraphIndex() {
     return existsSync(path.join(process.cwd(), '.codegraph'));
 }
-/** 跑 codegraph CLI 子进程,返回合并 stdout+stderr(带退出码),超时 60s。 */
-function runCodegraph(args) {
+/** 跑 codegraph CLI 子进程,返回合并 stdout+stderr(带退出码),超时 60s。
+ *  signal 透传(用户 Ctrl+C)→ 即时杀子进程,不等 60s 超时。 */
+function runCodegraph(args, signal) {
     return new Promise((done) => {
         const isWin = process.platform === 'win32';
         // win32 必须走 cmd.exe /c:Node 自 CVE-2024-27980 修复后,shell:false 直接 spawn
@@ -26,6 +27,7 @@ function runCodegraph(args) {
                 return;
             finished = true;
             clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
             done(s);
         };
         const onChunk = (chunk) => {
@@ -46,6 +48,17 @@ function runCodegraph(args) {
             child.kill();
             finish(`[超时,已终止]\n${out.trim()}`);
         }, 60000);
+        // abort(用户 Ctrl+C,经 executeTool ctx.signal 透传)→ 杀子进程 + 返[已中断]
+        const onAbort = () => {
+            child.kill();
+            finish(`[已中断]\n${out.trim()}`);
+        };
+        if (signal) {
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener('abort', onAbort, { once: true });
+        }
     });
 }
 export const codegraphTool = {
@@ -84,7 +97,7 @@ export const codegraphTool = {
         },
         required: ['action', 'query'],
     },
-    async execute(args) {
+    async execute(args, ctx) {
         if (!hasCodegraphIndex()) {
             return ('当前目录无 .codegraph/ 索引。codegraph 工具不可用。\n' +
                 '建索引:运行 `codegraph init`(需要 codegraph CLI:`npm i -g @colbymchenry/codegraph`)。\n' +
@@ -110,6 +123,6 @@ export const codegraphTool = {
         else {
             return `错误:未知 action "${action}",可选 explore 或 node。`;
         }
-        return runCodegraph(cliArgs);
+        return runCodegraph(cliArgs, ctx?.signal);
     },
 };

package/dist/tools/builtins/drop-context.d.ts

@@ -0,0 +1,18 @@
+import type { Tool } from '../types.js';
+/**
+ * 运行中上下文剔除工具:agent 检索到大量无关信息后,主动把历史里无关的 tool 结果替换为存根,
+ * 释放上下文空间(保 tool_call_id 配对不变量,只改 content)。
+ *
+ * 与 compact 的区别:compact 是阈值触发的整体压缩(微截 + 摘要);drop_context 是 agent 主动、
+ * 精准剔除"已判定无关"的具体 tool 结果。
+ *
+ * 保护:history[0](system)与当前轮(最后一个 user 及其之后)永不剔除——agent 还在用。
+ * 已是存根的不重复剔除(幂等)。永不抛错。
+ *
+ * 筛选(各维度 AND 组合,全部可选;不传 = 剔除所有可剔除的旧 tool 结果):
+ *  - toolNames:只剔除这些工具名的结果(如 ["grep","read_file"])
+ *  - contains:只剔除内容包含所有这些词(AND、大小写不敏感)的结果
+ *
+ * plan 模式不禁用:纯上下文管理,无文件 / 命令副作用。
+ */
+export declare const dropContextTool: Tool;

package/dist/tools/builtins/edit-file.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from '../types.js';
+export declare const editFileTool: Tool;

package/dist/tools/builtins/edit-file.js

@@ -4,6 +4,7 @@ import { resolve } from 'node:path';
 export const editFileTool = {
     name: 'edit_file',
     description: 'Replace a string in a file. old_string must occur exactly once and match exactly (including indentation/newlines). Use write_file for new files.',
+    risk: 'confirm',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/glob.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from '../types.js';
+export declare const globTool: Tool;

package/dist/tools/builtins/grep.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from '../types.js';
+export declare const grepTool: Tool;

package/dist/tools/builtins/index.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from '../types.js';
+export declare const builtinTools: Tool[];

package/dist/tools/builtins/index.js

@@ -18,6 +18,7 @@ import { memoryUpdateTool } from './memory-update.js';
 import { memoryForgetTool } from './memory-forget.js';
 import { taskTool } from './task.js';
 import { todolistTool } from './todolist.js';
+import { projectSkillUpdateTool } from './project-skill-update.js';
 /**
  * 所有内置工具,按注册顺序排列。
  * 加新工具:在本目录新建 `xxx.ts` 导出一个 Tool,再在下面数组里加一行。无需改 agent / llm。
@@ -41,6 +42,11 @@ const _memoryTools = _memoryEnabledAtBoot
         memoryForgetTool,
     ]
     : [];
+/** 项目专属 Skill 工具:仅在 MOCODE_PROJECT_SKILL=true 时注册,与 memory 同模式。 */
+const _projectSkillEnabledAtBoot = process.env.MOCODE_PROJECT_SKILL === 'true';
+const _projectSkillTools = _projectSkillEnabledAtBoot
+    ? [projectSkillUpdateTool]
+    : [];
 export const builtinTools = [
     readFileTool,
     writeFileTool,
@@ -56,6 +62,7 @@ export const builtinTools = [
     switchModeTool, // plan↔auto 自切(两模式都可见,不进 PLAN_DISABLED_TOOLS;副作用控制工具→串行分支)
     dropContextTool, // 运行中剔除无关 tool 结果(上下文管理,无副作用;两模式都可见,串行分支)
     ..._memoryTools,
+    ..._projectSkillTools,
     taskTool, // 派生子 agent(独立 history + 可受限工具集);plan 模式禁用(见 PLAN_DISABLED_TOOLS)
     todolistTool, // 工作记事本(plan 文件:复杂任务 checklist,落盘抗压缩);plan 模式可用(便于「先 plan 再 auto」时落地执行清单)
 ];

package/dist/tools/builtins/memory-forget.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from '../types.js';
+export declare const memoryForgetTool: Tool;

package/dist/tools/builtins/memory-forget.js

@@ -4,6 +4,7 @@ import { forgetEntry } from '../../memory/store.js';
 export const memoryForgetTool = {
     name: 'memory_forget',
     description: 'Forget a memory entry: default archive (hidden, revivable via memory_update); mode=delete hard-deletes. Pinned entries can\'t be deleted (unpin first).',
+    risk: 'confirm',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/memory-list.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from '../types.js';
+export declare const memoryListTool: Tool;

package/dist/tools/builtins/memory-save.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from '../types.js';
+export declare const memorySaveTool: Tool;

package/dist/tools/builtins/memory-save.js

@@ -5,6 +5,7 @@ import { saveEntry } from '../../memory/store.js';
 export const memorySaveTool = {
     name: 'memory_save',
     description: 'Save a cross-session long-term memory entry. Store only non-obvious, useful facts/decisions/pitfalls. Title enters the startup index; retrieve body via memory_search.',
+    risk: 'confirm',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/memory-search.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from '../types.js';
+export declare const memorySearchTool: Tool;

package/dist/tools/builtins/memory-update.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from '../types.js';
+export declare const memoryUpdateTool: Tool;

package/dist/tools/builtins/memory-update.js

@@ -4,6 +4,7 @@ import { updateEntry } from '../../memory/store.js';
 export const memoryUpdateTool = {
     name: 'memory_update',
     description: 'Update a memory entry in place (id unchanged). Use when facts changed / correcting outdated info / toggling pinned. Get id from memory_list or memory_search.',
+    risk: 'confirm',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/project-skill-update.js

@@ -0,0 +1,73 @@
+import { readProjectSkill, writeProjectSkill, appendProjectSkill, } from '../../project-skill/index.js';
+/**
+ * 项目专属 Skill 更新工具。
+ * 支持三种操作:
+ *   - read: 读取当前 skill 内容
+ *   - write: 全量覆盖(适合重构整个 skill)
+ *   - append: 追加到末尾(适合发现新坑点/约定时增量更新)
+ *
+ * 使用场景:
+ *   - 开发过程中发现项目特有的架构模式、命名约定
+ *   - 踩坑后记录避坑指南
+ *   - 总结项目关键决策和设计理由
+ *   - 随着项目开发，skill 越来越了解项目，开发效率越来越高
+ */
+export const projectSkillUpdateTool = {
+    name: 'project_skill_update',
+    description: 'Update the project-specific skill file (.mocode/project-skill.md). ' +
+        'Use this to record architectural patterns, naming conventions, common pitfalls, ' +
+        'and key decisions specific to this project. The skill persists across sessions and ' +
+        'is injected into the system prompt when MOCODE_PROJECT_SKILL=true. ' +
+        'Actions: "read" (view current content), "write" (replace all), "append" (add to end).',
+    risk: 'safe',
+    parameters: {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                enum: ['read', 'write', 'append'],
+                description: 'Action to perform: "read" to view current content, "write" to replace all, "append" to add to end',
+            },
+            content: {
+                type: 'string',
+                description: 'Content to write or append (required for "write" and "append" actions, ignored for "read")',
+            },
+        },
+        required: ['action'],
+    },
+    execute: async (args) => {
+        const action = String(args.action ?? '').trim();
+        const content = String(args.content ?? '');
+        switch (action) {
+            case 'read': {
+                const current = readProjectSkill();
+                if (!current) {
+                    return 'Project skill is empty or does not exist yet.';
+                }
+                return `Current project skill:\n\n${current}`;
+            }
+            case 'write': {
+                if (!content.trim()) {
+                    return 'Error: "write" action requires non-empty content parameter.';
+                }
+                const result = writeProjectSkill(content);
+                if (!result.ok) {
+                    return `Error: ${result.error}`;
+                }
+                return 'Project skill updated successfully (full replacement).';
+            }
+            case 'append': {
+                if (!content.trim()) {
+                    return 'Error: "append" action requires non-empty content parameter.';
+                }
+                const result = appendProjectSkill(content);
+                if (!result.ok) {
+                    return `Error: ${result.error}`;
+                }
+                return 'Project skill updated successfully (appended).';
+            }
+            default:
+                return `Error: Unknown action "${action}". Use "read", "write", or "append".`;
+        }
+    },
+};

package/dist/tools/builtins/read-file.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from '../types.js';
+export declare const readFileTool: Tool;

package/dist/tools/builtins/read-file.js

@@ -1,6 +1,8 @@
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { MAX_FILE_LINES } from '../constants.js';
+import { lookupSnapshotFile } from '../../project-snapshot/index.js';
+import { config } from '../../config/index.js';
 /** 默认单次 read_file 拉取的行数。刻意压低,逼 LLM 分块读大文件,
  * 配合 description 中的 PAGINATION IS MANDATORY 引导。
  * 300 行 ≈ 一个屏幕的源码量,够定位一段逻辑而不至于吃光上下文。 */
@@ -29,7 +31,21 @@ export const readFileTool = {
         const offset = Number(args.offset ?? 1);
         // 无论 LLM 传多大,单次硬钳到 MAX_FILE_LINES,杜绝「绕过分页引导一把全拿」。
         const limit = Math.min(Number(args.limit ?? DEFAULT_READ_LIMIT), MAX_FILE_LINES);
-        const data = await readFile(resolve(path), 'utf8');
+        // 项目快照 cache hit：mtime 校验通过则直接返回，省磁盘读
+        let data;
+        if (config.projectSnapshotEnabled) {
+            const absPath = resolve(path);
+            const cached = lookupSnapshotFile(absPath);
+            if (cached) {
+                data = cached.content;
+            }
+            else {
+                data = await readFile(absPath, 'utf8');
+            }
+        }
+        else {
+            data = await readFile(resolve(path), 'utf8');
+        }
         const lines = data.split(/\r?\n/);
         const start = Math.max(0, offset - 1);
         const end = Math.min(lines.length, start + limit);

package/dist/tools/builtins/run-command.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from '../types.js';
+export declare const runCommandTool: Tool;

package/dist/tools/builtins/run-command.js

@@ -5,6 +5,7 @@ import { getSandboxRoot, filterEnv, isCommandDenied } from '../../sandbox/index.
 export const runCommandTool = {
     name: 'run_command',
     description: 'Run a shell command, merging stdout+stderr. Default timeout 120s. For tests, builds, git, etc.',
+    risk: 'dangerous',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/switch-mode.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from '../types.js';
+export declare const switchModeTool: Tool;

package/dist/tools/builtins/task.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from '../types.js';
+export declare const taskTool: Tool;

package/dist/tools/builtins/task.js

@@ -8,6 +8,7 @@ import { MAX_OUTPUT } from '../constants.js';
 // 子 agent 中间过程不写主屏,只返回最终摘要;主 agent 据摘要决定下一步。
 export const taskTool = {
     name: 'task',
+    risk: 'dangerous',
     description: [
         'Spawn a sub-agent for an isolated sub-task (independent history; only its final summary returns to you).',
         'Use when a task splits into independent parts or its many tool calls would bloat your context.',

package/dist/tools/builtins/todolist.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from '../types.js';
+export declare const todolistTool: Tool;

package/dist/tools/builtins/use-skill.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from '../types.js';
+export declare const useSkillTool: Tool;

package/dist/tools/builtins/web-fetch.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from '../types.js';
+export declare const webFetchTool: Tool;

package/dist/tools/builtins/web-search.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from '../types.js';
+export declare const webSearchTool: Tool;

package/dist/tools/builtins/web-search.js

@@ -24,7 +24,7 @@ export const webSearchTool = {
         },
         required: ['query'],
     },
-    async execute(args) {
+    async execute(args, ctx) {
         const query = String(args.query ?? '').trim();
         if (!query)
             return '错误:query 不能为空。';
@@ -53,6 +53,15 @@ export const webSearchTool = {
         }
         const ctrl = new AbortController();
         const timer = setTimeout(() => ctrl.abort(), SEARCH_TIMEOUT_MS);
+        // 外部 abort signal(用户 Ctrl+C,经 executeTool ctx.signal 透传)→ 合并到 ctrl,fetch 即时取消(不等 30s 超时)
+        const onExternalAbort = () => ctrl.abort();
+        const externalSignal = ctx?.signal;
+        if (externalSignal) {
+            if (externalSignal.aborted)
+                ctrl.abort();
+            else
+                externalSignal.addEventListener('abort', onExternalAbort, { once: true });
+        }
         try {
             const resp = await fetch(url, {
                 method: 'POST',
@@ -127,6 +136,8 @@ export const webSearchTool = {
         }
         finally {
             clearTimeout(timer);
+            if (externalSignal)
+                externalSignal.removeEventListener('abort', onExternalAbort);
         }
     },
 };

package/dist/tools/builtins/write-file.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from '../types.js';
+export declare const writeFileTool: Tool;

package/dist/tools/builtins/write-file.js

@@ -4,6 +4,7 @@ import { resolve, dirname } from 'node:path';
 export const writeFileTool = {
     name: 'write_file',
     description: 'Create or overwrite a file; parent dirs created.',
+    risk: 'confirm',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/constants.d.ts

@@ -0,0 +1,52 @@
+export declare const MAX_FILE_LINES = 2000;
+export declare const MAX_OUTPUT = 20000;
+export declare const MAX_RESULTS = 100;
+/** 进 history 的单条工具结果上限(字符)。push-time 第一层裁剪,保 head + 标记 + tail。 */
+export declare const MAX_HISTORY_RESULT = 8000;
+/** use_skill 结果(SKILL.md 正文)的放宽上限:指令须完整,中截会破坏语义。 */
+export declare const MAX_SKILL_RESULT = 64000;
+/** 微压缩时旧工具结果截到的存根长度(字符)。 */
+export declare const MAX_OLD_TOOL_STUB = 600;
+/** 单条记忆 body 上限(字符)。进 history 前 memory_search 结果另有 MAX_MEMORY_RESULT 兜底。 */
+export declare const MAX_MEMORY_ENTRY = 4000;
+/** 启动注入 systemPrompt 的索引条目上限(遗忘封顶后 active 条目 ≤ MAX_ACTIVE,索引再封一层)。 */
+export declare const MAX_INDEX_ENTRIES = 50;
+/** active 记忆封顶:超则按 recallCount 低 × lastRecalledAt 老 淘汰到 archived。 */
+export declare const MAX_ACTIVE = 100;
+/** 衰减:active + !pinned + (lastRecalledAt|createdAt) 早于 DECAY_DAYS → archived。 */
+export declare const DECAY_DAYS = 30;
+/** GC:archived 超 GC_DAYS → 硬删。 */
+export declare const GC_DAYS = 90;
+/** memory_search 结果(召回的记忆正文)的放宽上限:指令性内容,中截破坏语义,对齐 use_skill。 */
+export declare const MAX_MEMORY_RESULT = 64000;
+export declare const IGNORE: string[];
+/** Hot/Cold 划分:当前 step 起往前 N 个 user turn 之内的工具结果视为 Hot(绝对不压),
+ * 之外的视为 Cold(可调度器压)。默认 4 = 跨过 4 个用户问题仍生效。 */
+export declare const HOT_TURN_WINDOW = 4;
+/** Cold 区内可被就地 stub 的 tool 消息最低 age(经过的消费者 push 数)。默认 2,
+ * 与 lifecycle.ts DEFAULT_AGE_THRESHOLD 对齐。 */
+export declare const TOOL_OLD_AGE = 2;
+/** 五区预算占比(总和 0.95,留 5% 给 Reserve)。对齐 user 修正版:
+ * System 15 / History 20 / Hot Tool 25 / Cold Tool 25 / Summary 10。 */
+export declare const BUDGET_RATIO: {
+    readonly system: 0.15;
+    readonly history: 0.2;
+    readonly toolRecent: 0.25;
+    readonly toolOld: 0.25;
+    readonly summary: 0.1;
+    readonly reserve: 0.05;
+};
+/**
+ * plan 模式下从工具 schema 里剔除的工具(模型根本看不到 → 调不到):
+ * 写盘 / 命令 / 记忆写入类 + task(派生子 agent,plan 模式只读不可有副作用)。单一事实源,
+ * 被 llm(planChatTools)与 agent(防御 backstop)共用。
+ * 只读工具(read_file/glob/grep/codegraph/web_search/web_fetch/use_skill/ask_human/memory_search/memory_list)保留。
+ */
+export declare const PLAN_DISABLED_TOOLS: Set<string>;
+/**
+ * 按当前 isMemoryEnabled() 现算 plan 模式应屏蔽的工具。
+ * memoryEnabled=false 时记忆工具整体不在 builtinTools 里,plan 屏蔽集里也无须再列 ——
+ * 反之留着只是死名字。统一过滤,避免 Set 里残留与已下架工具不一致的概念性冗余。
+ * 调用方(agent/core 串行分支、llm/planChatTools)每次 chat 时调本函数拿当前值。
+ */
+export declare function getPlanDisabledTools(): Set<string>;

package/dist/tools/registry.d.ts

@@ -0,0 +1,18 @@
+import type { Tool, DropContextFilter, DropContextResult } from './types.js';
+/**
+ * 工具注册表。当前 = 内置工具;
+ * 未来可在此合并 MCP 工具、用户自定义工具等(见 src/mcp/)。
+ */
+export declare const tools: Tool[];
+/**
+ * 按名调度工具,统一 try/catch + JSON 解析,返回字符串而非抛错。
+ * signal 透传给 tool.execute(经 ctx):长任务工具(run_command/web_fetch)abort 即时取消,
+ * 让用户 Ctrl+C 能跟手中断工具执行(而非等命令跑完 / 超时)。
+ * opts.skipRollback:子 agent 逻辑隔离用——跳过 recordMutation,子 agent 改动不进主回滚快照链。
+ * opts.dropContext:上下文剔除回调(drop_context 工具用),透传给 tool.execute 经 ctx。
+ */
+export declare function executeTool(name: string, argsRaw: string, signal?: AbortSignal, opts?: {
+    skipRollback?: boolean;
+    dropContext?: (filter: DropContextFilter) => DropContextResult;
+}): Promise<string>;
+export type { Tool, ToolContext, DropContextFilter, DropContextResult } from './types.js';

package/dist/tools/types.d.ts

@@ -0,0 +1,42 @@
+/** 工具执行时收到的运行时上下文(可选)。不用的工具可忽略。 */
+export interface ToolContext {
+    /** agent 循环的 abort signal(用户 Ctrl+C 中断当前轮)。长任务工具(run_command/web_fetch)
+     * 挂监听:abort 即取消(杀子进程 / 取消 fetch),让中断跟手而非等命令跑完或超时。
+     * 子 agent 透传主 signal:主 Ctrl+C 树杀子 agent(经 task→spawnAgent→runAgentCore→executeTool)。 */
+    signal?: AbortSignal;
+    /** 跳过回滚快照记录。子 agent(logical-isolation 模式)的 write_file/edit_file 改动不进主回滚链——
+     * 主 /rollback 不撤销子 agent 改动(靠 git 兜底)。主 agent 永远不设此 flag。 */
+    skipRollback?: boolean;
+    /** 上下文剔除回调(drop_context 工具用):把历史里命中的无关 tool 结果替换为存根(保
+     * tool_call_id 配对不变量,只改 content),原地修改 history。由 runAgentCore 闭包注入。
+     * 永不动 history[0](system)与当前轮(最后一个 user 消息及之后)的 tool 结果——agent 还在用。
+     * 返回剔除统计(条数 / 释放 token / 命中项),供 agent 确认。 */
+    dropContext?: (filter: DropContextFilter) => DropContextResult;
+}
+/** drop_context 的筛选条件(各字段 AND 组合,空/缺省 = 该维度不限)。 */
+export interface DropContextFilter {
+    /** 只剔除这些工具名的结果(如 ["grep","read_file"]);空/缺省 = 不限工具名。 */
+    toolNames?: string[];
+    /** 只剔除内容包含所有这些词(AND、大小写不敏感)的结果;空/缺省 = 不限内容。 */
+    contains?: string[];
+}
+/** drop_context 的剔除结果(回灌给 agent 供确认)。 */
+export interface DropContextResult {
+    /** 实际替换为存根的 tool 消息条数 */
+    dropped: number;
+    /** 估算释放的 token 数(剔除前后该区段 token 差) */
+    freedTokens: number;
+    /** 被剔除的 tool 消息(工具名 + tool_call_id 末 6 位)摘要 */
+    items: {
+        toolName: string;
+        toolCallId: string;
+    }[];
+}
+/** 工具统一接口。每个工具是一个 name + JSON Schema + execute。 */
+export interface Tool {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    /** ctx 可选:不关心的工具签名写 execute(args) 即可(TS 允许少参赋多参类型,向后兼容)。 */
+    execute: (args: Record<string, unknown>, ctx?: ToolContext) => Promise<string>;
+}

package/dist/ui/batch.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 工具调用批量折叠渲染(仿 Claude Code):
+ *   agent 一轮返回 N 个 tool_calls 时,不逐个打印 `● name ↳ result`,
+ *   改输出一行摘要 `● Ran N tools · read 3, grep 1, glob 1`;
+ *   鼠标点击该摘要行 → 展开完整明细(● 头 + ↳ preview / diff 块),再点折回。
+ *
+ * 设计要点:
+ *  - 实时执行 + renderHistory 回放共用本渲染器;
+ *  - 仅 buffer 写一行,详情行展开时才插入(mid-buffer insert via layout.contentInsertAfter);
+ *  - 默认折叠;展开/折叠不影响历史回放的 history 结构(history 仍存完整 tool_calls+tool 消息)。
+ *
+ * 状态全模块级(单实例)——一次 REPL 内所有 batch 共享,清内容区 / 退 alt 屏时统一重置。
+ */
+/** 一条工具调用在批内的展示数据(由 agent 的 hooks 累积,endBatch 时收尾)。 */
+export interface BatchEntry {
+    name: string;
+    /** summarizeToolCall(name, args):单行参数摘要(路径/模式/命令)。 */
+    callSummary: string;
+    /** summarizeToolResult(name, output):单行结果预览(行数/匹配数/首行)。mutation 工具为 ''。 */
+    resultSummary: string;
+    /** mutation 工具的成功 diff 块全文(由 renderFileChange 渲染出的多行 ANSI);非 mutation 为 null。
+     *  错误或非 mutation 走 resultSummary 的灰字 preview 行。 */
+    diffBlock: string | null;
+}
+/** 通知 buffer 整体清空(clearContent / exitAltScreen / 新一轮 turn)——本模块状态同步归零。 */
+export declare function reset(): void;
+/** 新建一个 batch(在 agent 拿到第一条 onToolHeader 时调)。返回 id。 */
+export declare function beginBatch(): string;
+/** 记一条工具调用(在 onToolHeader 时调,与 setEntryResult 配对;entries 顺序 = agent 调用顺序)。 */
+export declare function recordCall(id: string, name: string, callSummary: string): void;
+/** 记一条工具结果(diff 块或单行 preview);agent 在 onToolResult 时调,匹配最后一条未填的 entry。 */
+export declare function recordResult(id: string, name: string, resultSummary: string, diffBlock: string | null): void;
+/** 在 batch 收尾时(onToolBatchEnd):写摘要行 + 登记 summaryAbsIdx;若已展开(回放场景)立即插详情。 */
+export declare function endBatch(id: string, layout: {
+    contentWrite(s: string): void;
+    contentInsertAfter(after: number, lines: string[]): void;
+    totalRows(): number;
+}): void;
+/** 绝对行索引 → 命中 batch id(用于鼠标 release 反查);非摘要行返 null。 */
+export declare function findBatchByAbsLine(absLine: number): string | null;
+/** 当前 batch 是否已展开。 */
+export declare function isExpanded(id: string): boolean;
+/**
+ * 切换 batch 展开/折叠;无变化时 no-op。
+ * 折叠:从 buffer 删详情行(mid-buffer delete);
+ * 展开:把详情行插入摘要行下方(mid-buffer insert)。
+ * 同步更新 absLineToBatchId 中所有受影响的索引:
+ *   - 删除/插入点之后的 batch 摘要行索引相应平移。
+ * 含 mutation(write_file/edit_file)的 batch 强制展开——不允许折叠(写盘操作必须始终可见)。
+ */
+export declare function toggleBatch(id: string, layout: {
+    contentInsertAfter(after: number, lines: string[]): void;
+    contentDeleteFrom(startIdx: number, n: number): void;
+}): void;
+/**
+ * 当 buffer 中段插/删 N 行后,所有受影响 batch 的 summaryAbsIdx 需平移。
+ * 由 layout.contentInsertAfter / contentDeleteFrom 在每次变动后调一次,
+ * 参数 afterIdx 是被插入/删除点的绝对索引(插入点之前索引不变;之后索引 += delta)。
+ */
+export declare function shiftBatchesAfter(absIdx: number, delta: number): void;
+/** 把已构造好的 BatchEntry[] 直接落成摘要行(用于 renderHistory 回放;不记录 id 也不需可切换)。
+ *  含 mutation(write_file/edit_file)时整批展开——与实时 endBatch 行为一致。 */
+export declare function writeSummaryOnly(entries: BatchEntry[], layout: {
+    contentWrite(s: string): void;
+    contentInsertAfter(after: number, lines: string[]): void;
+    totalRows(): number;
+}): void;

package/dist/ui/clipboard.d.ts

@@ -0,0 +1,9 @@
+/** 写入系统剪贴板(OSC52 + 本地原生双通道)。 */
+export declare function copyToClipboard(text: string): void;
+/**
+ * 读取系统剪贴板(本地原生工具,OSC52 无法读取——终端不回传)。
+ * win32 用 PowerShell -NoProfile Get-Clipboard(比 clip.exe 只写无读更可靠,系统自带无需安装);
+ * darwin=pbpaste;linux 依次尝试 wl-paste / xclip -o / xsel -o,装了哪个用哪个。
+ * 都失败返回空串(不抛),调用方按"无内容可贴"处理。
+ */
+export declare function readClipboard(): Promise<string>;

package/dist/ui/content.d.ts

@@ -0,0 +1,55 @@
+export declare function reset(): void;
+/** 喂一个 SGR 码(\\x1B[...m):入 curRaw,并更新活跃状态(遇 reset 清空)。 */
+export declare function feedSgr(code: string): void;
+/** 喂一个可见字符(已按码点取出)。 */
+export declare function feedChar(ch: string): void;
+/** 提交当前行为自洽物理行,开新空行(SGR 状态继承到下行)。在 \\n / 折行 / tab 换行时调。 */
+export declare function breakRow(): void;
+/**
+ * 弹出 buffer 末尾 n 物理行(供 layout.rewindContent 撤回刚写入段用)。
+ * 当前行先 commit 再裁剪(消除 hasCurrent 边界);n ≥ totalRows 则全清,
+ * 但**不动 segMark** —— recall 走普通 contentWrite、不撞 md 段;
+ * segMark 由 reset() / commitSegment() 清,recall 不掺和。
+ */
+export declare function rewind(n: number): void;
+/** 标记段起点:快照当前缓冲状态,供 setLines 截断定位段头(md 流式渲染每 chunk 截断重渲)。 */
+export declare function beginSegment(): void;
+/**
+ * 用预渲染的自洽 ANSI 行替换当前段(从 segMark 起),供 markdown 流式渲染:
+ * layout.contentWriteMd 每 chunk 把累积 text 经 renderMarkdown 渲成自洽行,调此替换缓冲段。
+ * 截断 rows 到 segMark.rowIdx(擦上次渲染)+ push 新行;curSgr 复位为默认(行末 reset);
+ * **保留 segMark**(下次 setLines 还要截断),由 commitSegment 清除。
+ * 行须各自自洽(行内 SGR 自带、行末 reset)——不经 feedChar/feedSgr,直接入 rows,
+ * 故 setLines 后 hasCurrent=false(snapshot 只返 rows;续写位由 layout 跟踪)。
+ */
+export declare function setLines(lines: string[]): void;
+/** 提交段:清 segMark,后续写入不再被 setLines 截断(md 段结束、非 md 内容接续时调)。 */
+export declare function commitSegment(): void;
+/** 距尾 offset 行、取 count 行的窗口(映射到屏 1..count)。offset=0 即尾窗。 */
+export declare function sliceFromEnd(offset: number, count: number): string[];
+/** 快照总行数(含当前行),供 scrollBy 钳位。 */
+export declare function totalRows(): number;
+/** 取绝对行索引(0-based,含当前行)的原始自洽行;越界返 null。供鼠标选区文本提取。 */
+export declare function lineAt(abs: number): string | null;
+/**
+ * 在绝对行索引 after(0-based,已 commit)之后插入 N 条自洽行。
+ * 用于「折叠摘要行下展开明细」——把详情行在已写入摘要行后面塞入缓冲,
+ * 不重写尾部已有内容;且不影响更早的 buffer 行(hasCurrent 先 commit 再 splice)。
+ *
+ * 行须自洽(每行带行末 \x1B[0m),不经 feedChar/feedSgr,直接入 rows。
+ * after < 0 视为在所有已 commit 行之前插入;after ≥ 已 commit 行数则追加到末尾。
+ * 不动 segMark——此函数用于非 md 路径(BatchRenderer 展开/折叠);
+ * md 段切回 layout.contentWriteMd 时 setLines 仍按 segMark 截断。
+ *
+ * 后置条件:插入后 hasCurrent=false(新空行不由本函数建立);调用方须自行决定续写位
+ * (BatchRenderer 在插入后调 layout.contentWrite 续写,新 \n 自然在详情块后建新行)。
+ */
+export declare function insertAfter(after: number, lines: string[]): void;
+/**
+ * 从绝对行索引 startIdx(0-based,已 commit)起删 n 行。
+ * 用于「已展开明细折回摘要」——把详情行从中段裁掉,保留摘要行和后续内容。
+ * startIdx 越界或 n <= 0 直接 no-op。hasCurrent 时先 commit(同 insertAfter)。
+ *
+ * 后置条件:删除后 hasCurrent=false。后续 layout.contentWrite 自然续写。
+ */
+export declare function deleteFrom(startIdx: number, n: number): void;