botmux 2.66.0-canary.0 → 2.66.0

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,193 @@
+/**
+ * Mount an overlayfs: reads fall through to `lower` (real, zero copy); writes
+ * copy-up into `upper` (the landable changeset). `work` is overlayfs scratch on
+ * the same fs as `upper`. Returns true iff `mount` exited 0.
+ */
+export declare function mountOverlay(opts: {
+    lower: string;
+    upper: string;
+    work: string;
+    merged: string;
+}): boolean;
+/** True iff `path` is currently a mountpoint (host-side overlay still mounted). */
+export declare function isMounted(path: string): boolean;
+/** Unmount an overlay merged dir. Best-effort: lazy-umount (`-l`) if a normal
+ *  umount fails (busy fd from a still-draining child). No-op if not a mount. */
+export declare function unmountOverlay(merged: string): void;
+export interface SandboxPlan {
+    /** In-sandbox path the project is bound at — equals the original workingDir the
+     *  CLI was given, so the CLI's existing path args resolve. Also the child's chdir. */
+    projectMount: string;
+    /** Host path of the merged project overlay (reads=real lower, writes=upper). */
+    projectMerged: string;
+    /** In-sandbox path the home overlay is bound at — equals the real home path so
+     *  every CLI's hardcoded `~/.<cli>` resolves there. */
+    home: string;
+    /** Host path of the merged home overlay. */
+    homeMerged: string;
+    /** Daemon-mediated `botmux send` outbox — bound LAST so it wins over any mask. */
+    outbox: string;
+    /** Per-bot privacy masks: directories blanked with an empty tmpfs. */
+    hideDirs: string[];
+    /** Per-bot privacy masks: files blanked with a read-only empty placeholder. */
+    hideFiles: {
+        path: string;
+        empty: 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 (later mounts win): the whole real fs read-only first, then
+ * the home + project merged overlays bind over it (so writes there are isolated),
+ * then privacy masks blank specific paths, then the outbox binds LAST so it stays
+ * writable even if a mask covers a parent dir.
+ */
+export declare function buildSandboxArgs(plan: SandboxPlan): string[];
+/** Is file-sandbox enabled for this session? Spike gate = env; the real
+ *  per-bot BotConfig.sandbox flag is decided by the caller. */
+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, proxies). */
+    env: Record<string, string>;
+    /** Outbox dir the daemon watcher must service. */
+    outbox: string;
+    /** Project overlay UPPER dir — THE LANDABLE CHANGESET (used by sandbox-land). */
+    workDir: string;
+    /** HOME overlay UPPER dir (/var/tmp/botmux-sbx/<sid>/home-upper). The sandboxed
+     *  CLI's $HOME writes — INCLUDING its session jsonl under CLAUDE_CONFIG_DIR —
+     *  land here (invisible at the real path). The worker redirects its bridge/idle
+     *  watch into this via sandboxedClaudeDataDir() so it sees the CLI's turns. */
+    homeUpper: string;
+    /** Unmount the overlays + remove the per-session sandbox tree. */
+    cleanup: () => void;
+}
+/** The path where a sandboxed session's CLI actually writes a $HOME-relative
+ *  data dir (e.g. CLAUDE_CONFIG_DIR / `.claude-runtime`): the HOME overlay's
+ *  ephemeral UPPER copy. The worker redirects its jsonl/bridge watch here so it
+ *  sees the sandboxed CLI's writes (which are invisible at the real host path).
+ *  Mirrors prepareSandbox's homeUpper layout — keep in sync. */
+export declare function sandboxedClaudeDataDir(sessionId: string, realDataDir: string): string;
+/**
+ * Build the sandboxed spawn for a CLI session, or return null when sandboxing
+ * is off / unsupported / a required overlay mount fails (fail-safe = the worker
+ * treats null as a hard error and does NOT silently run unsandboxed).
+ *
+ * Layout under <dataDir>/sandboxes/<sessionId>/: outbox, shimbin, proj-upper
+ * (the landable changeset), proj-work, proj-merged, home-merged. The HOME
+ * overlay's upper/work live under /var/tmp/botmux-sbx/<sessionId>/ because
+ * overlayfs forbids upper/work inside the lower (= the real home).
+ */
+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[];
+    /** Per-bot privacy masks (opt-in, no defaults). Paths existing as dirs are
+     *  blanked with a tmpfs; files with an empty read-only placeholder. */
+    hidePaths?: string[];
+}): SandboxSpawn | null;
+/**
+ * Re-attach the daemon/worker side to an ALREADY-spawned sandbox session WITHOUT
+ * touching the overlays. Used on daemon-restart reattach to a persistent
+ * (tmux/herdr/zellij) pane whose bwrap'd CLI is still alive: the CLI is bound to
+ * its own namespace-pinned overlay, so we must NOT unmount/remount (that would
+ * leave a duplicate host-side mount the CLI isn't using). We only need the outbox
+ * path back so the watcher can keep servicing the live CLI's `botmux send`, plus
+ * the workDir (upper changeset for landing) and a cleanup that tears the residue
+ * down at close/exit. Returns null if the session has no sandbox tree on disk
+ * (never sandboxed). Linux-only, mirrors prepareSandbox's layout.
+ */
+export declare function attachSandboxOutbox(opts: {
+    sessionId: string;
+    dataDir: string;
+}): {
+    outbox: string;
+    workDir: string;
+    cleanup: () => void;
+} | null;
+/**
+ * Reclaim leaked sandbox residue.
+ *
+ * Two classes of leak are reclaimed:
+ *  1. NON-ACTIVE orphans — sid not in `activeSessionIds`: the session is gone, so
+ *     any leftover mount/dir is pure residue (the original startup-sweep case,
+ *     guarding against a daemon crash/kill that skipped killCli()).
+ *  2. ACTIVE-but-DEAD — sid IS in `activeSessionIds`, yet NEITHER of its merged
+ *     overlays is still mounted. This closes the blind spot where a sandboxed
+ *     worker was SIGKILL'd (straggler reaper) or crashed: the session stays
+ *     status='active' on disk, so the old "skip if active" rule would let the
+ *     leaked upper/work dirs survive across restarts indefinitely. We only GC an
+ *     active sid when its mounts are ALREADY gone — we NEVER tear down a live
+ *     mount (a CLI persisting in a tmux/herdr/zellij pane is still bound to it),
+ *     so a genuinely-live persistent session keeps its changeset.
+ *
+ * Safe to call repeatedly: wire once at daemon bootstrap AND on a periodic timer
+ * (the SIGKILL/straggler path can't run worker-side killCli(), so a startup-only
+ * sweep would let a crashed-active session's mount survive for the whole next
+ * daemon lifetime — one daemon per bot can run for days).
+ */
+export declare function sweepOrphanSandboxes(dataDir: string, activeSessionIds: Set<string>): void;
+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,
+ * and O_NONBLOCK so opening a FIFO/special the sandbox dropped into the (rw-bound)
+ * outbox returns IMMEDIATELY instead of blocking the synchronous watcher tick
+ * forever (a FIFO with no writer would otherwise hang the whole worker event
+ * loop — an agent-triggerable DoS). After open we fstat-reject anything that
+ * isn't a regular file (a FIFO opened O_NONBLOCK|O_RDONLY succeeds but isFile()
+ * is false → rejected here). 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":"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"}