hyacinth-ai 0.9.6

package/dist/tools/result-buffer.js

@@ -0,0 +1,146 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+// ── Constants ──────────────────────────────────────────────────────
+const DEFAULT_THRESHOLD = 16384; // 16 KB
+const DEFAULT_PREVIEW_CHARS = 500;
+const BUFFER_SUBDIR = 'buffered-results';
+// ── ToolResultBuffer ────────────────────────────────────────────────
+/**
+ * ToolResultBuffer — 通用工具结果中间层
+ *
+ * 所有工具（内置 / MCP / 插件 / Skill）的执行结果在注入对话历史前经过此类。
+ * 当结果字节数超过阈值时，将完整结果写入磁盘缓冲文件，对话中仅注入一条短的
+ * "指针消息"。LLM 通过已有的 `read` 工具（含 offset/limit 分页）按需读取。
+ *
+ * 对标 StormBreaker 模式：AgentLoop 构造函数内自初始化，不需要 factory.ts 注入。
+ *
+ * 七条原则自检（§0.5）：
+ *   ① 单一职责 — 只做"大结果→文件，小结果→透传"
+ *   ② 零侵入   — 删除此文件 + 移除 loop.ts 调用→系统正常运行
+ *   ③ 外部配置 — 阈值通过 configCenter 控制
+ *   ④ 数据分离 — 数据（缓冲文件）/ 配置（阈值）/ 代码（buffer 逻辑）
+ *   ⑤ 接口稳定 — 唯一入口 maybeBuffer(result, toolName): string
+ *   ⑥ 可独立测试 — 构造字符串→调 maybeBuffer→验证文件和指针格式
+ *   ⑦ 跨项目可移植 — 复制到任何 Agent 项目即可用
+ */
+export class ToolResultBuffer {
+    sessionDir;
+    enabled;
+    threshold;
+    includePreview;
+    previewChars;
+    bufferDir;
+    initialized = false;
+    constructor(config) {
+        this.sessionDir = config.sessionDir;
+        this.enabled = config.enabled ?? true;
+        this.threshold = config.threshold ?? DEFAULT_THRESHOLD;
+        this.includePreview = config.includePreview ?? true;
+        this.previewChars = config.previewChars ?? DEFAULT_PREVIEW_CHARS;
+        this.bufferDir = join(this.sessionDir, BUFFER_SUBDIR);
+    }
+    // ── Public API ──────────────────────────────────────────────────
+    /**
+     * 如果 `result` 超过阈值，写入磁盘并返回指针消息；否则原样返回。
+     * 先折叠连续重复行（日志/错误输出优化），再判断是否需要缓冲。
+     *
+     * @param result  工具执行返回的原始文本
+     * @param toolName  工具名（用于指针消息和文件名，如 `mcp__chrome-devtools__take_snapshot`）
+     * @returns 原始结果（≤阈值）或指针消息（>阈值）
+     */
+    maybeBuffer(result, toolName) {
+        if (!this.enabled)
+            return result;
+        // 折叠连续重复行 — 典型场景：日志中同一错误重复成百上千行
+        const folded = this.foldRepeatedLines(result);
+        if (folded.length <= this.threshold)
+            return folded;
+        return this.bufferToDisk(folded, toolName);
+    }
+    // ── Internal ────────────────────────────────────────────────────
+    /** 写入缓冲文件并生成指针消息。首次调用时懒创建缓冲目录。 */
+    bufferToDisk(result, toolName) {
+        this.ensureDir();
+        const filename = this.buildFilename(toolName, result);
+        const filePath = join(this.bufferDir, filename);
+        writeFileSync(filePath, result, 'utf-8');
+        return this.buildPointerMessage(result, toolName, filePath);
+    }
+    ensureDir() {
+        if (!this.initialized) {
+            mkdirSync(this.bufferDir, { recursive: true });
+            this.initialized = true;
+        }
+    }
+    /** 生成唯一文件名：`工具名-时间戳-短哈希.txt` */
+    buildFilename(toolName, content) {
+        const safeName = toolName.replace(/[^a-zA-Z0-9_-]/g, '-').slice(0, 64);
+        const timestamp = Date.now().toString(36);
+        const hash = this.fnv32a(content.slice(0, 512) + content.slice(-256));
+        return `${safeName}-${timestamp}-${hash}.txt`;
+    }
+    /** FNV-1a 32-bit hash — 轻量、确定性、零依赖 */
+    fnv32a(s) {
+        let hash = 2166136261;
+        for (let i = 0; i < s.length; i++) {
+            hash ^= s.charCodeAt(i);
+            hash = Math.imul(hash, 16777619);
+        }
+        return (hash >>> 0).toString(36);
+    }
+    /**
+     * 折叠连续重复行。当同一行连续出现 ≥5 次时，压缩为 "[×N] content"。
+     * 针对日志、错误输出等包含大量重复内容的场景，大幅减少 token 消耗。
+     */
+    foldRepeatedLines(result) {
+        const MIN_REPEAT = 5;
+        const lines = result.split('\n');
+        if (lines.length < MIN_REPEAT * 2)
+            return result; // 太短不值得扫描
+        const folded = [];
+        let i = 0;
+        while (i < lines.length) {
+            const line = lines[i];
+            let count = 1;
+            while (i + count < lines.length && lines[i + count] === line) {
+                count++;
+            }
+            if (count >= MIN_REPEAT) {
+                folded.push(`[×${count}] ${line}`);
+            }
+            else {
+                for (let j = 0; j < count; j++)
+                    folded.push(lines[i + j]);
+            }
+            i += count;
+        }
+        return folded.join('\n');
+    }
+    /** 获取缓冲目录路径（用于外部判断文件是否已缓冲）。 */
+    getBufferDir() {
+        return this.bufferDir;
+    }
+    /** 生成 LLM 可读的指针消息，引导其使用 `read` 工具按需读取。 */
+    buildPointerMessage(result, toolName, filePath) {
+        const sizeKB = (result.length / 1024).toFixed(1);
+        const lineCount = result.split('\n').length;
+        const thresholdKB = (this.threshold / 1024).toFixed(0);
+        const parts = [
+            `[Result Buffered — exceeds ${thresholdKB} KB limit]`,
+            `Tool:  ${toolName}`,
+            `Size:  ${result.length.toLocaleString()} bytes (${sizeKB} KB, ${lineCount.toLocaleString()} lines)`,
+            `File:  ${filePath}`,
+        ];
+        if (this.includePreview && this.previewChars > 0) {
+            const preview = result.length > this.previewChars
+                ? result.slice(0, this.previewChars) + '…'
+                : result;
+            parts.push('', `── Preview (first ${this.previewChars} chars) ──`, preview, '──');
+        }
+        // Suggest a safe limit that keeps each chunk under the buffer threshold
+        const safeLimit = Math.max(50, Math.floor(this.threshold / 120));
+        parts.push('', `Use read(file_path="${filePath}", offset=1, limit=${safeLimit}) to view in segments.`);
+        return parts.join('\n');
+    }
+}
+//# sourceMappingURL=result-buffer.js.map

