@armadra/agent 0.0.0-stage → 0.2.1

package/dist/hooks/types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * 命令式 Hook 契约（设计 §6.1）。[B0] 契约文件，实现归 B5。
+ *
+ * 补全与偏差：
+ * - 补全 `HookCommand`、`HookMatcherGroup`、`HookConfig`（hooks.json 文件形状）、
+ *   `HookRunResult`（单条命令结果）、`HookOutcome`（同一事件全部 Hook 合并后的结论）与
+ *   Runtime / AgentSession 需要的 `HookDispatcherApi`。
+ * - `HookDecision` = stdout JSON 里 `decision` 的取值；合并规则 deny > block > ask > allow。
+ */
+import type { PermissionMode } from "../permissions/types.js";
+export type HookEvent = "SessionStart" | "UserPromptSubmit" | "PreToolUse" | "PostToolUse" | "Stop" | "SubagentStop" | "PreCompact" | "Notification" | "SessionEnd";
+export declare const HOOK_EVENTS: readonly HookEvent[];
+export type HookDecision = "allow" | "deny" | "ask" | "block";
+export interface HookCommand {
+    type: "command";
+    command: string;
+    /** 缺省 60 000，上限 600 000。 */
+    timeoutMs?: number;
+}
+export interface HookMatcherGroup {
+    /** 缺省匹配全部；只在 Pre/PostToolUse 生效（语法见 §6.1 matcher）。 */
+    matcher?: string;
+    hooks: HookCommand[];
+}
+/** hooks.json 文件形状。 */
+export interface HookConfig {
+    version: 1;
+    hooks: Partial<Record<HookEvent, HookMatcherGroup[]>>;
+}
+export type HookSource = "user" | "profile" | "project" | "sdk";
+export interface HookNotification {
+    kind: "approval" | "settled" | "error" | "retry";
+    message: string;
+}
+/** stdin 输入：所有事件共有字段 + 事件特有字段。 */
+export interface HookInput {
+    hookEventName: HookEvent;
+    sessionId: string;
+    sessionFile?: string;
+    cwd: string;
+    transcriptPath?: string;
+    model: {
+        provider: string;
+        id: string;
+    };
+    permissionMode: PermissionMode;
+    depth: number;
+    /** 宿主适配器 id（未激活时缺省）。 */
+    host?: string;
+    /** SessionStart */
+    source?: "startup" | "resume" | "new" | "fork";
+    /** SessionEnd */
+    reason?: "exit" | "new" | "switch";
+    toolCallId?: string;
+    toolName?: string;
+    toolInput?: unknown;
+    toolResult?: {
+        content: string;
+        isError: boolean;
+    };
+    permissionDecision?: "allow" | "ask" | "deny";
+    prompt?: string;
+    lastAssistantText?: string;
+    /** 已由 Stop Hook 续跑过 → 处理器应避免再 block。 */
+    stopHookActive?: boolean;
+    tokensBefore?: number;
+    trigger?: "auto" | "manual";
+    notification?: HookNotification;
+    /** Pre/PostToolUse：本次调用来自 codemode 脚本里的 `tools.*`（设计 §5.5）。 */
+    viaCodemode?: boolean;
+    /** Pre/PostToolUse：codemode 内层调用时为外层 `codemode` 调用的 toolCallId。 */
+    parentToolCallId?: string;
+}
+/** stdout JSON 形状；空 / 非 JSON → 无决策。 */
+export interface HookOutput {
+    decision?: HookDecision;
+    reason?: string;
+    updatedInput?: unknown;
+    updatedPrompt?: string;
+    additionalContext?: string;
+    customInstructions?: string;
+    /** 任何事件：请求结束当前 run。 */
+    continue?: false;
+    /** TUI 不显示该 Hook 的输出。 */
+    suppressOutput?: true;
+}
+/** 单条 Hook 命令的执行结果。 */
+export interface HookRunResult {
+    event: HookEvent;
+    command: string;
+    source: HookSource;
+    /** null = 超时或被信号杀死。 */
+    exitCode: number | null;
+    timedOut: boolean;
+    durationMs: number;
+    stdout: string;
+    stderr: string;
+    /** stdout 解析成功时存在。 */
+    output?: HookOutput;
+}
+/** 同一事件下全部匹配 Hook 并行结束后的合并结论。 */
+export interface HookOutcome {
+    /** 最严：deny > block > ask > allow；无决策为 undefined。 */
+    decision?: HookDecision;
+    /** 决定性 Hook 的 reason，或退出码 2 时的 stderr。 */
+    reason?: string;
+    /** 只在恰好一个 Hook 返回时采用。 */
+    updatedInput?: unknown;
+    hasUpdatedInput: boolean;
+    updatedPrompt?: string;
+    /** 按配置顺序拼接。 */
+    additionalContext?: string;
+    customInstructions?: string;
+    /** 有 Hook 返回 `continue: false`。 */
+    stop: boolean;
+    suppressOutput: boolean;
+    results: HookRunResult[];
+    warnings: string[];
+}
+/** 所有事件共有的公共输入字段；dispatcher 每次运行时现取，调用方可按次覆盖（子 Agent）。 */
+export type HookCommonContext = Pick<HookInput, "sessionId" | "sessionFile" | "cwd" | "transcriptPath" | "model" | "permissionMode" | "depth" | "host">;
+/**
+ * `HookDispatcherApi.run` 第 4 参数：按次覆盖的公共字段。即 `Partial<HookCommonContext>`，
+ * 但在 `exactOptionalPropertyTypes` 下也接受显式 `undefined`（视为未给），方便子 Agent 直接传
+ * 可能为空的 `sessionFile`。
+ */
+export type HookContextOverrides = {
+    [K in keyof HookCommonContext]?: HookCommonContext[K] | undefined;
+};
+/** 事件对应的「事件特有」输入（公共字段由 dispatcher 填）。 */
+export type HookEventPayload = Omit<HookInput, "hookEventName" | "sessionId" | "sessionFile" | "cwd" | "transcriptPath" | "model" | "permissionMode" | "depth" | "host">;
+export interface HookDispatcherApi {
+    /** 该事件是否有任何已加载的 Hook（无则调用方可跳过构造输入）。 */
+    has(event: HookEvent, toolName?: string): boolean;
+    /**
+     * `context`：按次覆盖公共字段——子 Agent 传自己的 `depth / sessionId / sessionFile`，
+     * 未给的字段仍取 dispatcher 的缺省值；值为 `undefined` 的键视为未给。
+     */
+    run(event: HookEvent, payload: HookEventPayload, signal?: AbortSignal, context?: HookContextOverrides): Promise<HookOutcome>;
+    /** doctor / `/hooks` 列表。 */
+    list(): readonly {
+        event: HookEvent;
+        matcher?: string;
+        command: string;
+        source: HookSource;
+    }[];
+}

