@sema-agent/server 7.49.0 → 7.51.0

package/dist/plugins/remote-env-device.d.ts

@@ -0,0 +1,271 @@
+import { ExecutionError, FileError, RemoteExecutionError, type ExecutionEnv, type ExecutionEnvFactory, type ExecStreamOptions, type FileInfo, type OutputChunk, type RemoteConnectConfig, type RemoteExecutionEnv, type Result, type SessionToken, type SnapshotId, type VmLifecycleOptions, type WorkspaceHandle, type WriteExpectation, type WriteReceipt } from "@sema-agent/core";
+import { DEVICE_RATE_LIMIT_CODE, type DeviceErrorCode, type DeviceOwner, type DeviceRow, type DeviceStore } from "../device-store.js";
+import type { DeviceEnrollment } from "../device-enrollment.js";
+import type { DeviceWsHub } from "../device-ws-hub.js";
+import type { DeviceInstructionKind, DeviceOutcomeErrorCode } from "../device-ws-protocol.js";
+/** `WorkspaceHandle.provider` 与 `REMOTE_EXEC` 词表的那一个词,单点。 */
+export declare const DEVICE_PROVIDER: "device";
+/** core 没从包根导出 `ExecutionEnvExecOptions` —— 从接口上取,与六条兄弟腿逐字同姿势
+ *  (`remote-env-host.ts` 的 `type ExecOpts = Parameters<ExecutionEnv["exec"]>[1]`)。 */
+type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
+/**
+ * 设备**结局帧**的错误码 → core `FileErrorCode`。
+ *
+ * `Record<DeviceOutcomeErrorCode, …>` 是**穷举**的:协议的结局码闭集加词而此处不加行 = 编译红
+ * (#157 词表纪律;不是运行时 switch 的默认臂)。
+ *
+ * 🔴 三条不许折错的线:
+ *  ① `outcome_unknown` **原样过境**——core 把它排除在 `RETRYABLE_REMOTE_ERROR_CODES` 之外正是为了
+ *     「可能已经执行过」这一格;折成 `timeout`/`transport_lost` 会让上层按可重试处理,重驱已提交副作用。
+ *  ② `target_unavailable`(never-started 的诚实词)在 `FileErrorCode` 上**没有对位词** —— 落
+ *     `transport_lost`:它的契约是「连接故事已知、重连后可重试」,而 never-started 的重试确实是安全的。
+ *     诚实残余:file 面因此**分不出**「从未开始」与「传输中断」,两者都落在同一个可重试桶里(方向对、
+ *     粒度粗)。要分得开需要 core 在 `FileErrorCode` 上补 never-started 词 —— 已作 O12 的后续请托登记。
+ *  ③ exec 专属词(`shell_unavailable`/`spawn_error`/`callback_error`/`suspended`/`auth_failed`)出现在
+ *     file 面上是**设备端协议违约**(它把一个 exec 结局贴到一次文件操作上)⇒ 落 `unknown`,不猜。
+ */
+export declare const DEVICE_OUTCOME_TO_FILE_ERROR: Readonly<Record<DeviceOutcomeErrorCode, FileError["code"]>>;
+/**
+ * 设备**结局帧**的错误码 → core `ExecutionErrorCode`。穷举同上。
+ *
+ * 🔴 file 专属词(`already_exists`/`is_directory`/`not_directory`/`not_found`/`permission_denied`/
+ * `precondition_failed`/`invalid`)出现在 exec 面同样是协议违约 ⇒ `unknown`,不猜。
+ * `not_supported` 在 `ExecutionErrorCode` 上无对位词 —— 落 `shell_unavailable`(它的契约就是「命令
+ * **从未启动**,因为可执行面解析不了」,与「设备没有这条指令面」同侧;never-started 语义保住)。
+ */
+export declare const DEVICE_OUTCOME_TO_EXEC_ERROR: Readonly<Record<DeviceOutcomeErrorCode, ExecutionError["code"]>>;
+type RejectCode = DeviceErrorCode | typeof DEVICE_RATE_LIMIT_CODE;
+/**
+ * 汇聚端的 **typed 拒**(投递门**之前**,§5.3 投递边界:设备从未可能见过这条指令)→ core 错误码。
+ *
+ * 🔴 全部落在**可安全重试**的那一侧,这是投递边界给的硬事实,不是乐观估计。exec 面用 O12 的
+ * `target_unavailable`(「目标在 commit 前拒了,命令从未启动」的诚实词);file 面无对位词,同上落
+ * `transport_lost`。
+ * 例外 `identity_mismatch` / `revoked` / `not_found`:那是**永久**拒(换设备/吊销/不是你的),重试
+ * 只会同样失败 —— exec 面落 `auth_failed`(NEVER retry 的那一格),file 面无对位词落 `permission_denied`
+ * (「这条路你走不通,而且不是暂时的」是它最近的语义)。
+ */
+export declare const DEVICE_REJECT_TO_EXEC_ERROR: Readonly<Record<RejectCode, ExecutionError["code"]>>;
+export declare const DEVICE_REJECT_TO_FILE_ERROR: Readonly<Record<RejectCode, FileError["code"]>>;
+export interface DeviceEnvLogger {
+    warn(msg: string, fields?: Record<string, unknown>): void;
+    info?(msg: string, fields?: Record<string, unknown>): void;
+}
+export interface DeviceEnvFactoryDeps {
+    hub: DeviceWsHub;
+    store: DeviceStore;
+    enrollment: DeviceEnrollment;
+    /** 指令级默认超时(ms;`DEVICE_EXEC_TIMEOUT_MS`,§4.7)。core 的 per-command `timeout` 可收紧它。 */
+    execTimeoutMs?: number;
+    /** §4.3.3 蜂道:`deviceCwdHonored` 闸下由 resolve-spec 注册的 per-session cwd(**单写者**)。 */
+    perSessionCwd?: ReadonlyMap<string, string>;
+    perSessionShellEnv?: ReadonlyMap<string, Record<string, string>>;
+    logger?: DeviceEnvLogger;
+}
+interface DeviceEnvConfig {
+    hub: DeviceWsHub;
+    enrollment: DeviceEnrollment;
+    rootSessionId: string;
+    deviceId: string;
+    owner: DeviceOwner;
+    cwd: string;
+    shellEnv?: Record<string, string>;
+    execTimeoutMs: number;
+    /** 设备当前连接声明的指令面(`undefined` = 铸 env 时设备不在线 ⇒ 可选面一律缺席)。 */
+    supports: ReadonlySet<DeviceInstructionKind> | undefined;
+    logger?: DeviceEnvLogger;
+}
+export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
+    private readonly cfg;
+    /**
+     * 🔴 `suspendable: false` 在 core 契约里**同时断言**「工作区在目标上外部持久」(remote-env.ts 的
+     * load-bearing 不变量)—— 设备工作区 = 员工机磁盘,真持久 ✅,park-only 降级腿因此合法可用。
+     * 谁要把 executor 的工作区改成临时目录,先来改这一行:那一刻这个 `false` 就变成谎话,park 赎回会
+     * 落到一个空工作区上而链路上没有任何一层会报错。
+     */
+    readonly capabilities: {
+        isolation: boolean;
+        suspendable: boolean;
+    };
+    readonly externalContentTarget = true;
+    /** #211:设备路径不在 worker 宿主文件系统上 —— host-path 回执消费方据此拒绝把它当宿主路径呈现。 */
+    readonly hostLocalPaths = false;
+    cwd: string;
+    /** 可选面(presence-typed,见文件头「铁律」段):构造期按设备声明装配,缺席就是缺席。 */
+    readLink?: (path: string, abortSignal?: AbortSignal) => Promise<Result<string, FileError>>;
+    writeFileExclusive?: (path: string, content: string | Uint8Array, abortSignal?: AbortSignal) => Promise<Result<void, FileError>>;
+    writeFileGuarded?: (path: string, content: string | Uint8Array, expect: WriteExpectation, abortSignal?: AbortSignal) => Promise<Result<WriteReceipt, FileError>>;
+    private connected;
+    /** 拆除是**终态**(六条兄弟腿同纪律:destroy 之后 connect/exec/读面一律 fail-closed,不复活)。 */
+    private destroyed;
+    constructor(cfg: DeviceEnvConfig);
+    /**
+     * 铸造时装配的**保护型**可选面(guarded / exclusive 写)。`connect()` 拿它与设备**此刻**的声明对拍。
+     *
+     * 🔴 为什么只对拍这两条而不是全部 supports(codex R1-F2 的修法边界):这两条是 core 契约里
+     * 「缺席 ⇒ 调用方按 advisory 降级并自担 TOCTOU」的那一类 —— 它们的缺席是**放宽**方向。其余面
+     * (exec/read/…)缺席时调用会得到一条响亮的 `not_supported`,不构成静默降级。
+     */
+    private guardFaceSnapshot;
+    /**
+     * 设备**此刻**多出来的保护面(相对本 env 铸造时的快照)。非空 = 漂移。
+     *
+     * 🔴 **为什么这条判据不能只守 `connect()`**(codex R2-F3,判真):`connect()` 一辈子只跑一两次,而
+     * 设备的 WS 可以**透明重连** —— 断开、以同一 deviceId 连回来,`this.connected` 全程不变,后续
+     * `dispatch` 直接用汇聚端的**当前**连接。于是「弱能力连接上铸的 env + 设备连回时带上了 guarded 面」
+     * 这一形绕过了 connect 期的闸:core 仍看不到 guarded 方法、仍走非原子写降级,而没有任何一层再问一次。
+     * 所以判据要落在**每一次非原子写之前**(那正是被降级的那条路),connect 期的检查是它的早期快门。
+     */
+    private guardFaceDrift;
+    /**
+     * 铸造时**缺席**的保护面 —— 交给 hub 在投递门上原子复核(codex R3-F1)。
+     *
+     * adapter 侧的 {@link guardFaceDrift} 是**早期快门**:它与真正的下发之间隔着 `admitSession` 的一次
+     * SQL 往返,设备可以在那个窗口里以更强的能力连回来。投递门是本进程里唯一同时持有「最终选中的连接」
+     * 与「不可回退的 commit」的地方,所以权威判据在那儿;这里只负责把「我是在没有它们的前提下铸的」这句
+     * 话原样送过去。
+     */
+    private absentGuardFaces;
+    private driftError;
+    private resolve;
+    absolutePath(p: string): Promise<Result<string, FileError>>;
+    joinPath(parts: string[]): Promise<Result<string, FileError>>;
+    workspaceHandle(): WorkspaceHandle;
+    /**
+     * 不建连接:做**准入 + 取活连接**(文件头「唯一范式差」)。
+     *
+     * 🔴 **绝不换设备**:准入解出的 deviceId 与本 env 铸造时钉住的那一台不符 ⇒ typed
+     * `device.identity_mismatch`(lane 是身份不是偏好,§4.5 步 2)。这一格正是 park 赎回期换绑/吊销的
+     * 落点:静默改投等于把一次会话的全部工作区假设搬到另一台机器上。
+     */
+    connect(config?: RemoteConnectConfig): Promise<{
+        ok: true;
+        value: WorkspaceHandle;
+    } | {
+        ok: false;
+        error: RemoteExecutionError;
+    }>;
+    /** 控制面重连(core 在 transport 重挂时调)——语义与 connect 逐字同一条:重新准入 + 身份等值。 */
+    reconnect(_sessionToken: SessionToken): Promise<{
+        ok: true;
+        value: WorkspaceHandle;
+    } | {
+        ok: false;
+        error: RemoteExecutionError;
+    }>;
+    suspendVM(_options?: VmLifecycleOptions): Promise<{
+        ok: true;
+        value: SnapshotId;
+    } | {
+        ok: false;
+        error: RemoteExecutionError;
+    }>;
+    resumeVM(_snapshotId: SnapshotId, _options?: VmLifecycleOptions): Promise<{
+        ok: true;
+        value: WorkspaceHandle;
+    } | {
+        ok: false;
+        error: RemoteExecutionError;
+    }>;
+    postResumeInit(): Promise<{
+        ok: true;
+        value: void;
+    } | {
+        ok: false;
+        error: RemoteExecutionError;
+    }>;
+    private unsupported;
+    /**
+     * 解除本 env 与设备的关联。**不动设备上的工作区文件**(与 adb 腿「destroy 只断开不重置手机」同纪律
+     * —— 那是员工自己的盘,§11-O6 才是「要不要清理」这个问题的属主)。幂等,永不抛。
+     */
+    destroy(): Promise<void>;
+    cleanup(): Promise<void>;
+    /** 终态/未连接的 fail-closed 门(exec 面)。 */
+    private shellGate;
+    /** 终态/未连接的 fail-closed 门(文件面)。 */
+    private fsGate;
+    private timeoutMsFor;
+    private dispatch;
+    /**
+     * 三态结果 → 文件面的 `Result`。
+     *
+     * **穷举 switch,无 default 臂**:`DeviceDispatchResult` 加臂而此处不加 = 编译红。三态各自的
+     * 「重试安全性」在 hub 的类型注里逐字定义,本函数只做翻译,不重新判断。
+     */
+    private fileOutcome;
+    /** 结局 kind 与请求面不符 = 设备协议违约:响亮拒,**不猜**(否则一个没发生的操作会被读成成功)。 */
+    private wrongOutcome;
+    exec(command: string, options?: ExecOpts): Promise<Result<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }, ExecutionError>>;
+    /**
+     * 流式 exec。契约:按序 yield `stdout`/`stderr`,末尾**恰好一个** `exit` 片;失败在 exit 之前 throw
+     * `RemoteExecutionError`(core `OutputChunk` 契约)。
+     *
+     * 🔴 「恰好一个 exit」不是本层的信任,是**汇聚端已判过**的事实(hub 的 `expectsStreamTerminator`
+     * 对声明了流的调用强制唯一终止片,缺了就把整条指令判失败而不是静默尾截断)。本层只负责不把它弄丢。
+     */
+    execStream(command: string, options?: ExecStreamOptions): AsyncIterable<OutputChunk>;
+    exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
+    canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
+    private doReadLink;
+    readBinaryFile(p: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
+    readTextFile(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    readTextLines(p: string, options?: {
+        maxLines?: number;
+        abortSignal?: AbortSignal;
+    }): Promise<Result<string[], FileError>>;
+    listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
+    writeFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    appendFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    private doWrite;
+    /**
+     * O13 守卫写:前置条件与写入在设备上的**同一原子步**里发生,回一份落盘对象收据。
+     *
+     * 🔴 这是 §4.3.1「把裁决绑定到真实落盘对象」的**唯一**承载。它成立的边界要说清:关掉的是「调用方
+     * 铸前置条件」与「写入」之间那个窗;更早的策略裁决(例如等过人类审批的写门判决)不在这条收据里 ——
+     * core 的方法注对此已逐字声明,本腿不越界宣称。
+     */
+    private doGuardedWrite;
+    private warnMissingCreated;
+    createDir(p: string, options?: {
+        recursive?: boolean;
+        abortSignal?: AbortSignal;
+    }): Promise<Result<void, FileError>>;
+    remove(p: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+        abortSignal?: AbortSignal;
+    }): Promise<Result<void, FileError>>;
+    createTempDir(prefix?: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    createTempFile(options?: {
+        prefix?: string;
+        suffix?: string;
+        abortSignal?: AbortSignal;
+    }): Promise<Result<string, FileError>>;
+}
+/**
+ * device lane 的 `ExecutionEnvFactory`(`boot/execution-env.ts` 的第七臂)。
+ *
+ * 🔴 **异步工厂,且在铸 env 之前就把绑定读出来** —— 三个理由,每个都不能省:
+ *  ① `cwd` 是 `FileSystem` 的**同步属性**:缺省值 = 设备 hello 声明的 `workspaceRoot`,那在库里;
+ *  ② 可选面的 presence(`writeFileGuarded`…)必须在构造期定(core 降级律,见文件头);
+ *  ③ 「这个 placement 根本没绑设备」是**装配/准入错误**,不是一次运行期业务拒绝 —— 响亮抛,让 spawn
+ *     失败(core 对 `isolation:"worktree"` 的同款姿势:宁可 throw,绝不静默给一个不对的 env)。
+ *     对比:「绑了但现在不在线」是运行期事实 ⇒ 构造成功,`connect()` 回 typed `device.offline`。
+ */
+export declare function deviceExecutionEnvFactory(deps: DeviceEnvFactoryDeps): ExecutionEnvFactory;
+/**
+ * §4.3.3 的 cwd 优先序 —— 与 host 腿的 `effectiveHostWorkspace` **同源**:
+ *   ① 本 session 显式注册的 cwd(`deviceCwdHonored` 闸下由 resolve-spec 写);
+ *   ② `ctx.parentCwd`(委派子代:自己没注册过 cwd,继承父的工作目录 —— 少了它子代会丢工作目录);
+ *   ③ 设备 hello 声明并落库的 `workspaceRoot`(缺 cwd 时的解析基准,有明确 wire 契约,不是「executor
+ *      默认根」这种空话)。
+ */
+export declare function effectiveDeviceCwd(sessionCwd: string | undefined, parentCwd: string | undefined, row: Pick<DeviceRow, "workspaceRoot">): string;
+export {};
+//# sourceMappingURL=remote-env-device.d.ts.map