botmux 2.65.0 → 2.66.0-canary.1

package/README.en.md

@@ -64,7 +64,7 @@ Compared to OpenClaw-style approaches built on Agent SDKs:
 ## Prerequisites
 
 - **Node.js** >= 20
-- **AI coding CLI / local agent app** installed and authenticated (`claude`, `codex`, `coco`, `cursor-agent`, `gemini`, `opencode`, `hermes`, `seed` (Seed CLI, a Claude Code fork), `pi`, `copilot` (GitHub Copilot CLI), `traex` (TRAE CLI), or `agy` (Antigravity) in PATH)
+- **AI coding CLI / local agent app** installed and authenticated (`claude`, `codex`, `coco`, `cursor-agent`, `gemini`, `opencode`, `hermes`, `seed` (Seed CLI, a Claude Code fork), `pi`, `omp` (oh-my-pi, a Pi fork), `copilot` (GitHub Copilot CLI), `traex` (TRAE CLI), or `agy` (Antigravity) in PATH)
   - **CoCo requires `0.120.32+`**: type-ahead (sending a new message while a turn is still running, parked in CoCo's own message queue) relies on 0.120.32+ behavior; earlier versions may drop or serialize input while busy — upgrade before use
 - **tmux** >= 3.x (optional — auto-enabled when installed for persistent CLI sessions)
 - **CJK fonts** (only needed for screenshot rendering of Chinese text / emoji):

package/README.md

@@ -199,7 +199,7 @@ CLI 进入 botmux 会话时自动获得 `~/.botmux/bin` 在 PATH 中，以及一
 ## 前置要求
 
 - **Node.js** >= 20
-- **AI 编程 CLI / 本地 Agent 应用** 已安装并完成认证（`claude`、`codex`、`coco`、`cursor-agent`、`gemini`、`opencode`、`hermes`、`seed`（Seed CLI，Claude Code 衍生）、`pi`、`copilot`（GitHub Copilot CLI）、`traex`（TRAE CLI）或 `agy`（Antigravity）在 PATH 中）
+- **AI 编程 CLI / 本地 Agent 应用** 已安装并完成认证（`claude`、`codex`、`coco`、`cursor-agent`、`gemini`、`opencode`、`hermes`、`seed`（Seed CLI，Claude Code 衍生）、`pi`、`omp`（oh-my-pi，Pi 衍生）、`copilot`（GitHub Copilot CLI）、`traex`（TRAE CLI）或 `agy`（Antigravity）在 PATH 中）
   - **CoCo 最低版本 `0.120.32`**：type-ahead（会话忙时即可发新消息，由 CoCo 自己的消息队列接住）依赖 0.120.32+ 的行为；更早版本忙时输入可能丢失或串行，请升级后再用
 - **tmux** >= 3.x（可选，安装后自动启用会话常驻）
 - **CJK 字体**（用于截图渲染中文/emoji）：

package/dist/adapters/backend/sandbox.d.ts

@@ -0,0 +1,119 @@
+export interface SandboxPlan {
+    /** Host path of the per-session writable project copy (a `git clone` of the
+     *  source). Mounted INSIDE the sandbox at `projectMount`, not at this path. */
+    workDir: string;
+    /** In-sandbox path the clone is mounted at — MUST equal the original
+     *  workingDir the CLI was given (e.g. codex `-C <dir>`), so the CLI's existing
+     *  args resolve to the clone. Also the child's chdir. */
+    projectMount: string;
+    /** Per-session scoped HOME — bound over the real home path so every CLI's
+     *  hardcoded `~/.<cli>` resolves into this de-identified area. */
+    scopedHome: string;
+    /** Daemon-mediated `botmux send` outbox — the ONLY IPC surface bound in, so
+     *  bots.json / Lark creds never enter the sandbox. */
+    outbox: string;
+    /** Extra read-only paths the toolchain lives under (node/CLI binaries via
+     *  fnm, the botmux dist) — re-exposed AFTER the scoped-home mask because on
+     *  this host they sit under $HOME (e.g. ~/.local/share/fnm, ~/iserver/botmux). */
+    toolchainRo: string[];
+    /** Keep network egress. File-only scope ⇒ default true (npm/pip/git work). */
+    net?: boolean;
+}
+/**
+ * Build the bwrap argv prefix. Final spawn becomes:
+ *   bwrap <these args> -- <cliBin> <cliArgs...>
+ *
+ * Mount order matters: the scoped HOME is bound over the real home FIRST, then
+ * toolchain/work/outbox paths (some under home) are re-bound on top — bwrap
+ * applies binds in order, so the later, more specific mounts win.
+ */
+export declare function buildSandboxArgs(plan: SandboxPlan): string[];
+/**
+ * Materialise a de-identified config dir inside `scopedHome`: copy ONLY the
+ * auth/config files from the host's real config, never history/sessions.
+ * `dereference` resolves symlinks (codex's config.toml → config.toml.old) into
+ * real files, since the symlink target won't exist inside the masked home.
+ *
+ * Returns false if this CLI has no persistent config to scope (hermes/aiden/…).
+ */
+export declare function seedScopedConfig(cliId: string, scopedHome: string, projectMount?: string): boolean;
+/** Is file-sandbox enabled for this session? Spike gate = env; the real
+ *  per-bot BotConfig.sandbox flag is a follow-up. */
+export declare function sandboxEnabled(): boolean;
+export interface SandboxSpawn {
+    /** Replace the CLI binary with this (always 'bwrap'). */
+    bin: string;
+    /** bwrap args + '--' + original (bin, ...args). */
+    args: string[];
+    /** Env overrides to merge into childEnv (HOME, PATH, BOTMUX_SEND_RELAY). */
+    env: Record<string, string>;
+    /** Outbox dir the daemon watcher must service. */
+    outbox: string;
+    /** Per-session project copy (for logging / landing). */
+    workDir: string;
+    /** Remove the per-session sandbox tree. */
+    cleanup: () => void;
+}
+/**
+ * Build the sandboxed spawn for a CLI session, or return null when sandboxing
+ * is off / unsupported. Creates per-session dirs under
+ * <dataDir>/sandboxes/<sessionId>/, clones the source project, seeds a
+ * de-identified config dir, and installs a `botmux` shim on PATH.
+ */
+export declare function prepareSandbox(opts: {
+    /** Whether the sandbox is on for THIS session (per-bot BotConfig.sandbox OR
+     *  the BOTMUX_SANDBOX env force). Decided by the caller — prepareSandbox does
+     *  NOT re-read the env, so the dashboard per-bot toggle actually takes effect. */
+    enabled: boolean;
+    cliId: string;
+    sessionId: string;
+    sourceWorkingDir: string;
+    dataDir: string;
+    cliBin: string;
+    cliArgs: string[];
+}): SandboxSpawn | null;
+export interface RelayRequest {
+    contentFile?: unknown;
+    attachments?: unknown;
+    flags?: unknown;
+}
+export interface ValidatedRelay {
+    contentName: string;
+    attachmentNames: string[];
+    flags: string[];
+}
+/**
+ * PURE validation of an outbox relay request (schema + flag allowlist only — no
+ * filesystem access, so it's deterministically testable):
+ *  - contentFile/attachments must be plain basenames (no `/`, `\`, `..`).
+ *  - only allowlisted presentation flags pass; any other flag → reject (this
+ *    rejects raw `--content-file`/`--session-id`/path flags etc.).
+ * The TOCTOU-safe filesystem read is handled separately by materializeOutboxFile,
+ * NOT here — this function deliberately resolves no paths.
+ */
+export declare function validateRelayRequest(req: RelayRequest): {
+    ok: true;
+    value: ValidatedRelay;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * TOCTOU-safe copy of an outbox file (`outbox/<name>`, name already validated as
+ * a plain basename) into a host-private `dest`. Opens with O_NOFOLLOW so a
+ * symlink swapped in by the sandbox AFTER validation is rejected at open time;
+ * reads from the fd (not the path), so the inode can't be swapped under us.
+ * Returns false (reject) on symlink / non-regular / any error.
+ */
+export declare function materializeOutboxFile(outbox: string, name: string, dest: string): boolean;
+/**
+ * Daemon/worker-side outbox watcher. The sandboxed `botmux send` (relay mode)
+ * drops `<id>.req.json`; we validate (validateRelayRequest) and then MATERIALIZE
+ * the content/attachments into a host-private staging dir that is NOT bound into
+ * the sandbox — closing the TOCTOU window where the sandbox could swap an outbox
+ * file for a symlink between check and the host-side read. We then re-exec THIS
+ * build's `send` OUTSIDE the sandbox (full creds) against the private copies,
+ * with the session-id FORCED. This keeps every Lark credential out of the sandbox.
+ */
+export declare function startOutboxWatcher(outbox: string, baseEnv: NodeJS.ProcessEnv, sessionId: string): () => void;
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/adapters/backend/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../src/adapters/backend/sandbox.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,WAAW;IAC1B;mFAC+E;IAC/E,OAAO,EAAE,MAAM,CAAC;IAChB;;6DAEyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB;sEACkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB;0DACsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf;;sFAEkF;IAClF,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,8EAA8E;IAC9E,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAMD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,EAAE,CAmB5D;AA2CD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CA0BlG;AA4ED;qDACqD;AACrD,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAoDD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC;;sFAEkF;IAClF,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,GAAG,YAAY,GAAG,IAAI,CA2FtB;AAOD,MAAM,WAAW,YAAY;IAC3B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAQD,MAAM,WAAW,cAAc;IAAG,WAAW,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;CAAE;AAEpG;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,YAAY,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAwB1H;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAiBzF;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,IAAI,CAkE5G"}