package/dist/hooks/types.js

@@ -0,0 +1,20 @@
+/**
+ * 命令式 Hook 契约（设计 §6.1）。[B0] 契约文件，实现归 B5。
+ *
+ * 补全与偏差：
+ * - 补全 `HookCommand`、`HookMatcherGroup`、`HookConfig`（hooks.json 文件形状）、
+ *   `HookRunResult`（单条命令结果）、`HookOutcome`（同一事件全部 Hook 合并后的结论）与
+ *   Runtime / AgentSession 需要的 `HookDispatcherApi`。
+ * - `HookDecision` = stdout JSON 里 `decision` 的取值；合并规则 deny > block > ask > allow。
+ */
+export const HOOK_EVENTS = [
+    "SessionStart",
+    "UserPromptSubmit",
+    "PreToolUse",
+    "PostToolUse",
+    "Stop",
+    "SubagentStop",
+    "PreCompact",
+    "Notification",
+    "SessionEnd",
+];

package/dist/host/api-impl.d.ts

@@ -0,0 +1,75 @@
+/**
+ * HostApi 实现（设计 §6.2）。[B5]
+ *
+ * 核心不知道宿主：这里把 HostApi 的各个面接到注入的依赖上——工具注册表（B3）、会话访问器
+ * （B2 组装后才可用，所以全部是惰性函数）、指令收集、broker 槽、sendUser、UI 通知。
+ * 事件总线 `AgentEventBus` 由 bootstrap 创建并交给 AgentSession 发事件；处理器只观察，
+ * 抛错记日志；`emit` 等待全部处理器（`session_shutdown` 需要被 await）。
+ */
+import type { AgentEventName, AgentEvents, ApprovalBroker, HostAdapter, HostAdapterHandle, HostApi, HostMode, InstructionSource } from "./types.js";
+import type { ToolRegistryApi } from "../tools/types.js";
+import type { WarmingDecisionHandler } from "../ai/cache/types.js";
+export type HostNotify = (message: string, level: "info" | "warn" | "error") => void;
+export type HostLogLevel = "debug" | "info" | "warn" | "error";
+export type HostLogger = (level: HostLogLevel, message: string, detail?: unknown) => void;
+type Handler<E extends AgentEventName> = (event: AgentEvents[E]) => void | Promise<void>;
+/** 进程内事件总线（宿主观察 AgentEvents）。 */
+export declare class AgentEventBus {
+    private readonly handlers;
+    private readonly log;
+    constructor(log?: HostLogger);
+    on<E extends AgentEventName>(name: E, handler: Handler<E>): () => void;
+    listenerCount(name: AgentEventName): number;
+    /** 依次调用处理器并等待；处理器异常记日志后继续。 */
+    emit<E extends AgentEventName>(name: E, event: AgentEvents[E]): Promise<void>;
+}
+/** 惰性会话访问器（AgentSession 组装前调用返回占位值）。 */
+export interface HostSessionAccess {
+    id(): string;
+    file(): string | undefined;
+    cwd(): string;
+    model(): {
+        provider: string;
+        id: string;
+    } | undefined;
+}
+export interface HostApiDeps {
+    mode: HostMode;
+    env?: Readonly<NodeJS.ProcessEnv>;
+    session: HostSessionAccess;
+    tools: ToolRegistryApi;
+    bus: AgentEventBus;
+    /** 运行中按 steer 入队；会话未组装时抛错。 */
+    sendUser(text: string, origin: string): Promise<"started" | "queued">;
+    /** 交互 / line 模式的 UI 通知；未提供时写 stderr。模式层也可晚绑定：`binding.setNotify()`。 */
+    notify?: HostNotify;
+    /** 状态变化回调（TUI 状态栏刷新）。 */
+    onStatus?: (key: string, text: string | undefined) => void;
+    log?: HostLogger;
+    /** stderr 写入（测试注入）。 */
+    stderr?: (text: string) => void;
+}
+/** createHostApi 的产物：api 交给适配器，其余给 bootstrap / AgentSession。 */
+export interface HostApiBinding {
+    readonly api: HostApi;
+    /** 适配器追加的指令（系统提示 host 节，按追加顺序）。 */
+    readonly instructions: readonly InstructionSource[];
+    /** 适配器设置的 broker（最后一次 setBroker 生效）。 */
+    broker(): ApprovalBroker | undefined;
+    /** 适配器注册的工具名。 */
+    readonly registeredTools: readonly string[];
+    /** 适配器禁用的工具名。 */
+    readonly disabledTools: readonly string[];
+    status(): ReadonlyMap<string, string>;
+    /** 绑定成 Runtime 持有的 handle。 */
+    handle(adapter: HostAdapter, source: string): HostAdapterHandle;
+    /**
+     * 晚绑定 UI 通知（模式层在 TUI / RPC 就绪后调用）；覆盖构造时的 `deps.notify`，
+     * 传 undefined 恢复为构造时的值（未提供则写 stderr）。
+     */
+    setNotify(fn?: HostNotify): void;
+    /** [W3-C0] 宿主经 `cache.onWarmingDecision` 注册的否决钩子（最后注册且未注销的那个）。 */
+    warmingDecider(): WarmingDecisionHandler | undefined;
+}
+export declare function createHostApi(deps: HostApiDeps): HostApiBinding;
+export {};

