@sema-agent/server 7.140.0 → 7.142.0

package/dist/plugins/sandbox-read-floor.d.ts

@@ -0,0 +1,273 @@
+import { ExecutionError, type ReadFloor, type Result } from "@sema-agent/core";
+import { type SandboxFloorLane, type SandboxReadFloorKnob, type SandboxReadFloorState } from "../execution-lane-caps.js";
+/** F2 原因词闭集:连接时附着不过的那一步。 */
+export declare const READ_FLOOR_UNAVAILABLE_REASONS: readonly ["arch", "user_notif", "addfd_send", "uid_zero", "writable_system_path", "binary_digest", "relay_silent", "relay_identity", "provenance"];
+export type ReadFloorUnavailableReason = (typeof READ_FLOOR_UNAVAILABLE_REASONS)[number];
+/** F2:附着不过的环境上,带地板起动的拒句(纯字符串 ⇒ `build*`)。首句点名原因词;点名表的首行与旋钮。 */
+export declare function buildReadFloorUnavailableMessage(reason: ReadFloorUnavailableReason, detail: string | undefined, floor: ReadFloor | undefined): string;
+/** F6:守地板的环境上,不带地板的引擎起动的拒句。 */
+export declare function buildReadFloorMissingMessage(lane: SandboxFloorLane): string;
+/**
+ * 一次起动是什么(闭集,调用方必须表态 —— 没有缺省臂):
+ *  · `engine` —— 经执行环境公共起动口要起的命令(引擎的,或替引擎干活的服务端调用方的);带不带地板是它交来的事实。`hold` = 适配器之后还会以
+ *    同一起动号再起 `run`(k8s 后台作业的轮询 / 停 / 收尾读的是这次起动的产物,按这次起动的地板跑),登记留到 {@link SandboxReadFloor.release};
+ *  · `under` —— 以一次已登记(`hold`)起动的号再起一只 `run`(上面那类轮询);
+ *  · `adapter` —— 适配器自己的固定命令(文件面助手、探针、数据搬运、全杀);附着成功之后经监督者的 `plain` 起;
+ *  · `bootstrap` —— 本模块附着期间经适配器起动口跑的引导命令(量架构 / 工作区属主、放置、自检);只在附着中合法,别的时刻一律拒(响亮)。
+ */
+export type FloorStart = {
+    readonly kind: "engine";
+    readonly readFloor: ReadFloor | undefined;
+    readonly hold?: boolean;
+} | {
+    readonly kind: "under";
+    readonly startId: string | undefined;
+} | {
+    readonly kind: "adapter";
+} | {
+    readonly kind: "bootstrap";
+};
+export declare const ADAPTER_START: FloorStart;
+export declare const BOOTSTRAP_START: FloorStart;
+/** 引擎起动:`readFloor` 原样交(`undefined` = 这次起动不带地板)。 */
+export declare function engineStart(readFloor: ReadFloor | undefined, hold?: boolean): FloorStart;
+/** 起动身份:`root` = 车道以 root 起(e2b `user:"root"`、local-docker `-u 0`);`exec-user` = 车道自己的执行身份(改前的形)。 */
+export type FloorLaunchIdentity = "root" | "exec-user";
+/**
+ * 一次起动的答案(闭集;落到 argv 只经 {@link floorArgv} / {@link e2bFloorCommand} / {@link dockerIdentityFlags} 三只编码器):
+ *  · `bare` —— 与改前逐字同(车道自己的 shell argv 原样);
+ *  · `control` —— 附着中的引导命令:车道自己的 shell argv,以 `identity` 起,不经监督者;
+ *  · `run` —— 监督者 `run`(受滤):命令行头(`--` 之前,不含 `--env`)+ 起动身份 + 登记的起动号;
+ *  · `plain` —— 监督者 `plain`(不受滤、环境恒为构建形):命令行头 + 起动身份。不受滤的代码不得读受滤 uid 改得动的东西 ⇒ e2b 的编码不走登录 shell。
+ */
+export type FloorLaunch = {
+    readonly mode: "bare";
+} | {
+    readonly mode: "control";
+    readonly identity: FloorLaunchIdentity;
+} | {
+    readonly mode: "run";
+    readonly head: readonly string[];
+    readonly identity: FloorLaunchIdentity;
+    readonly startId: string;
+} | {
+    readonly mode: "plain";
+    readonly head: readonly string[];
+    readonly identity: FloorLaunchIdentity;
+};
+/** 监督者支持的架构(闭集)。 */
+export type FloorArch = "x86_64" | "aarch64";
+/** 沙箱里放监督者的目录:`<dir>/<arch>/sema-floor`(root 属主、0755,受滤用户不可写)。 */
+export declare const FLOOR_DIR = "/opt/sema/floor";
+export declare function floorBinaryPath(arch: FloorArch): string;
+/**
+ * 监督者四个模式的命令行头(唯一写处;`--env` 与 `--` 由编码器接)。`as` = 降权目标 uid(只 e2b:root 起的 L 降到工作区属主)。
+ * 环境一条规则(协议 §3.6):`run` 下受滤的命令继承起它的进程的环境(`--as` 时 HOME / USER / LOGNAME / SHELL 取 passwd),再叠 `--env`;
+ * `plain` 的环境恒为构建形(固定 PATH + 运行 uid 的 passwd 四项 + `--env`),不继承。
+ */
+export declare const FLOOR_ARGV: {
+    readonly run: (bin: string, startId: string, as: string | undefined) => readonly string[];
+    readonly plain: (bin: string, as: string | undefined) => readonly string[];
+    readonly serve: (bin: string, stateDir: string, fresh: boolean) => readonly string[];
+    readonly selfcheck: (bin: string, digest: string, as: string | undefined) => readonly string[];
+};
+/** 沙箱的来历:`created` = 本次连接新建、还没跑过命令(`serve --fresh` 落来历标记)· `resumed` = 恢复 / 重新附着(标记必须在,否则 `provenance`)。 */
+export type FloorOrigin = "created" | "resumed";
+/** 自检的答案:`sema-floor selfcheck ok <version> <arch>`(退出 0)或 `sema-floor selfcheck refused <word>: <detail>`(退出 125)。 */
+export type SelfcheckVerdict = {
+    readonly ok: true;
+    readonly version: string;
+    readonly arch: string;
+} | {
+    readonly ok: false;
+    readonly reason: ReadFloorUnavailableReason;
+    readonly detail?: string;
+};
+/** 读自检输出(恰一行)。读不出 / 原因词不在闭集 ⇒ `binary_digest`(这只二进制答的不是本服务读得懂的话 —— 与钉住的不是同一只)。 */
+export declare function parseSelfcheck(stdout: string, exitCode: number): SelfcheckVerdict;
+/** 一问最多几条路径(协议 v1 §5.1)。 */
+export declare const MAX_PATHS_PER_QUESTION = 256;
+/** 一帧(一行)的字节上界(协议 §5:每行至多 1 MiB)。超了 ⇒ 这只中继违约(关掉、按掉线处置)。 */
+export declare const MAX_RELAY_LINE_BYTES: number;
+/**
+ * 中继帧(D 的 stdout → 适配器;协议 v1 §5.2)。每帧**恰好**列出的字段,多一个 / 少一个 / 型错 / 不认识的 `t` ⇒ `broken`(`why` 说坏在哪,进日志;
+ * 带得出问号与路径数就带上:那一问整问拒,长度对齐)。
+ */
+export type RelayFrameIn = {
+    readonly t: "ready";
+    readonly pid: number;
+} | {
+    readonly t: "refused";
+    readonly why: string;
+    readonly detail: string;
+} | {
+    readonly t: "q";
+    readonly id: number;
+    readonly start: string;
+    readonly paths: readonly string[];
+} | {
+    readonly t: "gone";
+    readonly start: string;
+} | {
+    readonly t: "broken";
+    readonly why: string;
+    readonly id?: number;
+    readonly count?: number;
+};
+export declare function parseRelayFrame(line: string): RelayFrameIn;
+/** 适配器 → D 的唯一帧:与所问路径逐条对齐的判决(`null` = 放;非空串 = 拒,通常是判官答的拒行)。 */
+export interface RelayAnswer {
+    readonly t: "a";
+    readonly id: number;
+    readonly verdicts: readonly (string | null)[];
+}
+/** 未登记(或已撤)的起动、保留号、坏帧的那一问:每条路径一律拒,判决串是这一句(监督者不解读它)。 */
+export declare const UNJUDGED_VERDICT = "read floor: no verdict for this start";
+/** 判官:适配器进程里唯一回答「这条路径拒不拒」的东西。live object ⇒ `create*`。 */
+export interface FloorJudge {
+    /** 登记一次带地板的起动,回它的起动号(随机、不可猜)。`held` ⇒ 之后还会以这个号再起 `run`(`under`),直到 {@link release};否则这一次就是它唯一的起动。 */
+    register(floor: ReadFloor, held: boolean): string;
+    /** 以这个号再起一次 `run`(`under`)之前问:在册且适配器没说过「不再起」⇒ `true`(记下又有一只监督者将连上);否则 `false`(起动拒)。 */
+    launch(startId: string): boolean;
+    /** 适配器不会再以这个号起 `run` 了。登记要两件都到才撤(协议 §5.5):这一句 ∧ 此后的 `gone` —— `gone` 已在 ⇒ 当即撤;否则等它(还连着的监督者照旧有判官答)。 */
+    release(startId: string): void;
+    /** 一帧 → 要回的答(`undefined` = 不回:`ready` / `refused` / `gone` / 读不出问号或路径数的坏帧)。 */
+    answer(frame: RelayFrameIn): RelayAnswer | undefined;
+    /** 在册的起动数(钉与日志)。 */
+    readonly size: number;
+    clear(): void;
+}
+export declare function createFloorJudge(): FloorJudge;
+/** 一个架构的监督者构建:钉住的摘要 + 自核过的字节;没有 ⇒ 为什么没有(附着的拒起句带上它)。 */
+export type FloorBuild = {
+    readonly ok: true;
+    readonly digest: string;
+    readonly bytes: Uint8Array;
+} | {
+    readonly ok: false;
+    readonly why: string;
+};
+/** 监督者二进制的来源:每个架构一次读法 —— 摘要与字节同出一处,不会一个在一个不在。 */
+export interface FloorBinaries {
+    build(arch: FloorArch): FloorBuild;
+}
+/** 随包的二进制(`native/sandbox-read-floor/`):`DIGESTS` 每行 `<sha256>  <arch>/sema-floor`;字节读出来先自核摘要,不符 / 读不出 ⇒ 这个架构没有可用构建(拒起点名 `binary_digest`)。 */
+export declare function createPackagedFloorBinaries(root?: URL): FloorBinaries;
+export type FloorBootstrapResult = {
+    readonly ok: true;
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/** 中继长连的出口(本模块写帧、关连)。 */
+export interface FloorRelayLink {
+    send(line: string): void;
+    close(): void;
+}
+/** 中继长连的进口(传输把字节与关闭交给本模块)。 */
+export interface FloorRelayEvents {
+    data(chunk: string): void;
+    closed(why: string): void;
+}
+/** 一只适配器交给本模块的三件原语。引导命令经适配器**自己的起动接缝**(起动形 {@link BOOTSTRAP_START})起 —— 本模块只给命令行。 */
+export interface FloorTransport {
+    /** 跑一行 POSIX shell(本模块写的固定命令)作引导起动,收输出。 */
+    bootstrap(command: string): Promise<FloorBootstrapResult>;
+    /** 把 `bytes` 放到 `path`(root 属主、0755);k8s 由 pod 的只读卷带来,答 ok 不写。 */
+    place(path: string, bytes: Uint8Array): Promise<{
+        readonly ok: true;
+    } | {
+        readonly ok: false;
+        readonly error: string;
+    }>;
+    /** 以 `identity` 起中继(本模块写的一行 shell),stdin / stdout 作一条双工。 */
+    openRelay(identity: FloorLaunchIdentity, command: string, events: FloorRelayEvents): FloorRelayLink;
+}
+/** 一次附着的输入:沙箱来历,与工作区目录(e2b 降到它的属主)。 */
+export interface FloorAttach {
+    readonly origin: FloorOrigin;
+    readonly workspaceRoot: string;
+}
+export interface FloorLogger {
+    info?(event: string, fields?: Record<string, unknown>): void;
+    warn?(event: string, fields?: Record<string, unknown>): void;
+}
+/** 一只执行环境手里的地板模块。live object ⇒ `create*`。 */
+export interface SandboxReadFloor {
+    readonly lane: SandboxFloorLane;
+    /** 这只模块所在车道的状态({@link sandboxReadFloorState} 的读数;注入的守地板模块恒 `kept`)。 */
+    readonly state: SandboxReadFloorState;
+    /** 这只模块钉住的监督者二进制(守地板 ⇒ 在;裸模块 ⇒ 缺席)。k8s 的 pod 座({@link buildFloorPodSeat})只读它 —— 放进 pod 的与自检核的是同一份钉。 */
+    readonly binaries: FloorBinaries | undefined;
+    /** 唯一接缝:一次起动 → 答案,或 `spawn_error`(F2 / F6 / 时机不对的引导起动 / 已撤的号)。 */
+    wrap(start: FloorStart): Result<FloorLaunch, ExecutionError>;
+    /** 适配器不会再以这个号起 `run`(`hold` 起动的收尾)。登记在其后的 `gone` 到时撤(还连着的监督者照旧有判官答)。 */
+    release(startId: string | undefined): void;
+    /** 连接时附着(量架构 → 放置 → 中继 → 自检);不守地板的模块什么都不做。从不抛:不过 ⇒ 记原因词,带地板的起动按 F2 拒。 */
+    attach(transport: FloorTransport, how: FloorAttach): Promise<void>;
+    /** 把一次放置失败记下(k8s:pod 带不上二进制卷时由适配器告知;附着按 `binary_digest` 拒)。 */
+    refusePlacement(detail: string): void;
+    /** 环境拆掉:关中继、清登记、不再重起。 */
+    dispose(): void;
+}
+export interface KeptFloorOptions {
+    readonly lane: SandboxFloorLane;
+    readonly binaries: FloorBinaries;
+    readonly logger?: FloorLogger;
+    /** 中继起来后等首帧(`ready` / `refused`)的上界(ms;缺省 15 s)。 */
+    readonly relayReadyMs?: number;
+    /** 中继掉线后重起的次数上界(缺省 3;间隔自 `relayRestartBackoffMs` 起翻倍)。 */
+    readonly relayRestarts?: number;
+    readonly relayRestartBackoffMs?: number;
+}
+/**
+ * 守地板的模块(服务集里的车道,或钉注入)。状态机:`idle` →(附着)`attaching` → `ready` | `unavailable(原因词)`;中继掉线 ⇒ 重起
+ * (`serve` 不带 `--fresh`),重起不成 ⇒ `unavailable(relay_silent)`。
+ * 适配器自己的固定命令(I1):附着**从未开始**才裸起(这只模块还没把沙箱交给过受滤代码;恢复的沙箱由适配器先附着、再起任何命令);
+ * 附着一旦开始就再不裸起 —— 有过验明的监督者 ⇒ 经它的 `plain`(不依赖中继:掉线 / 重附着不成也照用),从没验明过 ⇒ 拒。
+ */
+export declare function createKeptSandboxReadFloor(opts: KeptFloorOptions): SandboxReadFloor;
+/**
+ * 一只执行环境的地板模块 —— 适配器构造时调一次。状态 = {@link sandboxReadFloorState}(与车道块同一只判据):`kept` ⇒ 守地板的模块
+ * (随包二进制),否则裸模块。
+ */
+export declare function createSandboxReadFloor(opts: {
+    readonly lane: SandboxFloorLane;
+    readonly knob: SandboxReadFloorKnob | undefined;
+    readonly logger?: FloorLogger;
+}): SandboxReadFloor;
+/** k8s / local-docker:答案 + 车道自己的 shell argv(`<shell> -c <command>`)→ 最终 argv。`bare` ⇒ 原样(改前逐字同)。 */
+export declare function floorArgv(launch: FloorLaunch, shellArgv: readonly string[]): readonly string[];
+/**
+ * e2b:SDK 恒以 `/bin/bash -l -c <cmd>` 起。`bare` ⇒ `cmd` 原样、这次命令的 env 交 SDK(改前的形)。`run` / `plain` ⇒ 外层 root shell 只 `exec`
+ * 监督者;这次命令的 env 经 `--env` 交监督者,外层 shell 不带任何每命令 env(`BASH_ENV` 一类不在过滤之前生效)。沙箱级 env(建沙箱时给的)本就在
+ * 每个进程的环境里,受滤命令照旧继承(协议 §3.6),不必再传。`run` 里命令照旧是登录 shell(读 profile 发生在地板之下,与改前同);`plain` 里是
+ * 非登录 `/bin/bash -c`:不受滤的代码不读工作区属主改得动的 profile。`control`(引导)⇒ root 跑原命令,不带每命令 env。
+ */
+export declare function e2bFloorCommand(launch: FloorLaunch, command: string, envs: Readonly<Record<string, string>> | undefined): {
+    readonly cmd: string;
+    readonly user?: "root";
+    readonly envs?: Record<string, string>;
+};
+/** local-docker:`docker exec` 的身份旗标(`root` ⇒ `-u 0`;否则无,改前的形)。 */
+export declare function dockerIdentityFlags(launch: FloorLaunch): readonly string[];
+/** k8s 卷名:唯一一张在 `ADAPTER_VOLUME_NAMES`(补丁卷不得复用)。 */
+export declare const FLOOR_K8S_VOLUME_NAMES: Readonly<Record<FloorArch, string>>;
+/** ConfigMap 里放二进制的键。 */
+export declare const FLOOR_K8S_CONFIGMAP_KEY = "sema-floor";
+/** 一只 pod 要带的地板座(纯数据 ⇒ `build*`):先建(或已在)的 ConfigMap、pod 卷、sandbox 容器的只读挂载。 */
+export interface FloorPodSeat {
+    readonly configMaps: ReadonlyArray<{
+        readonly name: string;
+        readonly arch: FloorArch;
+        readonly binaryDataB64: string;
+    }>;
+    readonly volumes: readonly unknown[];
+    readonly mounts: readonly unknown[];
+}
+/** 守地板的 k8s 模块 ⇒ 它钉住的每个架构一只 ConfigMap(名 = 架构 + 摘要前 16 位;同摘要同内容,409 = 已在)+ 卷 + 只读挂载;否则 `undefined`(pod 与改前逐字同)。 */
+export declare function buildFloorPodSeat(floor: SandboxReadFloor): FloorPodSeat | undefined;
+//# sourceMappingURL=sandbox-read-floor.d.ts.map