@hflin/cclin 0.1.0

package/dist/runtime/compaction.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @file 上下文压缩模块 — LLM 驱动的对话历史摘要。
+ *
+ * Phase 6：当对话历史的 token 数接近上下文窗口限制时，
+ * 调用 LLM 对历史生成结构化摘要，替换原始历史以释放空间。
+ *
+ * 设计参考 memo-code 的 compact_prompt.ts，但做了精简：
+ *   - 去掉了"保留最近 N 条 user 消息"的逻辑（简化）
+ *   - 保留了消息转文本、摘要检测、历史重建的核心流程
+ */
+import type { ChatMessage } from '../types.js';
+/**
+ * 给 LLM 的压缩指令。
+ *
+ * 这个 prompt 告诉 LLM："你在做一次检查点压缩，
+ * 帮下一个 LLM 接手工作"。关键点：
+ *   - 保留进展和关键决策
+ *   - 保留约束和用户偏好
+ *   - 清晰列出后续步骤
+ */
+export declare const CONTEXT_COMPACTION_SYSTEM_PROMPT = "You are performing a CONTEXT CHECKPOINT COMPACTION. Create a handoff summary for another LLM that will resume the task.\n\nInclude:\n- Current progress and key decisions made\n- Important context, constraints, or user preferences\n- What remains to be done (clear next steps)\n- Any critical data, examples, or references needed to continue\n\nBe concise, structured, and focused on helping the next LLM seamlessly continue the work.";
+/**
+ * 摘要消息的识别前缀。
+ *
+ * 压缩后的摘要以这段文字开头，
+ * 让后续的压缩轮次能识别"这是之前的摘要，不是原始对话"。
+ */
+export declare const CONTEXT_SUMMARY_PREFIX = "Another language model started to solve this problem and produced a summary of its thinking process. Use this summary to continue the task without redoing completed work.";
+/**
+ * 判断消息是否为之前压缩生成的摘要。
+ *
+ * 通过检查 user 消息是否以摘要前缀开头来识别。
+ * 压缩时需要跳过已有的摘要，避免"摘要套摘要"。
+ */
+export declare function isContextSummaryMessage(message: ChatMessage): boolean;
+/**
+ * 构建发给 LLM 的压缩请求（user prompt 部分）。
+ *
+ * 将整个对话历史转为文本格式，让 LLM 阅读后生成摘要。
+ */
+export declare function buildCompactionUserPrompt(messages: ChatMessage[]): string;
+/**
+ * 用压缩摘要重建历史数组。
+ *
+ * 新历史结构：[system (如有)] + [摘要消息]
+ * 这样历史从完整对话变为一条摘要，大幅减少 token 数。
+ */
+export declare function buildCompactedHistory(systemMessage: ChatMessage | undefined, summary: string): ChatMessage[];
+//# sourceMappingURL=compaction.d.ts.map

package/dist/runtime/compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../src/runtime/compaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAO9C;;;;;;;;GAQG;AACH,eAAO,MAAM,gCAAgC,sbAQ6C,CAAA;AAE1F;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,+KAC6I,CAAA;AA2ChL;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAGrE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACrC,QAAQ,EAAE,WAAW,EAAE,GACxB,MAAM,CAaR;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACjC,aAAa,EAAE,WAAW,GAAG,SAAS,EACtC,OAAO,EAAE,MAAM,GAChB,WAAW,EAAE,CAUf"}

package/dist/runtime/compaction.js