package/dist/host/api-impl.js

@@ -0,0 +1,173 @@
+/**
+ * HostApi 实现（设计 §6.2）。[B5]
+ *
+ * 核心不知道宿主：这里把 HostApi 的各个面接到注入的依赖上——工具注册表（B3）、会话访问器
+ * （B2 组装后才可用，所以全部是惰性函数）、指令收集、broker 槽、sendUser、UI 通知。
+ * 事件总线 `AgentEventBus` 由 bootstrap 创建并交给 AgentSession 发事件；处理器只观察，
+ * 抛错记日志；`emit` 等待全部处理器（`session_shutdown` 需要被 await）。
+ */
+import { AmaError } from "../errors.js";
+import { AMA_VERSION } from "../version.js";
+import { HOST_API_VERSION } from "./types.js";
+/** 进程内事件总线（宿主观察 AgentEvents）。 */
+export class AgentEventBus {
+    handlers = new Map();
+    log;
+    constructor(log = () => undefined) {
+        this.log = log;
+    }
+    on(name, handler) {
+        const set = this.handlers.get(name) ?? new Set();
+        set.add(handler);
+        this.handlers.set(name, set);
+        return () => {
+            set.delete(handler);
+        };
+    }
+    listenerCount(name) {
+        return this.handlers.get(name)?.size ?? 0;
+    }
+    /** 依次调用处理器并等待；处理器异常记日志后继续。 */
+    async emit(name, event) {
+        const set = this.handlers.get(name);
+        if (set === undefined || set.size === 0)
+            return;
+        for (const handler of [...set]) {
+            try {
+                await handler(event);
+            }
+            catch (error) {
+                this.log("error", `宿主事件处理器异常（${name}）`, error);
+            }
+        }
+    }
+}
+const TOOL_NAME = /^[a-z][a-z0-9_]{1,63}$/;
+function validateTool(tool) {
+    if (typeof tool !== "object" || tool === null) {
+        throw new AmaError("invalid_arguments", "tools.register：工具定义应为对象");
+    }
+    if (typeof tool.name !== "string" || !TOOL_NAME.test(tool.name)) {
+        throw new AmaError("invalid_arguments", `tools.register：工具名不合法：${String(tool.name)}`);
+    }
+    if (typeof tool.execute !== "function") {
+        throw new AmaError("invalid_arguments", `tools.register：${tool.name} 缺少 execute()`);
+    }
+    if (!["read", "write", "execute"].includes(tool.permission)) {
+        throw new AmaError("invalid_arguments", `tools.register：${tool.name} 的 permission 不合法`);
+    }
+}
+export function createHostApi(deps) {
+    const instructions = [];
+    const registeredTools = [];
+    const disabledTools = [];
+    const status = new Map();
+    let broker;
+    const warmingHandlers = [];
+    let notify = deps.notify;
+    const writeErr = deps.stderr ?? ((text) => void process.stderr.write(text));
+    const log = deps.log ??
+        ((level, message) => {
+            if (level === "warn" || level === "error")
+                writeErr(`ama: [host] ${message}\n`);
+        });
+    const api = Object.freeze({
+        version: HOST_API_VERSION,
+        agent: Object.freeze({ name: "ama", version: AMA_VERSION }),
+        env: Object.freeze({ ...(deps.env ?? process.env) }),
+        mode: deps.mode,
+        session: Object.freeze({
+            id: () => deps.session.id(),
+            file: () => deps.session.file(),
+            cwd: () => deps.session.cwd(),
+            model: () => deps.session.model(),
+        }),
+        tools: Object.freeze({
+            register(tool) {
+                validateTool(tool);
+                if (deps.tools.get(tool.name) !== undefined) {
+                    throw new AmaError("tool_exists", `tools.register：工具 ${tool.name} 已存在`);
+                }
+                deps.tools.register(tool, "host");
+                registeredTools.push(tool.name);
+            },
+            disable(name) {
+                deps.tools.disable(name);
+                if (!disabledTools.includes(name))
+                    disabledTools.push(name);
+            },
+            list: () => deps.tools.list(),
+        }),
+        instructions: Object.freeze({
+            add(source) {
+                if (source.kind === "file" && typeof source.path !== "string") {
+                    throw new AmaError("invalid_arguments", "instructions.add：file 需要 path");
+                }
+                if (source.kind === "text" && typeof source.text !== "string") {
+                    throw new AmaError("invalid_arguments", "instructions.add：text 需要 text");
+                }
+                instructions.push({ ...source });
+            },
+        }),
+        events: Object.freeze({
+            on: (name, handler) => deps.bus.on(name, handler),
+        }),
+        approvals: Object.freeze({
+            setBroker(next) {
+                if (typeof next?.ask !== "function") {
+                    throw new AmaError("invalid_arguments", "approvals.setBroker：broker 需要 ask()");
+                }
+                broker = next;
+            },
+        }),
+        messages: Object.freeze({
+            sendUser: (text, origin) => deps.sendUser(text, origin ?? "host"),
+        }),
+        ui: Object.freeze({
+            notify(message, level = "info") {
+                // 交互 / line 由 UI 显示；rpc 由模式转成事件；print（或未注入）写 stderr。
+                if (notify !== undefined && deps.mode !== "print") {
+                    notify(message, level);
+                    return;
+                }
+                writeErr(`ama: [host${level === "info" ? "" : ` ${level}`}] ${message}\n`);
+            },
+            setStatus(key, text) {
+                if (text === undefined || text === "")
+                    status.delete(key);
+                else
+                    status.set(key, text);
+                deps.onStatus?.(key, text);
+            },
+        }),
+        log,
+        cache: Object.freeze({
+            onWarmingDecision(handler) {
+                if (typeof handler !== "function") {
+                    throw new AmaError("invalid_arguments", "cache.onWarmingDecision：需要函数");
+                }
+                warmingHandlers.push(handler);
+                return () => {
+                    const index = warmingHandlers.lastIndexOf(handler);
+                    if (index >= 0)
+                        warmingHandlers.splice(index, 1);
+                };
+            },
+        }),
+    });
+    return {
+        api,
+        instructions,
+        broker: () => broker,
+        registeredTools,
+        disabledTools,
+        status: () => status,
+        handle(adapter, source) {
+            return { adapter, api, source, status: () => status };
+        },
+        setNotify(fn) {
+            notify = fn ?? deps.notify;
+        },
+        warmingDecider: () => warmingHandlers.at(-1),
+    };
+}

