@bolloon/bolloon-agent 0.2.12 → 0.2.13

package/dist/agents/react-loop.js

@@ -0,0 +1,120 @@
+/**
+ * ReAct Loop 决策层 (decideNext + runStep)
+ *
+ * 2026-06-30 抽出:
+ *   - 原 PiAgentSession.runReActLoop 是 1100+ 行的 private 巨石函数, 既管 LLM IO 又管状态机.
+ *   - 现在抽出"决策下一步"为纯函数, claude code / 外部 harness 可独立消融验证.
+ *
+ * 决策表 (apply 到 LLM 回复 + 当前 state):
+ *   1. reply 是 AI failure sentinel        → continue (push error 进 history, 让 LLM 反思)
+ *   2. reply 可 parse 出 tool call         → execute-tool (调 tool, push result 进 history)
+ *   3. reply 含 <final gen> 且无 tool_call → final (LLM 显式终止)
+ *   4. reply 无 <final gen>, 无 tool_call  → continue (LLM 可能再想想, 让下一轮重新生成)
+ *
+ * 这个模块不调 LLM, 只接受 reply/state 返回下一步决策. LLM 调用 + 真正状态变更
+ *   仍由 PiAgentSession 协调. 这样 claude code 可以独立 unit-test 决策边界.
+ */
+import { parseToolCall, isFinalResponse } from './parse-tool-call.js';
+/** 把 LLM 回复归到一种 next action — 纯函数. */
+export function decideNext(ctx) {
+    if (ctx.signalAborted) {
+        return { kind: 'continue', reason: 'signal-aborted-upstream' };
+    }
+    if (ctx.atMaxIterations) {
+        return { kind: 'final', answer: '(max iterations reached, fail-safe)', reason: 'max-iterations' };
+    }
+    // AI failure sentinel 优先 (matches pi-sdk.ts 现有顺序 L2558)
+    //   LLM 偶尔在 retry 中夹杂 sentinel + 工具块, sentinel 是必须先看的"停止信号"
+    if (isAiFailureSentinel(ctx.reply)) {
+        return { kind: 'continue', reason: 'ai-failure-sentinel' };
+    }
+    // 工具调用优先 (per 2026-06-19 fix) — 在 sentinel 之后
+    const tc = parseToolCall(ctx.reply, { tools: ctx.knownToolNames });
+    if (tc) {
+        if (!ctx.knownToolNames.has(tc.name)) {
+            // 名字解析出来但不在已知集合 — LLM 幻觉高频场景
+            return { kind: 'parse-error', reason: `unknown-tool:${tc.name}` };
+        }
+        return {
+            kind: 'execute-tool',
+            name: tc.name,
+            args: tc.args,
+            reason: 'parse-tool-call',
+        };
+    }
+    // final gen 终止
+    if (isFinalResponse(ctx.reply)) {
+        return { kind: 'final', answer: ctx.reply, reason: 'final-gen-marker' };
+    }
+    // 默认 — 普通 text, 让 LLM 继续想
+    return { kind: 'continue', reason: 'no-tool-no-final' };
+}
+/**
+ * isAiFailureSentinel — 检测 LLM 上游失败哨兵.
+ * bolloon 用 [AI 服务调用失败] 前缀作为哨兵 — runReActLoop 收到时
+ *   把错误当 tool result push 进 history, 让 LLM 下轮能反思.
+ */
+export function isAiFailureSentinel(reply) {
+    if (!reply)
+        return false;
+    const trimmed = reply.trim();
+    return trimmed.startsWith('[AI 服务调用失败]') ||
+        trimmed.startsWith('[AI 调用失败]') ||
+        trimmed.startsWith('[错误:');
+}
+/** extractFinalText — 抽 LLM 输出里能呈现给用户的最终文字 (已是 Message 状态). */
+export function extractFinalText(reply, marker = '<final gen>') {
+    const idx = reply.indexOf(marker);
+    if (idx !== -1) {
+        const after = reply.substring(idx + marker.length).trim();
+        return after || reply.substring(0, idx).trim();
+    }
+    return reply;
+}
+/**
+ * 错误累计判定 — 当 totalErrors 达阈值时, 给 final 答案 + 汇总.
+ * 这是独立的小函数, 因为 runReActLoop 用它决定是否继续.
+ */
+export function shouldForceExit(totalErrors, maxTotalErrors) {
+    return totalErrors >= maxTotalErrors;
+}
+/**
+ * 2026-07-01 (v0.2.4 子任务 1): 迭代上限判定 — 纯函数.
+ * 之前 runReActLoop 在循环顶部硬编码 `if (iteration >= MAX_REACT_ITERATIONS)`,
+ * 抽出后 claude code 可独立单测 + 替代.
+ */
+export function decideMaxIterations(iteration, maxIterations) {
+    return {
+        shouldExit: iteration >= maxIterations,
+        finalAnswer: iteration >= maxIterations
+            ? '(本轮 ReAct 循环达到最大步数, 强制结束)'
+            : '',
+    };
+}
+/**
+ * 2026-07-01 (v0.2.4 子任务 1): context overflow 判定 — 纯函数.
+ * 之前 runReActLoop 紧接 decideMaxIterations 之后硬编码 token 阈值检查.
+ * 抽出后行为一致 + 可测.
+ */
+export function decideContextOverflow(estimatedTokens, threshold) {
+    return {
+        shouldExit: estimatedTokens > threshold,
+        finalAnswer: estimatedTokens > threshold
+            ? `(本轮 ReAct 循环因上下文溢出终止)`
+            : '',
+    };
+}
+/**
+ * 2026-07-01 (v0.2.4 子任务 1): compact 触发判定 — 纯函数.
+ * 之前 runReActLoop 入口处: estimatedTokens > compactThreshold → 跑 maybeAutoCompact.
+ * 抽出纯函数后, claude code 能 dry-run "token X 时该 compact 吗".
+ */
+export function shouldCompactBeforeIteration(estimatedTokens, compactThreshold) {
+    return estimatedTokens > compactThreshold;
+}
+/**
+ * 同一工具连续失败 N 次, 提示 LLM 不要再用同一个工具 (force final).
+ */
+export function shouldHintToStopSameTool(consecutiveFails, threshold) {
+    return consecutiveFails >= threshold;
+}

