@syrkos/filaxis 0.1.0-alpha.10

package/dist/driver.d.ts

@@ -0,0 +1,130 @@
+/**
+ * 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>;
+    /** 启动长跑会话（立即返回） */
+    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/dist/events.d.ts

@@ -0,0 +1,26 @@
+export interface EventBusOptions {
+    /** iterable 形态的每订阅队列上限（满丢最旧并计数） */
+    queueMax?: number;
+}
+type Handler<E> = (ev: E) => void;
+export declare class EventBus<E extends {
+    type: string;
+}> {
+    private emitter;
+    private readonly queueMax;
+    /** 每个迭代订阅一份独立队列：{queue, dropped, active} */
+    private iterables;
+    constructor(opts?: EventBusOptions);
+    /** 订阅（可按 type 过滤）；返回退订函数 */
+    on(type: E["type"] | "*", handler: Handler<E>): () => void;
+    once(type: E["type"], handler: Handler<E>): void;
+    off(type: E["type"] | "*", handler: Handler<E>): void;
+    /** 发布：同步分发到订阅者与迭代队列 */
+    emit(ev: E): void;
+    /** AsyncIterable 形态句柄：可 for-await 消费（可按 type 过滤），dropped() 查溢出丢弃数 */
+    iterable(type?: E["type"]): AsyncIterable<E> & {
+        dropped(): number;
+    };
+    listenerCount(type?: E["type"]): number;
+}
+export {};

package/dist/factory.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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";
+export type DriverFactory = (descriptor: RuntimeDescriptor) => RuntimeDriver;
+export declare class RuntimeFactory {
+    private custom;
+    /** 开放注册：第三方 Transport 与内置同权；重复注册拒绝（FEAT-01 异常策略） */
+    registerDriver(type: string, factory: DriverFactory): void;
+    unregisterDriver(type: string): boolean;
+    registeredTypes(): string[];
+    create(descriptor: RuntimeDescriptor, fallbackCwd?: string): RuntimeDriver;
+}

package/dist/file-edit.d.ts

@@ -0,0 +1,43 @@
+/**
+ * file-edit.ts — 受控文件编辑（远端 CAS 原子写回 + 合成 SSH 往返）
+ *
+ * 第六季盲测实锤：SKILL 教了受控编辑但 SDK 无一级导出——Agent 读 7 轮源码自研
+ * 20 行样板（50 万 cache tokens）；裸 SSH 组则 sed -i 两翻车并写坏远端配置。
+ *
+ * 第七季盲测反馈（B2 逐秒拆解）：旧实现一次 editFile = 5 次串行 SSH 往返
+ * （stat/read/stat/write/stat），Windows 无 ControlMaster 下放大到 15s+。
+ * 本版：合成 **2 次往返**（读+戳 1 次；**远端 CAS 原子写回** 1 次——GPT 并发
+ * 安全意见采纳：「最后一次校验与写入放进同一个远端受控操作」——戳比对与写回
+ * 在远端一条命令内原子完成，杜绝 A/B 丢失更新）+ 方言适配（stat/base64 三族，
+ * 每 driver 缓存一次探测）。大文件（base64>30KB）自动回落旧 5 次路径（fs 层）。
+ *
+ * **仅适用 UTF-8 文本**（readFile 返回 UTF-8 字符串；二进制文件的编辑走
+ * readBase64 + 消费方自行改写 + writeFile）。
+ */
+import type { RuntimeDriver } from "./driver.js";
+export interface EditFileOptions {
+    /** 多处命中时全替换（缺省 false——多处命中报错，精确替换语义） */
+    all?: boolean;
+}
+export interface EditFileResult {
+    path: string;
+    occurrences: number;
+    bytesBefore: number;
+    bytesAfter: number;
+    /** 写前锁核验的 mtimeMs（CAS 远端原子比对用） */
+    lockedAtMtimeMs: number;
+}
+export declare class EditConflictError extends Error {
+    constructor(message: string);
+}
+/**
+ * 受控编辑（合成 2 次往返 + 远端 CAS 原子写回）：
+ * ① 读+戳（1 次往返）：`stat 戳; __FXS__; base64 读` —— 拿 (mtime,size)+全文
+ * ② 精确替换（本地）：0 命中/多处命中（未开 all）拒绝
+ * ③ CAS 原子写回（1 次往返）：远端一条命令内完成「戳比对 + tmp 写 + mv 原子替换 + 新戳回执」
+ *    —— 戳不符（他人先写）→ EditConflictError；写后回执新戳
+ *
+ * @throws EditConflictError TOCTOU 冲突（CAS 戳不符）
+ * @throws Error 未命中 / 多处命中（未开 all）/ 远端层无 stat 能力
+ */
+export declare function editFile(drv: RuntimeDriver, path: string, oldStr: string, newStr: string, opts?: EditFileOptions): Promise<EditFileResult>;

