minimal-agent 0.2.0 → 0.3.1

package/src/plugins/hookEngine.js

@@ -0,0 +1,258 @@
+/**
+ * ============================================================
+ *  src/plugins/hookEngine.ts —— Claude Code 风格 hook 派发引擎
+ * ------------------------------------------------------------
+ *  统一加载所有插件目录下的 hooks/hooks.json，按事件名建表，
+ *  在 minimal-agent 的关键节点（Stop / PreToolUse / PostToolUse /
+ *  UserPromptSubmit / SessionStart / SessionEnd / PreCompact /
+ *  Notification / SubagentStop）触发对应的 shell 命令。
+ *
+ *  契约（与 Claude Code 对齐）：
+ *    - hook 命令通过 stdin 收到 JSON payload（包含 session_id、
+ *      transcript_path、cwd、hook_event_name 等基础字段 + 事件特定字段）
+ *    - 命令在 stdout 输出 JSON：
+ *        { decision: "block" | "approve" | "pass",
+ *          reason?, systemMessage?, output?, suppressOutput? }
+ *    - 解析失败 / 非 0 退出 / 空输出 → 视为 pass
+ *    - 多 hook 串行执行，遇到第一个 block 立即短路返回
+ *
+ *  Windows 兼容：
+ *    - 以 .sh 结尾的命令直接跳过，并 warn 一次（bash 通常不可用）
+ *    - 其他命令（.ps1 / .cmd / .bat / 可执行文件）走 shell:true
+ *    - POSIX 上一律 `bash -c <command>`，避免依赖文件可执行位
+ *
+ *  Matcher 支持（PreToolUse / PostToolUse）：
+ *    - 在 matcher 组级别声明 `matcher: 'Bash|Edit'` 等正则
+ *    - payload.tool_name 不匹配则跳过这组所有命令
+ *    - 缺省 matcher 视为通配
+ * ============================================================
+ */
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const HOOK_EVENT_NAMES = new Set([
+    'PreToolUse',
+    'PostToolUse',
+    'Stop',
+    'SubagentStop',
+    'UserPromptSubmit',
+    'SessionStart',
+    'SessionEnd',
+    'PreCompact',
+    'Notification',
+]);
+const HOOK_TIMEOUT_MS = 30_000;
+const hookTable = new Map();
+let warnedWindowsShellSkip = false;
+function pluginNameFromRoot(pluginRoot) {
+    const norm = pluginRoot.replace(/\\/g, '/');
+    const parts = norm.split('/').filter(Boolean);
+    return parts[parts.length - 1] ?? pluginRoot;
+}
+async function loadOnePluginHooks(pluginRoot) {
+    const hooksJsonPath = join(pluginRoot, 'hooks', 'hooks.json');
+    let parsed;
+    try {
+        const raw = await readFile(hooksJsonPath, 'utf8');
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return;
+    const hooksObj = parsed.hooks;
+    if (!hooksObj || typeof hooksObj !== 'object')
+        return;
+    const pluginName = pluginNameFromRoot(pluginRoot);
+    for (const [eventKey, groups] of Object.entries(hooksObj)) {
+        if (!HOOK_EVENT_NAMES.has(eventKey))
+            continue;
+        if (!Array.isArray(groups))
+            continue;
+        const eventName = eventKey;
+        for (const group of groups) {
+            if (!group || typeof group !== 'object')
+                continue;
+            const matcher = typeof group.matcher === 'string'
+                ? (group.matcher)
+                : undefined;
+            const innerHooks = group.hooks;
+            if (!Array.isArray(innerHooks))
+                continue;
+            for (const h of innerHooks) {
+                if (!h || typeof h !== 'object')
+                    continue;
+                const type = h.type;
+                const command = h.command;
+                if (type !== 'command' || typeof command !== 'string' || !command)
+                    continue;
+                const resolved = command.replaceAll('${CLAUDE_PLUGIN_ROOT}', pluginRoot);
+                const entry = {
+                    command: resolved,
+                    pluginRoot,
+                    pluginName,
+                    matcher,
+                };
+                const list = hookTable.get(eventName) ?? [];
+                list.push(entry);
+                hookTable.set(eventName, list);
+            }
+        }
+    }
+}
+/** 加载所有插件目录的 hooks.json，按事件名建表（模块级缓存）。 */
+export async function loadHooks(pluginRoots) {
+    hookTable.clear();
+    for (const root of pluginRoots) {
+        await loadOnePluginHooks(root);
+    }
+}
+/** 重置 hook 缓存（测试用） */
+export function _resetHookEngine() {
+    hookTable.clear();
+    warnedWindowsShellSkip = false;
+}
+function matcherAllows(matcher, toolName) {
+    if (!matcher)
+        return true;
+    if (typeof toolName !== 'string' || !toolName)
+        return true;
+    try {
+        const re = new RegExp(`^(${matcher})$`);
+        return re.test(toolName);
+    }
+    catch {
+        return true;
+    }
+}
+function isPosixShellScript(command) {
+    // 仅按文件后缀判断，命令字符串可能带参数，截取首段
+    const head = command.trim().split(/\s+/)[0] ?? '';
+    return head.toLowerCase().endsWith('.sh');
+}
+function runOneHook(hook, payload) {
+    return new Promise((resolve) => {
+        const isWin = process.platform === 'win32';
+        if (isWin && isPosixShellScript(hook.command)) {
+            if (!warnedWindowsShellSkip) {
+                warnedWindowsShellSkip = true;
+                console.warn(`[minimal-agent] Skipping POSIX shell hook on Windows: ${hook.command}`);
+            }
+            resolve({ decision: 'pass' });
+            return;
+        }
+        const env = {
+            ...process.env,
+            CLAUDE_PLUGIN_ROOT: hook.pluginRoot,
+        };
+        let child;
+        try {
+            if (isWin) {
+                // Windows 上其他类型脚本（.ps1 / .cmd / .bat / 可执行文件）走 shell
+                child = spawn(hook.command, { env, shell: true });
+            }
+            else {
+                // POSIX 一律 bash -c，避开文件可执行位 / shebang 问题
+                child = spawn('bash', ['-c', hook.command], { env });
+            }
+        }
+        catch {
+            resolve({ decision: 'pass' });
+            return;
+        }
+        let stdout = '';
+        let settled = false;
+        const finalize = (decision) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(decision);
+        };
+        const timer = setTimeout(() => {
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                // ignore
+            }
+            console.warn(`[minimal-agent] Hook timeout (>${HOOK_TIMEOUT_MS}ms): ${hook.command}`);
+            finalize({ decision: 'pass' });
+        }, HOOK_TIMEOUT_MS);
+        child.stdout?.on('data', (data) => {
+            stdout += data.toString();
+        });
+        child.on('error', () => {
+            finalize({ decision: 'pass' });
+        });
+        child.on('close', (code) => {
+            if (code !== 0) {
+                finalize({ decision: 'pass' });
+                return;
+            }
+            const trimmed = stdout.trim();
+            if (!trimmed) {
+                finalize({ decision: 'pass' });
+                return;
+            }
+            try {
+                const parsed = JSON.parse(trimmed);
+                const decision = parsed.decision;
+                if (decision === 'block' || decision === 'approve') {
+                    const result = {
+                        decision,
+                        reason: typeof parsed.reason === 'string' ? parsed.reason : undefined,
+                        systemMessage: typeof parsed.systemMessage === 'string' ? parsed.systemMessage : undefined,
+                        output: typeof parsed.output === 'string' ? parsed.output : undefined,
+                        suppressOutput: typeof parsed.suppressOutput === 'boolean' ? parsed.suppressOutput : undefined,
+                    };
+                    if (decision === 'block') {
+                        result.blockedBy = hook.pluginName;
+                    }
+                    finalize(result);
+                    return;
+                }
+                finalize({ decision: 'pass' });
+            }
+            catch {
+                finalize({ decision: 'pass' });
+            }
+        });
+        try {
+            child.stdin?.write(JSON.stringify(payload));
+            child.stdin?.end();
+        }
+        catch {
+            // 子进程已挂掉等情况，等 'close' / 'error' 处理
+        }
+    });
+}
+/**
+ * 触发某事件。payload 会与 base 字段合并写入 stdin。
+ * 多 hook 同事件 → 按声明顺序串行执行，遇到 block 立即短路返回。
+ * Windows 上 .sh 命令直接跳过 + 一次性 warn。
+ */
+export async function triggerHook(eventName, payload) {
+    const hooks = hookTable.get(eventName);
+    if (!hooks || hooks.length === 0) {
+        return { decision: 'pass' };
+    }
+    const fullPayload = {
+        ...payload,
+        hook_event_name: eventName,
+    };
+    let lastDecision = { decision: 'pass' };
+    for (const hook of hooks) {
+        if (eventName === 'PreToolUse' || eventName === 'PostToolUse') {
+            if (!matcherAllows(hook.matcher, fullPayload.tool_name))
+                continue;
+        }
+        const result = await runOneHook(hook, fullPayload);
+        if (result.decision === 'block') {
+            return result;
+        }
+        lastDecision = result;
+    }
+    return lastDecision;
+}