package/dist/agents/session-store.js

@@ -0,0 +1,171 @@
+/**
+ * session-store — 持久化 Message[] (LLM 历史) 到 ~/.bolloon/sessions/cache/<key>.json
+ *
+ * 2026-06-30 抽出:
+ *   - 之前 PiAgentSession 用 constraint-runtime 的 saveSession (存 string[]) + 独立的 hydrateMessageHistory
+ *     读路径, 写路径不存在 — claude code / 外部 harness 想"接续 prompt"完全无入口.
+ *   - 现在抽出 SessionStore 模块, 暴露纯 IO 接口, 完全可消融测试:
+ *       saveMessages(key, msgs) — 写
+ *       loadMessages(key)      — 读
+ *       listKeys()              — 列全部 key
+ *       deleteKey(key)          — 清
+ *   - 任何目录位置都可注入 (默认 ~/.bolloon/sessions/cache/), 测试里指向临时 dir.
+ *
+ * 使用:
+ *   import { sessionStore } from './session-store';
+ *   sessionStore.saveMessages('cli:session-A', messageHistory);
+ *   const restored = sessionStore.loadMessages('cli:session-A');
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+export class SessionStore {
+    cacheDir;
+    constructor(config = {}) {
+        this.cacheDir = config.cacheDir ?? path.join(os.homedir(), '.bolloon', 'sessions', 'cache');
+    }
+    /** 当前缓存目录 (只读). */
+    get dir() {
+        return this.cacheDir;
+    }
+    /** 单文件路径 — 暴露出来方便测试和外部读取.
+     *
+     * 2026-07-04 fix: Windows 文件名禁止 `:` (NTFS). web server 用 `channelId:currentSessionId`
+     * 拼 sessionKey (server.ts:1759 之类), 会含 `:`. 在 Linux/macOS 上能用, Windows 上
+     * fs.writeFile 抛 EINVAL. 修法: filename 层 escape `:` → `__`, key 保持不变
+     * (load/save/listKeys/deleteKey 全部透明).
+     */
+    pathFor(key) {
+        if (!key || key.includes('/') || key.includes('..')) {
+            throw new Error(`SessionStore: invalid key ${JSON.stringify(key)}`);
+        }
+        return path.join(this.cacheDir, `${SessionStore.filenameEscape(key)}.json`);
+    }
+    /** 把 session key 转换成跨平台安全的 filename (escape Windows 非法字符). */
+    static filenameEscape(key) {
+        return key.replace(/:/g, '__');
+    }
+    /** listKeys 反向: 把 filename 还原成 session key. */
+    static filenameUnescape(filenameKey) {
+        return filenameKey.replace(/__/g, ':');
+    }
+    /**
+     * 写 history to disk.
+     * - 自动 ensure 缓存目录
+     * - 失败抛错 (写失败不应静默 — 用户可能依赖持久化作为审计)
+     */
+    async saveMessages(key, messages) {
+        if (!key || key.includes('/') || key.includes('..')) {
+            throw new Error(`SessionStore: invalid key ${JSON.stringify(key)}`);
+        }
+        await fs.mkdir(this.cacheDir, { recursive: true });
+        const payload = {
+            key,
+            messages,
+            metadata: {
+                savedAt: Date.now(),
+                cwd: process.cwd(),
+                totalCount: messages.length,
+            },
+        };
+        const filePath = this.pathFor(key);
+        // 写临时文件 + rename — 防止半写损坏
+        const tmpPath = `${filePath}.tmp`;
+        await fs.writeFile(tmpPath, JSON.stringify(payload, null, 2), 'utf-8');
+        await fs.rename(tmpPath, filePath);
+    }
+    /**
+     * 同步版 (PiAgentSession 里多条路径用同步 — 避免 async 链)
+     * 失败抛错
+     */
+    saveMessagesSync(key, messages) {
+        if (!key || key.includes('/') || key.includes('..')) {
+            throw new Error(`SessionStore: invalid key ${JSON.stringify(key)}`);
+        }
+        fsSyncMkdir(this.cacheDir);
+        const payload = {
+            key,
+            messages,
+            metadata: {
+                savedAt: Date.now(),
+                cwd: process.cwd(),
+                totalCount: messages.length,
+            },
+        };
+        const filePath = this.pathFor(key);
+        const tmpPath = `${filePath}.tmp`;
+        fsSyncWrite(tmpPath, JSON.stringify(payload, null, 2));
+        fsSyncRename(tmpPath, filePath);
+    }
+    /**
+     * 读 history from disk.
+     * - key 不存在 → 返回 null (不抛错)
+     * - 文件存在但 JSON 损坏 → 抛错 (claude code 应该感知坏数据)
+     * - 文件 schema 不匹配 (新版格式) → 抛错含 details
+     */
+    async loadMessages(key) {
+        if (!key || key.includes('/') || key.includes('..')) {
+            throw new Error(`SessionStore: invalid key ${JSON.stringify(key)}`);
+        }
+        const filePath = this.pathFor(key);
+        let raw;
+        try {
+            raw = await fs.readFile(filePath, 'utf-8');
+        }
+        catch (e) {
+            if (e?.code === 'ENOENT')
+                return null;
+            throw e;
+        }
+        const parsed = JSON.parse(raw);
+        if (!parsed || !Array.isArray(parsed.messages)) {
+            throw new Error(`SessionStore: ${key} schema invalid (missing messages[])`);
+        }
+        return parsed.messages;
+    }
+    /** 列所有 keys — 用于调试 / claude code "看有哪些 session 可接续". */
+    async listKeys() {
+        try {
+            await fs.mkdir(this.cacheDir, { recursive: true });
+            const files = await fs.readdir(this.cacheDir);
+            return files
+                .filter(f => f.endsWith('.json') && !f.endsWith('.tmp'))
+                .map(f => SessionStore.filenameUnescape(f.slice(0, -'.json'.length)))
+                .sort();
+        }
+        catch {
+            return [];
+        }
+    }
+    /** 删一条 session — 失败抛错. */
+    async deleteKey(key) {
+        if (!key || key.includes('/') || key.includes('..')) {
+            throw new Error(`SessionStore: invalid key ${JSON.stringify(key)}`);
+        }
+        try {
+            await fs.unlink(this.pathFor(key));
+        }
+        catch (e) {
+            if (e?.code !== 'ENOENT')
+                throw e;
+        }
+    }
+}
+// --- sync fs helpers (避免 import 'fs' 二次) ---
+function fsSyncMkdir(dir) {
+    try {
+        require('fs').mkdirSync(dir, { recursive: true });
+    }
+    catch (e) {
+        if (e?.code !== 'EEXIST')
+            throw e;
+    }
+}
+function fsSyncWrite(filePath, content) {
+    require('fs').writeFileSync(filePath, content, 'utf-8');
+}
+function fsSyncRename(from, to) {
+    require('fs').renameSync(from, to);
+}
+/** 默认 store 实例 (用 ~/.bolloon/sessions/cache/). 业务代码用这个. */
+export const sessionStore = new SessionStore();

