@sema-agent/server 7.50.0 → 7.51.0

package/dist/device-ws-protocol.d.ts

@@ -0,0 +1,429 @@
+import type { ExecutionErrorCode, FileErrorCode } from "@sema-agent/core";
+/** 唯一的 upgrade 路径(§5.1:`GET /v1/device/ws`)。 */
+export declare const DEVICE_WS_PATH = "/v1/device/ws";
+/** 本 server 铸/认的协议版本。加帧/加字段 = additive 不升版;改语义 = 升版(§5.6)。 */
+export declare const DEVICE_PROTOCOL_VERSION = 1;
+/** 低于此版本 ⇒ `helloReject: protocol_version_unsupported`(响亮拒,不静默降级,#157)。 */
+export declare const DEVICE_MIN_PROTOCOL_VERSION = 1;
+/** 签名的 domain tag —— 换域即换 tag,防止别处的 Ed25519 签名被拿来当握手用。 */
+export declare const DEVICE_HELLO_DOMAIN_TAG = "sema.device.hello.v1";
+/**
+ * 传输面硬帽。
+ *
+ * 🔴 `maxPreAuthFrameBytes` 与 `handshakeDeadlineMs` 是**未鉴权洪泛**的边界(§5.1 pre-auth 资源边界):
+ * 它们必须早于任何 SQL 查询与大对象解析生效 —— 一条 1MiB 的垃圾首帧不该换来一次设备表查询。
+ */
+export declare const DEVICE_WS_LIMITS: {
+    /** 单帧上限(§5.1:文本帧 JSON,超限 = 协议错误)。 */
+    readonly maxFrameBytes: number;
+    /** 鉴权**之前**允许的帧尺寸(hello 首帧)。 */
+    readonly maxPreAuthFrameBytes: 4096;
+    /** upgrade 到 helloAck/helloReject 的墙钟上限。 */
+    readonly handshakeDeadlineMs: 5000;
+    /** `payload` 下行分片的默认片长(单帧帽之下留出 base64 膨胀与帧头余量)。 */
+    readonly defaultPayloadPartBytes: number;
+};
+/** 设备 → 服务端的帧型全集。 */
+export declare const DEVICE_FRAME_TYPES: readonly ["hello", "generationAck", "heartbeat", "result", "chunk", "goodbye"];
+export type DeviceFrameType = (typeof DEVICE_FRAME_TYPES)[number];
+/** 服务端 → 设备的帧型全集。 */
+export declare const DEVICE_SERVER_FRAME_TYPES: readonly ["challenge", "helloAck", "helloReject", "instruction", "payload", "cancel", "resultAck", "chunkAck", "bye", "ping"];
+export type DeviceServerFrameType = (typeof DEVICE_SERVER_FRAME_TYPES)[number];
+/** 握手拒因(§5.1/§5.2)。`auth_failed` 刻意同时承载「不存在的 deviceId」与「验签失败」——反枚举。 */
+export declare const DEVICE_HELLO_REJECT_CODES: readonly ["auth_failed", "revoked", "protocol_version_unsupported", "draining", "already_connected"];
+export type DeviceHelloRejectCode = (typeof DEVICE_HELLO_REJECT_CODES)[number];
+/** 服务端主动断连的理由(§5.2/§8-R4/§8-R7)。 */
+export declare const DEVICE_BYE_REASONS: readonly ["revoked", "draining", "superseded"];
+export type DeviceByeReason = (typeof DEVICE_BYE_REASONS)[number];
+/** 设备优雅下线的理由(§5.2)。 */
+export declare const DEVICE_GOODBYE_REASONS: readonly ["shutdown", "sleep", "user_stop"];
+export type DeviceGoodbyeReason = (typeof DEVICE_GOODBYE_REASONS)[number];
+/** 上行流片的种类。`exit` = exec 流的**唯一**终止片,直接承载 exitCode(core OutputChunk 契约)。 */
+export declare const DEVICE_CHUNK_KINDS: readonly ["stdout", "stderr", "data", "exit"];
+export type DeviceChunkKind = (typeof DEVICE_CHUNK_KINDS)[number];
+/** cancel 的终局回执状态(§5.3)。 */
+export declare const DEVICE_CANCEL_STATES: readonly ["not_started", "killed"];
+export type DeviceCancelState = (typeof DEVICE_CANCEL_STATES)[number];
+/**
+ * 指令状态闭集(§5.3 task-R2-1)。
+ *
+ * 🔴 **刻意没有第五个词**:轮2 删掉的那个「已投递」态不可观测(`ws.send()` 成功 ≠ 设备收到),留着
+ * 必逼实现者在 commit 与它之间造一个窗口,让「窗口内到达的结果」被当成 unexpected 丢掉。两条路径:
+ * `queued → dispatch_committed → terminal` 与 `queued → terminal_never_started`。
+ */
+export declare const DEVICE_INSTRUCTION_STATES: readonly ["queued", "dispatch_committed", "terminal", "terminal_never_started"];
+export type DeviceInstructionState = (typeof DEVICE_INSTRUCTION_STATES)[number];
+/** 指令 kind ↔ core 的 FileSystem+Shell 面 1:1(§5.1;双端穷举 switch)。 */
+export declare const DEVICE_INSTRUCTION_KINDS: readonly ["exec", "execStream", "readTextFile", "readTextLines", "readBinaryFile", "writeFile", "writeFileExclusive", "writeFileGuarded", "appendFile", "fileInfo", "listDir", "canonicalPath", "exists", "readLink", "createDir", "remove", "createTempDir", "createTempFile", "statBatch"];
+export type DeviceInstructionKind = (typeof DEVICE_INSTRUCTION_KINDS)[number];
+/** 认得就收窄,认不出就 null(**不猜**:未知 kind 恒不下发,fail-closed 方向)。 */
+export declare function asInstructionKind(v: string): DeviceInstructionKind | null;
+/**
+ * 结果帧的错误码闭集 = core 的 `FileErrorCode ∪ ExecutionErrorCode`(§5.1「error code 全闭集」:
+ * 未知值映射为协议错误而非透传 string)。`satisfies` 保证这里没有 core 不认识的词。
+ */
+export declare const DEVICE_OUTCOME_ERROR_CODES: readonly ["aborted", "already_exists", "auth_failed", "callback_error", "invalid", "is_directory", "not_directory", "not_found", "not_supported", "outcome_unknown", "permission_denied", "precondition_failed", "shell_unavailable", "spawn_error", "suspended", "target_unavailable", "timeout", "transport_lost", "unknown"];
+export type DeviceOutcomeErrorCode = (typeof DEVICE_OUTCOME_ERROR_CODES)[number];
+/**
+ * **编译期**对账的另一半:core 往 `FileErrorCode`/`ExecutionErrorCode` 加一个词而本表没跟 ⇒ `Exclude`
+ * 不再是 `never` ⇒ `return v` 编译红。`satisfies` 只挡「本表多写了 core 不认的词」,这条挡「本表漏了
+ * core 的词」——两个方向都要,否则提货 core 新版时错误码表会静默变成子集(未覆盖的词落进
+ * `parseOutcomeErrorCode` 的 null 臂 = 一个合法结局被当协议错误拒掉)。
+ */
+export declare function assertCoreOutcomeErrorCodesAreCovered(v: Exclude<FileErrorCode | ExecutionErrorCode, DeviceOutcomeErrorCode>): never;
+/** 帧解析的拒因闭集(进 `device_frame_unexpected` 审计行的 `detail.reason`)。 */
+export declare const DEVICE_FRAME_REJECT_REASONS: readonly ["frame_too_large", "not_json", "not_object", "unknown_type", "bad_shape"];
+export type DeviceFrameRejectReason = (typeof DEVICE_FRAME_REJECT_REASONS)[number];
+/**
+ * 汇聚端在**解析之后**还会拒的理由(世代闸 / pending 表不变量)。与解析拒因合成审计行的闭集词表:
+ * 两段合起来才是「一条设备帧可能被拒的全部理由」,审计消费方按这一张表读。
+ */
+export declare const DEVICE_FRAME_GATE_REJECT_REASONS: readonly ["pre_hello", "generation_mismatch", "unknown_instruction", "instruction_not_committed", "device_mismatch"];
+export type DeviceFrameGateRejectReason = (typeof DEVICE_FRAME_GATE_REJECT_REASONS)[number];
+/** 审计行 `detail.reason` 的全集。 */
+export declare const DEVICE_FRAME_AUDIT_REASONS: readonly ["frame_too_large", "not_json", "not_object", "unknown_type", "bad_shape", "pre_hello", "generation_mismatch", "unknown_instruction", "instruction_not_committed", "device_mismatch"];
+export type DeviceFrameAuditReason = DeviceFrameRejectReason | DeviceFrameGateRejectReason;
+/** 设备文件面的 wire 投影(A-4 的 adapter 负责映射到 core `FileInfo`;本层只冻结形)。 */
+export interface WireFileInfo {
+    path: string;
+    kind: "file" | "dir" | "symlink" | "other";
+    size: number;
+    mtimeMs: number;
+    mode?: number;
+}
+/**
+ * 守卫写的前置条件在 wire 上的投影(core `WriteExpectation` 的字段子集,逐字同名)。
+ *
+ * 🔴 刻意**不**直接把 core 的类型放上 wire:wire 型是本仓铸的、cli 消费的独立契约(§3.7),core 加一
+ * 个字段不该无声地变成一条设备必须懂的新前置条件 —— 那是静默的语义升版。core 加字段时这里编译不红,
+ * 但 adapter 侧的**穷举投影**会红(见 `remote-env-device.ts` 的 `toWireExpectation`)。
+ */
+export interface WireWriteExpectation {
+    canonicalPath: string;
+    fileId?: string;
+    exclusive?: boolean;
+    noFollow?: boolean;
+}
+/** 指令结局(§5.1 `InstructionOutcome`)。 */
+export type DeviceInstructionOutcome = {
+    ok: true;
+    kind: "exec";
+    exitCode: number;
+    truncated?: {
+        stdout?: boolean;
+        stderr?: boolean;
+    };
+} | {
+    ok: true;
+    kind: "read";
+} | {
+    ok: true;
+    kind: "stat";
+    info?: WireFileInfo;
+    entries?: WireFileInfo[];
+    existsValue?: boolean;
+    canonicalPath?: string;
+    linkTarget?: string | null;
+}
+/** 写面的**落盘对象收据**(§4.3.1 / core `WriteReceipt`)。`created` 是 additive 扩键(车A-4):
+ *  core 的收据形要求它,缺席 = adapter 只能猜「是新建还是覆盖」,而猜出来的收据就是假收据。 */
+ | {
+    ok: true;
+    kind: "write";
+    canonicalPath: string;
+    inode?: string;
+    created?: boolean;
+} | {
+    ok: true;
+    kind: "void";
+} | {
+    ok: true;
+    kind: "cancelled";
+    state: DeviceCancelState;
+} | {
+    ok: false;
+    errorCode: DeviceOutcomeErrorCode;
+    message: string;
+};
+/** per-kind 精确入参(§5.1 task-R1-8:`InstructionArgs` 按 kind 判别,非 any)。 */
+export interface DeviceInstructionArgsByKind {
+    exec: {
+        command: string;
+    };
+    execStream: {
+        command: string;
+    };
+    readTextFile: {
+        path: string;
+    };
+    readTextLines: {
+        path: string;
+        offset?: number;
+        limit?: number;
+    };
+    readBinaryFile: {
+        path: string;
+    };
+    /** 内容**不在** args 里:走 `payload` 下行子序(§5.1),args 只带长度与摘要供设备校验。 */
+    writeFile: {
+        path: string;
+        contentLen: number;
+        sha256: string;
+    };
+    writeFileExclusive: {
+        path: string;
+        contentLen: number;
+        sha256: string;
+    };
+    /** `expect` = core `WriteExpectation` 的 wire 投影(车A-4 additive):设备在**同一原子步**里验证它。 */
+    writeFileGuarded: {
+        path: string;
+        contentLen: number;
+        sha256: string;
+        expect: WireWriteExpectation;
+    };
+    appendFile: {
+        path: string;
+        contentLen: number;
+        sha256: string;
+    };
+    fileInfo: {
+        path: string;
+    };
+    listDir: {
+        path: string;
+    };
+    canonicalPath: {
+        path: string;
+    };
+    exists: {
+        path: string;
+    };
+    readLink: {
+        path: string;
+    };
+    createDir: {
+        path: string;
+        recursive?: boolean;
+    };
+    remove: {
+        path: string;
+        recursive?: boolean;
+    };
+    createTempDir: {
+        prefix?: string;
+    };
+    createTempFile: {
+        prefix?: string;
+        suffix?: string;
+    };
+    statBatch: {
+        paths: string[];
+    };
+}
+export type DeviceChallengeFrame = {
+    t: "challenge";
+    nonce: string;
+    protocolVersion: number;
+};
+export type DeviceHelloAckFrame = {
+    t: "helloAck";
+    ok: true;
+    heartbeatIntervalMs: number;
+    maxInflight: number;
+    /** ⚠️ canonical 十进制**字符串**(F18:SQL BIGINT 超 2^53,wire 不声明装不下 SQL 类型的字段)。 */
+    gen: string;
+    pendingInstructions: string[];
+    chunkWatermarks: Record<string, number>;
+};
+export type DeviceHelloRejectFrame = {
+    t: "helloReject";
+    code: DeviceHelloRejectCode;
+    minProtocolVersion?: number;
+};
+export type DeviceInstructionFrame = {
+    [K in DeviceInstructionKind]: {
+        t: "instruction";
+        gen: string;
+        instructionId: string;
+        rootSessionId: string;
+        issuedSeq: number;
+        kind: K;
+        args: DeviceInstructionArgsByKind[K];
+        cwd?: string;
+        shellEnv?: Record<string, string>;
+        timeoutMs: number;
+    };
+}[DeviceInstructionKind];
+export type DevicePayloadFrame = {
+    t: "payload";
+    gen: string;
+    instructionId: string;
+    part: "begin" | "chunk" | "commit";
+    offset?: number;
+    dataB64?: string;
+    totalLen?: number;
+    sha256?: string;
+};
+export type DeviceServerFrame = DeviceChallengeFrame | DeviceHelloAckFrame | DeviceHelloRejectFrame | DeviceInstructionFrame | DevicePayloadFrame | {
+    t: "cancel";
+    gen: string;
+    instructionId: string;
+} | {
+    t: "resultAck";
+    gen: string;
+    instructionId: string;
+} | {
+    t: "chunkAck";
+    gen: string;
+    instructionId: string;
+    upToStreamSeq: number;
+} | {
+    t: "bye";
+    gen: string;
+    reason: DeviceByeReason;
+} | {
+    t: "ping";
+};
+export type DeviceHelloFrame = {
+    t: "hello";
+    protocolVersion: number;
+    deviceId: string;
+    epoch: string;
+    signatureB64: string;
+    platform: {
+        os: string;
+        arch: string;
+        executorVersion: string;
+    };
+    workspaceRoot: string;
+    pathFlavor: string;
+    /**
+     * 🔴 刻意是 `string[]` 而不是 `DeviceInstructionKind[]`:协议是 additive 的(§5.6),一个**更新的**
+     * executor 会声明本 server 还不认识的 kind。收窄在这里拒 = 老 server 认不下新 executor;所以帧里存
+     * 原样,由汇聚端与自己的闭集取交集 —— 不认识的 kind 恒不下发,方向仍是 fail-closed。
+     */
+    supports: string[];
+    resuming?: {
+        unackedResults: number;
+    };
+};
+export type DeviceFrame = DeviceHelloFrame | {
+    t: "generationAck";
+    gen: string;
+} | {
+    t: "heartbeat";
+    gen: string;
+    seq: number;
+    inflight: string[];
+} | {
+    t: "result";
+    gen: string;
+    instructionId: string;
+    deviceSeq: number;
+    outcome: DeviceInstructionOutcome;
+} | {
+    t: "chunk";
+    gen: string;
+    instructionId: string;
+    streamSeq: number;
+    kind: DeviceChunkKind;
+    dataB64?: string;
+    exitCode?: number;
+} | {
+    t: "goodbye";
+    gen: string;
+    reason: DeviceGoodbyeReason;
+    graceMs?: number;
+};
+export type DeviceResultFrame = Extract<DeviceFrame, {
+    t: "result";
+}>;
+export type DeviceChunkFrame = Extract<DeviceFrame, {
+    t: "chunk";
+}>;
+export type DeviceGoodbyeFrame = Extract<DeviceFrame, {
+    t: "goodbye";
+}>;
+export type DeviceHeartbeatFrame = Extract<DeviceFrame, {
+    t: "heartbeat";
+}>;
+export type DeviceFrameParse = {
+    ok: true;
+    frame: DeviceFrame;
+} | {
+    ok: false;
+    reason: DeviceFrameRejectReason;
+    detail: string;
+};
+/**
+ * **规范** base64(codex 对抗轮 R1-F6,判真)。
+ *
+ * 🔴 为什么不能只判「是个字符串」再交给 `Buffer.from(v, "base64")`:Node 的解码是**宽松**的 ——
+ * `"!!!!"` 解出一个**空** Buffer 而不抛,`"aG@k="` 悄悄丢掉非法字符照样解出两个字节。于是一条被
+ * 传输层损坏(或被恶意构造)的流片会以「合法的空/短数据」进入交付路径,水位照常推进、chunkAck
+ * 照常回给设备 —— 设备释放了它手上唯一的正本,调用方拿到的是**静默损坏**的输出。
+ * 在协议边界判规范形 + 回编码自比,这条路就没了。跨仓同判据:cli 侧编码器必须产规范形。
+ */
+export declare function isCanonicalBase64(v: string): boolean;
+/** `gen` 的**规范**十进制串。前导零/正号/空白/小数/负数/超安全整数一律 null(见文件头 F18 注)。 */
+export declare function parseGeneration(v: string): number | null;
+export declare function formatGeneration(n: number): string;
+/**
+ * 设备帧的唯一解析入口。
+ *
+ * 🔴 顺序是 帽 → JSON → 对象 → 帧型 → 形:每一步都有自己的拒因词,审计行才能回答「它到底哪儿坏了」。
+ * 没有任何一步会「尽量修一下再放行」——安全轴上的坏形帧只有响亮拒一条路(#157)。
+ */
+export declare function parseDeviceFrameText(text: string, opts?: {
+    maxBytes?: number;
+}): DeviceFrameParse;
+/**
+ * 26 位 Crockford base32(ULID)→ 16 字节。非法字符/长度 ⇒ `null`(**不猜**:一个被静默补零的 epoch
+ * 会让两个不同的 executor 进程签出同一份字节)。
+ */
+export declare function decodeUlid16(s: string): Buffer | null;
+/**
+ * 握手签名的**唯一**字节编码(§5.1 末,跨仓冻结):
+ * `"sema.device.hello.v1" ‖ u32be(len(nonce))‖nonce ‖ u32be(len(deviceId))‖deviceId ‖ epoch16 ‖ u32be(version)`。
+ */
+export declare function buildHelloSignaturePayload(input: {
+    nonce: string;
+    deviceId: string;
+    epoch: string;
+    protocolVersion: number;
+}): Buffer;
+/**
+ * 验签判决。`reason` **只进日志**(wire 上永远是同一个 `auth_failed` —— 反枚举),但它必须存在:
+ * 一个「公钥导入失败」和一个「签名对不上」在运维上是两回事,把它们一起折成 `false` 就等于把
+ * 「这台设备的公钥列存坏了」这条事实永久删掉(#191 门② SHAPE C:错误要**当数据交出**,不是吞掉)。
+ */
+export type HelloSignatureVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * 验签。公钥 wire 形 = **raw 32 字节的 base64**(店里 `devices.pubkey` 存的就是它)。
+ *
+ * 🔴 **恒不抛**:握手期的输入全部来自未鉴权的对端,一个畸形 base64 把异常抛进 socket 事件回调 =
+ * 未鉴权者可以让进程走进 uncaughtException。所以每条失败路径都收敛成 `{ok:false, reason}` —— 方向
+ * 是拒(fail-closed),而拒的**原因**原样交给调用方去打日志。
+ */
+export declare function verifyHelloSignature(input: {
+    pubkeyB64: string;
+    signatureB64: string;
+    payload: Buffer;
+}): HelloSignatureVerdict;
+/**
+ * 幂等键(§5.1:server 铸 ULID,**不可猜**)。设备按它去重(at-most-once);wire 上刻意不承载
+ * runId/toolCallId —— 它们在 `ExecutionEnv` 面结构性拿不到(core `ExecutionEnvFactoryContext`
+ * 只有 sessionId/taskId),关联在 server 侧 pending 表里完成。
+ */
+export declare function mintInstructionId(nowMs?: number): string;
+/** 一次性 challenge nonce(128 位熵,base64url canonical,每 socket 一次)。 */
+export declare function mintChallengeNonce(): string;
+/** executor 进程 epoch 的铸造(测试/自测用;真值由设备侧每次启动自铸)。 */
+export declare function mintDeviceEpoch(nowMs?: number): string;
+//# sourceMappingURL=device-ws-protocol.d.ts.map