@@ -0,0 +1,118 @@
+/**
+ * @file 上下文压缩模块 — LLM 驱动的对话历史摘要。
+ *
+ * Phase 6：当对话历史的 token 数接近上下文窗口限制时，
+ * 调用 LLM 对历史生成结构化摘要，替换原始历史以释放空间。
+ *
+ * 设计参考 memo-code 的 compact_prompt.ts，但做了精简：
+ *   - 去掉了"保留最近 N 条 user 消息"的逻辑（简化）
+ *   - 保留了消息转文本、摘要检测、历史重建的核心流程
+ */
+/** 单条消息内容的最大字符数（超出时截断，避免压缩请求本身过大）。 */
+const MAX_MESSAGE_CONTENT_CHARS = 4_000;
+// ─── 压缩提示词 ─────────────────────────────────────────────────────────────
+/**
+ * 给 LLM 的压缩指令。
+ *
+ * 这个 prompt 告诉 LLM："你在做一次检查点压缩，
+ * 帮下一个 LLM 接手工作"。关键点：
+ *   - 保留进展和关键决策
+ *   - 保留约束和用户偏好
+ *   - 清晰列出后续步骤
+ */
+export const CONTEXT_COMPACTION_SYSTEM_PROMPT = `You are performing a CONTEXT CHECKPOINT COMPACTION. Create a handoff summary for another LLM that will resume the task.
+
+Include:
+- Current progress and key decisions made
+- Important context, constraints, or user preferences
+- What remains to be done (clear next steps)
+- Any critical data, examples, or references needed to continue
+
+Be concise, structured, and focused on helping the next LLM seamlessly continue the work.`;
+/**
+ * 摘要消息的识别前缀。
+ *
+ * 压缩后的摘要以这段文字开头，
+ * 让后续的压缩轮次能识别"这是之前的摘要，不是原始对话"。
+ */
+export const CONTEXT_SUMMARY_PREFIX = 'Another language model started to solve this problem and produced a summary of its thinking process. Use this summary to continue the task without redoing completed work.';
+// ─── 工具函数 ────────────────────────────────────────────────────────────────
+/**
+ * 截断过长的消息内容。
+ *
+ * 防止压缩请求本身太大（比如一个工具返回了 10 万字的文件内容）。
+ */
+function normalizeContent(content) {
+    const compact = content.replace(/\r\n/g, '\n').trim();
+    if (compact.length <= MAX_MESSAGE_CONTENT_CHARS) {
+        return compact;
+    }
+    return `${compact.slice(0, MAX_MESSAGE_CONTENT_CHARS)}...`;
+}
+/**
+ * 将单条消息转换为人类可读的文本行。
+ *
+ * 格式：[index] ROLE (附加信息)\n内容
+ * 这个格式让 LLM 能清晰理解对话的结构和顺序。
+ */
+function messageToTranscriptLine(message, index) {
+    const role = message.role.toUpperCase();
+    if (message.role === 'assistant' && message.tool_calls?.length) {
+        const toolNames = message.tool_calls
+            .map((tc) => tc.function.name)
+            .join(', ');
+        return `[${index}] ${role} (tool_calls: ${toolNames})\n${normalizeContent(message.content)}`;
+    }
+    if (message.role === 'tool') {
+        const toolName = message.name ? ` (${message.name})` : '';
+        return `[${index}] ${role}${toolName}\n${normalizeContent(message.content)}`;
+    }
+    return `[${index}] ${role}\n${normalizeContent(message.content)}`;
+}
+// ─── 公开 API ────────────────────────────────────────────────────────────────
+/**
+ * 判断消息是否为之前压缩生成的摘要。
+ *
+ * 通过检查 user 消息是否以摘要前缀开头来识别。
+ * 压缩时需要跳过已有的摘要，避免"摘要套摘要"。
+ */
+export function isContextSummaryMessage(message) {
+    if (message.role !== 'user')
+        return false;
+    return message.content.startsWith(`${CONTEXT_SUMMARY_PREFIX}\n`);
+}
+/**
+ * 构建发给 LLM 的压缩请求（user prompt 部分）。
+ *
+ * 将整个对话历史转为文本格式，让 LLM 阅读后生成摘要。
+ */
+export function buildCompactionUserPrompt(messages) {
+    const transcript = messages.length
+        ? messages
+            .map((msg, i) => messageToTranscriptLine(msg, i))
+            .join('\n\n')
+        : '(empty)';
+    return [
+        'Conversation history to summarize:',
+        transcript,
+        '',
+        'Return only the summary body in plain text. Do not add markdown fences.',
+    ].join('\n');
+}
+/**
+ * 用压缩摘要重建历史数组。
+ *
+ * 新历史结构：[system (如有)] + [摘要消息]
+ * 这样历史从完整对话变为一条摘要，大幅减少 token 数。
+ */
+export function buildCompactedHistory(systemMessage, summary) {
+    const summaryMessage = {
+        role: 'user',
+        content: `${CONTEXT_SUMMARY_PREFIX}\n${summary}`,
+    };
+    if (systemMessage) {
+        return [systemMessage, summaryMessage];
+    }
+    return [summaryMessage];
+}
+//# sourceMappingURL=compaction.js.map

