minimal-agent 0.10.0 → 0.12.0

package/src/plugins/hookEngine.ts

@@ -0,0 +1,341 @@
+/**
+ * ============================================================
+ *  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';
+
+import { sanitizeCredentialEnv } from '../config/configService.js';
+
+export type HookEventName =
+  | 'PreToolUse'
+  | 'PostToolUse'
+  | 'Stop'
+  | 'SubagentStop'
+  | 'UserPromptSubmit'
+  | 'SessionStart'
+  | 'SessionEnd'
+  | 'PreCompact'
+  | 'Notification';
+
+export interface HookDecision {
+  /** 'block' = 阻止当前事件 / 注入下一轮 prompt；'approve' = 显式通过；'pass'/undefined = 默认通过 */
+  decision?: 'block' | 'approve' | 'pass';
+  /** block 时，作为下一轮 user input 注入；approve 时仅日志 */
+  reason?: string;
+  /** UI/日志展示的提示 */
+  systemMessage?: string;
+  /** 输出给用户的额外文本（PreToolUse/PostToolUse 等） */
+  output?: string;
+  /** 是否抑制工具默认输出 */
+  suppressOutput?: boolean;
+  /** 多 hook 时，第一个返回 'block' 即短路 */
+  blockedBy?: string;
+}
+
+export interface HookPayloadBase {
+  session_id: string;
+  transcript_path: string;
+  cwd: string;
+  hook_event_name: HookEventName;
+}
+
+interface HookCommand {
+  /** ${CLAUDE_PLUGIN_ROOT} 已替换为绝对路径 */
+  command: string;
+  /** 命令所属的插件根目录（用于 spawn 时设置 CLAUDE_PLUGIN_ROOT env） */
+  pluginRoot: string;
+  /** 来源插件名（用于日志 / blockedBy） */
+  pluginName: string;
+  /** 可选 matcher 正则字符串（仅对 PreToolUse / PostToolUse 有意义） */
+  matcher?: string;
+}
+
+const HOOK_EVENT_NAMES: ReadonlySet<HookEventName> = new Set<HookEventName>([
+  'PreToolUse',
+  'PostToolUse',
+  'Stop',
+  'SubagentStop',
+  'UserPromptSubmit',
+  'SessionStart',
+  'SessionEnd',
+  'PreCompact',
+  'Notification',
+]);
+
+const HOOK_TIMEOUT_MS = 30_000;
+
+const hookTable = new Map<HookEventName, HookCommand[]>();
+let warnedWindowsShellSkip = false;
+
+function pluginNameFromRoot(pluginRoot: string): string {
+  const norm = pluginRoot.replace(/\\/g, '/');
+  const parts = norm.split('/').filter(Boolean);
+  return parts[parts.length - 1] ?? pluginRoot;
+}
+
+async function loadOnePluginHooks(pluginRoot: string): Promise<void> {
+  const hooksJsonPath = join(pluginRoot, 'hooks', 'hooks.json');
+
+  let parsed: unknown;
+  try {
+    const raw = await readFile(hooksJsonPath, 'utf8');
+    parsed = JSON.parse(raw);
+  } catch {
+    return;
+  }
+
+  if (!parsed || typeof parsed !== 'object') return;
+  const hooksObj = (parsed as { hooks?: unknown }).hooks;
+  if (!hooksObj || typeof hooksObj !== 'object') return;
+
+  const pluginName = pluginNameFromRoot(pluginRoot);
+
+  for (const [eventKey, groups] of Object.entries(hooksObj as Record<string, unknown>)) {
+    if (!HOOK_EVENT_NAMES.has(eventKey as HookEventName)) continue;
+    if (!Array.isArray(groups)) continue;
+
+    const eventName = eventKey as HookEventName;
+
+    for (const group of groups) {
+      if (!group || typeof group !== 'object') continue;
+      const matcher = typeof (group as { matcher?: unknown }).matcher === 'string'
+        ? ((group as { matcher: string }).matcher)
+        : undefined;
+      const innerHooks = (group as { hooks?: unknown }).hooks;
+      if (!Array.isArray(innerHooks)) continue;
+
+      for (const h of innerHooks) {
+        if (!h || typeof h !== 'object') continue;
+        const type = (h as { type?: unknown }).type;
+        const command = (h as { command?: unknown }).command;
+        if (type !== 'command' || typeof command !== 'string' || !command) continue;
+
+        const resolved = command.replaceAll('${CLAUDE_PLUGIN_ROOT}', pluginRoot);
+
+        const entry: HookCommand = {
+          command: resolved,
+          pluginRoot,
+          pluginName,
+          matcher,
+        };
+
+        const list = hookTable.get(eventName) ?? [];
+        list.push(entry);
+        hookTable.set(eventName, list);
+      }
+    }
+  }
+}
+
+/** 加载所有插件目录的 hooks.json，按事件名建表（模块级缓存）。 */
+export async function loadHooks(pluginRoots: string[]): Promise<void> {
+  hookTable.clear();
+  for (const root of pluginRoots) {
+    await loadOnePluginHooks(root);
+  }
+}
+
+/** 重置 hook 缓存（测试用） */
+export function _resetHookEngine(): void {
+  hookTable.clear();
+  warnedWindowsShellSkip = false;
+}
+
+function matcherAllows(matcher: string | undefined, toolName: unknown): boolean {
+  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: string): boolean {
+  // 仅按文件后缀判断，命令字符串可能带参数，截取首段
+  const head = command.trim().split(/\s+/)[0] ?? '';
+  return head.toLowerCase().endsWith('.sh');
+}
+
+function runOneHook(
+  hook: HookCommand,
+  payload: Record<string, unknown>,
+): Promise<HookDecision> {
+  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 = {
+      ...sanitizeCredentialEnv(),
+      CLAUDE_PLUGIN_ROOT: hook.pluginRoot,
+    };
+
+    let child: ReturnType<typeof spawn>;
+    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: HookDecision) => {
+      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: Buffer) => {
+      stdout += data.toString();
+    });
+    // stderr 内容不消费但必须排空：spawn 默认 pipe，无 reader 时 hook 往 stderr
+    // 写满 ~64KB 管道缓冲会阻塞，硬等到 30s 超时被 SIGTERM。
+    child.stderr?.resume();
+
+    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) as Record<string, unknown>;
+        const decision = parsed.decision;
+
+        if (decision === 'block' || decision === 'approve') {
+          const result: HookDecision = {
+            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: HookEventName,
+  payload: Omit<HookPayloadBase, 'hook_event_name'> & Record<string, unknown>,
+): Promise<HookDecision> {
+  const hooks = hookTable.get(eventName);
+  if (!hooks || hooks.length === 0) {
+    return { decision: 'pass' };
+  }
+
+  const fullPayload: Record<string, unknown> = {
+    ...payload,
+    hook_event_name: eventName,
+  };
+
+  let lastDecision: HookDecision = { 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.ts

@@ -0,0 +1,133 @@
+/**
+ * ============================================================
+ *  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。
+ * ============================================================
+ */
+
+import type { ContextBundle } from '../context/contextBundle.js';
+import type { AgentRuntimeContext } from '../runtime/agentRuntimeContext.js';
+import type {
+  RunAgentTurnOptions,
+  RunAgentTurnResult,
+} from '../session/runAgentTurn.js';
+import type { SessionState } from '../session/sessionState.js';
+import type {
+  LoopEvent,
+  Message,
+  PromptCacheContext,
+  Provider,
+  ToolCallContext,
+  ToolResult,
+} from '../types.js';
+
+/** 框架传给插件的运行时上下文（仅暴露执行 LLM/工具 所需的最小集合）。 */
+export interface PluginContext {
+  provider: Provider;
+  /** 调用方持有的消息历史，插件可读可写（mutate 同一引用） */
+  history: Message[];
+  /** 用户取消信号 */
+  signal?: AbortSignal;
+  /** 多租户场景注入的隔离 session 状态；缺省走模块单例 */
+  sessionState?: SessionState;
+  /** maxTurns 透传 */
+  maxTurns?: number;
+  /** 当前回合的瞬时外部上下文；插件不得把它持久化到 history。 */
+  transientContext?: string;
+  transientBundle?: ContextBundle;
+  promptCache?: PromptCacheContext;
+  /** Canonical host-issued trust context; plugins may narrow it but never elevate it. */
+  runtimeContext?: AgentRuntimeContext;
+  /** Host tool names are an upper bound. Plugins may narrow, never expand. */
+  allowedTools?: readonly string[];
+  /**
+   * Host tool dispatcher. Rich plugins must use the same injected executor as
+   * the parent run so tests, embedders and host-specific dispatch remain on one
+   * execution path.
+   */
+  executeTool?: (
+    name: string,
+    rawArgsJson: string,
+    signal?: AbortSignal,
+    context?: ToolCallContext,
+  ) => Promise<ToolResult>;
+  /**
+   * 宿主的**授权与可见性上下文**，原样转交给工具层（`executeTool` 第四参）。
+   *
+   * ⚠️ 为什么是**一个** `Pick<ToolCallContext, …>` 而不是逐个平铺四个字段：
+   *   · 它就是「工具接收什么」那个**已有**抽象的子集 —— 用 `Pick` 绑定，
+   *     `ToolCallContext` 改了这里跟着改，不会出现两份各自漂移的定义；
+   *   · 将来新增宿主能力（移动端、远程桌面…）时这个接口零改动（Open/Closed）。
+   *
+   * ⚠️ 此前缺席的后果：`pluginRunner` 的三处下传里，两条 runQuery 路径都带了
+   * browserRun/computerRun，**唯独 `api.runCommand(...)` 那一处漏了** —— 于是
+   * `PluginContext` 比 `RunQueryOptions` 窄，富插件（如 workflow-runner）永远拿不到
+   * 宿主授权。表现是 workflow 里调 ComputerUse 恒返回「当前宿主未启用 Computer Use」，
+   * 而同一个工具在主循环里好好的。
+   *
+   * 插件**不应**无条件把它转给每一步：能力要由各步显式声明后按需转发
+   * （见 workflow-runner 的 `StepDef.uses`），否则一份无人值守的脚本就隐式拿到了
+   * 完整的机器控制权。
+   */
+  host?: Pick<
+    ToolCallContext,
+    'browserRun' | 'computerRun' | 'computerIntervention' | 'toolGate'
+  >;
+}
+
+/** TUI/App 生命周期传给富插件的宿主能力。 */
+export interface PluginRuntimeContext {
+  provider: Provider;
+  signal?: AbortSignal;
+  runAgentTurn: (opts: RunAgentTurnOptions) => Promise<RunAgentTurnResult>;
+}
+
+/**
+ * 插件自定义事件的开放形状。
+ *
+ * 任何带 `type: string` 字段的对象都允许；payload 字段由插件自己定义。
+ * 框架 yield 时原样透传，UI 的 handleEvent 用 switch 派发——
+ * 无 case 匹配的 type 走 default no-op，等同静默忽略。
+ *
+ * 例：workflow-runner 的 WorkflowEvent（`type: 'workflow_start'` 等）
+ *     在结构上自动满足 PluginEvent，无需 cast。
+ */
+export interface PluginEvent {
+  type: string;
+  [key: string]: unknown;
+}
+
+/**
+ * 插件 plugin.ts 的 default export 形状。
+ *
+ * `runCommand` 接管声明式 markdown fallback：返回 AsyncGenerator 让框架直接 yield* 出去。
+ * 返回类型允许 LoopEvent（框架已识别）+ PluginEvent（插件私有事件）混合 yield。
+ * 不实现 runCommand → 框架回退到 buildCommandInput + runQuery（纯 prompt 模式）。
+ */
+export interface PluginApi {
+  activate?(
+    ctx: PluginRuntimeContext,
+  ): // biome-ignore lint/suspicious/noConfusingVoidType: lifecycle hooks intentionally accept synchronous void or an async disposer.
+  Promise<void | (() => void)> | void | (() => void);
+  runCommand?(
+    commandName: string,
+    args: string,
+    ctx: PluginContext,
+  ): AsyncGenerator<LoopEvent | PluginEvent, void, void>;
+}

package/src/plugins/pluginLifecycle.ts

@@ -0,0 +1,34 @@
+import { discoverPlugins } from './commandRouter.js';
+import { loadPluginApi } from './pluginLoader.js';
+import type { PluginRuntimeContext } from './pluginApi.js';
+
+export async function activatePlugins(
+  ctx: PluginRuntimeContext,
+): Promise<() => void> {
+  const manifests = await discoverPlugins();
+  const cleanups: Array<() => void> = [];
+
+  for (const manifest of manifests) {
+    const api = await loadPluginApi(manifest.root);
+    if (!api?.activate) continue;
+    try {
+      const cleanup = await api.activate(ctx);
+      if (typeof cleanup === 'function') cleanups.push(cleanup);
+    } catch (err) {
+      console.warn(
+        `[minimal-agent] plugin activate failed (${manifest.name}): ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    }
+  }
+
+  return () => {
+    for (const cleanup of cleanups.reverse()) {
+      try {
+        cleanup();
+      } catch {
+      }
+    }
+  };
+}

package/src/plugins/pluginLoader.ts

@@ -0,0 +1,147 @@
+/**
+ * ============================================================
+ *  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 声明式插件）
+ *   - 两个文件都存在 + plugin.ts mtime > plugin.js mtime → console.warn
+ *     提示 stale（dev 模式跑过 build 后又改 .ts 源码的常见坑），加载行为
+ *     不变仍优先 plugin.js
+ *   - import 失败（语法错 / 运行时抛错）→ console.warn + 缓存 null
+ *   - import 成功但 default 不是对象 → 缓存 null
+ *   - 缓存 key = pluginRoot 绝对路径
+ *
+ *  框架 hot-reload 由测试调用 _resetPluginLoader() 实现。
+ * ============================================================
+ */
+
+import { existsSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import type { PluginApi } from './pluginApi.js';
+
+const loaderCache = new Map<string, PluginApi | null>();
+
+/**
+ * 内置插件静态注册表（仅绿色版 compile 入口 entry.compiled.tsx 会填充）。
+ *
+ * 背景：`bun --compile` 后，rich 插件的 plugin.ts 顺链 import 的框架 SDK
+ * （`../../../src/plugin-sdk.js`）已被焊进 exe、磁盘上不存在 → 动态 import
+ * 外部 plugin.ts 必抛错。绿色版改为在 compile 入口**静态 import** 内置插件
+ * （`src/plugins/builtinRegistry.ts`），让 bun 把执行器整树打进 exe，再经
+ * setBuiltinPluginApi 注册到这里；loadPluginApi 在磁盘加载缺失/失败时回退到此表。
+ *
+ * dev / npm 模式：entry.compiled 永不被 import → 此表恒为空 → 回退分支不触发
+ * → loadPluginApi 行为与改动前逐字节一致。
+ *
+ * key = 插件目录名（`plugins/<id>/` 的 `<id>`，等于 `basename(pluginRoot)`）。
+ */
+const builtinApis = new Map<string, PluginApi>();
+
+/** 由绿色版 compile 入口调用，注册内置插件执行器。dev/npm 不会调用。 */
+export function setBuiltinPluginApi(key: string, api: PluginApi): void {
+  builtinApis.set(key, api);
+}
+
+function isPluginApi(value: unknown): value is PluginApi {
+  if (!value || typeof value !== 'object') return false;
+  const { runCommand } = value as { runCommand?: unknown };
+  if (runCommand !== undefined && typeof runCommand !== 'function') return false;
+  return true;
+}
+
+/**
+ * 加载插件目录下的 plugin.ts；不存在或失败返回 null。
+ * 同一 pluginRoot 多次调用走缓存，避免重复 import。
+ */
+export async function loadPluginApi(pluginRoot: string): Promise<PluginApi | null> {
+  if (loaderCache.has(pluginRoot)) {
+    return loaderCache.get(pluginRoot) ?? null;
+  }
+
+  // prefer plugin.js（install / Node 兼容），fallback plugin.ts（dev / 用户 Bun 插件）
+  const jsPath = join(pluginRoot, 'plugin.js');
+  const tsPath = join(pluginRoot, 'plugin.ts');
+  const jsExists = existsSync(jsPath);
+  const tsExists = existsSync(tsPath);
+
+  // dev 模式 stale 检测：两文件都存在 + .ts 比 .js 新 → 用户改了源码但没清编译产物
+  if (jsExists && tsExists) {
+    try {
+      const jsMtime = statSync(jsPath).mtimeMs;
+      const tsMtime = statSync(tsPath).mtimeMs;
+      if (tsMtime > jsMtime) {
+        console.warn(
+          `[minimal-agent] 检测到 stale plugin.js（${pluginRoot}）：plugin.ts 比 plugin.js 新，` +
+            `加载器仍优先吃 plugin.js。如果你刚改过源码却没生效，请跑 \`bun run clean\` 删掉原地编译产物。`,
+        );
+      }
+    } catch {
+      // stat 失败静默，不影响加载
+    }
+  }
+
+  // 绿色版回退：磁盘加载缺失/失败时，按目录名查 exe 内静态注册表。
+  // dev/npm 注册表恒空 → 永远返回 null → 不改变下方任何分支的最终结果。
+  const builtinKey = basename(pluginRoot);
+  const builtinFallback = (): PluginApi | null => {
+    const api = builtinApis.get(builtinKey);
+    if (api) {
+      loaderCache.set(pluginRoot, api);
+      return api;
+    }
+    return null;
+  };
+
+  const pluginEntry = jsExists ? jsPath : tsExists ? tsPath : undefined;
+  if (!pluginEntry) {
+    // 磁盘无 plugin.js/.ts：绿色目录只铺声明式部分（plugin.json + commands/），
+    // 执行器在 exe 内注册表 → 这里命中。dev/npm 注册表空 → 维持原 null。
+    const fb = builtinFallback();
+    if (fb) return fb;
+    loaderCache.set(pluginRoot, null);
+    return null;
+  }
+
+  try {
+    const mod = await import(pathToFileURL(pluginEntry).href);
+    const candidate = (mod as { default?: unknown }).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) {
+    // 绿色版：磁盘铺了 plugin.js 但它顺链 import 的框架 SDK 在 exe 内、磁盘没有
+    // → import 抛错 → 回退到 exe 内注册表。dev/npm 注册表空 → 维持原 warn + null。
+    const fb = builtinFallback();
+    if (fb) return fb;
+    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(): void {
+  loaderCache.clear();
+  builtinApis.clear();
+}