package/src/plugins/pluginApi.js

@@ -0,0 +1,23 @@
+/**
+ * ============================================================
+ *  src/plugins/pluginApi.ts —— 插件 plugin.ts 的契约
+ * ------------------------------------------------------------
+ *  双层插件契约的"代码层"接口：
+ *
+ *    plugins/<id>/.claude-plugin/plugin.json  → 元数据
+ *    plugins/<id>/commands/*.md               → 声明式 slash 命令（默认走 LLM）
+ *    plugins/<id>/hooks/hooks.json            → 声明式 hook
+ *    plugins/<id>/plugin.ts                   → 可选！要接管命令分发时才写
+ *
+ *  纯 markdown 插件（无 plugin.ts）零修改 drop-in，覆盖 99% Anthropic 上游用例；
+ *  富插件写 plugin.ts 接管 runCommand，把全部逻辑放在自己目录里，外部 src/ 一行不改。
+ *
+ *  PluginContext 是框架"愿意暴露给插件"的最小运行时上下文：
+ *   - provider / history / signal / sessionState 都是 runQuery 本来就接受的
+ *   - 插件作者通过 src/plugin-sdk.ts 取 runQuery、chat、executeTool 等
+ *
+ *  PluginEvent 是事件层的"开放契约"：插件可以 yield 任意带 type 字段的自定义事件
+ *   ——框架原样透传，UI 不识别就静默忽略。让插件不必把私有事件挤进 LoopEvent。
+ * ============================================================
+ */
+export {};