package/dist/runtime/compaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.js","sourceRoot":"","sources":["../../src/runtime/compaction.ts"],"names":[],"mappings":"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"}

package/dist/runtime/compaction.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @file Unit tests for context compaction module (Phase 6).
+ *
+ * Tests: isContextSummaryMessage, buildCompactionUserPrompt, buildCompactedHistory
+ */
+export {};
+//# sourceMappingURL=compaction.test.d.ts.map

package/dist/runtime/compaction.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.test.d.ts","sourceRoot":"","sources":["../../src/runtime/compaction.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/runtime/compaction.test.js

@@ -0,0 +1,70 @@
+/**
+ * @file Unit tests for context compaction module (Phase 6).
+ *
+ * Tests: isContextSummaryMessage, buildCompactionUserPrompt, buildCompactedHistory
+ */
+import { describe, it, expect } from 'vitest';
+import { isContextSummaryMessage, buildCompactionUserPrompt, buildCompactedHistory, } from './compaction.js';
+// ─── Test Fixtures ────────────────────────────────────────────────────────────
+function msg(role, content) {
+    return { role, content };
+}
+function summaryMsg(text) {
+    return {
+        role: 'user',
+        content: `Another language model started to solve this problem and produced a summary of its thinking process. Use this summary to continue the task without redoing completed work.\n${text}`,
+    };
+}
+// ─── Tests ────────────────────────────────────────────────────────────────────
+describe('isContextSummaryMessage', () => {
+    it('should identify summary messages', () => {
+        expect(isContextSummaryMessage(summaryMsg('stuff'))).toBe(true);
+    });
+    it('should reject non-summary user messages', () => {
+        expect(isContextSummaryMessage(msg('user', 'hello'))).toBe(false);
+    });
+    it('should reject assistant messages', () => {
+        expect(isContextSummaryMessage(msg('assistant', 'sup'))).toBe(false);
+    });
+});
+describe('buildCompactionUserPrompt', () => {
+    it('should format message transcript correctly', () => {
+        const history = [
+            msg('user', 'What is 1+1?'),
+            msg('assistant', '2'),
+            msg('user', 'wrong'),
+        ];
+        const prompt = buildCompactionUserPrompt(history);
+        expect(prompt).toContain('[0] USER\nWhat is 1+1?');
+        expect(prompt).toContain('[1] ASSISTANT\n2');
+        expect(prompt).toContain('[2] USER\nwrong');
+    });
+});
+describe('buildCompactedHistory', () => {
+    it('should merge summary and retain system message', () => {
+        const history = [
+            msg('system', 'sys prompt here'),
+            msg('user', 'hi'),
+            msg('assistant', 'hello'),
+            msg('user', 'do it'),
+        ];
+        const compacted = buildCompactedHistory(history[0], 'New Summary');
+        expect(compacted).toHaveLength(2);
+        expect(compacted[0].role).toBe('system');
+        expect(compacted[0].content).toBe('sys prompt here');
+        expect(compacted[1].role).toBe('user');
+        expect(compacted[1].content).toContain('Another language model started');
+        expect(compacted[1].content).toContain('New Summary');
+    });
+    it('should work without system message', () => {
+        const history = [
+            msg('user', 'hi'),
+            msg('assistant', 'hello'),
+        ];
+        const compacted = buildCompactedHistory(undefined, 'Summary Only');
+        expect(compacted).toHaveLength(1);
+        expect(compacted[0].role).toBe('user');
+        expect(compacted[0].content).toContain('Summary Only');
+    });
+});
+//# sourceMappingURL=compaction.test.js.map

