@syrkos/filaxis 0.1.0-alpha.10

package/src/agent-toolkit.ts

@@ -0,0 +1,247 @@
+/**
+ * agent-toolkit.ts — 原生 Agent 工具集（Gemini 试用反馈 #3）
+ *
+ * 一行 `createAgentToolkit(stack)` 生成 LLM 工具面（run_command / spawn_and_observe /
+ * stop_and_verify）——OpenAI/Anthropic/Vercel AI SDK 通吃的 {tools, handlers} 双层结构：
+ * 定义层喂模型，执行层留宿主（桥到任意框架）。语义契约（退出码是数据/终态三态/
+ * 就绪握手）由内核承载，宿主零胶水。
+ */
+import type { RuntimeStack } from "./runtime-stack.js";
+import { editFile } from "./file-edit.js";
+import type { RuntimeDriver } from "./driver.js";
+
+export interface AgentToolDef {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>; // JSON Schema
+    };
+}
+
+export interface AgentToolHandlers {
+    run_command(args: { command: string; timeout_ms?: number; layer?: string }): Promise<{
+        stdout: string; stderr: string; exit_code: number; effective_user?: string;
+    }>;
+    read_file(args: { path: string; layer?: string }): Promise<{ path: string; content: string; size: number; mtime_ms: number }>;
+    edit_file(args: { path: string; old: string; new: string; all?: boolean; layer?: string }): Promise<{
+        path: string; occurrences: number; bytes_before: number; bytes_after: number;
+    }>;
+    observe_stream(args: { command: string; duration_ms?: number; stream?: "stdout" | "stderr" | "both"; name?: string }): Promise<{
+        session_id: string; lines: Array<{ stream: string; text: string }>;
+    }>;
+    spawn_and_observe(args: { command: string; ready_marker?: string; error_pattern?: string; name?: string }): Promise<{
+        session_id: string; log_base: string; note?: string;
+    }>;
+    stop_and_verify(args: { session_id: string }): Promise<{
+        status: "exited" | "stopped" | "unknown"; exit_code?: number | null; note?: string;
+    }>;
+}
+
+export interface AgentToolkit {
+    tools: AgentToolDef[];
+    handlers: AgentToolHandlers;
+    /** 工具面绑定的层（缺省 local；远端层经 stack.connect 后传入重绑） */
+    readonly layer: Promise<RuntimeDriver>;
+}
+
+export interface AgentToolkitOptions {
+    /** 层描述符（缺省 local）；也可直接传已连接的 driver */
+    descriptor?: { driver: string; target?: string; config?: Record<string, unknown> };
+    driver?: RuntimeDriver;
+    /** 就绪握手与 watcher 轮询的超时上限 */
+    readyTimeoutMs?: number;
+}
+
+const TOOL_DEFS: AgentToolDef[] = [
+    {
+        type: "function",
+        function: {
+            name: "run_command",
+            description:
+                "执行一次性命令。退出码如实返回（非零不是异常——是数据，供条件分支）；" +
+                "只有无法执行（超时/中断/连接死）才报错。stdout 与 stderr 分离返回。",
+            parameters: {
+                type: "object",
+                properties: {
+                    command: { type: "string", description: "shell 命令" },
+                    timeout_ms: { type: "number", description: "超时毫秒（缺省 120000）" },
+                },
+                required: ["command"],
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "spawn_and_observe",
+            description:
+                "启动长跑任务（立即返回句柄不阻塞）。可选就绪标记（ready_marker——回溯热窗口，" +
+                "快输出进程竞态安全）与错误模式（error_pattern——命中即自动收摊防遗忘泄漏）。" +
+                "后续用 stop_and_verify 停止并核实终态。",
+            parameters: {
+                type: "object",
+                properties: {
+                    command: { type: "string", description: "长跑命令" },
+                    ready_marker: { type: "string", description: "就绪标记（如 'listening on'）" },
+                    error_pattern: { type: "string", description: "错误模式（命中即收摊）" },
+                    name: { type: "string", description: "会话名（人读前缀）" },
+                },
+                required: ["command"],
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "stop_and_verify",
+            description:
+                "停止任务并核实终态。status 三态：exited=拿到退出码；stopped=终止已核实；" +
+                "unknown=核实不可达（非成功非失败——重试核实或显式上报，严禁当已清理）。",
+            parameters: {
+                type: "object",
+                properties: {
+                    session_id: { type: "string", description: "spawn_and_observe 返回的 session_id" },
+                },
+                required: ["session_id"],
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "read_file",
+            description: "读取远端层文件（UTF-8 文本）。返回内容与 (size, mtime_ms)。",
+            parameters: {
+                type: "object",
+                properties: {
+                    path: { type: "string" },
+                },
+                required: ["path"],
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "edit_file",
+            description:
+                "受控编辑远端文件：精确替换（唯一命中校验，all=true 全替换）+ TOCTOU 乐观锁（他人先写则拒绝）" +
+                "+ base64 保真写回（零 Shell 转义——绝不 sed -i）。未命中/多处命中/冲突均报错不盲写。",
+            parameters: {
+                type: "object",
+                properties: {
+                    path: { type: "string" },
+                    old: { type: "string", description: "待替换片段（含足够上下文唯一）" },
+                    new: { type: "string" },
+                    all: { type: "boolean", description: "多处命中全替换（缺省报错）" },
+                },
+                required: ["path", "old", "new"],
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "observe_stream",
+            description:
+                "长跑观察（限时快照）：启动长跑会话并观察一段时间（缺省 8s）按流过滤（stderr/stdout/both），" +
+                "返回行对象（带 stream 标记）。跨流序为到达序。",
+            parameters: {
+                type: "object",
+                properties: {
+                    command: { type: "string" },
+                    duration_ms: { type: "number", description: "观察时长（缺省 8000）" },
+                    stream: { type: "string", enum: ["stdout", "stderr", "both"], description: "流过滤（缺省 both）" },
+                    name: { type: "string" },
+                },
+                required: ["command"],
+            },
+        },
+    },
+];
+
+/** 生成 Agent 工具集（定义层 + 执行层；宿主桥接到任意 LLM 框架） */
+export function createAgentToolkit(stack: RuntimeStack, opts: AgentToolkitOptions = {}): AgentToolkit {
+    const layer: Promise<RuntimeDriver> = opts.driver
+        ? Promise.resolve(opts.driver)
+        : stack.connect(opts.descriptor ?? { driver: "local" });
+    const readyTimeoutMs = opts.readyTimeoutMs ?? 15_000;
+
+    return {
+        tools: TOOL_DEFS,
+        layer,
+        handlers: {
+            async run_command({ command, timeout_ms }) {
+                const drv = await layer;
+                const r = await drv.exec(command, { timeoutMs: timeout_ms });
+                return {
+                    stdout: r.stdout, stderr: r.stderr, exit_code: r.exitCode,
+                    effective_user: r.effectiveUser,
+                };
+            },
+            async spawn_and_observe({ command, ready_marker, error_pattern, name }) {
+                const drv = await layer;
+                const h = await drv.execSession(command, name ? { name } : undefined);
+                if (error_pattern) {
+                    drv.watchSession(h.sessionId, { pattern: error_pattern, once: false, thenStop: true });
+                }
+                let note: string | undefined;
+                if (ready_marker) {
+                    // 就绪握手（回溯热窗口——快输出进程竞态安全）
+                    const t0 = Date.now();
+                    for (;;) {
+                        const lines = await drv.tailSession(h.sessionId, 50);
+                        if (lines.some((l) => l.includes(ready_marker))) { note = "ready"; break; }
+                        if (Date.now() - t0 > readyTimeoutMs) {
+                            await drv.stopSession(h.sessionId).catch(() => undefined);
+                            throw new Error(`ready 超时（${readyTimeoutMs}ms 未见 '${ready_marker}'——已自动停止）`);
+                        }
+                        await new Promise((r) => setTimeout(r, 100));
+                    }
+                }
+                return { session_id: h.sessionId, log_base: h.logBase, note };
+            },
+            async read_file({ path }) {
+                const drv = await layer;
+                if (!drv.fs.stat) throw new Error("该层不支持 read_file 的元数据（fs.stat 缺席）");
+                const st = await drv.fs.stat(path);
+                if (!st) throw new Error(`文件不存在: ${path}`);
+                const content = await drv.fs.readFile(path);
+                return { path, content, size: st.size, mtime_ms: st.mtimeMs };
+            },
+            async edit_file({ path, old, new: newStr, all }) {
+                const drv = await layer;
+                const r = await editFile(drv, path, old, newStr, { all });
+                return { path: r.path, occurrences: r.occurrences, bytes_before: r.bytesBefore, bytes_after: r.bytesAfter };
+            },
+            async observe_stream({ command, duration_ms, stream, name }) {
+                const drv = await layer;
+                const h = await drv.execSession(command, name ? { name } : undefined);
+                const dur = duration_ms ?? 8000;
+                await new Promise((r) => setTimeout(r, dur));
+                // 双流：driver 带 sessions.tailLines（local/ssh 均有）用行对象；否则 stdout 投影兜底
+                const anyDrv = drv as unknown as {
+                    sessions?: { tailLines?: (id: string, n?: number) => Array<{ stream: string; text: string }> };
+                };
+                const lines = anyDrv.sessions?.tailLines
+                    ? anyDrv.sessions.tailLines(h.sessionId, 500)
+                    : (await drv.tailSession(h.sessionId, 500)).map((t) => ({ stream: "stdout", text: t }));
+                const filtered = (stream && stream !== "both") ? lines.filter((l) => l.stream === stream) : lines;
+                await drv.stopSession(h.sessionId).catch(() => undefined);
+                return { session_id: h.sessionId, lines: filtered };
+            },
+            async stop_and_verify({ session_id }) {
+                const drv = await layer;
+                const r = (await drv.stopSession(session_id)) as { status?: string; exitCode?: number | null };
+                if (r.status === "exited") return { status: "exited", exit_code: r.exitCode };
+                if (r.status === "stopped") return { status: "stopped", note: "终止已核实（SIGKILL 升级在场）" };
+                if (r.status === "unknown") return { status: "unknown", note: "核实不可达——重连后核实或显式上报" };
+                // 无 status 的旧形态 driver：exitCode 可判 exited
+                return r.exitCode != null
+                    ? { status: "exited", exit_code: r.exitCode }
+                    : { status: "stopped", note: "已发终止（旧形态 driver——建议升级内核取三态）" };
+            },
+        },
+    };
+}

package/src/dialect.ts

@@ -0,0 +1,100 @@
+/**
+ * dialect.ts — 远端命令方言适配层（FEAT-14：GNU · BSD · busybox 三族原语探测与渲染）
+ *
+ * 动机（生产实锤）：`base64 -w 0` 为纯 GNU 方言——FreeBSD/OPNsense 的 base64
+ * 不认 `-w`（BSD 用 `-b`，解码历史差异 `-d`/`-D`）；sha256 工具 Linux=sha256sum /
+ * FreeBSD=/sbin/sha256 -q / 精简容器=busybox 或 openssl dgst。目标环境
+ * （OPNsense/Alpine）不探测必错。探测结果**按连接缓存**（探测键由调用方持有）。
+ */
+import type { ExecResult } from "./driver.js";
+
+export type DialectFamily = "gnu" | "bsd" | "busybox" | "openssl-fallback" | "unknown";
+
+/** 一套已探测的远端原语（渲染为 argv 前缀，拼接数据参数后执行） */
+export interface RemoteDialect {
+    family: DialectFamily;
+    /** 编码（无换行输出）：["base64","-w","0"]（GNU）/ ["base64"]（BSD·默认不折行） */
+    base64Encode: string[];
+    /** 解码：GNU ["base64","-d"] / BSD ["base64","-D"] */
+    base64Decode: string[];
+    /** sha256 摘要：["sha256sum"] / ["sha256","-q"] / busybox ["sha256sum"] / openssl ["openssl","dgst","-sha256"] */
+    sha256: string[];
+}
+
+export type ExecFn = (command: string) => Promise<Pick<ExecResult, "stdout" | "exitCode">>;
+
+/** 探测失败时的兜底：全部原语标记不可用（显式，不静默用错方言） */
+export const NULL_DIALECT: RemoteDialect = {
+    family: "unknown",
+    base64Encode: [],
+    base64Decode: [],
+    sha256: [],
+};
+
+async function tryCmd(exec: ExecFn, cmd: string): Promise<{ ok: boolean; stdout: string }> {
+    try {
+        const r = await exec(cmd);
+        return { ok: r.exitCode === 0, stdout: r.stdout };
+    } catch {
+        return { ok: false, stdout: "" };
+    }
+}
+
+/** 探测远端方言（每命令独立判定；缺原语=该族标记跳过，非报错） */
+export async function probeDialect(exec: ExecFn): Promise<RemoteDialect> {
+    // ── base64 编码：GNU 认 -w 0，BSD 报错（认 -b）──
+    const gnuEnc = await tryCmd(exec, "printf filaxis | base64 -w 0");
+    if (gnuEnc.ok && gnuEnc.stdout.includes("ZmlsYXhpcw==")) {
+        // GNU base64 在场；解码参数再探（GNU -d）
+        const gnuDec = await tryCmd(exec, "printf ZmlsYXhpcw== | base64 -d");
+        if (gnuDec.ok && gnuDec.stdout.includes("filaxis")) {
+            const sha = await detectSha256(exec);
+            return { family: sha.family, base64Encode: ["base64", "-w", "0"], base64Decode: ["base64", "-d"], sha256: sha.argv };
+        }
+    }
+    // ── BSD：无 -w 默认不折行；解码 -D（老 BSD）或 -d（新）──
+    const bsdEnc = await tryCmd(exec, "printf filaxis | base64");
+    if (bsdEnc.ok && bsdEnc.stdout.replace(/\s+/g, "").includes("ZmlsYXhpcw==")) {
+        const decD = await tryCmd(exec, "printf ZmlsYXhpcw== | base64 -d");
+        const decFlag = decD.ok && decD.stdout.includes("filaxis") ? "-d" : "-D";
+        const sha = await detectSha256(exec);
+        return { family: sha.family, base64Encode: ["base64"], base64Decode: ["base64", decFlag], sha256: sha.argv };
+    }
+    // ── base64 完全缺席（极简容器）：全 NULL（调用方显式降级别的原语路径）──
+    return { ...NULL_DIALECT, sha256: (await detectSha256(exec)).argv };
+}
+
+const HEX64 = /[0-9a-f]{64}/;
+
+async function detectSha256(exec: ExecFn): Promise<{ family: DialectFamily; argv: string[] }> {
+    const coreutils = await tryCmd(exec, "printf filaxis | sha256sum");
+    if (coreutils.ok && HEX64.test(coreutils.stdout)) {
+        return { family: "gnu", argv: ["sha256sum"] };
+    }
+    const bsd = await tryCmd(exec, "printf filaxis | sha256 -q");
+    if (bsd.ok && HEX64.test(bsd.stdout.trim())) {
+        return { family: "bsd", argv: ["sha256", "-q"] };
+    }
+    const openssl = await tryCmd(exec, "printf filaxis | openssl dgst -sha256");
+    if (openssl.ok && HEX64.test(openssl.stdout)) {
+        return { family: "openssl-fallback", argv: ["openssl", "dgst", "-sha256"] };
+    }
+    return { family: "unknown", argv: [] };
+}
+
+/** 按连接缓存：探测键（调用方用连接身份）→ 方言 */
+export class DialectCache {
+    private cache = new Map<string, RemoteDialect>();
+
+    async get(probeKey: string, exec: ExecFn, force = false): Promise<RemoteDialect> {
+        if (!force && this.cache.has(probeKey)) return this.cache.get(probeKey)!;
+        const d = await probeDialect(exec);
+        this.cache.set(probeKey, d);
+        return d;
+    }
+
+    invalidate(probeKey?: string): void {
+        if (probeKey) this.cache.delete(probeKey);
+        else this.cache.clear();
+    }
+}

package/src/driver.ts

@@ -0,0 +1,142 @@
+/**
+ * driver.ts — RuntimeDriver 统一契约（多 Transport 执行内核）
+ *
+ * 净室平移自 Aethelum-Nexus `src/core/tools/runtime/driver.ts`
+ * （源锚点：Aethelum-Nexus dev @ 8977ff3），按 REQ-0001 OSS 化改造：
+ * - ExecResult 新增 stderr（FEAT-03：exec 通道 stdout/stderr 物理分离；源版无此字段）
+ * - ExecOptions 新增 channel（FEAT-03：通道显式化 "exec" | "pty"，缺省 exec）
+ * - 剔除 interactionManager/sessionId（凭据交互策略属 FEAT-12，M1 后续批次设计后进契约）
+ * - capabilities 保留为纯数据标签（语义解释权归消费方；源注释中的策略引擎字样改为通用表述）
+ *
+ * 已知 driver 快捷方式（可自动生成 launchCmd）：
+ *   "local"    — 进程内原生执行，唯一特殊值
+ *   "ssh"      — ssh [-options] <target>
+ *   "docker"   — <runtime> exec -i <target> <shell> -i  (runtime 默认 docker，可换 podman/nerdctl 等)
+ *   "k8s"      — <runtime> exec -i [-n ns] <target> -- <shell> -i  (runtime 默认 kubectl，可换 oc/k3s 等)
+ *   "teleport" — tsh ssh [--cluster=c] [login@]<target>
+ *
+ * 任意字符串也合法（e.g. "nix-shell", "conda", "distrobox"），
+ * 但必须在 config.launchCmd 中提供完整的启动命令。
+ */
+
+export type RuntimeDriverType = "local" | "browser" | "ssh" | "docker" | "k8s" | (string & {});
+
+export interface RuntimeDescriptor {
+    driver: RuntimeDriverType;
+    /** 连接目标（ssh: user@host；container: 容器名/ID；自定义: 任意标签） */
+    target?: string;
+    /** 驱动配置：sshOptions / shell / runtime / namespace / launchCmd 等 */
+    config?: Record<string, unknown>;
+    /** 持久会话 ID（tmux 后端管理的长连接标识，跨重启恢复用） */
+    terminalId?: string;
+    /**
+     * 持久化的工作目录。调用方执行 cd 后异步更新，跨重启恢复时用于重建上下文。
+     */
+    cwd?: string;
+    /**
+     * 该运行时环境的能力标签列表（纯数据——消费方可据此做环境感知策略，
+     * 内核不解释）。内置约定示例：
+     *   "read-only"   — 禁止写操作
+     *   "production"  — 生产环境，高危操作从严
+     *   "sandbox"     — 沙箱环境，可放宽检查
+     */
+    capabilities?: string[];
+}
+
+/**
+ * 执行通道（FEAT-03）：
+ * - "exec"（缺省）——非 PTY 通道：stdout/stderr 物理分离；层上下文经
+ *   cwd/env/enterSteps 管线重放拼装（独立 channel 复现层进入路径）
+ * - "pty"——层内 PTY marker 协议：天然继承层内交互状态（su 身份/cd/export），
+ *   stderr 混流为终端语义（不承诺分离）
+ */
+export type ExecChannel = "exec" | "pty";
+
+export interface ExecOptions {
+    timeoutMs?: number;
+    env?: Record<string, string>;
+    /** 临时覆盖命令执行路径 */
+    cwd?: string;
+    /** 执行通道（缺省 "exec"） */
+    channel?: ExecChannel;
+    /** AbortSignal 硬中断子进程：abort 时子进程立即 SIGTERM，Promise 以 AbortError reject */
+    signal?: AbortSignal;
+}
+
+export interface ExecResult {
+    stdout: string;
+    /** exec 通道物理分离的 stderr；pty 通道下并入 stdout（终端语义） */
+    stderr: string;
+    exitCode: number;
+    /** 执行完成时该通道命令上下文的有效用户（marker 尾缀 id -un 实测——层内 su/sudo 变更可追踪） */
+    effectiveUser?: string;
+}
+
+export interface FileEntry {
+    name: string;
+    isDirectory: boolean;
+    size?: number;
+    mtime?: number;
+}
+
+export interface FileStat {
+    mtimeMs: number;
+    size: number;
+}
+
+export interface FileSystemDriver {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    readdir(path: string): Promise<FileEntry[]>;
+    rm(path: string, options?: { recursive?: boolean; force?: boolean }): Promise<void>;
+    mkdir(path: string, options?: { recursive?: boolean }): Promise<void>;
+    /** 可选 stat（mtimeMs/size）——先读后写闸的数据依赖 */
+    stat?(path: string): Promise<FileStat | null>;
+    /**
+     * 可选 readBase64——二进制安全读取。readFile 返回 UTF-8 字符串会破坏
+     * 二进制字节；本方法返回裸 base64。local 层实现；远端层无此方法时
+     * 调用方应显式处理「该层不支持二进制读取」。
+     */
+    readBase64?(path: string): Promise<string>;
+}
+
+import type {
+    SessionStartOptions,
+    SessionHandleInfo,
+    WatchOptions,
+    ReadLogOptions,
+} from "./session-types.js";
+
+export interface RuntimeDriver {
+    // 基础信息
+    descriptor: RuntimeDescriptor;
+
+    // 核心环境能力
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+
+    // ── 长跑会话生命周期（spawn 即返 + 落盘日志 + 热窗口 + watcher）──
+    /** 启动长跑会话（立即返回） */
+    execSession(command: string, opts?: SessionStartOptions): Promise<SessionHandleInfo>;
+    /** 热窗口快照：最近 n 行 */
+    tailSession(sessionId: string, lines?: number): Promise<string[]>;
+    /** 读会话日志文件（全量/大范围） */
+    readSessionLog(sessionId: string, opts?: ReadLogOptions): Promise<string>;
+    /** 注册 watcher：命中 → 会话事件（内核事件接口，见 FEAT-09） */
+    watchSession(sessionId: string, opts: WatchOptions): { cancel(): void };
+    /** 停止会话（SIGTERM→SIGKILL 升级；发出后核实终态） */
+    stopSession(sessionId: string): Promise<{ exitCode?: number | null }>;
+    /** 会话列表 */
+    listSessions(): Array<{ sessionId: string; command: string; running: boolean; startedAt: number }>;
+
+    // 原生路径解析与环境获取
+    getCwd(): Promise<string>;
+    getEnv(key: string): Promise<string | undefined>;
+
+    // 强隔离文件系统
+    fs: FileSystemDriver;
+
+    // 初始化与销毁
+    init(): Promise<void>;
+    destroy(): Promise<void>;
+}

package/src/events.ts

@@ -0,0 +1,96 @@
+/**
+ * events.ts — 内核事件总线（FEAT-09：EventEmitter + AsyncIterable 双形态，零队列依赖）
+ *
+ * 消费方异常与内核生命周期隔离（AC-10：on 回调异常不杀内核与流）。
+ * AsyncIterable 形态为有界队列：满时丢最旧并累计 dropped（慢消费者可查证——
+ * 不承诺无限缓冲，与热窗口「有限历史」同一哲学）。
+ */
+import { EventEmitter } from "node:events";
+
+const DEFAULT_ITER_QUEUE_MAX = 1024;
+
+export interface EventBusOptions {
+    /** iterable 形态的每订阅队列上限（满丢最旧并计数） */
+    queueMax?: number;
+}
+
+type Handler<E> = (ev: E) => void;
+
+export class EventBus<E extends { type: string }> {
+    private emitter = new EventEmitter();
+    private readonly queueMax: number;
+    /** 每个迭代订阅一份独立队列：{queue, dropped, active} */
+    private iterables = new Set<{ queue: E[]; dropped: number; active: boolean }>();
+
+    constructor(opts: EventBusOptions = {}) {
+        this.queueMax = opts.queueMax ?? DEFAULT_ITER_QUEUE_MAX;
+        this.emitter.setMaxListeners(0); // 多订阅是常态（每会话/每流），不告警
+    }
+
+    /** 订阅（可按 type 过滤）；返回退订函数 */
+    on(type: E["type"] | "*", handler: Handler<E>): () => void {
+        const wrapped = (ev: E) => {
+            try {
+                handler(ev);
+            } catch {
+                /* 消费方异常不外溢（AC-10） */
+            }
+        };
+        this.emitter.on(type === "*" ? "__all" : (type as string), wrapped as (ev: E) => void);
+        return () => this.emitter.off(type === "*" ? "__all" : (type as string), wrapped as (ev: E) => void);
+    }
+
+    once(type: E["type"], handler: Handler<E>): void {
+        try {
+            this.emitter.once(type as string, handler);
+        } catch { /* 同上 */ }
+    }
+
+    off(type: E["type"] | "*", handler: Handler<E>): void {
+        this.emitter.off(type === "*" ? "__all" : (type as string), handler as (ev: E) => void);
+    }
+
+    /** 发布：同步分发到订阅者与迭代队列 */
+    emit(ev: E): void {
+        this.emitter.emit(ev.type as string, ev);
+        this.emitter.emit("__all", ev);
+        for (const it of this.iterables) {
+            if (!it.active) continue;
+            if (it.queue.length >= this.queueMax) {
+                it.queue.shift();
+                it.dropped++;
+            }
+            it.queue.push(ev);
+        }
+    }
+
+    /** AsyncIterable 形态句柄：可 for-await 消费（可按 type 过滤），dropped() 查溢出丢弃数 */
+    iterable(type?: E["type"]): AsyncIterable<E> & { dropped(): number } {
+        const entry = { queue: [] as E[], dropped: 0, active: true };
+        this.iterables.add(entry);
+        const handle = {
+            [Symbol.asyncIterator]: async function* (): AsyncGenerator<E> {
+                try {
+                    while (entry.active) {
+                        if (entry.queue.length === 0) {
+                            await new Promise((r) => setTimeout(r, 10));
+                            continue;
+                        }
+                        const ev = entry.queue.shift()!;
+                        if (type && ev.type !== type) continue;
+                        yield ev;
+                    }
+                } finally {
+                    entry.active = false;
+                }
+            },
+            dropped: () => entry.dropped,
+        } as AsyncIterable<E> & { dropped(): number };
+        (handle as unknown as { __entry: typeof entry }).__entry = entry;
+        return handle;
+    }
+
+    listenerCount(type?: E["type"]): number {
+        return this.emitter.listenerCount(type === "*" || !type ? "__all" : (type as string));
+    }
+}

package/src/factory.ts

@@ -0,0 +1,51 @@
+/**
+ * factory.ts — Transport 工厂与开放注册表（FEAT-01/FEAT-09：AC-09 第三方 driver 同权接入）
+ *
+ * 净室平移自 Aethelum-Nexus `src/core/tools/runtime/factory.ts`（源锚 8977ff3），
+ * OSS 化：注册表对外开放（registerDriver）；内置 local，其余 Transport 分批落位。
+ */
+import type { RuntimeDriver, RuntimeDescriptor } from "./driver.js";
+import { LocalRuntimeDriver } from "./local-driver.js";
+import { SshPtyDriver } from "./ssh-pty-driver.js";
+import { TmuxSessionDriver } from "./tmux-driver.js";
+
+export type DriverFactory = (descriptor: RuntimeDescriptor) => RuntimeDriver;
+
+export class RuntimeFactory {
+    private custom = new Map<string, DriverFactory>();
+
+    /** 开放注册：第三方 Transport 与内置同权；重复注册拒绝（FEAT-01 异常策略） */
+    registerDriver(type: string, factory: DriverFactory): void {
+        if (this.custom.has(type) || ["local", "ssh", "tmux"].includes(type)) {
+            throw new Error(`driver '${type}' 已注册，拒绝覆盖——先 unregister 或换类型名`);
+        }
+        this.custom.set(type, factory);
+    }
+
+    unregisterDriver(type: string): boolean {
+        return this.custom.delete(type);
+    }
+
+    registeredTypes(): string[] {
+        return ["local", "ssh", "tmux", ...this.custom.keys()];
+    }
+
+    create(descriptor: RuntimeDescriptor, fallbackCwd?: string): RuntimeDriver {
+        if (descriptor.driver === "local") {
+            return LocalRuntimeDriver.fromDescriptor(descriptor, fallbackCwd);
+        }
+        if (descriptor.driver === "ssh") {
+            return new SshPtyDriver(descriptor);
+        }
+        if (descriptor.driver === "tmux") {
+            return new TmuxSessionDriver(descriptor);
+        }
+        const f = this.custom.get(descriptor.driver);
+        if (f) return f(descriptor);
+        // 未知 driver 且无注册工厂：结构化错误（docker/k8s/teleport 快捷方式经
+        // launchCmd 走 tmux 后端，或 registerDriver 自定义——FEAT-01/FEAT-09）
+        throw new Error(
+            `未知 driver '${descriptor.driver}'——经 registerDriver() 注册，或在 config.launchCmd 提供完整启动命令`,
+        );
+    }
+}