sema-core 2.0.11 → 2.0.13

package/dist/services/hooks/hookTriggers.js

@@ -0,0 +1,295 @@
+"use strict";
+/**
+ * Hook 埋点入口
+ *
+ * 核心链路仅 import 本模块。埋点稳定性硬约束：
+ * ① 无匹配条目零开销早退；② 整体 try/catch fail-open，
+ * 内部任何错误只记日志不上抛——未配置 hooks 的现有用户零影响。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fireSessionStart = fireSessionStart;
+exports.fireUserPromptSubmit = fireUserPromptSubmit;
+exports.firePreToolUse = firePreToolUse;
+exports.firePostToolUse = firePostToolUse;
+exports.firePostToolUseFailure = firePostToolUseFailure;
+exports.firePermissionRequest = firePermissionRequest;
+exports.fireStop = fireStop;
+exports.fireSessionEnd = fireSessionEnd;
+const EventSystem_1 = require("../../events/EventSystem");
+const toolAliases_1 = require("../../prompt/toolAliases");
+const cwd_1 = require("../../util/cwd");
+const log_1 = require("../../util/log");
+const hooksManager_1 = require("./hooksManager");
+const hookRunner_1 = require("./hookRunner");
+const MAIN_AGENT = 'main';
+function neutralAggregate() {
+    return { ran: false, blocked: false, decision: 'none', additionalContext: [] };
+}
+/**
+ * fail-open 总兜底：入口全部逻辑（含单例获取、开关读取）都在其中执行，
+ * 任何异常只记日志并返回中性结果，绝不上抛到核心链路
+ */
+async function safeRun(neutral, fn) {
+    try {
+        return await fn();
+    }
+    catch (error) {
+        (0, log_1.logWarn)(`[Hook] 内部错误(fail-open): ${error}`);
+        return neutral;
+    }
+}
+function emitNotice(sessionId, data) {
+    (0, EventSystem_1.getEventBus)().emit('hook:notice', data, sessionId);
+}
+/**
+ * 顺序执行单个事件下的全部命中条目并聚合结果
+ * - 第一个阻断（block / deny）立即停止后续条目
+ * - 聚合优先级：deny > ask > allow > none（ask 保守优先于 allow）
+ */
+async function runEventHooks(event, sessionId, payload, entries, signal) {
+    const aggregate = { ran: true, blocked: false, decision: 'none', additionalContext: [] };
+    const payloadJson = JSON.stringify(payload);
+    for (const entry of entries) {
+        // 中断后短路剩余条目，避免逐个 spawn 出立即被 kill 的进程
+        if (signal?.aborted)
+            break;
+        const exec = await (0, hookRunner_1.executeHookCommand)(entry.command, payloadJson, entry.timeoutMs, signal);
+        const outcome = (0, hookRunner_1.parseHookOutput)(event, exec);
+        // 审计日志（PreToolUse / PermissionRequest 的 allow 等于把权限决策交给 hook 脚本，日志不可省）
+        (0, log_1.logInfo)(`[Hook][audit] event=${event} agent=${String(payload.agent_id ?? MAIN_AGENT)} ` +
+            `source=${entry.source} command="${entry.command}" timeoutMs=${entry.timeoutMs} ` +
+            `exit=${exec.exitCode} timedOut=${exec.timedOut} kind=${outcome.kind} ` +
+            `decision=${outcome.decision ?? '-'} duration=${exec.durationMs}ms`);
+        if (exec.timedOut) {
+            emitNotice(sessionId, {
+                kind: 'warning',
+                hookEvent: event,
+                message: `hook 执行超时（${entry.timeoutMs / 1000}s）已终止: ${entry.command}`,
+                command: entry.command,
+                source: entry.source,
+            });
+        }
+        // 不可阻断事件上的 block 输出被忽略：告警而非静默，
+        // 避免用户从其他工具迁移来的续驱配置（Stop + exit 2）看似生效实则无效
+        if (outcome.blockIgnored) {
+            emitNotice(sessionId, {
+                kind: 'warning',
+                hookEvent: event,
+                message: `${event} 事件不支持阻断，hook 的 block 输出已忽略: ${entry.command}`,
+                command: entry.command,
+                source: entry.source,
+            });
+        }
+        if (outcome.systemMessage) {
+            emitNotice(sessionId, {
+                kind: 'systemMessage',
+                hookEvent: event,
+                message: outcome.systemMessage,
+                command: entry.command,
+                source: entry.source,
+            });
+        }
+        if (outcome.additionalContext) {
+            aggregate.additionalContext.push(outcome.additionalContext);
+        }
+        // fail-closed 条目：hook 执行失败按阻断处理
+        const effectiveKind = outcome.kind === 'error' && entry.failClosed ? 'block' : outcome.kind;
+        if (effectiveKind === 'block') {
+            aggregate.blocked = true;
+            aggregate.blockReason =
+                outcome.kind === 'error'
+                    ? `hook failed (fail-closed): ${entry.command}`
+                    : outcome.reason;
+            break;
+        }
+        if (outcome.decision === 'deny') {
+            aggregate.decision = 'deny';
+            aggregate.decisionReason = outcome.reason;
+            break;
+        }
+        if (outcome.decision === 'ask') {
+            aggregate.decision = 'ask';
+            if (outcome.reason)
+                aggregate.decisionReason = outcome.reason;
+        }
+        else if (outcome.decision === 'allow' && aggregate.decision === 'none') {
+            aggregate.decision = 'allow';
+            if (outcome.reason)
+                aggregate.decisionReason = outcome.reason;
+        }
+    }
+    // 聚合后总量再做一次截断
+    const total = aggregate.additionalContext.join('\n\n');
+    if (total.length > hookRunner_1.MAX_ADDITIONAL_CONTEXT_CHARS) {
+        aggregate.additionalContext = [(0, hookRunner_1.truncateContext)(total)];
+    }
+    return aggregate;
+}
+function buildCommonPayload(event, sessionId, agentId) {
+    return {
+        session_id: sessionId,
+        cwd: (0, cwd_1.readInitialCwd)(),
+        hook_event_name: event,
+        agent_id: agentId,
+    };
+}
+/**
+ * 工具类事件的统一触发（PreToolUse / PostToolUse / PostToolUseFailure / PermissionRequest）
+ */
+async function runToolEventHooks(event, sessionId, agentId, semaToolName, extraPayload, signal) {
+    // ran 在 safeRun 外持有：条目进入执行链路后即置位，
+    // 后续执行失败/被中断（fail-open 返回中性结果）时 ran 仍为 true
+    let ran = false;
+    const result = await safeRun(neutralAggregate(), async () => {
+        const manager = (0, hooksManager_1.getHooksManager)();
+        await manager.ready();
+        const genericToolName = (0, toolAliases_1.toGenericToolName)(semaToolName);
+        const entries = manager.getMatchedEntries(event, genericToolName, semaToolName);
+        if (entries.length === 0)
+            return neutralAggregate();
+        ran = true;
+        const payload = {
+            ...buildCommonPayload(event, sessionId, agentId),
+            tool_name: genericToolName,
+            sema_tool_name: semaToolName,
+            ...extraPayload,
+        };
+        return runEventHooks(event, sessionId, payload, entries, signal);
+    });
+    return { ...result, ran };
+}
+// ==================== 8 个事件入口 ====================
+/**
+ * SessionStart：engine session 初始化成功后触发；不可阻断
+ * @returns 注入模型上下文的 additionalContext，无则 null
+ */
+async function fireSessionStart(sessionId) {
+    return safeRun(null, async () => {
+        const manager = (0, hooksManager_1.getHooksManager)();
+        await manager.ready();
+        const entries = manager.getMatchedEntries('SessionStart');
+        if (entries.length === 0)
+            return null;
+        const payload = { ...buildCommonPayload('SessionStart', sessionId, MAIN_AGENT), source: 'startup' };
+        const aggregate = await runEventHooks('SessionStart', sessionId, payload, entries);
+        return aggregate.additionalContext.length > 0 ? aggregate.additionalContext.join('\n\n') : null;
+    });
+}
+/**
+ * UserPromptSubmit：用户输入进入命令处理或模型处理前触发
+ * block → 丢弃本次输入（原因经 hook:notice 展示给用户，由调用方发出）
+ */
+async function fireUserPromptSubmit(sessionId, prompt, signal) {
+    const neutral = { blocked: false };
+    let ran = false;
+    const result = await safeRun(neutral, async () => {
+        const manager = (0, hooksManager_1.getHooksManager)();
+        await manager.ready();
+        const entries = manager.getMatchedEntries('UserPromptSubmit');
+        if (entries.length === 0)
+            return neutral;
+        ran = true;
+        const payload = { ...buildCommonPayload('UserPromptSubmit', sessionId, MAIN_AGENT), prompt };
+        const aggregate = await runEventHooks('UserPromptSubmit', sessionId, payload, entries, signal);
+        return {
+            blocked: aggregate.blocked,
+            reason: aggregate.blockReason,
+            additionalContext: aggregate.additionalContext.length > 0 ? aggregate.additionalContext.join('\n\n') : undefined,
+        };
+    });
+    return { ...result, ran };
+}
+/**
+ * PreToolUse：工具执行前触发
+ * deny → 工具不执行，原因以 is_error tool_result 回给模型（exit 2 等价 deny）
+ * allow → 跳过权限询问直接执行；ask/无输出 → 走原权限流程
+ */
+async function firePreToolUse(sessionId, agentId, semaToolName, input, signal) {
+    const aggregate = await runToolEventHooks('PreToolUse', sessionId, agentId, semaToolName, { tool_input: input }, signal);
+    if (aggregate.blocked) {
+        return { decision: 'deny', reason: aggregate.blockReason, ran: aggregate.ran };
+    }
+    if (aggregate.decision === 'allow' || aggregate.decision === 'deny') {
+        return { decision: aggregate.decision, reason: aggregate.decisionReason, ran: aggregate.ran };
+    }
+    return { decision: 'none', ran: aggregate.ran };
+}
+/**
+ * PostToolUse：工具执行成功后触发
+ * @returns contextBlocks 注入模型上下文的文本块（exit 2 的 stderr 与 additionalContext）
+ */
+async function firePostToolUse(sessionId, agentId, semaToolName, input, response, signal) {
+    const aggregate = await runToolEventHooks('PostToolUse', sessionId, agentId, semaToolName, { tool_input: input, tool_response: response }, signal);
+    const contextBlocks = [...aggregate.additionalContext];
+    if (aggregate.blocked && aggregate.blockReason) {
+        // 工具已执行完，无法撤销，stderr 仅回灌模型
+        contextBlocks.push(`[PostToolUse hook] ${aggregate.blockReason}`);
+    }
+    return { contextBlocks };
+}
+/**
+ * PostToolUseFailure：工具执行抛错后触发（可注入纠错提示）
+ */
+async function firePostToolUseFailure(sessionId, agentId, semaToolName, input, error, signal) {
+    const aggregate = await runToolEventHooks('PostToolUseFailure', sessionId, agentId, semaToolName, { tool_input: input, error }, signal);
+    const contextBlocks = [...aggregate.additionalContext];
+    if (aggregate.blocked && aggregate.blockReason) {
+        contextBlocks.push(`[PostToolUseFailure hook] ${aggregate.blockReason}`);
+    }
+    return { contextBlocks };
+}
+/**
+ * PermissionRequest：权限系统即将向用户发起询问前触发
+ * allow → 批准（等价用户 agree，不产生永久授权）；deny → 拒绝（exit 2 等价 deny）；
+ * ask/无输出 → 保持正常询问流程
+ */
+async function firePermissionRequest(sessionId, agentId, semaToolName, input, signal) {
+    const aggregate = await runToolEventHooks('PermissionRequest', sessionId, agentId, semaToolName, { tool_input: input }, signal);
+    if (aggregate.blocked) {
+        return { decision: 'deny', reason: aggregate.blockReason };
+    }
+    if (aggregate.decision === 'allow' || aggregate.decision === 'deny') {
+        return { decision: aggregate.decision, reason: aggregate.decisionReason };
+    }
+    return { decision: 'none' };
+}
+/**
+ * Stop：主链路一轮处理自然完成并转入 idle 时触发，fire-and-forget（观察型埋点）。
+ * 不可阻断（暂不支持续驱，block 输出忽略并告警）、不注入上下文；
+ * systemMessage 照常经 hook:notice 展示。中断的轮次与排队输入接续的轮次不触发。
+ */
+function fireStop(sessionId) {
+    void safeRun(null, async () => {
+        const manager = (0, hooksManager_1.getHooksManager)();
+        await manager.ready();
+        const entries = manager.getMatchedEntries('Stop');
+        if (entries.length === 0)
+            return null;
+        // stop_hook_active 对齐通用 hooks 字段形状（无续驱恒为 false），方便脚本跨端复用
+        const payload = { ...buildCommonPayload('Stop', sessionId, MAIN_AGENT), stop_hook_active: false };
+        await runEventHooks('Stop', sessionId, payload, entries);
+        return null;
+    });
+}
+/**
+ * SessionEnd：会话关闭时触发，fire-and-forget（不可阻断，输出忽略）
+ */
+function fireSessionEnd(sessionId) {
+    void safeRun(null, async () => {
+        // async 函数体在首个 await 前同步执行：缓存就绪时条目在本调用返回前即被同步捕获，
+        // 不受 SemaCore.dispose 同步链路随后清空 hooksManager 缓存的影响（捕获的是过滤后的新数组）。
+        // 缓存未就绪（会话刚创建即销毁的窄窗口）走异步加载兜底，此时仍可能因 dispose 竞态跳过——
+        // SessionEnd 本为 best-effort（宿主进程随即退出也可能截断 hook 执行），该残余可接受
+        const manager = (0, hooksManager_1.getHooksManager)();
+        if (!manager.isReady()) {
+            await manager.ready();
+        }
+        const entries = manager.getMatchedEntries('SessionEnd');
+        if (entries.length === 0)
+            return null;
+        const payload = { ...buildCommonPayload('SessionEnd', sessionId, MAIN_AGENT), reason: 'dispose' };
+        await runEventHooks('SessionEnd', sessionId, payload, entries);
+        return null;
+    });
+}
+//# sourceMappingURL=hookTriggers.js.map