package/dist/runtime/compaction.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.test.js","sourceRoot":"","sources":["../../src/runtime/compaction.test.ts"],"names":[],"mappings":"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"}

package/dist/runtime/history.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @file 会话历史持久化 — JSONL 格式写入。
+ *
+ * 参考 memo-code 的 history.ts，
+ * 每个事件写为一行 JSON，支持串行写入队列。
+ */
+import type { HistoryEvent, HistoryEventType, HistorySink, Role } from '../types.js';
+/** JSONL 历史写入器：每条事件一行 JSON。 */
+export declare class JsonlHistorySink implements HistorySink {
+    private filePath;
+    private ensureDirPromise;
+    private writeQueue;
+    private closed;
+    constructor(filePath: string);
+    /** 确保目标目录存在。 */
+    private ensureDirectory;
+    /** 追加一条事件到 JSONL 文件。 */
+    append(event: HistoryEvent): Promise<void>;
+    /** 等待所有挂起的写入完成。 */
+    flush(): Promise<void>;
+    /** 关闭写入器。 */
+    close(): Promise<void>;
+}
+/** 创建一条结构化历史事件。 */
+export declare function createHistoryEvent(params: {
+    sessionId: string;
+    type: HistoryEventType;
+    turn?: number;
+    step?: number;
+    content?: string;
+    role?: Role;
+    meta?: Record<string, unknown>;
+}): HistoryEvent;
+//# sourceMappingURL=history.d.ts.map

package/dist/runtime/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/runtime/history.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EACR,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,IAAI,EACP,MAAM,aAAa,CAAA;AAIpB,+BAA+B;AAC/B,qBAAa,gBAAiB,YAAW,WAAW;IAKpC,OAAO,CAAC,QAAQ;IAJ5B,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,UAAU,CAAmC;IACrD,OAAO,CAAC,MAAM,CAAQ;gBAEF,QAAQ,EAAE,MAAM;IAEpC,gBAAgB;IAChB,OAAO,CAAC,eAAe;IAUvB,wBAAwB;IAClB,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAehD,mBAAmB;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,aAAa;IACP,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAK/B;AAID,mBAAmB;AACnB,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACvC,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,gBAAgB,CAAA;IACtB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,IAAI,CAAC,EAAE,IAAI,CAAA;IACX,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC,GAAG,YAAY,CAWf"}

package/dist/runtime/history.js

@@ -0,0 +1,63 @@
+/**
+ * @file 会话历史持久化 — JSONL 格式写入。
+ *
+ * 参考 memo-code 的 history.ts，
+ * 每个事件写为一行 JSON，支持串行写入队列。
+ */
+import { appendFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+// ─── JsonlHistorySink ────────────────────────────────────────────────────────
+/** JSONL 历史写入器：每条事件一行 JSON。 */
+export class JsonlHistorySink {
+    filePath;
+    ensureDirPromise = null;
+    writeQueue = Promise.resolve();
+    closed = false;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    /** 确保目标目录存在。 */
+    ensureDirectory() {
+        if (!this.ensureDirPromise) {
+            this.ensureDirPromise = mkdir(dirname(this.filePath), { recursive: true }).then(() => { });
+        }
+        return this.ensureDirPromise;
+    }
+    /** 追加一条事件到 JSONL 文件。 */
+    async append(event) {
+        if (this.closed) {
+            throw new Error('History sink is closed');
+        }
+        this.writeQueue = this.writeQueue.then(async () => {
+            await this.ensureDirectory();
+            await appendFile(this.filePath, `${JSON.stringify(event)}\n`, 'utf8');
+        });
+        return this.writeQueue;
+    }
+    /** 等待所有挂起的写入完成。 */
+    async flush() {
+        await this.writeQueue;
+    }
+    /** 关闭写入器。 */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        await this.flush();
+    }
+}
+// ─── 辅助函数 ─────────────────────────────────────────────────────────────────
+/** 创建一条结构化历史事件。 */
+export function createHistoryEvent(params) {
+    return {
+        ts: new Date().toISOString(),
+        sessionId: params.sessionId,
+        type: params.type,
+        turn: params.turn,
+        step: params.step,
+        content: params.content,
+        role: params.role,
+        meta: params.meta,
+    };
+}
+//# sourceMappingURL=history.js.map

