@armadra/agent 0.0.0-stage → 0.2.1

package/dist/hooks/matcher.js

@@ -0,0 +1,108 @@
+/**
+ * Hook matcher（设计 §6.1「matcher」）。[B5]
+ *
+ * 语法：缺省 / 空串 / `*` 匹配全部；`bash` 精确；`write|edit` 多选；`canvas_*` glob；
+ * `bash(git push*)` 先匹配工具名，再对参数文本做 glob；`/regex/flags` 对工具名做正则。
+ * 括号内的文本：bash → `input.command`；文件类工具 → `input.path`（或 `file_path`）；
+ * 其它工具 → 输入 JSON 文本。`|` 只在括号外分隔候选。只在 Pre/PostToolUse 生效。
+ */
+/** glob → 正则：`*` 任意字符串（含 `/`），`?` 单个字符，其余字面量。 */
+export function globToRegExp(glob) {
+    let source = "";
+    for (const ch of glob) {
+        if (ch === "*")
+            source += ".*";
+        else if (ch === "?")
+            source += ".";
+        else
+            source += ch.replace(/[\\^$.+()|[\]{}]/g, "\\$&");
+    }
+    return new RegExp(`^${source}$`, "s");
+}
+/** 括号外的 `|` 切分。 */
+export function splitAlternatives(matcher) {
+    const parts = [];
+    let depth = 0;
+    let current = "";
+    for (const ch of matcher) {
+        if (ch === "(")
+            depth++;
+        else if (ch === ")")
+            depth = Math.max(0, depth - 1);
+        if (ch === "|" && depth === 0) {
+            parts.push(current);
+            current = "";
+        }
+        else {
+            current += ch;
+        }
+    }
+    parts.push(current);
+    return parts.map((p) => p.trim()).filter((p) => p !== "");
+}
+/** 括号内 glob 匹配的参数文本。 */
+export function argumentText(toolName, input) {
+    if (typeof input === "object" && input !== null) {
+        const record = input;
+        if (toolName === "bash" && typeof record["command"] === "string")
+            return record["command"];
+        for (const key of ["path", "file_path", "pattern"]) {
+            const value = record[key];
+            if (typeof value === "string")
+                return value;
+        }
+    }
+    if (typeof input === "string")
+        return input;
+    try {
+        return JSON.stringify(input) ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+const REGEX_FORM = /^\/(.+)\/([a-z]*)$/s;
+const CALL_FORM = /^([^()]+)\((.*)\)$/s;
+function compileAlternative(alt, nameOnly = false) {
+    const regex = REGEX_FORM.exec(alt);
+    if (regex !== null) {
+        const re = new RegExp(regex[1] ?? "", (regex[2] ?? "").replace(/[gy]/g, ""));
+        return (toolName) => re.test(toolName);
+    }
+    const call = CALL_FORM.exec(alt);
+    if (call !== null) {
+        const name = globToRegExp((call[1] ?? "").trim());
+        const arg = globToRegExp((call[2] ?? "").trim());
+        if (nameOnly)
+            return (toolName) => name.test(toolName);
+        return (toolName, input) => name.test(toolName) && arg.test(argumentText(toolName, input));
+    }
+    const name = globToRegExp(alt);
+    return (toolName) => name.test(toolName);
+}
+/**
+ * 编译 matcher；语法错误（非法正则）抛 Error。
+ * `nameOnly`：忽略括号参数，只看工具名（输入未知时判断「可能匹配」）。
+ */
+export function compileMatcher(matcher, nameOnly = false) {
+    if (matcher === undefined)
+        return () => true;
+    const trimmed = matcher.trim();
+    if (trimmed === "" || trimmed === "*")
+        return () => true;
+    // 整串是正则时不按 `|` 切分（正则里的 `|` 是正则自己的）。
+    if (REGEX_FORM.test(trimmed))
+        return compileAlternative(trimmed);
+    const alternatives = splitAlternatives(trimmed).map((alt) => compileAlternative(alt, nameOnly));
+    return (toolName, input) => alternatives.some((m) => m(toolName, input));
+}
+/** 校验 matcher 语法；返回错误信息或 undefined。 */
+export function checkMatcher(matcher) {
+    try {
+        compileMatcher(matcher);
+        return undefined;
+    }
+    catch (error) {
+        return error.message;
+    }
+}

package/dist/hooks/protocol.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Hook 输入 / 输出的构造、校验与决策合并（设计 §6.1）。[B5]
+ *
+ * 退出码语义：0 放行并解析 stdout；2 阻止（stderr 作为 reason）；其它非零 = Hook 自身错误，
+ * 非阻塞、记 warning、按「无决策」继续；超时同非阻塞错误，但 PreToolUse 超时按 deny。
+ * 合并：决策最严 `deny > block > ask > allow`；`updatedInput` / `updatedPrompt` 只接受唯一
+ * 一个返回者（多个则全部忽略并 warning）；`additionalContext` / `customInstructions` 按配置顺序拼接。
+ */
+import type { HookDecision, HookEvent, HookInput, HookOutcome, HookOutput, HookRunResult } from "./types.js";
+export declare const DECISION_SEVERITY: Readonly<Record<HookDecision, number>>;
+/** 退出码 2 映射的阻止决策；undefined = 该事件忽略退出码 2。 */
+export declare function blockingDecision(event: HookEvent): HookDecision | undefined;
+export interface ParsedOutput {
+    output?: HookOutput;
+    warnings: string[];
+}
+/** 解析 stdout：空 / 非 JSON / 非对象 → 无输出；字段类型不对的丢弃并 warning。 */
+export declare function parseHookOutput(stdout: string): ParsedOutput;
+/** 单条结果的有效决策与 reason（已按事件与退出码解释）。 */
+export interface Interpreted {
+    decision?: HookDecision;
+    reason?: string;
+    warning?: string;
+    /** 是否采用 stdout 的其它字段（只有退出码 0）。 */
+    useOutput: boolean;
+}
+export declare function interpretResult(result: HookRunResult): Interpreted;
+/** 合并同一事件下全部结果（`results` 已按配置顺序排列）。 */
+export declare function mergeResults(results: readonly HookRunResult[], extraWarnings?: readonly string[]): HookOutcome;
+/** 无任何 Hook 时的空结论。 */
+export declare function emptyOutcome(): HookOutcome;
+/** 给 shell 脚本的环境变量（§6.1）。 */
+export declare function hookEnv(input: HookInput): Record<string, string>;

package/dist/hooks/protocol.js

@@ -0,0 +1,240 @@
+/**
+ * Hook 输入 / 输出的构造、校验与决策合并（设计 §6.1）。[B5]
+ *
+ * 退出码语义：0 放行并解析 stdout；2 阻止（stderr 作为 reason）；其它非零 = Hook 自身错误，
+ * 非阻塞、记 warning、按「无决策」继续；超时同非阻塞错误，但 PreToolUse 超时按 deny。
+ * 合并：决策最严 `deny > block > ask > allow`；`updatedInput` / `updatedPrompt` 只接受唯一
+ * 一个返回者（多个则全部忽略并 warning）；`additionalContext` / `customInstructions` 按配置顺序拼接。
+ */
+export const DECISION_SEVERITY = {
+    deny: 4,
+    block: 3,
+    ask: 2,
+    allow: 1,
+};
+/** 各事件接受的决策（其它决策忽略并 warning；deny / block 在两类事件间互换）。 */
+const ACCEPTED = {
+    PreToolUse: ["allow", "deny", "ask"],
+    PostToolUse: ["block"],
+    UserPromptSubmit: ["block"],
+    Stop: ["block"],
+    SubagentStop: ["block"],
+    PreCompact: ["block"],
+    SessionStart: ["block"],
+    Notification: [],
+    SessionEnd: [],
+};
+/** 退出码 2 映射的阻止决策；undefined = 该事件忽略退出码 2。 */
+export function blockingDecision(event) {
+    if (event === "PreToolUse")
+        return "deny";
+    if (event === "Notification" || event === "SessionEnd")
+        return undefined;
+    return "block";
+}
+/** 解析 stdout：空 / 非 JSON / 非对象 → 无输出；字段类型不对的丢弃并 warning。 */
+export function parseHookOutput(stdout) {
+    const text = stdout.trim();
+    if (text === "" || (text[0] !== "{" && text[0] !== "["))
+        return { warnings: [] };
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return { warnings: [] };
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return { warnings: [] };
+    const raw = value;
+    const output = {};
+    const warnings = [];
+    const decision = raw["decision"];
+    if (decision !== undefined) {
+        if (decision === "allow" || decision === "deny" || decision === "ask" || decision === "block") {
+            output.decision = decision;
+        }
+        else {
+            warnings.push(`未知 decision：${JSON.stringify(decision)}`);
+        }
+    }
+    for (const key of [
+        "reason",
+        "updatedPrompt",
+        "additionalContext",
+        "customInstructions",
+    ]) {
+        const v = raw[key];
+        if (v === undefined)
+            continue;
+        if (typeof v === "string")
+            output[key] = v;
+        else
+            warnings.push(`${key} 应为字符串`);
+    }
+    if ("updatedInput" in raw)
+        output.updatedInput = raw["updatedInput"];
+    if (raw["continue"] === false)
+        output.continue = false;
+    if (raw["suppressOutput"] === true)
+        output.suppressOutput = true;
+    return { output, warnings };
+}
+function describe(result) {
+    return `Hook ${result.event}「${result.command}」`;
+}
+function normalizeDecision(event, decision) {
+    const accepted = ACCEPTED[event];
+    if (accepted.includes(decision))
+        return decision;
+    if (decision === "deny" && accepted.includes("block"))
+        return "block";
+    if (decision === "block" && accepted.includes("deny"))
+        return "deny";
+    return undefined;
+}
+export function interpretResult(result) {
+    const event = result.event;
+    if (result.timedOut) {
+        const message = `${describe(result)} 超时（${result.durationMs} ms）`;
+        if (event === "PreToolUse")
+            return { decision: "deny", reason: message, warning: message, useOutput: false };
+        return { warning: message, useOutput: false };
+    }
+    if (result.exitCode === 2) {
+        const decision = blockingDecision(event);
+        const reason = result.stderr.trim() || `${describe(result)} 以退出码 2 阻止`;
+        if (decision === undefined)
+            return { useOutput: false };
+        return { decision, reason, useOutput: false };
+    }
+    if (result.exitCode !== 0) {
+        const tail = result.stderr.trim().split("\n").slice(-3).join(" | ");
+        const code = result.exitCode === null ? "被信号终止" : `退出码 ${result.exitCode}`;
+        return {
+            warning: `${describe(result)} 失败（${code}）${tail === "" ? "" : `：${tail}`}`,
+            useOutput: false,
+        };
+    }
+    const output = result.output;
+    if (output?.decision === undefined)
+        return { useOutput: true };
+    const decision = normalizeDecision(event, output.decision);
+    if (decision === undefined) {
+        return {
+            useOutput: true,
+            warning: `${describe(result)} 的 decision "${output.decision}" 对 ${event} 无效，已忽略`,
+        };
+    }
+    const interpreted = { decision, useOutput: true };
+    if (output.reason !== undefined)
+        interpreted.reason = output.reason;
+    return interpreted;
+}
+function joinTexts(values) {
+    const parts = values.map((v) => v.trim()).filter((v) => v !== "");
+    return parts.length > 0 ? parts.join("\n\n") : undefined;
+}
+/** 合并同一事件下全部结果（`results` 已按配置顺序排列）。 */
+export function mergeResults(results, extraWarnings = []) {
+    const warnings = [...extraWarnings];
+    let decision;
+    let reason;
+    const inputs = [];
+    const prompts = [];
+    const contexts = [];
+    const instructions = [];
+    let stop = false;
+    let suppressOutput = false;
+    for (const result of results) {
+        const interpreted = interpretResult(result);
+        if (interpreted.warning !== undefined)
+            warnings.push(interpreted.warning);
+        if (interpreted.decision !== undefined) {
+            if (decision === undefined ||
+                DECISION_SEVERITY[interpreted.decision] > DECISION_SEVERITY[decision]) {
+                decision = interpreted.decision;
+                reason = interpreted.reason;
+            }
+            else if (interpreted.decision === decision && reason === undefined) {
+                reason = interpreted.reason;
+            }
+        }
+        if (!interpreted.useOutput || result.output === undefined)
+            continue;
+        const output = result.output;
+        if ("updatedInput" in output)
+            inputs.push(output.updatedInput);
+        if (output.updatedPrompt !== undefined)
+            prompts.push(output.updatedPrompt);
+        if (output.additionalContext !== undefined)
+            contexts.push(output.additionalContext);
+        if (output.customInstructions !== undefined)
+            instructions.push(output.customInstructions);
+        if (output.continue === false) {
+            stop = true;
+            if (reason === undefined && output.reason !== undefined)
+                reason = output.reason;
+        }
+        if (output.suppressOutput === true)
+            suppressOutput = true;
+    }
+    const outcome = {
+        hasUpdatedInput: false,
+        stop,
+        suppressOutput,
+        results: [...results],
+        warnings,
+    };
+    if (decision !== undefined)
+        outcome.decision = decision;
+    if (reason !== undefined)
+        outcome.reason = reason;
+    if (inputs.length === 1) {
+        outcome.updatedInput = inputs[0];
+        outcome.hasUpdatedInput = true;
+    }
+    else if (inputs.length > 1) {
+        warnings.push(`${inputs.length} 个 Hook 同时返回 updatedInput，全部忽略`);
+    }
+    if (prompts.length === 1 && prompts[0] !== undefined)
+        outcome.updatedPrompt = prompts[0];
+    else if (prompts.length > 1)
+        warnings.push(`${prompts.length} 个 Hook 同时返回 updatedPrompt，全部忽略`);
+    const additionalContext = joinTexts(contexts);
+    if (additionalContext !== undefined)
+        outcome.additionalContext = additionalContext;
+    const customInstructions = joinTexts(instructions);
+    if (customInstructions !== undefined)
+        outcome.customInstructions = customInstructions;
+    return outcome;
+}
+/** 无任何 Hook 时的空结论。 */
+export function emptyOutcome() {
+    return { hasUpdatedInput: false, stop: false, suppressOutput: false, results: [], warnings: [] };
+}
+/** 给 shell 脚本的环境变量（§6.1）。 */
+export function hookEnv(input) {
+    const env = {
+        AMA_HOOK_EVENT: input.hookEventName,
+        AMA_SESSION_ID: input.sessionId,
+        AMA_CWD: input.cwd,
+    };
+    if (input.toolName !== undefined)
+        env["AMA_TOOL_NAME"] = input.toolName;
+    const file = filePathOf(input);
+    if (file !== undefined)
+        env["AMA_FILE"] = file;
+    return env;
+}
+function filePathOf(input) {
+    if (input.toolName === undefined || !["write", "edit", "read"].includes(input.toolName)) {
+        return undefined;
+    }
+    const toolInput = input.toolInput;
+    if (typeof toolInput !== "object" || toolInput === null)
+        return undefined;
+    const record = toolInput;
+    const path = record["path"] ?? record["file_path"];
+    return typeof path === "string" ? path : undefined;
+}

package/dist/hooks/runner.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Hook 子进程执行（设计 §6.1「退出码语义」「并行与顺序」）。[B5]
+ *
+ * - POSIX：`sh -c <command>`，独立进程组，超时 / abort 时 SIGTERM 整组，1 s 后 SIGKILL。
+ * - Windows：Git Bash（`AMA_HOOK_SHELL` 或常见安装位置）→ 否则 `cmd /d /s /c`。
+ * - cwd 为会话 cwd；stdin 写完 JSON 即关闭（Hook 不读 stdin 时忽略 EPIPE）。
+ * - stdout / stderr 各收集上限 1 MiB，超出截断。
+ * - 同一事件的多条 Hook 并行启动，结果按配置顺序返回。
+ */
+import type { LoadedHook } from "./config.js";
+import type { HookInput, HookRunResult } from "./types.js";
+export declare const MAX_OUTPUT_BYTES: number;
+export interface ShellCommand {
+    file: string;
+    args: string[];
+    /** Windows cmd 需要原样传参。 */
+    verbatim: boolean;
+}
+/** 选择 shell 并拼装参数。 */
+export declare function shellFor(command: string, platform?: NodeJS.Platform, env?: Readonly<Record<string, string | undefined>>): ShellCommand;
+export interface RunHookOptions {
+    cwd: string;
+    /** 叠加到 process.env 之上的环境。 */
+    env?: Readonly<Record<string, string | undefined>>;
+    signal?: AbortSignal | undefined;
+}
+/** 运行一条 Hook 命令；不抛错（spawn 失败记为退出码 127 + stderr）。 */
+export declare function runHookCommand(hook: Pick<LoadedHook, "event" | "command" | "timeoutMs" | "source">, input: HookInput, options: RunHookOptions): Promise<HookRunResult>;
+/** 并行运行，结果按入参顺序返回。 */
+export declare function runHooks(hooks: readonly Pick<LoadedHook, "event" | "command" | "timeoutMs" | "source">[], input: HookInput, options: RunHookOptions): Promise<HookRunResult[]>;

package/dist/hooks/runner.js

@@ -0,0 +1,143 @@
+/**
+ * Hook 子进程执行（设计 §6.1「退出码语义」「并行与顺序」）。[B5]
+ *
+ * - POSIX：`sh -c <command>`，独立进程组，超时 / abort 时 SIGTERM 整组，1 s 后 SIGKILL。
+ * - Windows：Git Bash（`AMA_HOOK_SHELL` 或常见安装位置）→ 否则 `cmd /d /s /c`。
+ * - cwd 为会话 cwd；stdin 写完 JSON 即关闭（Hook 不读 stdin 时忽略 EPIPE）。
+ * - stdout / stderr 各收集上限 1 MiB，超出截断。
+ * - 同一事件的多条 Hook 并行启动，结果按配置顺序返回。
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { hookEnv, parseHookOutput } from "./protocol.js";
+export const MAX_OUTPUT_BYTES = 1024 * 1024;
+const KILL_GRACE_MS = 1_000;
+/** 选择 shell 并拼装参数。 */
+export function shellFor(command, platform = process.platform, env = process.env) {
+    if (platform !== "win32")
+        return { file: "/bin/sh", args: ["-c", command], verbatim: false };
+    const candidates = [
+        env["AMA_HOOK_SHELL"],
+        env["ProgramFiles"] && join(env["ProgramFiles"], "Git", "bin", "bash.exe"),
+        env["ProgramW6432"] && join(env["ProgramW6432"], "Git", "bin", "bash.exe"),
+    ];
+    for (const candidate of candidates) {
+        if (candidate && existsSync(candidate))
+            return { file: candidate, args: ["-c", command], verbatim: false };
+    }
+    return {
+        file: env["ComSpec"] ?? "cmd.exe",
+        args: ["/d", "/s", "/c", `"${command}"`],
+        verbatim: true,
+    };
+}
+class Collector {
+    chunks = [];
+    size = 0;
+    truncated = false;
+    push(chunk) {
+        if (this.size >= MAX_OUTPUT_BYTES) {
+            this.truncated = true;
+            return;
+        }
+        const room = MAX_OUTPUT_BYTES - this.size;
+        const part = chunk.length > room ? chunk.subarray(0, room) : chunk;
+        if (part.length < chunk.length)
+            this.truncated = true;
+        this.chunks.push(part);
+        this.size += part.length;
+    }
+    text() {
+        return Buffer.concat(this.chunks).toString("utf8");
+    }
+}
+function killTree(pid, signal) {
+    if (pid === undefined)
+        return;
+    try {
+        if (process.platform === "win32") {
+            spawn("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+        }
+        else {
+            process.kill(-pid, signal);
+        }
+    }
+    catch {
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            // 进程已退出
+        }
+    }
+}
+/** 运行一条 Hook 命令；不抛错（spawn 失败记为退出码 127 + stderr）。 */
+export function runHookCommand(hook, input, options) {
+    const started = Date.now();
+    const shell = shellFor(hook.command);
+    return new Promise((resolveResult) => {
+        const stdout = new Collector();
+        const stderr = new Collector();
+        let timedOut = false;
+        let settled = false;
+        const child = spawn(shell.file, shell.args, {
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env, ...hookEnv(input) },
+            stdio: ["pipe", "pipe", "pipe"],
+            detached: process.platform !== "win32",
+            windowsHide: true,
+            windowsVerbatimArguments: shell.verbatim,
+        });
+        let killTimer;
+        const terminate = () => {
+            killTree(child.pid, "SIGTERM");
+            killTimer = setTimeout(() => killTree(child.pid, "SIGKILL"), KILL_GRACE_MS);
+            killTimer.unref();
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            terminate();
+        }, hook.timeoutMs);
+        const onAbort = () => terminate();
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        const finish = (exitCode, extraStderr) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (killTimer !== undefined)
+                clearTimeout(killTimer);
+            options.signal?.removeEventListener("abort", onAbort);
+            const out = stdout.text();
+            const result = {
+                event: hook.event,
+                command: hook.command,
+                source: hook.source,
+                exitCode: timedOut ? null : exitCode,
+                timedOut,
+                durationMs: Date.now() - started,
+                stdout: out,
+                stderr: stderr.text() + (extraStderr ?? ""),
+            };
+            if (!timedOut && exitCode === 0) {
+                const parsed = parseHookOutput(out);
+                if (parsed.output !== undefined)
+                    result.output = parsed.output;
+            }
+            resolveResult(result);
+        };
+        child.stdout.on("data", (chunk) => stdout.push(chunk));
+        child.stderr.on("data", (chunk) => stderr.push(chunk));
+        child.on("error", (error) => finish(127, `${error.message}\n`));
+        child.on("close", (code) => finish(code));
+        child.stdin.on("error", () => {
+            // Hook 没读 stdin 就退出：EPIPE 无害。
+        });
+        child.stdin.end(`${JSON.stringify(input)}\n`);
+    });
+}
+/** 并行运行，结果按入参顺序返回。 */
+export function runHooks(hooks, input, options) {
+    return Promise.all(hooks.map((hook) => runHookCommand(hook, input, options)));
+}