package/src/plugins/pluginLoader.js

@@ -0,0 +1,71 @@
+/**
+ * ============================================================
+ *  src/plugins/pluginLoader.ts —— plugin entry dynamic import 缓存层
+ * ------------------------------------------------------------
+ *  按 pluginRoot 路径 lazy import 插件目录下的 plugin.js（优先）
+ *  或 plugin.ts（回退）。
+ *
+ *  双候选探测的原因：
+ *   - install 模式（npm 包内）：tsc 编译后只剩 plugin.js，Node + Bun
+ *     都能加载
+ *   - dev 模式（仓库源码）：物理只有 plugin.ts，Bun 直接吃
+ *   - 用户 cwd 自带插件：可能写 .ts（须 Bun 跑）或 .js（Node + Bun 都行）
+ *
+ *  契约：
+ *   - 两个文件都不存在 → 缓存 null（纯 markdown 声明式插件）
+ *   - import 失败（语法错 / 运行时抛错）→ console.warn + 缓存 null
+ *   - import 成功但 default 不是对象 → 缓存 null
+ *   - 缓存 key = pluginRoot 绝对路径
+ *
+ *  框架 hot-reload 由测试调用 _resetPluginLoader() 实现。
+ * ============================================================
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+const loaderCache = new Map();
+function isPluginApi(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const { runCommand } = value;
+    if (runCommand !== undefined && typeof runCommand !== 'function')
+        return false;
+    return true;
+}
+/**
+ * 加载插件目录下的 plugin.ts；不存在或失败返回 null。
+ * 同一 pluginRoot 多次调用走缓存，避免重复 import。
+ */
+export async function loadPluginApi(pluginRoot) {
+    if (loaderCache.has(pluginRoot)) {
+        return loaderCache.get(pluginRoot) ?? null;
+    }
+    // prefer plugin.js（install / Node 兼容），fallback plugin.ts（dev / 用户 Bun 插件）
+    const pluginEntry = ['plugin.js', 'plugin.ts']
+        .map((f) => join(pluginRoot, f))
+        .find((p) => existsSync(p));
+    if (!pluginEntry) {
+        loaderCache.set(pluginRoot, null);
+        return null;
+    }
+    try {
+        const mod = await import(pathToFileURL(pluginEntry).href);
+        const candidate = mod.default;
+        if (!isPluginApi(candidate)) {
+            console.warn(`[minimal-agent] plugin.ts default export is not a valid PluginApi: ${pluginRoot}`);
+            loaderCache.set(pluginRoot, null);
+            return null;
+        }
+        loaderCache.set(pluginRoot, candidate);
+        return candidate;
+    }
+    catch (err) {
+        console.warn(`[minimal-agent] failed to load plugin entry at ${pluginRoot}: ${err instanceof Error ? err.message : String(err)}`);
+        loaderCache.set(pluginRoot, null);
+        return null;
+    }
+}
+/** 测试用：重置加载器缓存。 */
+export function _resetPluginLoader() {
+    loaderCache.clear();
+}