package/dist/runtime/history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.js","sourceRoot":"","sources":["../../src/runtime/history.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAQnC,gFAAgF;AAEhF,+BAA+B;AAC/B,MAAM,OAAO,gBAAgB;IAKL;IAJZ,gBAAgB,GAAyB,IAAI,CAAA;IAC7C,UAAU,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAA;IAC7C,MAAM,GAAG,KAAK,CAAA;IAEtB,YAAoB,QAAgB;QAAhB,aAAQ,GAAR,QAAQ,CAAQ;IAAG,CAAC;IAExC,gBAAgB;IACR,eAAe;QACnB,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACzB,IAAI,CAAC,gBAAgB,GAAG,KAAK,CACzB,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EACtB,EAAE,SAAS,EAAE,IAAI,EAAE,CACtB,CAAC,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;QACpB,CAAC;QACD,OAAO,IAAI,CAAC,gBAAgB,CAAA;IAChC,CAAC;IAED,wBAAwB;IACxB,KAAK,CAAC,MAAM,CAAC,KAAmB;QAC5B,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAA;QAC7C,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE;YAC9C,MAAM,IAAI,CAAC,eAAe,EAAE,CAAA;YAC5B,MAAM,UAAU,CACZ,IAAI,CAAC,QAAQ,EACb,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAC5B,MAAM,CACT,CAAA;QACL,CAAC,CAAC,CAAA;QACF,OAAO,IAAI,CAAC,UAAU,CAAA;IAC1B,CAAC;IAED,mBAAmB;IACnB,KAAK,CAAC,KAAK;QACP,MAAM,IAAI,CAAC,UAAU,CAAA;IACzB,CAAC;IAED,aAAa;IACb,KAAK,CAAC,KAAK;QACP,IAAI,IAAI,CAAC,MAAM;YAAE,OAAM;QACvB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;QAClB,MAAM,IAAI,CAAC,KAAK,EAAE,CAAA;IACtB,CAAC;CACJ;AAED,6EAA6E;AAE7E,mBAAmB;AACnB,MAAM,UAAU,kBAAkB,CAAC,MAQlC;IACG,OAAO;QACH,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC5B,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,IAAI,EAAE,MAAM,CAAC,IAAI;KACpB,CAAA;AACL,CAAC"}