package/dist/tools/runtime-control.d.ts

@@ -0,0 +1,163 @@
+import type { Tool } from './interface.js';
+import type { ToolRegistry } from './registry.js';
+import type { AgentLoop } from '../orchestrator/loop.js';
+import type { ProviderRouter } from '../provider/router.js';
+import type { ModelRouter } from '../provider/model-router.js';
+import type { SkillRegistry } from '../skills/registry.js';
+import type { RuntimeConfigCenter } from '../runtime/config-center.js';
+import type { AgentRegistry } from '../agents/registry.js';
+import type { HeartbeatScheduler } from '../schedule/scheduler.js';
+import type { MCPSystem } from '../mcp/system.js';
+import type { CompanionSessionManager } from '../memory/companion-session.js';
+/**
+ * switch_provider — switch to a specific named provider.
+ * Calls agentLoop.switchProvider(name) which does per-named-provider switching
+ * and updates the orchestrator (unlike toggleProvider which only flips local/online).
+ */
+export declare function createSwitchProviderTool(agentLoop: AgentLoop): Tool;
+/**
+ * list_providers — list all registered providers with their types and models.
+ */
+export declare function createListProvidersTool(providerRouter: ProviderRouter): Tool;
+/**
+ * provider_info — show details about the currently active provider.
+ */
+export declare function createProviderInfoTool(agentLoop: AgentLoop): Tool;
+/**
+ * switch_to_auto_route — switch provider routing back to automatic mode.
+ */
+export declare function createSwitchToAutoRouteTool(agentLoop: AgentLoop): Tool;
+/**
+ * toggle_tool — enable or disable a specific tool by name.
+ */
+export declare function createToggleToolTool(toolRegistry: ToolRegistry, configCenter?: RuntimeConfigCenter): Tool;
+/**
+ * list_tools — list all registered tools with their enabled/disabled status.
+ */
+export declare function createListToolsTool(toolRegistry: ToolRegistry): Tool;
+/**
+ * toggle_skill — enable or disable a specific skill by name.
+ */
+export declare function createToggleSkillTool(skillRegistry: SkillRegistry, configCenter?: RuntimeConfigCenter): Tool;
+/**
+ * list_skills — list all registered skills with their enabled/disabled status.
+ */
+export declare function createListSkillsTool(skillRegistry: SkillRegistry): Tool;
+/**
+ * toggle_sub_agent — enable or disable a specific sub-agent by name.
+ */
+export declare function createToggleSubAgentTool(agentRegistry: AgentRegistry, configCenter?: RuntimeConfigCenter): Tool;
+/**
+ * list_sub_agents — list all registered sub-agents with their enabled/disabled status and instance IDs.
+ */
+export declare function createListSubAgentsTool(agentRegistry: any): Tool;
+/**
+ * spawn_sub_agent — clone an existing sub-agent to create a parallel instance (分身).
+ */
+export declare function createSpawnSubAgentTool(agentRegistry: any): Tool;
+/**
+ * create_sub_agent — create a brand-new custom sub-agent at runtime.
+ * When persist=true, also writes prompt file and agents.json config to disk
+ * so the agent survives restarts and rebuilds.
+ */
+export declare function createCreateSubAgentTool(agentRegistry: any, cwd: string): Tool;
+/**
+ * update_sub_agent — modify an existing sub-agent's configuration at runtime.
+ */
+export declare function createUpdateSubAgentTool(agentRegistry: any): Tool;
+/**
+ * destroy_sub_agent — permanently delete a sub-agent instance and its session directory.
+ */
+export declare function createDestroySubAgentTool(agentRegistry: AgentRegistry, parentSessionDir: string): Tool;
+/**
+ * interrupt — interrupt the currently running agent loop.
+ */
+export declare function createInterruptTool(agentLoop: AgentLoop): Tool;
+/**
+ * current_session — show which session is currently active.
+ */
+export declare function createCurrentSessionTool(agentLoop: AgentLoop): Tool;
+/**
+ * session_stats — show current session statistics.
+ */
+export declare function createSessionStatsTool(agentLoop: AgentLoop): Tool;
+/**
+ * list_sessions — list all existing sessions.
+ */
+export declare function createListSessionsTool(agentLoop: AgentLoop, cwd: string): Tool;
+/**
+ * new_session — create a brand-new session and switch to it immediately.
+ */
+export declare function createNewSessionTool(agentLoop: AgentLoop, cwd: string): Tool;
+/**
+ * switch_session — load and switch to an existing session.
+ *
+ * 注册链路：
+ *   src/tools/runtime-control.ts（本文件）→ 工具实现
+ *   → 注册到 ToolRegistry（factory.ts 中通过 registerSessionTools 调用）
+ *   → tool_result 写入 conversation.jsonl（loop.ts append 阶段）
+ *   → 出现在 Zone 3 (History) 的对话历史中
+ *
+ * ⚠️ tool_result 的文案会影响模型对当前会话状态的认知。
+ *    如需修改返回文案，注意与 new_session、current_session 保持一致。
+ */
+export declare function createSwitchSessionTool(agentLoop: AgentLoop, cwd: string): Tool;
+/**
+ * delete_session — permanently delete a session and its data.
+ */
+export declare function createDeleteSessionTool(agentLoop: AgentLoop, cwd: string): Tool;
+/**
+ * allow_tool — add a tool to the safety allowedTools whitelist.
+ */
+export declare function createAllowToolTool(configCenter: RuntimeConfigCenter): Tool;
+/**
+ * disallow_tool — remove a tool from the safety allowedTools whitelist.
+ */
+export declare function createDisallowToolTool(configCenter: RuntimeConfigCenter): Tool;
+/**
+ * list_allowlist — show current allowed tools and commands.
+ */
+export declare function createListAllowlistTool(configCenter: RuntimeConfigCenter): Tool;
+/**
+ * add_task — create a new scheduled task on the HeartbeatScheduler.
+ */
+export declare function createAddTaskTool(scheduler: HeartbeatScheduler, 
+/** 可选：自动检测当前渠道的函数（从 session meta.json 读取） */
+getChannel?: () => string | undefined, 
+/** 可选：自动检测当前 sessionId 的函数 */
+getSessionId?: () => string | undefined, 
+/** 可选：自动检测当前模式的函数（normal / companion） */
+getMode?: () => 'normal' | 'companion' | undefined): Tool;
+/**
+ * remove_task — delete a scheduled task by id or name.
+ */
+export declare function createRemoveTaskTool(scheduler: HeartbeatScheduler, getMode?: () => 'normal' | 'companion' | undefined): Tool;
+/**
+ * list_tasks — list all scheduled tasks.
+ */
+export declare function createListTasksTool(scheduler: HeartbeatScheduler, getMode?: () => 'normal' | 'companion' | undefined): Tool;
+/**
+ * toggle_task — enable or disable a scheduled task.
+ */
+export declare function createToggleTaskTool(scheduler: HeartbeatScheduler, getMode?: () => 'normal' | 'companion' | undefined): Tool;
+/**
+ * mcp_status — query MCP server connection states.
+ */
+export declare function createMcpStatusTool(mcpSystem: MCPSystem): Tool;
+export declare function createListModelChannelsTool(modelRouter: ModelRouter): Tool;
+export declare function createAddModelChannelTool(modelRouter: ModelRouter): Tool;
+export declare function createRemoveModelChannelTool(modelRouter: ModelRouter): Tool;
+export declare function createSetChannelModelTool(modelRouter: ModelRouter): Tool;
+export declare function createResetChannelModelTool(modelRouter: ModelRouter): Tool;
+export declare function createChannelInfoTool(modelRouter: ModelRouter): Tool;
+export declare function createSetChannelRoleTool(modelRouter: ModelRouter): Tool;
+/**
+ * companion_mode — 陪伴模式切换（进入 / 退出）。
+ */
+export declare function createCompanionModeTool(agentLoop: AgentLoop, companionSessionManager: CompanionSessionManager): Tool;
+/**
+ * reset_companion_session — 重置陪伴 session，清空所有陪伴记忆。
+ * 仅在陪伴模式下可用。
+ */
+export declare function createResetCompanionSessionTool(agentLoop: AgentLoop, companionSessionManager: CompanionSessionManager): Tool;
+//# sourceMappingURL=runtime-control.d.ts.map