@skillfm/local 2.0.0 → 2.0.3

package/dist/guard/cli.js

@@ -0,0 +1,249 @@
+/**
+ * BSO M9-4 — skillfm-guard CLI 入口
+ *
+ * Refs: docs/prd/PRD-BSO-M9-HARNESS-HOOKS.md §3.4 + §3.5
+ *
+ * 子命令（由 harness 的 hook 机制触发）：
+ *   - session-start      → SessionStart（warn-only；启 sidecar 记录 session）
+ *   - pre-tool-use       → PreToolUse（阻断性；未 brain_run → exit 2）
+ *   - post-tool-use      → PostToolUse（warn-only；audit 用途）
+ *   - check-script-loaded → doctor / 旁路用，查询当前 sidecar 状态
+ *
+ * Claude Code hook payload 约定（Anthropic spec）：
+ *   - SessionStart: stdin JSON { session_id, source?, cwd? }
+ *   - PreToolUse:   stdin JSON { session_id, tool_name, tool_input? }
+ *   - PostToolUse:  stdin JSON { session_id, tool_name, tool_response? }
+ *
+ * Fail-open 原则：sidecar 不可达 / 超时 / 解析失败一律 exit 0 + stderr warn，
+ * 只有 sidecar 明确返回 412 才 exit 2。这样保证 hook 故障不会锁死用户 UX。
+ */
+import { callGuardCheck, callGuardPostToolUse, callGuardSessionStart, readSidecarEndpoint, } from './sidecar-client.js';
+// ============================================================================
+// stdin 读取（非阻塞，超时 300ms）
+// ============================================================================
+async function readStdinJson(timeoutMs = 300) {
+    if (process.stdin.isTTY)
+        return {};
+    return new Promise((resolve) => {
+        const chunks = [];
+        let done = false;
+        const timer = setTimeout(() => {
+            if (done)
+                return;
+            done = true;
+            resolve({});
+        }, timeoutMs);
+        process.stdin.on('data', (c) => chunks.push(c));
+        process.stdin.on('end', () => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            const raw = Buffer.concat(chunks).toString('utf-8').trim();
+            if (!raw)
+                return resolve({});
+            try {
+                const parsed = JSON.parse(raw);
+                if (parsed && typeof parsed === 'object')
+                    resolve(parsed);
+                else
+                    resolve({});
+            }
+            catch {
+                resolve({});
+            }
+        });
+        process.stdin.on('error', () => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            resolve({});
+        });
+    });
+}
+function parseArgs(argv) {
+    const [sub = '', ...rest] = argv;
+    const flags = {};
+    for (let i = 0; i < rest.length; i += 1) {
+        const token = rest[i];
+        if (token.startsWith('--')) {
+            const eq = token.indexOf('=');
+            if (eq > 0) {
+                flags[token.slice(2, eq)] = token.slice(eq + 1);
+            }
+            else {
+                const next = rest[i + 1];
+                if (next !== undefined && !next.startsWith('--')) {
+                    flags[token.slice(2)] = next;
+                    i += 1;
+                }
+                else {
+                    flags[token.slice(2)] = true;
+                }
+            }
+        }
+    }
+    return { subcommand: sub, flags };
+}
+// ============================================================================
+// 辅助：提取 session_id / tool / harness
+// ============================================================================
+function extractContext(stdinJson, flags) {
+    const session_id = (typeof flags.session === 'string' && flags.session) ||
+        (typeof stdinJson.session_id === 'string' && stdinJson.session_id) ||
+        process.env.SKILLFM_HOOK_SESSION_ID ||
+        'unknown-session';
+    const tool = (typeof flags.tool === 'string' && flags.tool) ||
+        (typeof stdinJson.tool_name === 'string' && stdinJson.tool_name) ||
+        undefined;
+    const harness = (typeof flags.harness === 'string' && flags.harness) ||
+        process.env.SKILLFM_HARNESS ||
+        undefined;
+    return { session_id, tool, harness };
+}
+function warnToStderr(msg) {
+    process.stderr.write(`⚠️  [skillfm-guard] ${msg}\n`);
+}
+function infoToStderr(msg) {
+    // 刻意用 stderr：Claude Code / Aider 等 hook 只把 stderr 展示给用户
+    process.stderr.write(`[skillfm-guard] ${msg}\n`);
+}
+// ============================================================================
+// 子命令：session-start
+// ============================================================================
+async function cmdSessionStart(stdin, flags) {
+    const endpoint = readSidecarEndpoint();
+    const { session_id, harness } = extractContext(stdin, flags);
+    if (!endpoint) {
+        warnToStderr('sidecar 未运行，无法注册 session（hook 层不阻断）');
+        return 0;
+    }
+    try {
+        await callGuardSessionStart(endpoint, {
+            session_id,
+            harness,
+            cwd: process.cwd(),
+        });
+    }
+    catch (err) {
+        warnToStderr(`session-start 调 sidecar 失败: ${err.message}`);
+    }
+    return 0;
+}
+// ============================================================================
+// 子命令：pre-tool-use（阻断性）
+// ============================================================================
+async function cmdPreToolUse(stdin, flags) {
+    const endpoint = readSidecarEndpoint();
+    const { session_id, tool, harness } = extractContext(stdin, flags);
+    if (!endpoint) {
+        warnToStderr('sidecar 未运行（fail-open，hook 放行）');
+        return 0;
+    }
+    try {
+        const r = await callGuardCheck(endpoint, { session_id, tool, harness });
+        if (r.status === 200)
+            return 0;
+        if (r.status === 412) {
+            const body = r.body;
+            const hint = body?.hint ||
+                '请先调用 SkillFM 的 brain_run（或 list_skills 浏览），让 SkillFM 记录本次编排意图再执行破坏性操作。';
+            process.stderr.write(`⛔ [skillfm-guard] BLOCKED — ${tool || 'destructive tool'}\n` +
+                `   reason: ${body?.reason || 'script not loaded'}\n` +
+                `   ${hint}\n`);
+            return 2;
+        }
+        // 其他状态码（5xx / 404 等）fail-open
+        warnToStderr(`sidecar 返回异常状态 ${r.status}，fail-open 放行`);
+        return 0;
+    }
+    catch (err) {
+        warnToStderr(`pre-tool-use 调 sidecar 失败: ${err.message}（fail-open 放行）`);
+        return 0;
+    }
+}
+// ============================================================================
+// 子命令：post-tool-use（warn-only）
+// ============================================================================
+async function cmdPostToolUse(stdin, flags) {
+    const endpoint = readSidecarEndpoint();
+    const { session_id, tool, harness } = extractContext(stdin, flags);
+    if (!endpoint)
+        return 0;
+    try {
+        await callGuardPostToolUse(endpoint, { session_id, tool, harness, outcome: 'ok' });
+    }
+    catch {
+        // post-tool-use 失败 silent
+    }
+    return 0;
+}
+// ============================================================================
+// 子命令：check-script-loaded
+// ============================================================================
+async function cmdCheckScriptLoaded(stdin, flags) {
+    const endpoint = readSidecarEndpoint();
+    const { session_id } = extractContext(stdin, flags);
+    if (!endpoint) {
+        process.stdout.write(JSON.stringify({ ok: false, reason: 'sidecar not running' }) + '\n');
+        return 0;
+    }
+    try {
+        const r = await callGuardCheck(endpoint, { session_id });
+        process.stdout.write(JSON.stringify({ status: r.status, body: r.body }) + '\n');
+        return 0;
+    }
+    catch (err) {
+        process.stdout.write(JSON.stringify({ ok: false, reason: err.message }) + '\n');
+        return 0;
+    }
+}
+// ============================================================================
+// 主入口
+// ============================================================================
+export async function runGuardCli(argv) {
+    const { subcommand, flags } = parseArgs(argv);
+    if (subcommand === '--help' || subcommand === '-h' || subcommand === 'help' || subcommand === '') {
+        process.stdout.write([
+            'Usage: skillfm-guard <subcommand> [flags]',
+            '',
+            'Subcommands:',
+            '  session-start         Hook: harness session start (warn-only)',
+            '  pre-tool-use          Hook: pre-tool-use (blocking — exit 2 if brain_run not called)',
+            '  post-tool-use         Hook: post-tool-use (warn-only, audit)',
+            '  check-script-loaded   Diagnostic: print current guard state as JSON',
+            '',
+            'Flags:',
+            '  --session=<id>        Session identifier (else read stdin JSON or $SKILLFM_HOOK_SESSION_ID)',
+            '  --tool=<name>         Tool name (else read stdin tool_name)',
+            '  --harness=<name>      Harness hint (else $SKILLFM_HARNESS)',
+            '',
+            'Fail-open: sidecar unreachable / timeout → exit 0 + stderr warn. Only sidecar 412 blocks.',
+        ].join('\n') + '\n');
+        return 0;
+    }
+    const stdin = await readStdinJson();
+    switch (subcommand) {
+        case 'session-start':
+            return cmdSessionStart(stdin, flags);
+        case 'pre-tool-use':
+            return cmdPreToolUse(stdin, flags);
+        case 'post-tool-use':
+            return cmdPostToolUse(stdin, flags);
+        case 'check-script-loaded':
+            return cmdCheckScriptLoaded(stdin, flags);
+        default:
+            warnToStderr(`unknown subcommand "${subcommand}" (fail-open)`);
+            infoToStderr('run `skillfm-guard --help` for usage');
+            return 0;
+    }
+}
+// 允许直接 node ./dist/guard/cli.js 运行
+if (import.meta.url === `file://${process.argv[1]}`) {
+    runGuardCli(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+        process.stderr.write(`[skillfm-guard] fatal: ${err?.message || err}\n`);
+        process.exit(0); // fail-open
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/guard/cli.js.map

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

package/dist/guard/sidecar-client.d.ts

@@ -0,0 +1,46 @@
+/**
+ * BSO M9-4 — skillfm-guard → sidecar HTTP client
+ *
+ * Refs: docs/prd/PRD-BSO-M9-HARNESS-HOOKS.md §3.5
+ *
+ * hook 进程生命短（几十毫秒），对 sidecar 有严格的"秒级响应 + fail-open"要求：
+ *   - 超时 (default 500ms) → 降级放行（exit 0）+ stderr warn
+ *   - 网络错误 / sidecar 不在 → 降级放行
+ *   - 仅在 sidecar 明确返回 412 时才阻断（exit 2）
+ */
+export interface SidecarEndpoint {
+    url: string;
+    port: number;
+}
+export declare function readSidecarEndpoint(): SidecarEndpoint | null;
+export interface GuardCheckInput {
+    session_id: string;
+    tool?: string;
+    harness?: string;
+}
+export interface GuardCheckResponse {
+    status: number;
+    body: unknown;
+}
+/**
+ * GET /internal/guard/check — fail-open on any error
+ */
+export declare function callGuardCheck(endpoint: SidecarEndpoint, input: GuardCheckInput, timeoutMs?: number): Promise<GuardCheckResponse>;
+/**
+ * POST /internal/guard/session-start
+ */
+export declare function callGuardSessionStart(endpoint: SidecarEndpoint, payload: {
+    session_id: string;
+    harness?: string;
+    cwd?: string;
+}, timeoutMs?: number): Promise<GuardCheckResponse>;
+/**
+ * POST /internal/guard/post-tool-use
+ */
+export declare function callGuardPostToolUse(endpoint: SidecarEndpoint, payload: {
+    session_id: string;
+    tool?: string;
+    harness?: string;
+    outcome?: 'ok' | 'error';
+}, timeoutMs?: number): Promise<GuardCheckResponse>;
+//# sourceMappingURL=sidecar-client.d.ts.map

package/dist/guard/sidecar-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar-client.d.ts","sourceRoot":"","sources":["../../src/guard/sidecar-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,mBAAmB,IAAI,eAAe,GAAG,IAAI,CAY5D;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,eAAe,EACzB,KAAK,EAAE,eAAe,EACtB,SAAS,SAAqB,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CAgB7B;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,EAC/D,SAAS,SAAqB,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CAe7B;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE;IACP,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC;CAC1B,EACD,SAAS,SAAqB,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CAe7B"}

package/dist/guard/sidecar-client.js

@@ -0,0 +1,92 @@
+/**
+ * BSO M9-4 — skillfm-guard → sidecar HTTP client
+ *
+ * Refs: docs/prd/PRD-BSO-M9-HARNESS-HOOKS.md §3.5
+ *
+ * hook 进程生命短（几十毫秒），对 sidecar 有严格的"秒级响应 + fail-open"要求：
+ *   - 超时 (default 500ms) → 降级放行（exit 0）+ stderr warn
+ *   - 网络错误 / sidecar 不在 → 降级放行
+ *   - 仅在 sidecar 明确返回 412 时才阻断（exit 2）
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const LOCAL_SETTINGS_FILE = join(homedir(), '.skillfm', 'local.json');
+const DEFAULT_TIMEOUT_MS = 500;
+export function readSidecarEndpoint() {
+    try {
+        if (!existsSync(LOCAL_SETTINGS_FILE))
+            return null;
+        const raw = JSON.parse(readFileSync(LOCAL_SETTINGS_FILE, 'utf-8'));
+        if (!raw.url)
+            return null;
+        const parsed = new URL(raw.url);
+        return { url: raw.url.replace(/\/$/, ''), port: Number(parsed.port) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * GET /internal/guard/check — fail-open on any error
+ */
+export async function callGuardCheck(endpoint, input, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const params = new URLSearchParams();
+    params.set('session_id', input.session_id);
+    if (input.tool)
+        params.set('tool', input.tool);
+    if (input.harness)
+        params.set('harness', input.harness);
+    const url = `${endpoint.url}/internal/guard/check?${params.toString()}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, { method: 'GET', signal: controller.signal });
+        const body = await res.json().catch(() => ({}));
+        return { status: res.status, body };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * POST /internal/guard/session-start
+ */
+export async function callGuardSessionStart(endpoint, payload, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(`${endpoint.url}/internal/guard/session-start`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(payload),
+            signal: controller.signal,
+        });
+        const body = await res.json().catch(() => ({}));
+        return { status: res.status, body };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * POST /internal/guard/post-tool-use
+ */
+export async function callGuardPostToolUse(endpoint, payload, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(`${endpoint.url}/internal/guard/post-tool-use`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(payload),
+            signal: controller.signal,
+        });
+        const body = await res.json().catch(() => ({}));
+        return { status: res.status, body };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=sidecar-client.js.map

package/dist/guard/sidecar-client.js.map

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

package/dist/guard/state.d.ts

@@ -0,0 +1,80 @@
+/**
+ * BSO M9-4 — guard session 状态（in-memory，sidecar 内驻）
+ *
+ * Refs: docs/prd/PRD-BSO-M9-HARNESS-HOOKS.md §3.4
+ *
+ * 跟踪每个 harness session 的 brain_run 调用状态：
+ *   - harness SessionStart hook 调 POST /internal/guard/session-start → 登记 session
+ *   - agent 走 /brain/run → 触发 markSessionBrainRun(session_id? 或 fallback global last-at)
+ *   - harness PreToolUse hook 调 GET /internal/guard/check → 判定是否 "recent brain_run"
+ *
+ * MVP 限制（协议层冻结：不能给 /brain/run 加 session_id 参数）：
+ *   - /brain/run 并不知道当前 harness session_id（agent 不传）
+ *   - 所以 markSessionBrainRun 只打 global `lastBrainRunAt`
+ *   - check 逻辑：如果 session 存在且 (last_brain_run_at within windowMs) → 放行
+ *
+ * 后续迭代（M9.5+）可以加 per-session 精确追踪（当 MCP 协议允许带 session_id 时）。
+ */
+export interface GuardSession {
+    session_id: string;
+    harness?: string;
+    cwd?: string;
+    started_at: number;
+    /** 本 session 期间是否有过 brain_run（false 时 check 看 global fallback） */
+    brain_run_called_locally: boolean;
+    last_tool_check_at?: number;
+    last_pre_tool_blocked_at?: number;
+    pre_tool_blocked_count: number;
+}
+export interface GuardStateSnapshot {
+    sessions: GuardSession[];
+    last_brain_run_at: number | null;
+    last_brain_run_skill_id: string | null;
+    brain_run_window_ms: number;
+}
+export declare class GuardState {
+    private readonly now;
+    private readonly windowMs;
+    private sessions;
+    private lastBrainRunAt;
+    private lastBrainRunSkillId;
+    constructor(now?: () => number, windowMs?: number);
+    startSession(opts: {
+        session_id: string;
+        harness?: string;
+        cwd?: string;
+    }): GuardSession;
+    /** /brain/run 调用后调。因协议层没带 session_id，这里只更新 global；若 caller 知道 sid 可传入 */
+    markBrainRun(skill_id: string | null, session_id?: string): void;
+    /**
+     * PreToolUse 的核心决策。
+     *
+     * 放行条件（任一命中即可）：
+     *   A) session 存在，且该 session 本地记录过 brain_run
+     *   B) 没 session 级记录，但 global lastBrainRunAt 在 windowMs 内
+     *   C) session 存在且 harness 在 fail-open 白名单（目前无）
+     *
+     * 拦截：session 不存在 → 放行（hook 层可能在 SessionStart 之前触发）
+     *       session 存在但两个条件都不满足 → 拦截
+     */
+    checkPreToolUse(opts: {
+        session_id: string;
+        tool?: string;
+    }): {
+        allow: boolean;
+        reason: string;
+        hint?: string;
+    };
+    /** PostToolUse：纯 audit，不阻断 */
+    recordPostToolUse(opts: {
+        session_id: string;
+        tool?: string;
+        outcome?: 'ok' | 'error';
+    }): void;
+    snapshot(): GuardStateSnapshot;
+    /** 测试/诊断用：清空状态 */
+    reset(): void;
+}
+/** 单例（sidecar 进程内共享） */
+export declare const guardState: GuardState;
+//# sourceMappingURL=state.d.ts.map

package/dist/guard/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/guard/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,wBAAwB,EAAE,OAAO,CAAC;IAClC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,qBAAa,UAAU;IAMnB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAN3B,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,mBAAmB,CAAuB;gBAG/B,GAAG,GAAE,MAAM,MAAyB,EACpC,QAAQ,GAAE,MAAoC;IAGjE,YAAY,CAAC,IAAI,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,YAAY;IAaxF,yEAAyE;IACzE,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;IAShE;;;;;;;;;;OAUG;IACH,eAAe,CAAC,IAAI,EAAE;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,GAAG;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;IAuCrD,8BAA8B;IAC9B,iBAAiB,CAAC,IAAI,EAAE;QACtB,UAAU,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC;KAC1B,GAAG,IAAI;IAMR,QAAQ,IAAI,kBAAkB;IAS9B,kBAAkB;IAClB,KAAK,IAAI,IAAI;CAKd;AAED,wBAAwB;AACxB,eAAO,MAAM,UAAU,YAAmB,CAAC"}

package/dist/guard/state.js

@@ -0,0 +1,119 @@
+/**
+ * BSO M9-4 — guard session 状态（in-memory，sidecar 内驻）
+ *
+ * Refs: docs/prd/PRD-BSO-M9-HARNESS-HOOKS.md §3.4
+ *
+ * 跟踪每个 harness session 的 brain_run 调用状态：
+ *   - harness SessionStart hook 调 POST /internal/guard/session-start → 登记 session
+ *   - agent 走 /brain/run → 触发 markSessionBrainRun(session_id? 或 fallback global last-at)
+ *   - harness PreToolUse hook 调 GET /internal/guard/check → 判定是否 "recent brain_run"
+ *
+ * MVP 限制（协议层冻结：不能给 /brain/run 加 session_id 参数）：
+ *   - /brain/run 并不知道当前 harness session_id（agent 不传）
+ *   - 所以 markSessionBrainRun 只打 global `lastBrainRunAt`
+ *   - check 逻辑：如果 session 存在且 (last_brain_run_at within windowMs) → 放行
+ *
+ * 后续迭代（M9.5+）可以加 per-session 精确追踪（当 MCP 协议允许带 session_id 时）。
+ */
+const DEFAULT_BRAIN_RUN_WINDOW_MS = 5 * 60 * 1000; // 5 分钟
+export class GuardState {
+    now;
+    windowMs;
+    sessions = new Map();
+    lastBrainRunAt = null;
+    lastBrainRunSkillId = null;
+    constructor(now = () => Date.now(), windowMs = DEFAULT_BRAIN_RUN_WINDOW_MS) {
+        this.now = now;
+        this.windowMs = windowMs;
+    }
+    startSession(opts) {
+        const sess = {
+            session_id: opts.session_id,
+            harness: opts.harness,
+            cwd: opts.cwd,
+            started_at: this.now(),
+            brain_run_called_locally: false,
+            pre_tool_blocked_count: 0,
+        };
+        this.sessions.set(opts.session_id, sess);
+        return sess;
+    }
+    /** /brain/run 调用后调。因协议层没带 session_id，这里只更新 global；若 caller 知道 sid 可传入 */
+    markBrainRun(skill_id, session_id) {
+        this.lastBrainRunAt = this.now();
+        this.lastBrainRunSkillId = skill_id;
+        if (session_id) {
+            const s = this.sessions.get(session_id);
+            if (s)
+                s.brain_run_called_locally = true;
+        }
+    }
+    /**
+     * PreToolUse 的核心决策。
+     *
+     * 放行条件（任一命中即可）：
+     *   A) session 存在，且该 session 本地记录过 brain_run
+     *   B) 没 session 级记录，但 global lastBrainRunAt 在 windowMs 内
+     *   C) session 存在且 harness 在 fail-open 白名单（目前无）
+     *
+     * 拦截：session 不存在 → 放行（hook 层可能在 SessionStart 之前触发）
+     *       session 存在但两个条件都不满足 → 拦截
+     */
+    checkPreToolUse(opts) {
+        const sess = this.sessions.get(opts.session_id);
+        if (sess)
+            sess.last_tool_check_at = this.now();
+        if (sess?.brain_run_called_locally) {
+            return { allow: true, reason: 'session-local brain_run recorded' };
+        }
+        if (this.lastBrainRunAt !== null) {
+            const age = this.now() - this.lastBrainRunAt;
+            if (age <= this.windowMs) {
+                return {
+                    allow: true,
+                    reason: `global brain_run within ${Math.round(age / 1000)}s (window ${Math.round(this.windowMs / 1000)}s)`,
+                };
+            }
+        }
+        // 未登记 session 且没 recent global brain_run → 保守拦截
+        if (!sess) {
+            // Session 未登记（SessionStart hook 可能被跳过）：fail-open 放行 + 登记
+            this.startSession({ session_id: opts.session_id });
+            return {
+                allow: true,
+                reason: 'session not previously registered; allowed + registered',
+            };
+        }
+        sess.pre_tool_blocked_count += 1;
+        sess.last_pre_tool_blocked_at = this.now();
+        return {
+            allow: false,
+            reason: 'no brain_run recorded for this session (locally or globally within 5min window)',
+            hint: '请先调用 SkillFM 的 brain_run（或至少一次 list_skills）让 SkillFM 记录本次编排意图，然后再执行破坏性操作。sidecar 的 9 安全红线仍在兜底。',
+        };
+    }
+    /** PostToolUse：纯 audit，不阻断 */
+    recordPostToolUse(opts) {
+        const s = this.sessions.get(opts.session_id);
+        if (s)
+            s.last_tool_check_at = this.now();
+        // audit log 目前落 stderr 即可，未来可接 M8 审计 endpoint
+    }
+    snapshot() {
+        return {
+            sessions: Array.from(this.sessions.values()),
+            last_brain_run_at: this.lastBrainRunAt,
+            last_brain_run_skill_id: this.lastBrainRunSkillId,
+            brain_run_window_ms: this.windowMs,
+        };
+    }
+    /** 测试/诊断用：清空状态 */
+    reset() {
+        this.sessions.clear();
+        this.lastBrainRunAt = null;
+        this.lastBrainRunSkillId = null;
+    }
+}
+/** 单例（sidecar 进程内共享） */
+export const guardState = new GuardState();
+//# sourceMappingURL=state.js.map

package/dist/guard/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/guard/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,2BAA2B,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,OAAO;AAqB1D,MAAM,OAAO,UAAU;IAMF;IACA;IANX,QAAQ,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC3C,cAAc,GAAkB,IAAI,CAAC;IACrC,mBAAmB,GAAkB,IAAI,CAAC;IAElD,YACmB,MAAoB,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,EACpC,WAAmB,2BAA2B;QAD9C,QAAG,GAAH,GAAG,CAAiC;QACpC,aAAQ,GAAR,QAAQ,CAAsC;IAC9D,CAAC;IAEJ,YAAY,CAAC,IAA4D;QACvE,MAAM,IAAI,GAAiB;YACzB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE;YACtB,wBAAwB,EAAE,KAAK;YAC/B,sBAAsB,EAAE,CAAC;SAC1B,CAAC;QACF,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,yEAAyE;IACzE,YAAY,CAAC,QAAuB,EAAE,UAAmB;QACvD,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACjC,IAAI,CAAC,mBAAmB,GAAG,QAAQ,CAAC;QACpC,IAAI,UAAU,EAAE,CAAC;YACf,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YACxC,IAAI,CAAC;gBAAE,CAAC,CAAC,wBAAwB,GAAG,IAAI,CAAC;QAC3C,CAAC;IACH,CAAC;IAED;;;;;;;;;;OAUG;IACH,eAAe,CAAC,IAGf;QACC,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAChD,IAAI,IAAI;YAAE,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE/C,IAAI,IAAI,EAAE,wBAAwB,EAAE,CAAC;YACnC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,kCAAkC,EAAE,CAAC;QACrE,CAAC;QAED,IAAI,IAAI,CAAC,cAAc,KAAK,IAAI,EAAE,CAAC;YACjC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,cAAc,CAAC;YAC7C,IAAI,GAAG,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACzB,OAAO;oBACL,KAAK,EAAE,IAAI;oBACX,MAAM,EAAE,2BAA2B,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,aAAa,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,IAAI;iBAC3G,CAAC;YACJ,CAAC;QACH,CAAC;QAED,gDAAgD;QAChD,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,yDAAyD;YACzD,IAAI,CAAC,YAAY,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;YACnD,OAAO;gBACL,KAAK,EAAE,IAAI;gBACX,MAAM,EAAE,yDAAyD;aAClE,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,sBAAsB,IAAI,CAAC,CAAC;QACjC,IAAI,CAAC,wBAAwB,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC3C,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,MAAM,EACJ,iFAAiF;YACnF,IAAI,EACF,gGAAgG;SACnG,CAAC;IACJ,CAAC;IAED,8BAA8B;IAC9B,iBAAiB,CAAC,IAIjB;QACC,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC7C,IAAI,CAAC;YAAE,CAAC,CAAC,kBAAkB,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzC,8CAA8C;IAChD,CAAC;IAED,QAAQ;QACN,OAAO;YACL,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;YAC5C,iBAAiB,EAAE,IAAI,CAAC,cAAc;YACtC,uBAAuB,EAAE,IAAI,CAAC,mBAAmB;YACjD,mBAAmB,EAAE,IAAI,CAAC,QAAQ;SACnC,CAAC;IACJ,CAAC;IAED,kBAAkB;IAClB,KAAK;QACH,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAClC,CAAC;CACF;AAED,wBAAwB;AACxB,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,UAAU,EAAE,CAAC"}