package/dist/runtime/hooks.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @file Hook 系统 — 生命周期钩子的注册与执行引擎。
+ *
+ * Phase 7：提供 HookRunnerMap 注册表和 runHook() 安全执行器，
+ * 让 ReAct 循环在关键节点发射事件，由外部中间件处理 UI/日志等。
+ *
+ * 设计要点：
+ *   - runHook() 内部 try/catch，单个 handler 失败不影响主流程
+ *   - snapshotHistory() 深拷贝历史，防止 hook 修改共享状态
+ *   - buildHookRunners() 合并 hooks + middlewares 到统一注册表
+ */
+import type { ChatMessage, AgentHooks, AgentMiddleware, AgentHookHandler, TurnStartHookPayload, ActionHookPayload, ObservationHookPayload, FinalHookPayload, ContextUsageHookPayload, ContextCompactedHookPayload, ApprovalHookPayload, ApprovalResponseHookPayload, TitleGeneratedHookPayload } from '../types.js';
+/** 9 种 Hook 名称。 */
+export type HookName = 'onTurnStart' | 'onAction' | 'onObservation' | 'onFinal' | 'onContextUsage' | 'onContextCompacted' | 'onApprovalRequest' | 'onApprovalResponse' | 'onTitleGenerated';
+/** Hook 名称 → Payload 类型映射。 */
+export type HookPayloadMap = {
+    onTurnStart: TurnStartHookPayload;
+    onAction: ActionHookPayload;
+    onObservation: ObservationHookPayload;
+    onFinal: FinalHookPayload;
+    onContextUsage: ContextUsageHookPayload;
+    onContextCompacted: ContextCompactedHookPayload;
+    onApprovalRequest: ApprovalHookPayload;
+    onApprovalResponse: ApprovalResponseHookPayload;
+    onTitleGenerated: TitleGeneratedHookPayload;
+};
+/** Hook 注册表：每个 hook 名称对应一个 handler 数组。 */
+export type HookRunnerMap = {
+    [K in HookName]: AgentHookHandler<HookPayloadMap[K]>[];
+};
+/**
+ * 从 hooks + middlewares 配置构建统一的 HookRunnerMap。
+ *
+ * hooks 先注册，然后按顺序注册每个 middleware。
+ * 这样 hooks 里的 handler 总是最先执行。
+ */
+export declare function buildHookRunners(hooks?: AgentHooks, middlewares?: AgentMiddleware[]): HookRunnerMap;
+/**
+ * 安全执行指定 Hook 的所有 handler。
+ *
+ * 关键设计：每个 handler 独立 try/catch，
+ * 一个 handler 抛错不会阻止后续 handler 执行，
+ * 也不会影响主流程（ReAct 循环继续）。
+ */
+export declare function runHook<K extends HookName>(map: HookRunnerMap, name: K, payload: HookPayloadMap[K]): Promise<void>;
+/**
+ * 深拷贝对话历史（传给 hook 的快照）。
+ *
+ * 防止 hook 中的代码意外修改共享的 history 数组。
+ * 对 assistant 消息的 tool_calls 做三层拷贝，
+ * 确保 function 对象也是独立副本。
+ */
+export declare function snapshotHistory(history: ChatMessage[]): ChatMessage[];
+//# sourceMappingURL=hooks.d.ts.map

package/dist/runtime/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/runtime/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACR,WAAW,EACX,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,gBAAgB,EAChB,uBAAuB,EACvB,2BAA2B,EAC3B,mBAAmB,EACnB,2BAA2B,EAC3B,yBAAyB,EAC5B,MAAM,aAAa,CAAA;AAIpB,mBAAmB;AACnB,MAAM,MAAM,QAAQ,GACd,aAAa,GACb,UAAU,GACV,eAAe,GACf,SAAS,GACT,gBAAgB,GAChB,oBAAoB,GACpB,mBAAmB,GACnB,oBAAoB,GACpB,kBAAkB,CAAA;AAExB,8BAA8B;AAC9B,MAAM,MAAM,cAAc,GAAG;IACzB,WAAW,EAAE,oBAAoB,CAAA;IACjC,QAAQ,EAAE,iBAAiB,CAAA;IAC3B,aAAa,EAAE,sBAAsB,CAAA;IACrC,OAAO,EAAE,gBAAgB,CAAA;IACzB,cAAc,EAAE,uBAAuB,CAAA;IACvC,kBAAkB,EAAE,2BAA2B,CAAA;IAC/C,iBAAiB,EAAE,mBAAmB,CAAA;IACtC,kBAAkB,EAAE,2BAA2B,CAAA;IAC/C,gBAAgB,EAAE,yBAAyB,CAAA;CAC9C,CAAA;AAED,0CAA0C;AAC1C,MAAM,MAAM,aAAa,GAAG;KACvB,CAAC,IAAI,QAAQ,GAAG,gBAAgB,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE;CACzD,CAAA;AA2CD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC5B,KAAK,CAAC,EAAE,UAAU,EAClB,WAAW,CAAC,EAAE,eAAe,EAAE,GAChC,aAAa,CASf;AAED;;;;;;GAMG;AACH,wBAAsB,OAAO,CAAC,CAAC,SAAS,QAAQ,EAC5C,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,CAarE"}