package/dist/services/hooks/hookTriggers.js.map

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

package/dist/services/hooks/hooksManager.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Hooks 管理器
+ *
+ * 负责 hooks.json 的加载、合并、校验、缓存与 matcher 匹配。
+ * 加载顺序：用户级(~/.sema/hooks/hooks.json) → 项目级(<workingDir>/.sema/hooks/hooks.json)，
+ * 同一事件的条目按加载顺序追加（不覆盖）。
+ */
+import { HooksInfo, LoadedHookEntry } from '../../types/hook';
+declare class HooksManager {
+    private userConfigPath;
+    private projectConfigPath;
+    private entriesByEvent;
+    private infoCache;
+    private loadingPromise;
+    private matcherCache;
+    constructor();
+    /**
+     * 发起一次加载（single-flight：并发调用共享同一个在飞 promise，避免重复文件 IO）
+     */
+    private startLoad;
+    /**
+     * 等待配置缓存就绪（就绪后近零开销）
+     */
+    ready(): Promise<void>;
+    /**
+     * 配置缓存是否已就绪（同步判断，供需要同步捕获条目的调用方使用）
+     */
+    isReady(): boolean;
+    /**
+     * 返回指定事件下 matcher 命中的可执行条目（仅 status === 'ok'）
+     * 工具类事件按通用工具名 / 内置名匹配；其他事件忽略 matcher 总是触发
+     */
+    getMatchedEntries(event: string, genericToolName?: string, semaToolName?: string): LoadedHookEntry[];
+    /**
+     * 获取合并后的配置视图
+     * @param refresh true 时重新加载配置，下一次 hook 触发即生效
+     */
+    getHooksInfo(refresh?: boolean): Promise<HooksInfo>;
+    private invalidateCache;
+    /**
+     * 加载并缓存配置。保证不抛错且总是落缓存：任何异常兜底为空配置，
+     * 避免缓存留 null 导致后续每次 hook 触发都重试文件 IO
+     */
+    private loadAndCache;
+    /**
+     * 解析单个 hooks.json 内容为条目列表（校验只标 status，不抛错）
+     */
+    private parseHooksFile;
+    private clampTimeoutMs;
+    /**
+     * matcher 编译（结果按 matcher 字符串缓存）：
+     * 1. 缺失/空串/'*' → 全匹配
+     * 2. 按 '|' 分段后每段均为简单名 → 精确集合匹配（通用工具名和内置名均可命中）
+     * 3. 否则整串按正则匹配通用工具名；编译失败 logWarn 一次且该条永不匹配
+     */
+    private compileMatcher;
+    dispose(): void;
+}
+/**
+ * 获取 Hooks Manager 实例（单例模式）
+ */
+export declare function getHooksManager(): HooksManager;
+export { HooksManager };
+//# sourceMappingURL=hooksManager.d.ts.map

package/dist/services/hooks/hooksManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooksManager.d.ts","sourceRoot":"","sources":["../../../src/services/hooks/hooksManager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,OAAO,EAIL,SAAS,EACT,eAAe,EAEhB,MAAM,kBAAkB,CAAA;AAazB,cAAM,YAAY;IAChB,OAAO,CAAC,cAAc,CAAQ;IAC9B,OAAO,CAAC,iBAAiB,CAAQ;IAEjC,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,cAAc,CAA6B;IACnD,OAAO,CAAC,YAAY,CAAsC;;IAU1D;;OAEG;IACH,OAAO,CAAC,SAAS;IASjB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;;OAGG;IACH,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,eAAe,EAAE;IAYpG;;;OAGG;IACG,YAAY,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC;IAYzD,OAAO,CAAC,eAAe;IAMvB;;;OAGG;YACW,YAAY;IAqF1B;;OAEG;IACH,OAAO,CAAC,cAAc;IA0DtB,OAAO,CAAC,cAAc;IAUtB;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IA+BtB,OAAO,IAAI,IAAI;CAGhB;AAMD;;GAEG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAK9C;AAED,OAAO,EAAE,YAAY,EAAE,CAAA"}