package/dist/agents/shell-guard.js

@@ -13,7 +13,7 @@
  *   "commandAllowlist": ["git", "npm", "tsc", "vitest", "cat", "ls", "..."],
  *   "commandDenylist": ["rm", "mv", "chmod", "sudo", "su", "curl", "wget"],
  *   "pathAllowlist": [
- *     "src/web/client.js",
+ *     "src/web/client.ts",
  *     "src/agents/workflow-engine.ts",
  *     "*.md",
  *     "docs/**"
@@ -58,7 +58,7 @@ const FALLBACK_COMMAND_ALLOWLIST = new Set([
 ]);
 const FALLBACK_PATH_ALLOWLIST = [
     // 自由区: AI 可以改
-    'src/web/client.js',
+    'src/web/client.ts',
     'src/web/style.css',
     'src/agents/workflow-engine.ts',
     'src/agents/workflow-pivot-loop.ts',

package/dist/agents/tool-registry.js

@@ -0,0 +1,136 @@
+/**
+ * ToolRegistry — 工具注册表 + 别名解析器
+ *
+ * 2026-06-30 抽出:
+ *   - 原 PiAgentSession.tools Map + resolveToolName 是 private 方法, 测试无法直接验证 alias 映射
+ *   - 现在抽到独立模块, 完全可消融测试.
+ *
+ * 设计目标:
+ *   1. claude code / 外部 harness 直接 import, 用同一份 alias 表
+ *   2. 注册/反注册/查表都是纯方法, 无副作用
+ *   3. 默认 alias 表跟 parse-tool-call.ts 保持一致 (read→read_file, bash→shell_exec 等)
+ *   4. 自定义 alias 可注入 (业务可扩)
+ *
+ * 用法:
+ *   import { ToolRegistry, DEFAULT_ALIASES } from './tool-registry';
+ *   const reg = new ToolRegistry();
+ *   reg.register({ name: 'shell_exec', description: '...', parameters: {}, execute });
+ *   reg.has('bash');                  // true (alias 命中)
+ *   reg.resolve('bash');              // 'shell_exec'
+ *   reg.get('shell_exec')?.execute({ command: 'ls' });
+ */
+/** 默认 alias 表 — Claude Code 风格 → bolloon 工具名 */
+export const DEFAULT_ALIASES = Object.freeze({
+    // file ops
+    read: 'read_file',
+    edit: 'edit_file',
+    write: 'write_file',
+    rm: 'delete_file',
+    mv: 'move_file',
+    cat: 'read_file',
+    // shell
+    bash: 'shell_exec',
+    shell: 'shell_exec',
+    sh: 'shell_exec',
+    // test/build
+    test: 'vitest_run',
+    vitest: 'vitest_run',
+    typecheck: 'tsc_check',
+    tsc: 'tsc_check',
+    // git
+    log: 'git_log',
+    show: 'git_show',
+    diff: 'git_diff',
+    commit: 'git_commit',
+    push: 'git_push',
+    branch: 'git_branch',
+    checkout: 'git_branch',
+    stash: 'git_stash',
+    // task
+    todo_write: 'create_task',
+    todowrite: 'create_task',
+    task: 'create_task',
+});
+export class ToolRegistry {
+    tools = new Map();
+    aliases;
+    constructor(aliases = DEFAULT_ALIASES) {
+        this.aliases = new Map();
+        for (const [k, v] of Object.entries(aliases)) {
+            this.aliases.set(k.toLowerCase(), v);
+        }
+    }
+    /** 注册一个 tool (alias 字典不动) */
+    register(tool) {
+        if (!tool.name)
+            throw new Error('ToolRegistry.register: tool.name 必填');
+        this.tools.set(tool.name, tool);
+    }
+    /** 批量注册 */
+    registerAll(tools) {
+        for (const t of tools)
+            this.register(t);
+    }
+    /** 反注册 — 名字 + 对应 alias (如果有指向它) 全部清掉. */
+    unregister(name) {
+        const existed = this.tools.delete(name);
+        // 反向清 alias
+        for (const [alias, target] of this.aliases.entries()) {
+            if (target === name)
+                this.aliases.delete(alias);
+        }
+        return existed;
+    }
+    /** 查 tool (只查主名, alias 走 resolve). */
+    get(name) {
+        return this.tools.get(name);
+    }
+    /** 是否注册 (主名 + alias 命中都算). */
+    has(name) {
+        if (this.tools.has(name))
+            return true;
+        const aliased = this.aliases.get(name.toLowerCase());
+        return aliased !== undefined && this.tools.has(aliased);
+    }
+    /** 把 LLM 输出的名字 (可能是 alias / 大小写不一致) 解析为标准主名. */
+    resolve(name) {
+        if (this.tools.has(name))
+            return name;
+        const lower = name.toLowerCase();
+        const aliased = this.aliases.get(lower);
+        if (aliased && this.tools.has(aliased))
+            return aliased;
+        if (this.tools.has(lower))
+            return lower;
+        return null;
+    }
+    /** 列出所有主名. 顺序按注册时间. */
+    list() {
+        return Array.from(this.tools.keys());
+    }
+    /** 当前 alias 表快照 (调试用). */
+    get aliasMap() {
+        const out = {};
+        for (const [k, v] of this.aliases.entries())
+            out[k] = v;
+        return out;
+    }
+    /** 个数 */
+    get size() {
+        return this.tools.size;
+    }
+    /** 清空 */
+    clear() {
+        this.tools.clear();
+        // alias 表保留 (除非调用方显式 clear, alias 表是稳定的)
+    }
+    /** 调一个 tool, 名字可能是 alias. throw if 未知. */
+    async invoke(name, args) {
+        const canonical = this.resolve(name);
+        if (!canonical) {
+            throw new Error(`ToolRegistry.invoke: 未知工具名 ${JSON.stringify(name)}`);
+        }
+        const tool = this.tools.get(canonical);
+        return tool.execute(args);
+    }
+}