package/dist/runtime/hooks.js

@@ -0,0 +1,113 @@
+/**
+ * @file Hook 系统 — 生命周期钩子的注册与执行引擎。
+ *
+ * Phase 7：提供 HookRunnerMap 注册表和 runHook() 安全执行器，
+ * 让 ReAct 循环在关键节点发射事件，由外部中间件处理 UI/日志等。
+ *
+ * 设计要点：
+ *   - runHook() 内部 try/catch，单个 handler 失败不影响主流程
+ *   - snapshotHistory() 深拷贝历史，防止 hook 修改共享状态
+ *   - buildHookRunners() 合并 hooks + middlewares 到统一注册表
+ */
+// ─── 内部工具函数 ─────────────────────────────────────────────────────────────
+/** 创建空的 Hook 注册表。 */
+function emptyHookMap() {
+    return {
+        onTurnStart: [],
+        onAction: [],
+        onObservation: [],
+        onFinal: [],
+        onContextUsage: [],
+        onContextCompacted: [],
+        onApprovalRequest: [],
+        onApprovalResponse: [],
+        onTitleGenerated: [],
+    };
+}
+/**
+ * 将单个中间件的 handler 注册到注册表中。
+ *
+ * 遍历中间件上所有可选的 hook 属性，
+ * 如果存在则 push 到对应数组。
+ */
+function registerMiddleware(target, middleware) {
+    if (!middleware)
+        return;
+    if (middleware.onTurnStart)
+        target.onTurnStart.push(middleware.onTurnStart);
+    if (middleware.onAction)
+        target.onAction.push(middleware.onAction);
+    if (middleware.onObservation)
+        target.onObservation.push(middleware.onObservation);
+    if (middleware.onFinal)
+        target.onFinal.push(middleware.onFinal);
+    if (middleware.onContextUsage)
+        target.onContextUsage.push(middleware.onContextUsage);
+    if (middleware.onContextCompacted)
+        target.onContextCompacted.push(middleware.onContextCompacted);
+    if (middleware.onApprovalRequest)
+        target.onApprovalRequest.push(middleware.onApprovalRequest);
+    if (middleware.onApprovalResponse)
+        target.onApprovalResponse.push(middleware.onApprovalResponse);
+    if (middleware.onTitleGenerated)
+        target.onTitleGenerated.push(middleware.onTitleGenerated);
+}
+// ─── 公开 API ────────────────────────────────────────────────────────────────
+/**
+ * 从 hooks + middlewares 配置构建统一的 HookRunnerMap。
+ *
+ * hooks 先注册，然后按顺序注册每个 middleware。
+ * 这样 hooks 里的 handler 总是最先执行。
+ */
+export function buildHookRunners(hooks, middlewares) {
+    const map = emptyHookMap();
+    registerMiddleware(map, hooks);
+    if (Array.isArray(middlewares)) {
+        for (const mw of middlewares) {
+            registerMiddleware(map, mw);
+        }
+    }
+    return map;
+}
+/**
+ * 安全执行指定 Hook 的所有 handler。
+ *
+ * 关键设计：每个 handler 独立 try/catch，
+ * 一个 handler 抛错不会阻止后续 handler 执行，
+ * 也不会影响主流程（ReAct 循环继续）。
+ */
+export async function runHook(map, name, payload) {
+    const handlers = map[name];
+    if (!handlers.length)
+        return;
+    for (const handler of handlers) {
+        try {
+            await handler(payload);
+        }
+        catch (err) {
+            console.warn(`Hook ${name} failed: ${err.message}`);
+        }
+    }
+}
+/**
+ * 深拷贝对话历史（传给 hook 的快照）。
+ *
+ * 防止 hook 中的代码意外修改共享的 history 数组。
+ * 对 assistant 消息的 tool_calls 做三层拷贝，
+ * 确保 function 对象也是独立副本。
+ */
+export function snapshotHistory(history) {
+    return history.map((msg) => {
+        if (msg.role === 'assistant' && msg.tool_calls?.length) {
+            return {
+                ...msg,
+                tool_calls: msg.tool_calls.map((tc) => ({
+                    ...tc,
+                    function: { ...tc.function },
+                })),
+            };
+        }
+        return { ...msg };
+    });
+}
+//# sourceMappingURL=hooks.js.map