package/src/plugins/pluginRunner.js

@@ -0,0 +1,65 @@
+/**
+ * ============================================================
+ *  src/plugins/pluginRunner.ts —— 框架级 slash-命令分发器
+ * ------------------------------------------------------------
+ *  通用分发器，**不含任何插件特定逻辑**。
+ *
+ *  执行路径：
+ *    1) 非 / 输入 → 直接透传 runQuery（T-A-O-R 红线，零插件副作用）
+ *    2) / 输入 → discoverPlugins → resolveCommand
+ *       a) 命中插件且其 plugin.ts 暴露 runCommand → 让 plugin.ts 接管
+ *       b) 命中插件但只有声明式 commands/*.md → 把 prompt 拼好喂给 runQuery
+ *       c) 未命中 → 当普通问句喂给 runQuery（让 LLM 自己解释 / 未知命令）
+ * ============================================================
+ */
+import { discoverPlugins, resolveCommand, buildCommandInput, } from './commandRouter.js';
+import { loadPluginApi } from './pluginLoader.js';
+import { runQuery } from '../loop.js';
+export async function* runWithPlugins(userInput, options) {
+    const { provider, history, signal } = options;
+    const isSlashCommand = userInput.trimStart().startsWith('/');
+    if (!isSlashCommand) {
+        yield* runQuery(userInput, {
+            provider,
+            history,
+            signal,
+            maxTurns: options.maxTurns,
+            sessionState: options.sessionState,
+        });
+        return;
+    }
+    await discoverPlugins();
+    const matched = resolveCommand(userInput);
+    if (!matched) {
+        // 未知 / 命令直接喂 LLM,让模型自然回复(等同于普通文本)
+        yield* runQuery(userInput, {
+            provider,
+            history,
+            signal,
+            maxTurns: options.maxTurns,
+            sessionState: options.sessionState,
+        });
+        return;
+    }
+    // 优先 plugin.ts.runCommand（富插件接管）
+    const api = await loadPluginApi(matched.cmd.pluginRoot);
+    if (api?.runCommand) {
+        yield* api.runCommand(matched.cmd.name, matched.arguments, {
+            provider,
+            history,
+            signal,
+            sessionState: options.sessionState,
+            maxTurns: options.maxTurns,
+        });
+        return;
+    }
+    // 声明式 fallback：把 markdown 命令体拼成 prompt 喂 LLM
+    const promptInput = buildCommandInput(matched);
+    yield* runQuery(promptInput, {
+        provider,
+        history,
+        signal,
+        maxTurns: options.maxTurns,
+        sessionState: options.sessionState,
+    });
+}