package/dist/file-transfer.d.ts

@@ -0,0 +1,44 @@
+import type { RemoteDialect } from "./dialect.js";
+/** 远端执行回调（通常是 driver 的 exec 通道） */
+export type TransferExec = (command: string) => Promise<{
+    stdout: string;
+    exitCode: number;
+}>;
+export interface TransferResult {
+    bytes: number;
+    /** 远端回读核实的 sha256（与本地一致才返回成功） */
+    sha256: string;
+    /** 校验是否通过 */
+    verified: boolean;
+}
+export declare class TransferVerificationError extends Error {
+    constructor(op: "put" | "get", detail: string);
+}
+/**
+ * 上行 put：本地 → 远端。分块 base64 append 到远端临时文件 → 方言 decode 落位
+ * → size + sha256 回读双校验。任何一步退出码非零 → 抛错（落位原子性：先临时
+ * 文件后 mv 语义——失败不污染目标）。
+ */
+export declare function putFile(exec: TransferExec, dialect: RemoteDialect, localPath: string, remotePath: string): Promise<TransferResult>;
+/**
+ * 下行 get：远端 → 本地。方言 base64 编码回传 → 本地落盘 → sha256 对核。
+ */
+export declare function getFile(exec: TransferExec, dialect: RemoteDialect, remotePath: string, localPath: string): Promise<TransferResult>;
+export type SftpSpawnImpl = (argv: string[], batch: string) => Promise<{
+    exitCode: number | null;
+    stderr: string;
+}>;
+export interface SftpOptions {
+    /** 连接参数（host key 策略/端口/密钥——与 ssh 通道同源） */
+    connArgs: string[];
+    /** spawn 注入（缺省真实 sftp 子进程 + `-b -` batch 模式）——mock 全测关键 */
+    spawnImpl?: SftpSpawnImpl;
+}
+/**
+ * sftp 快路径 put：`sftp -b -` batch 模式（stdin 喂 `put` 命令）。
+ * 成功后仍走 size/sha256 双校验（与 base64 路径同一信任标准——快路径不豁免校验）。
+ * 缺席/失败由调用方捕获后降级 base64 管道（PRD FEAT-14 降级链）。
+ */
+export declare function sftpPutFile(exec: TransferExec, dialect: RemoteDialect, localPath: string, remotePath: string, opts: SftpOptions): Promise<TransferResult>;
+/** sftp 快路径 get（batch `get`；校验同 put） */
+export declare function sftpGetFile(exec: TransferExec, dialect: RemoteDialect, remotePath: string, localPath: string, opts: SftpOptions): Promise<TransferResult>;

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 牵丝 Filaxis — 面向自动化与 Agent 的远程执行运行时 SDK
+ * 千里一线，执行有迹。—— Connect · Execute · Observe · Reattach
+ *
+ * M1 第一批出口：契约与纯逻辑件。驱动实现（ssh/local/tmux）、会话管理器、
+ * 事件总线按里程碑分批落位（REQ-0001 M1-M4）。
+ */
+export * from "./driver.js";
+export * from "./session-types.js";
+export * from "./session-buffer.js";
+export * from "./logger.js";
+export * from "./local-session-manager.js";
+export * from "./local-driver.js";
+export * from "./events.js";
+export * from "./factory.js";
+export * from "./runtime-stack.js";
+export * from "./dialect.js";
+export * from "./ssh-helpers.js";
+export * from "./remote-session-manager.js";
+export * from "./ssh-pty-driver.js";
+export * from "./tmux-driver.js";
+export * from "./terminal-manager.js";
+export { DEFAULT_TERMINAL_CONFIG, compilePromptPatterns, TmuxError } from "./terminal/types.js";
+export type { TerminalConfig, PromptPayload, PromptResponder, TmuxResult } from "./terminal/types.js";
+export * from "./terminal/output-buffer.js";
+export * from "./stream-session-manager.js";
+export * from "./file-transfer.js";
+export * from "./layer-env.js";
+export { resolveLocalShell } from "./shell-discovery.js";
+export { createAgentToolkit } from "./agent-toolkit.js";
+export type { AgentToolkit, AgentToolDef, AgentToolHandlers, AgentToolkitOptions } from "./agent-toolkit.js";
+export { discoverLayer } from "./layer-discovery.js";
+export type { DiscoverLayerOptions, DiscoverLayerResult } from "./layer-discovery.js";
+export * from "./stream-window.js";
+export { Vt100Screen } from "./vt100-screen.js";
+export type { Vt100ScreenOptions } from "./vt100-screen.js";
+export { editFile, EditConflictError } from "./file-edit.js";
+export type { EditFileOptions, EditFileResult } from "./file-edit.js";