package/dist/runtime/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/runtime/hooks.ts"],"names":[],"mappings":"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"}

package/dist/runtime/hooks.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @file Unit tests for Hooks system (Phase 7).
+ *
+ * Tests: buildHookRunners, runHook, snapshotHistory
+ */
+export {};
+//# sourceMappingURL=hooks.test.d.ts.map

package/dist/runtime/hooks.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.test.d.ts","sourceRoot":"","sources":["../../src/runtime/hooks.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/runtime/hooks.test.js

@@ -0,0 +1,73 @@
+/**
+ * @file Unit tests for Hooks system (Phase 7).
+ *
+ * Tests: buildHookRunners, runHook, snapshotHistory
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { buildHookRunners, runHook, snapshotHistory, } from './hooks.js';
+// ─── Tests ────────────────────────────────────────────────────────────────────
+describe('runHook', () => {
+    it('should execute handlers successfully', async () => {
+        const h1 = vi.fn(async () => undefined);
+        const h2 = vi.fn(async () => undefined);
+        await runHook({ onTurnStart: [h1, h2] }, 'onTurnStart', { history: [] });
+        expect(h1).toHaveBeenCalledOnce();
+        expect(h2).toHaveBeenCalledOnce();
+    });
+    it('should isolate errors and continue sequence', async () => {
+        const h1 = vi.fn(async () => { throw new Error('First failed'); });
+        const h2 = vi.fn(async () => undefined);
+        // Console.error will be called, hide it to avoid noisy test output
+        const spy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        await runHook({ onTurnStart: [h1, h2] }, 'onTurnStart', { history: [] });
+        expect(h1).toHaveBeenCalledOnce();
+        expect(h2).toHaveBeenCalledOnce(); // h2 still runs despite h1 error
+        spy.mockRestore();
+    });
+});
+describe('buildHookRunners', () => {
+    it('should merge app hooks and middleware correctly', () => {
+        const globalHook = {
+            onTurnStart: vi.fn(),
+        };
+        const middleware = {
+            name: 'test-mid',
+            onTurnStart: vi.fn(),
+        };
+        const runners = buildHookRunners(globalHook, [middleware]);
+        expect(runners).toBeDefined();
+        expect(runners.onTurnStart).toHaveLength(2);
+    });
+});
+describe('snapshotHistory', () => {
+    it('should perform deep copy of message history', () => {
+        const original = [
+            { role: 'user', content: 'hello' },
+            {
+                role: 'assistant',
+                content: 'hi',
+                tool_calls: [{
+                        id: '1', type: 'function', function: { name: 'f', arguments: '{}' }
+                    }]
+            },
+        ];
+        const snapshot = snapshotHistory(original);
+        // It should match structure
+        expect(snapshot).toEqual(original);
+        // But be a different reference at the top level
+        expect(snapshot).not.toBe(original);
+        // And different reference at the tool calls level
+        const originalAsst = original[1];
+        const snapshotAsst = snapshot[1];
+        expect(snapshotAsst.tool_calls).not.toBe(originalAsst.tool_calls);
+        // Modifying original shouldn't affect snapshot
+        original.push({ role: 'user', content: 'mutated' });
+        expect(snapshot).toHaveLength(2);
+        // Modifying deep object doesn't affect snapshot
+        if (originalAsst.tool_calls) {
+            originalAsst.tool_calls[0].function.arguments = '{"mutated":true}';
+        }
+        expect(snapshotAsst.tool_calls?.[0].function.arguments).toBe('{}');
+    });
+});
+//# sourceMappingURL=hooks.test.js.map

package/dist/runtime/hooks.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.test.js","sourceRoot":"","sources":["../../src/runtime/hooks.test.ts"],"names":[],"mappings":"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"}