package/dist/host/loader.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `--host` 宿主适配器加载（设计 §6.2、§11.1 第 13 步）。[B5]
+ *
+ * - 路径相对 cwd 解析；`.cjs` 用 createRequire，`.mjs` 用动态 import，`.js` 先 require、
+ *   遇到 ESM 再动态 import。模块导出可以是 `default`（ESM 默认导出 / CJS `module.exports`）
+ *   或具名的 `hostApi` + `create`。
+ * - 动态 import 的说明符是变量：bundle 是 CJS，esbuild 只改写字面量说明符的 `import()`，
+ *   变量说明符原样保留，所以 bundle 里也能加载 ESM 适配器。
+ * - 版本：`hostApi !== HOST_API_VERSION` → StartupError 78；加载失败 / 形状不对 → 6。
+ * - `create(api)` 超时 10 s 或抛错 → 6；返回 undefined → 不激活。
+ */
+import type { HostAdapter, HostAdapterHandle, HostApi, HostModule } from "./types.js";
+import type { HostApiBinding } from "./api-impl.js";
+export declare const HOST_CREATE_TIMEOUT_MS = 10000;
+/** 从模块命名空间 / exports 取出 HostModule 形状。 */
+export declare function extractHostModule(namespace: unknown, label: string): HostModule;
+/** 加载并校验适配器模块。 */
+export declare function loadHostModule(spec: string, cwd?: string): Promise<HostModule>;
+/** 调 create(api)；返回 undefined 表示不激活。 */
+export declare function createAdapter(module: HostModule, api: HostApi, label: string, timeoutMs?: number): Promise<HostAdapter | undefined>;
+export interface ActivateHostInput {
+    /** 模块路径或已加载的 HostModule（SDK）。 */
+    module: string | HostModule;
+    binding: HostApiBinding;
+    cwd?: string;
+    timeoutMs?: number;
+}
+/** 第 13 步：加载 → 版本校验 → create；返回 handle 或 undefined（未激活）。 */
+export declare function activateHost(input: ActivateHostInput): Promise<HostAdapterHandle | undefined>;
+/** 调 dispose（幂等；异常交给 onError）。 */
+export declare function disposeHost(handle: HostAdapterHandle | undefined, onError?: (error: unknown) => void): Promise<void>;