package/src/plugins/transcript.js

@@ -0,0 +1,171 @@
+/**
+ * ============================================================
+ *  src/plugins/transcript.ts —— Claude Code 风格的 JSONL transcript 写入
+ * ------------------------------------------------------------
+ *  插件 hook（如 stop-hook.sh）通过 stdin 收到 `transcript_path` 后
+ *  会 grep / jq 这份 JSONL 文件来还原对话。schema 必须与 Anthropic
+ *  Claude Code 真实 transcript 对齐：每行一个 JSON 对象，形如
+ *    { type, uuid, session_id, timestamp, message: { role, content: [...parts] } }
+ *  content 为 typed parts 数组：text / tool_use / tool_result。
+ *
+ *  设计要点：
+ *   - OpenAI 风格的 assistant.tool_calls 在这里被拍平成 content 数组
+ *     里的 tool_use parts（Claude Code 的真实格式）
+ *   - tool role 消息被包装成 type:'user' + tool_result part（上游惯例）
+ *   - 同步 appendFileSync —— spawn 的 hook 子进程要立刻看到最新内容
+ *   - 任何写入异常都被吞掉只 warn —— transcript 失败绝不能拖垮 agent
+ *   - 零依赖（只用 node 内置）
+ *
+ *  存储位置：~/.minimal-agent/transcripts/<sessionId>.jsonl
+ * ============================================================
+ */
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+// 模块级状态：当前会话的 handle（lazy 初始化）
+let current = null;
+function transcriptDir() {
+    return join(homedir(), '.minimal-agent', 'transcripts');
+}
+function generateSessionId() {
+    return `${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
+}
+function ensureHandle(sessionId) {
+    // 如果指定了 sessionId 且与当前不同 → 切到新文件
+    if (sessionId && current && current.sessionId === sessionId) {
+        return current;
+    }
+    if (!sessionId && current) {
+        return current;
+    }
+    const sid = sessionId ?? generateSessionId();
+    const dir = transcriptDir();
+    try {
+        mkdirSync(dir, { recursive: true });
+    }
+    catch (err) {
+        console.warn(`[transcript] mkdir failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const handle = {
+        sessionId: sid,
+        path: join(dir, `${sid}.jsonl`),
+    };
+    current = handle;
+    return handle;
+}
+function writeLine(line) {
+    try {
+        const handle = ensureHandle();
+        appendFileSync(handle.path, `${JSON.stringify(line)}\n`, 'utf8');
+    }
+    catch (err) {
+        console.warn(`[transcript] write failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+/**
+ * 初始化 transcript：在 ~/.minimal-agent/transcripts/ 下打开 <sessionId>.jsonl。
+ * 如果未提供 sessionId，用时间戳 + 随机后缀生成。
+ * 多次调用同一 sessionId 会复用同一文件（append）。
+ */
+export function initTranscript(sessionId) {
+    // 显式 init：即便 current 已存在也允许切换到指定 sessionId
+    if (sessionId) {
+        const dir = transcriptDir();
+        try {
+            mkdirSync(dir, { recursive: true });
+        }
+        catch (err) {
+            console.warn(`[transcript] mkdir failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        current = {
+            sessionId,
+            path: join(dir, `${sessionId}.jsonl`),
+        };
+        return current;
+    }
+    return ensureHandle();
+}
+/** 获取当前会话的 transcript 路径。未 init 时 lazy 初始化。 */
+export function getCurrentTranscriptPath() {
+    return ensureHandle().path;
+}
+/** 追加一条 user 消息。 */
+export function appendUserMessage(content) {
+    const handle = ensureHandle();
+    writeLine({
+        type: 'user',
+        uuid: randomUUID(),
+        session_id: handle.sessionId,
+        timestamp: nowIso(),
+        message: {
+            role: 'user',
+            content: [{ type: 'text', text: content }],
+        },
+    });
+}
+/** 追加一条 assistant 消息。tool_calls 转成 content 数组里的 tool_use parts。 */
+export function appendAssistantMessage(message) {
+    const handle = ensureHandle();
+    const parts = [];
+    // 文本部分：null / 空字符串都跳过
+    if (typeof message.content === 'string' && message.content.length > 0) {
+        parts.push({ type: 'text', text: message.content });
+    }
+    // tool_calls 拍平成 tool_use parts
+    if (Array.isArray(message.tool_calls)) {
+        for (const tc of message.tool_calls) {
+            let input;
+            try {
+                input = JSON.parse(tc.function.arguments);
+            }
+            catch {
+                input = { _raw: tc.function.arguments };
+            }
+            parts.push({
+                type: 'tool_use',
+                id: tc.id,
+                name: tc.function.name,
+                input,
+            });
+        }
+    }
+    writeLine({
+        type: 'assistant',
+        uuid: randomUUID(),
+        session_id: handle.sessionId,
+        timestamp: nowIso(),
+        message: {
+            role: 'assistant',
+            content: parts,
+        },
+    });
+}
+/** 追加一条 tool 执行结果（来自 tool role 消息）。 */
+export function appendToolResult(toolCallId, _toolName, ok, content) {
+    const handle = ensureHandle();
+    writeLine({
+        type: 'user',
+        uuid: randomUUID(),
+        session_id: handle.sessionId,
+        timestamp: nowIso(),
+        message: {
+            role: 'user',
+            content: [
+                {
+                    type: 'tool_result',
+                    tool_use_id: toolCallId,
+                    content,
+                    is_error: !ok,
+                },
+            ],
+        },
+    });
+}
+/** 重置当前 handle（用于测试 / /new 清屏后开新 session）。 */
+export function resetTranscript() {
+    current = null;
+}

package/src/prompts/projectInstructions.js

@@ -0,0 +1,48 @@
+/**
+ * ============================================================
+ *  src/prompts/projectInstructions.ts —— 项目级指令加载
+ * ------------------------------------------------------------
+ *  检查当前工作目录下是否存在 minimal-agent.md，
+ *  如果存在则全量读取并返回其内容。
+ *
+ *  用途类似：
+ *    - kakadeai 的 CLAUDE.md
+ *    - Cursor 的 .cursorrules
+ *    - GitHub Copilot 的 .github/copilot-instructions.md
+ *
+ *  设计原则：
+ *    1. 静默失败：文件不存在时不报错、不打印警告、返回 null
+ *    2. 全量注入：不做截断或摘要，原样拼入 messages 数组
+ *    3. 实时读取：每次 buildInitialHistory 都重新读（用户改了立即生效）
+ *    4. 独立消息：作为单独的 system message 插入，
+ *       不污染全局 system prompt 的 token 结构
+ * ============================================================
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const FILENAME = 'minimal-agent.md';
+/**
+ * 尝试从 cwd 加载项目指令文件。
+ *
+ * @param cwd 当前工作目录
+ * @returns 文件内容字符串（如果存在），null 如果不存在或读取出错
+ */
+export async function loadProjectInstructions(cwd) {
+    const filePath = join(cwd, FILENAME);
+    try {
+        const content = await readFile(filePath, 'utf-8');
+        const trimmed = content.trim();
+        if (trimmed.length === 0)
+            return null;
+        return trimmed;
+    }
+    catch (e) {
+        // ENOENT（文件不存在）→ 最常见的情况 → 静默返回 null
+        // 其他错误（权限/I/O/编码等）→ stderr 警告一次，仍返回 null 不阻止启动
+        const code = e.code;
+        if (code !== 'ENOENT') {
+            process.stderr.write(`[minimal-agent] 跳过项目指令 ${filePath}：${code ?? e.message}\n`);
+        }
+        return null;
+    }
+}