package/dist/host/loader.js

@@ -0,0 +1,147 @@
+/**
+ * `--host` 宿主适配器加载（设计 §6.2、§11.1 第 13 步）。[B5]
+ *
+ * - 路径相对 cwd 解析；`.cjs` 用 createRequire，`.mjs` 用动态 import，`.js` 先 require、
+ *   遇到 ESM 再动态 import。模块导出可以是 `default`（ESM 默认导出 / CJS `module.exports`）
+ *   或具名的 `hostApi` + `create`。
+ * - 动态 import 的说明符是变量：bundle 是 CJS，esbuild 只改写字面量说明符的 `import()`，
+ *   变量说明符原样保留，所以 bundle 里也能加载 ESM 适配器。
+ * - 版本：`hostApi !== HOST_API_VERSION` → StartupError 78；加载失败 / 形状不对 → 6。
+ * - `create(api)` 超时 10 s 或抛错 → 6；返回 undefined → 不激活。
+ */
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { StartupError } from "../errors.js";
+import { HOST_API_VERSION } from "./types.js";
+const EXIT_HOST = 6;
+const EXIT_HOST_VERSION = 78;
+export const HOST_CREATE_TIMEOUT_MS = 10_000;
+/** 变量作说明符的 `import()`：esbuild 打 CJS 时原样保留（字面量说明符才会被改写成 require）。 */
+function dynamicImport(specifier) {
+    return import(specifier);
+}
+function loadFailure(message, cause) {
+    return new StartupError("host_load_failed", message, EXIT_HOST, cause === undefined ? {} : { cause });
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function importModule(path) {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".mjs"))
+        return dynamicImport(pathToFileURL(path).href);
+    const require = createRequire(pathToFileURL(path).href);
+    if (lower.endsWith(".cjs"))
+        return require(path);
+    try {
+        return require(path);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ERR_REQUIRE_ESM" ||
+            code === "ERR_REQUIRE_ASYNC_MODULE" ||
+            error instanceof SyntaxError) {
+            return dynamicImport(pathToFileURL(path).href);
+        }
+        throw error;
+    }
+}
+function isRecord(value) {
+    return (typeof value === "object" || typeof value === "function") && value !== null;
+}
+/** 从模块命名空间 / exports 取出 HostModule 形状。 */
+export function extractHostModule(namespace, label) {
+    const candidates = [];
+    if (isRecord(namespace)) {
+        if (isRecord(namespace["default"])) {
+            const inner = namespace["default"];
+            // CJS 经 import 加载时 default 再套一层 default。
+            if (isRecord(inner["default"]) && !("hostApi" in inner))
+                candidates.push(inner["default"]);
+            candidates.push(inner);
+        }
+        candidates.push(namespace);
+    }
+    const found = candidates.find((c) => isRecord(c) && ("hostApi" in c || "create" in c));
+    if (!isRecord(found))
+        throw loadFailure(`${label}: 不是宿主适配器模块（缺少 hostApi / create 导出）`);
+    if (found["hostApi"] !== HOST_API_VERSION) {
+        throw new StartupError("host_version_mismatch", `${label}: 宿主适配器 hostApi=${String(found["hostApi"])}，ama 需要 ${HOST_API_VERSION}`, EXIT_HOST_VERSION);
+    }
+    if (typeof found["create"] !== "function")
+        throw loadFailure(`${label}: 缺少 create(api) 函数`);
+    return found;
+}
+/** 加载并校验适配器模块。 */
+export async function loadHostModule(spec, cwd = process.cwd()) {
+    const path = isAbsolute(spec) ? spec : resolve(cwd, spec);
+    if (!existsSync(path))
+        throw loadFailure(`宿主适配器不存在：${path}`);
+    let namespace;
+    try {
+        namespace = await importModule(path);
+    }
+    catch (error) {
+        throw loadFailure(`宿主适配器加载失败：${path}：${errorText(error)}`, error);
+    }
+    return extractHostModule(namespace, path);
+}
+/** 调 create(api)；返回 undefined 表示不激活。 */
+export async function createAdapter(module, api, label, timeoutMs = HOST_CREATE_TIMEOUT_MS) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(loadFailure(`${label}: create() 超过 ${timeoutMs} ms 未返回`)), timeoutMs);
+    });
+    let adapter;
+    try {
+        adapter = await Promise.race([Promise.resolve().then(() => module.create(api)), timeout]);
+    }
+    catch (error) {
+        if (error instanceof StartupError)
+            throw error;
+        throw loadFailure(`${label}: create() 失败：${errorText(error)}`, error);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (adapter === undefined || adapter === null)
+        return undefined;
+    if (typeof adapter !== "object" || typeof adapter.id !== "string" || adapter.id === "") {
+        throw loadFailure(`${label}: create() 返回的适配器缺少 id`);
+    }
+    return adapter;
+}
+/** 第 13 步：加载 → 版本校验 → create；返回 handle 或 undefined（未激活）。 */
+export async function activateHost(input) {
+    let module;
+    let source;
+    if (typeof input.module === "string") {
+        source = isAbsolute(input.module)
+            ? input.module
+            : resolve(input.cwd ?? process.cwd(), input.module);
+        module = await loadHostModule(source);
+    }
+    else {
+        source = "sdk";
+        module = extractHostModule(input.module, "sdk");
+    }
+    const adapter = await createAdapter(module, input.binding.api, source, input.timeoutMs);
+    return adapter === undefined ? undefined : input.binding.handle(adapter, source);
+}
+const disposed = new WeakSet();
+/** 调 dispose（幂等；异常交给 onError）。 */
+export async function disposeHost(handle, onError = () => undefined) {
+    if (handle === undefined)
+        return;
+    if (disposed.has(handle))
+        return;
+    disposed.add(handle);
+    try {
+        await handle.adapter.dispose?.();
+    }
+    catch (error) {
+        onError(error);
+    }
+}