pi-terminal-mux 0.2.2 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-terminal-mux
 
-Terminal multiplexer abstraction for pi extensions — one unified surface API across **muxy, cmux, tmux, zellij, wezterm, herdr and otty**, with automatic **headless fallback** (background child process + log file) when no multiplexer is detected.
+Terminal multiplexer abstraction for pi extensions — one unified surface API across **muxy, cmux, tmux, zellij, wezterm, herdr, otty and orca**, with automatic **headless fallback** (background child process + log file) when no multiplexer is detected.
 
 Any pi extension that needs terminal interaction (splitting panes, sending commands, reading screens, closing panes, waiting for process exit) should depend on this package instead of re-implementing backend detection and command assembly.
 
@@ -57,10 +57,11 @@ closeSurface(surface);
 | wezterm | `WEZTERM_UNIX_SOCKET` + `wezterm` command |
 | herdr | `HERDR_ENV=1` + `HERDR_PANE_ID` + `herdr` command |
 | otty | `TERM_PROGRAM=otty` + `otty` command |
+| orca | `TERM_PROGRAM=Orca` + `orca` command + reachable Orca runtime |
 
 Default priority follows the table order (muxy first). Force a backend with:
 
-- `PI_TERMINAL_MUX` (preferred): `muxy | cmux | tmux | zellij | wezterm | herdr | otty`
+- `PI_TERMINAL_MUX` (preferred): `muxy | cmux | tmux | zellij | wezterm | herdr | otty | orca`
 - `PI_SUBAGENT_MUX`: backward-compatible alias
 
 If the forced backend's runtime is unavailable, `getMuxBackend()` returns `null` — it never silently falls back to another backend.
@@ -71,7 +72,7 @@ If the forced backend's runtime is unavailable, `getMuxBackend()` returns `null`
 
 | Function | Description |
 |----------|-------------|
-| `createSurface(name)` | Smart placement (cmux: first right-split then tabs; zellij: tab-aware tiled/stacked; muxy/otty: breadth-first splits), returns a surface handle |
+| `createSurface(name)` | Smart placement (cmux: first right-split then tabs; zellij: tab-aware tiled/stacked; muxy/otty: breadth-first splits; orca: new tab in the current worktree), returns a surface handle |
 | `createSurfaceSplit(name, direction, fromSurface?)` | Split in an explicit direction (left/right/up/down) |
 | `sendCommand(surface, command)` | Send a command and press Enter |
 | `sendLongCommand(surface, command, opts?)` | Write long commands to a script file first; `opts.scriptPreamble` injects env exports; returns the script path |
@@ -88,7 +89,7 @@ If the forced backend's runtime is unavailable, `getMuxBackend()` returns `null`
 
 ### Backend-native APIs
 
-Backend-native functions are also re-exported (e.g. `createHerdrSurface`, `splitHerdrPane`, `readHerdrScreen`, `sendOttyCommand`, `renameOttyTab`, ...). Subpath imports are available too: `pi-terminal-mux/mux`, `pi-terminal-mux/herdr`, `pi-terminal-mux/otty`.
+Backend-native functions are also re-exported (e.g. `createHerdrSurface`, `splitHerdrPane`, `readHerdrScreen`, `sendOttyCommand`, `renameOttyTab`, `createOrcaSurface`, `sendOrcaCommand`, ...). Subpath imports are available too: `pi-terminal-mux/mux`, `pi-terminal-mux/herdr`, `pi-terminal-mux/otty`, `pi-terminal-mux/orca`.
 
 ## Headless mode
 
@@ -108,7 +109,7 @@ When no backend is detected, `createSurface` returns a `headless:`-prefixed surf
 
 - **No machine coupling**: every backend is selected via runtime detection (env vars + command availability); no hardcoded local paths; missing CLIs degrade backend-by-backend down to headless.
 - **Localized user-facing text**: setup hints go through the [pi-extensions-i18n](https://www.npmjs.com/package/pi-extensions-i18n) catalog with complete `zh-CN` and `en-US` entries.
-- **Agent pane anchoring**: the agent's own pane ID on muxy/herdr/otty is captured at module load (`AGENT_MUXY_PANE_ID` etc.), immune to later focus switches.
+- **Agent pane anchoring**: the agent's own pane ID on muxy/herdr/otty/orca is captured at module load (`AGENT_MUXY_PANE_ID`, `AGENT_ORCA_TERMINAL_HANDLE` etc.), immune to later focus switches.
 
 ## License
 

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 终端多路复用器统一抽象层，供 pi 扩展复用。任何涉及终端交互（分屏、发命令、读屏、关屏、等待退出）的插件都应依赖本包，而不是各自重新实现 backend 探测与命令拼装。
 
-一套统一的 surface API 跨 **muxy、cmux、tmux、zellij、wezterm、herdr、otty** 七个后端，探测不到任何后端时自动降级为 **headless**（后台子进程 + 日志文件）。
+一套统一的 surface API 跨 **muxy、cmux、tmux、zellij、wezterm、herdr、otty、orca** 八个后端，探测不到任何后端时自动降级为 **headless**（后台子进程 + 日志文件）。
 
 [English README](./README.md)
 
@@ -56,10 +56,11 @@ closeSurface(surface);
 | wezterm | `WEZTERM_UNIX_SOCKET` + `wezterm` 命令 |
 | herdr | `HERDR_ENV=1` + `HERDR_PANE_ID` + `herdr` 命令 |
 | otty | `TERM_PROGRAM=otty` + `otty` 命令 |
+| orca | `TERM_PROGRAM=Orca` + `orca` 命令 + Orca runtime 可达 |
 
 默认优先级即上表顺序（muxy 优先）。可用环境变量强制指定后端：
 
-- `PI_TERMINAL_MUX`（推荐）：`muxy | cmux | tmux | zellij | wezterm | herdr | otty`
+- `PI_TERMINAL_MUX`（推荐）：`muxy | cmux | tmux | zellij | wezterm | herdr | otty | orca`
 - `PI_SUBAGENT_MUX`：同上的向后兼容别名
 
 指定的后端运行环境不满足时 `getMuxBackend()` 返回 `null`，不会悄悄降级到其他后端。
@@ -70,7 +71,7 @@ closeSurface(surface);
 
 | 函数 | 说明 |
 |------|------|
-| `createSurface(name)` | 智能放置新 surface（cmux 首次右分屏后续开 tab、zellij tab 感知平铺/堆叠、muxy/otty 广度优先分屏），返回 surface 标识 |
+| `createSurface(name)` | 智能放置新 surface（cmux 首次右分屏后续开 tab、zellij tab 感知平铺/堆叠、muxy/otty 广度优先分屏、orca 在当前 worktree 新建 tab），返回 surface 标识 |
 | `createSurfaceSplit(name, direction, fromSurface?)` | 指定方向（left/right/up/down）分屏 |
 | `sendCommand(surface, command)` | 发送命令并回车执行 |
 | `sendLongCommand(surface, command, opts?)` | 长命令先写脚本文件再执行；`opts.scriptPreamble` 可注入 env export；返回脚本路径 |
@@ -87,7 +88,7 @@ closeSurface(surface);
 
 ### 后端原生 API
 
-各后端原生函数也从包入口透出（如 `createHerdrSurface`、`splitHerdrPane`、`readHerdrScreen`、`sendOttyCommand`、`renameOttyTab`……），子路径导入亦可：`pi-terminal-mux/mux`、`pi-terminal-mux/herdr`、`pi-terminal-mux/otty`。
+各后端原生函数也从包入口透出（如 `createHerdrSurface`、`splitHerdrPane`、`readHerdrScreen`、`sendOttyCommand`、`renameOttyTab`、`createOrcaSurface`、`sendOrcaCommand`……），子路径导入亦可：`pi-terminal-mux/mux`、`pi-terminal-mux/herdr`、`pi-terminal-mux/otty`、`pi-terminal-mux/orca`。
 
 ## Headless 模式
 
@@ -107,7 +108,7 @@ closeSurface(surface);
 
 - **不绑定具体机器**：全部后端通过运行时探测（环境变量 + 命令存在性）选择，零硬编码本机路径；外部 CLI 缺失时按后端逐个降级，最终落到 headless。
 - **用户文案国际化**：面向用户的提示走 [pi-extensions-i18n](https://www.npmjs.com/package/pi-extensions-i18n) catalog，中英文齐全。
-- **agent pane 锚定**：muxy/herdr/otty 的 agent 自身 pane ID 在模块加载时捕获（`AGENT_MUXY_PANE_ID` 等），不受用户后续焦点切换影响。
+- **agent pane 锚定**：muxy/herdr/otty/orca 的 agent 自身 pane ID 在模块加载时捕获（`AGENT_MUXY_PANE_ID`、`AGENT_ORCA_TERMINAL_HANDLE` 等），不受用户后续焦点切换影响。
 
 ## License
 

package/locales/mux.json

@@ -31,9 +31,13 @@
     "zh-CN": "请在 Otty 中运行 pi（Otty 会自动设置 TERM_PROGRAM=otty）。",
     "en-US": "Run pi inside Otty (Otty sets TERM_PROGRAM=otty automatically)."
   },
+  "setupHint.orca": {
+    "zh-CN": "请在 Orca 中运行 pi（Orca 会自动设置 TERM_PROGRAM=Orca 和 ORCA_TERMINAL_HANDLE）。",
+    "en-US": "Run pi inside Orca (Orca sets TERM_PROGRAM=Orca and ORCA_TERMINAL_HANDLE automatically)."
+  },
   "setupHint.generic": {
-    "zh-CN": "请在 Muxy、cmux（`cmux pi`）、tmux（`tmux new -A -s pi 'pi'`）、zellij（`zellij --session pi`，然后运行 `pi`）、WezTerm、herdr（运行 `herdr`，拆分 pane 后在其中运行 `pi`）或 Otty（Otty 会自动设置 TERM_PROGRAM=otty）中启动 pi。",
-    "en-US": "Start pi inside Muxy, cmux (`cmux pi`), tmux (`tmux new -A -s pi 'pi'`), zellij (`zellij --session pi`, then run `pi`), WezTerm, herdr (run `herdr`, split a pane, then run `pi` in it), or Otty (Otty sets TERM_PROGRAM=otty automatically)."
+    "zh-CN": "请在 Muxy、cmux（`cmux pi`）、tmux（`tmux new -A -s pi 'pi'`）、zellij（`zellij --session pi`，然后运行 `pi`）、WezTerm、herdr（运行 `herdr`，拆分 pane 后在其中运行 `pi`）、Otty（Otty 会自动设置 TERM_PROGRAM=otty）或 Orca（Orca 会自动设置 TERM_PROGRAM=Orca）中启动 pi。",
+    "en-US": "Start pi inside Muxy, cmux (`cmux pi`), tmux (`tmux new -A -s pi 'pi'`), zellij (`zellij --session pi`, then run `pi`), WezTerm, herdr (run `herdr`, split a pane, then run `pi` in it), Otty (Otty sets TERM_PROGRAM=otty automatically), or Orca (Orca sets TERM_PROGRAM=Orca automatically)."
   },
   "setupHint.herdrPreferred": {
     "zh-CN": "请在 herdr 中启动 pi（必须设置 HERDR_ENV=1；先运行 herdr，再在 pane 中启动 pi）。",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-terminal-mux",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Terminal multiplexer abstraction for pi extensions — unified surface API across muxy, cmux, tmux, zellij, wezterm, herdr and otty, with headless fallback",
   "type": "module",
   "main": "./index.ts",
@@ -9,7 +9,8 @@
     "./package.json": "./package.json",
     "./mux": "./src/mux.ts",
     "./herdr": "./src/herdr.ts",
-    "./otty": "./src/otty.ts"
+    "./otty": "./src/otty.ts",
+    "./orca": "./src/orca.ts"
   },
   "files": [
     "index.ts",

package/src/backends/orca.ts

@@ -0,0 +1,380 @@
+/**
+ * orca.ts — Orca 终端后端（https://orca.dev，Stably 的 agent 工作台）
+ *
+ * Orca 是面向 agent 的桌面工作台，通过 `orca` CLI 提供 terminal 编程化控制：
+ *   - `orca terminal create --title <name> --json`     新建 tab（不抢焦点）
+ *   - `orca terminal split --terminal <h> --direction horizontal|vertical --json`
+ *   - `orca terminal send --terminal <h> --text <text> [--enter]`
+ *   - `orca terminal read --terminal <h> --limit <N> --json`
+ *   - `orca terminal close --terminal <h> [--tab]`
+ *   - `orca terminal rename --terminal <h> --title <name>`
+ *   - `orca terminal list --json` / `orca status --json`
+ *
+ * 所有 JSON 响应共享信封：{ id, ok, result, _meta }。
+ *   - create → result.terminal.handle
+ *   - split  → result.split.handle
+ *   - read   → result.terminal.tail（字符串数组，最新在尾部）
+ *
+ * 与其他 backend 的关键差异：
+ *   1. Orca 注入 ORCA_TERMINAL_HANDLE（类似 cmux 的 CMUX_SURFACE_ID），
+ *      模块加载时冻结为 AGENT_ORCA_TERMINAL_HANDLE。
+ *   2. create() 走"新 tab"而非分屏：Orca 是 worktree 中心的工作台，
+ *      官方建议 agent 用 `terminal create` 开新终端；不拆分 agent 自己的
+ *      pane，避免压缩 pi 的 UI。因此不使用 shared.ts 的 BFS 分屏状态机。
+ *   3. Escape 通过发送裸 ESC（`\u001b`，即 `0x1b`）字节实现，TUI 会将其解释为 Escape 键。
+ *   4. rename 作用于 tab 标题；split 出来的 pane 与源 pane 共享 tab，
+ *      所以 createSplit 不做 rename（否则会把 agent 所在 tab 一起改名）。
+ *   5. split 方向只有 horizontal|vertical。实测（Orca 1.4.174）：
+ *      horizontal = 水平分割线 = 上下堆叠，vertical = 垂直分割线 = 左右并排。
+ *      因此映射 left/right→vertical、up/down→horizontal。
+ *
+ * 日志、命令检测复用 backends/shared.ts。
+ */
+
+import { spawnSync } from "node:child_process";
+import { createBackendLogger, hasCommand } from "./shared.ts";
+import type { BackendOps } from "./types.ts";
+
+const ORCA_RUNTIME_CHECK_TIMEOUT_MS = 1_500;
+const ORCA_COMMAND_TIMEOUT_MS = 10_000;
+
+// ── 日志（统一格式，写入 /tmp/pi-mux-orca.log） ──
+const orcaLog = createBackendLogger("orca", "/tmp/pi-mux-orca.log");
+
+// ── Orca 检测 ──
+
+/**
+ * 检测 orca backend 是否可用：
+ *   1. 当前进程在 Orca 终端内运行（TERM_PROGRAM=Orca）
+ *   2. `orca` 命令在 PATH 中
+ *   3. Orca runtime 可达（`orca status --json` 返回 ok:true，带 1.5s 超时）
+ *
+ * 不要求 ORCA_TERMINAL_HANDLE：create/read/send 等操作都针对显式 handle，
+ * 只有 createSplit 的默认 split 源需要它（缺失时由 splitOrcaTerminal 报错）。
+ */
+export function isOrcaRuntimeAvailable(): boolean {
+  if (process.env.TERM_PROGRAM !== "Orca") return false;
+  if (!hasCommand("orca")) return false;
+
+  // 最后一道闸：CLI 存在但 runtime 未启动时 `orca status` 会失败或 hang。
+  // spawnSync timeout 兜底，避免探测卡死主流程。
+  try {
+    const result = spawnSync("orca", ["status", "--json"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: ORCA_RUNTIME_CHECK_TIMEOUT_MS,
+    });
+    if (result.error || result.status !== 0) return false;
+    const parsed = parseOrcaJson(result.stdout ?? "");
+    return parsed?.ok === true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Agent terminal handle ──
+
+/**
+ * 捕获于模块加载时的 agent terminal handle。
+ * Orca 注入 ORCA_TERMINAL_HANDLE（类似 cmux 注入 CMUX_SURFACE_ID），
+ * 冻结到常量，不受用户后续切换 tab 影响。
+ */
+export const AGENT_ORCA_TERMINAL_HANDLE: string | null = process.env.ORCA_TERMINAL_HANDLE ?? null;
+
+// ── JSON 信封解析（纯函数，可单测） ──
+
+/** orca CLI 的 JSON 响应信封 */
+export interface OrcaEnvelope {
+  ok?: boolean;
+  result?: Record<string, unknown>;
+}
+
+export function parseOrcaJson(output: string): OrcaEnvelope | null {
+  const trimmed = output.trim();
+  if (!trimmed) return null;
+  try {
+    const parsed = JSON.parse(trimmed) as OrcaEnvelope;
+    if (typeof parsed !== "object" || parsed === null) return null;
+    return parsed;
+  } catch (e) {
+    orcaLog(`[parse json] failed: ${(e as Error).message} raw=${JSON.stringify(trimmed.slice(0, 200))}`);
+    return null;
+  }
+}
+
+/** 从 `terminal create --json` 响应提取 handle：result.terminal.handle */
+export function extractOrcaCreateHandle(payload: OrcaEnvelope | null): string | null {
+  if (payload?.ok !== true) return null;
+  const terminal = payload?.result?.["terminal"];
+  if (typeof terminal !== "object" || terminal === null) return null;
+  const handle = (terminal as Record<string, unknown>)["handle"];
+  return typeof handle === "string" && handle ? handle : null;
+}
+
+/** 从 `terminal split --json` 响应提取新 pane handle：result.split.handle */
+export function extractOrcaSplitHandle(payload: OrcaEnvelope | null): string | null {
+  if (payload?.ok !== true) return null;
+  const split = payload?.result?.["split"];
+  if (typeof split !== "object" || split === null) return null;
+  const handle = (split as Record<string, unknown>)["handle"];
+  return typeof handle === "string" && handle ? handle : null;
+}
+
+/** 从 `terminal read --json` 响应提取屏幕行：result.terminal.tail（数组，最新在尾部） */
+export function extractOrcaReadTail(payload: OrcaEnvelope | null): string[] {
+  if (payload?.ok !== true) return [];
+  const terminal = payload?.result?.["terminal"];
+  if (typeof terminal !== "object" || terminal === null) return [];
+  const tail = (terminal as Record<string, unknown>)["tail"];
+  if (!Array.isArray(tail)) return [];
+  return tail.filter((line): line is string => typeof line === "string");
+}
+
+/**
+ * 统一方向 → orca split 方向。
+ * 实测（Orca 1.4.174，分割线轴约定，与 iTerm 一致）：
+ *   horizontal = 上下堆叠（up/down），vertical = 左右并排（left/right）。
+ */
+export function orcaSplitDirection(direction: "left" | "right" | "up" | "down"): "horizontal" | "vertical" {
+  return direction === "left" || direction === "right" ? "vertical" : "horizontal";
+}
+
+// ── Orca CLI 调用的薄封装 ──
+
+/**
+ * 调用 `orca` 命令并返回 stdout。
+ * 失败时 stderr 写入 log，原样抛错（调用方决定如何处理）。
+ */
+function orcaExec(args: string[]): string {
+  const cmdline = `orca ${args
+    .map((a) => (a.includes(" ") || a.includes('"') ? JSON.stringify(a) : a))
+    .join(" ")}`;
+  orcaLog(`[exec] ${cmdline}`);
+  const result = spawnSync("orca", args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: ORCA_COMMAND_TIMEOUT_MS,
+  });
+  if (result.error) {
+    orcaLog(`[exec] ERROR (spawn): ${result.error.message}`);
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    const stderr = (result.stderr ?? "").trim();
+    orcaLog(`[exec] ERROR status=${result.status} stderr=${JSON.stringify(stderr)}`);
+    throw new Error(`orca ${args[0]} ${args[1] ?? ""} failed (status=${result.status}): ${stderr}`);
+  }
+  orcaLog(`[exec] -> ${JSON.stringify(result.stdout.trim().slice(0, 200))}`);
+  return result.stdout;
+}
+
+/** 调用 `orca` 命令，失败只记 log 不抛错。用于 send/rename/close 这类 best-effort 操作。 */
+function orcaExecSilent(args: string[]): void {
+  const cmdline = `orca ${args
+    .map((a) => (a.includes(" ") || a.includes('"') ? JSON.stringify(a) : a))
+    .join(" ")}`;
+  orcaLog(`[exec silent] ${cmdline}`);
+  const result = spawnSync("orca", args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: ORCA_COMMAND_TIMEOUT_MS,
+  });
+  if (result.error || result.status !== 0) {
+    orcaLog(
+      `[exec silent] ERROR status=${result.status} stderr=${JSON.stringify(
+        (result.stderr ?? "").trim().slice(0, 200),
+      )}`,
+    );
+  }
+}
+
+// ── 对外 API ──
+
+/**
+ * 创建一个新的 subagent terminal。
+ *
+ * 实现：`orca terminal create --title <name>` 在当前 worktree 新建 tab
+ * （CLI 语义：不抢焦点）。与 otty/muxy 的 BFS 分屏不同，新 tab 不会压缩
+ * agent 自己的 pane，符合 Orca 的 worktree 中心工作流。
+ *
+ * 失败返回 ""（与 otty createSurface 一致，调用方统一处理）。
+ */
+export function createOrcaSurface(name: string): string {
+  try {
+    const raw = orcaExec(["terminal", "create", "--title", name, "--json"]);
+    const handle = extractOrcaCreateHandle(parseOrcaJson(raw));
+    if (!handle) {
+      orcaLog(`[create] no handle in response for name=${JSON.stringify(name)}`);
+      return "";
+    }
+    orcaLog(`[create] new=${handle} name=${JSON.stringify(name)}`);
+    return handle;
+  } catch (e) {
+    orcaLog(`[create] failed: ${(e as Error).message}`);
+    return "";
+  }
+}
+
+/**
+ * 指定方向分屏创建新 pane。
+ * fromSurface 缺省时从 agent 自己的 terminal（ORCA_TERMINAL_HANDLE）拆。
+ * 失败返回 ""。
+ */
+export function splitOrcaTerminal(
+  direction: "left" | "right" | "up" | "down",
+  fromSurface?: string,
+): string {
+  const source = fromSurface ?? AGENT_ORCA_TERMINAL_HANDLE;
+  if (!source) {
+    orcaLog(`[split] no source terminal (ORCA_TERMINAL_HANDLE not set)`);
+    return "";
+  }
+  const orcaDir = orcaSplitDirection(direction);
+  try {
+    const raw = orcaExec(["terminal", "split", "--terminal", source, "--direction", orcaDir, "--json"]);
+    const handle = extractOrcaSplitHandle(parseOrcaJson(raw));
+    if (!handle) {
+      orcaLog(`[split] no handle in response (from=${source} dir=${orcaDir})`);
+      return "";
+    }
+    orcaLog(`[split] from=${source} dir=${orcaDir} new=${handle}`);
+    return handle;
+  } catch (e) {
+    orcaLog(`[split] from=${source} dir=${orcaDir} failed: ${(e as Error).message}`);
+    return "";
+  }
+}
+
+/**
+ * 给 terminal 发送命令 + Enter。
+ * `orca terminal send --text <cmd> --enter`，失败只记 log（best-effort）。
+ */
+export function sendOrcaCommand(handle: string, command: string): void {
+  orcaExecSilent(["terminal", "send", "--terminal", handle, "--text", command, "--enter"]);
+}
+
+/**
+ * 给 terminal 发送 Escape。
+ * 实现：发送裸 ESC（`\u001b`，即 `0x1b`）字节，TUI 会将其解释为 Escape 键。
+ * 注意不能用 --enter（会把 ESC 和回车拼成一行输入）。
+ */
+export function sendOrcaEscape(handle: string): void {
+  orcaExecSilent(["terminal", "send", "--terminal", handle, "--text", "\u001b"]);
+}
+
+/**
+ * 读取 terminal 屏幕最后 N 行。
+ * `orca terminal read --limit <N> --json` → result.terminal.tail，拼成文本返回。
+ * 失败返回 ""（与 otty readScreen 一致）。
+ */
+export function readOrcaScreen(handle: string, lines = 50): string {
+  try {
+    const raw = orcaExec(["terminal", "read", "--terminal", handle, "--limit", String(lines), "--json"]);
+    return extractOrcaReadTail(parseOrcaJson(raw)).join("\n");
+  } catch (e) {
+    orcaLog(`[read] terminal=${handle} failed: ${(e as Error).message}`);
+    return "";
+  }
+}
+
+/**
+ * 查询 terminal 是否仍在 list 中（三态）。
+ * true = 确认存在；false = 成功取到 list 且 handle 不在其中；
+ * null = 查询本身失败（runtime 不可达/响应异常），不能当作“已关闭”。
+ */
+function queryOrcaTerminalExists(handle: string): boolean | null {
+  try {
+    const raw = orcaExec(["terminal", "list", "--json"]);
+    const parsed = parseOrcaJson(raw);
+    const terminals = parsed?.result?.["terminals"];
+    if (!Array.isArray(terminals)) return null;
+    return terminals.some(
+      (t) => typeof t === "object" && t !== null && (t as Record<string, unknown>)["handle"] === handle,
+    );
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 关闭 terminal。
+ *
+ * create() 生成的 surface 独占一个 tab，split 生成的 pane 共享 tab。
+ * 策略（best-effort，绝不 throw，避免 pollForExit 退出流程被打断）：
+ *   1. `terminal close`（关 pane/session）
+ *   2. 验证 handle 是否还在列表；不在了则完成
+ *   3. 仍在则补 `terminal close --tab`（单 pane tab 的残留情况）
+ *   4. 仍失败仅 log warn
+ */
+export function closeOrcaSurface(handle: string): void {
+  orcaExecSilent(["terminal", "close", "--terminal", handle, "--json"]);
+
+  let exists = queryOrcaTerminalExists(handle);
+  if (exists === false) {
+    orcaLog(`[close] terminal ${handle} closed`);
+    return;
+  }
+  if (exists === null) {
+    // 查询失败不能当作已关闭；继续尝试 --tab 兜底
+    orcaLog(`[close] WARN terminal ${handle} list query failed, cannot verify close`);
+  }
+
+  orcaLog(`[close] terminal ${handle} still present, trying --tab`);
+  orcaExecSilent(["terminal", "close", "--terminal", handle, "--tab", "--json"]);
+
+  exists = queryOrcaTerminalExists(handle);
+  if (exists === false) {
+    orcaLog(`[close] terminal ${handle} closed via --tab`);
+  } else if (exists === null) {
+    orcaLog(`[close] WARN terminal ${handle} close sent but unverifiable (list query failed)`);
+  } else {
+    orcaLog(`[close] WARN terminal ${handle} still present after close --tab`);
+  }
+}
+
+/**
+ * 重命名 terminal 所在 tab。
+ * 注意：rename 作用于 tab 标题，split pane 与源 pane 共享 tab ——
+ * 调用方需确认 target 是独立 tab（create() 产物或 agent 自己的 terminal）。
+ */
+export function renameOrcaTerminal(handle: string, name: string): void {
+  orcaExecSilent(["terminal", "rename", "--terminal", handle, "--title", name]);
+}
+
+// ── BackendOps 适配器（薄包装以上原生函数，行为语义见各函数注释） ──
+
+/** BackendOps 适配器：所有方法薄包装 orca 原生函数 */
+export const ops: BackendOps = {
+  /** 创建 orca surface（新 tab，不抢焦点） */
+  create(name: string): string {
+    return createOrcaSurface(name);
+  },
+  /** 指定方向分屏；不做 rename（split pane 与源 pane 共享 tab 标题） */
+  createSplit(name: string, direction: "left" | "right" | "up" | "down", fromSurface?: string): string {
+    return splitOrcaTerminal(direction, fromSurface);
+  },
+  /** 向 orca terminal 发送命令并执行 */
+  send(surface: string, command: string): void {
+    sendOrcaCommand(surface, command);
+  },
+  /** 向 orca terminal 发送 Escape（裸 ESC 字节） */
+  sendEscape(surface: string): void {
+    sendOrcaEscape(surface);
+  },
+  /** 同步读取 orca terminal 屏幕最后 N 行 */
+  read(surface: string, lines = 50): string {
+    return readOrcaScreen(surface, lines);
+  },
+  /** 异步读取 orca terminal 屏幕最后 N 行 */
+  async readAsync(surface: string, lines = 50): Promise<string> {
+    return readOrcaScreen(surface, lines);
+  },
+  /** 关闭 orca terminal（best-effort：close → close --tab → log warn） */
+  close(surface: string): void {
+    closeOrcaSurface(surface);
+  },
+  /** 重命名 orca terminal 所在 tab */
+  rename(surface: string, name: string): void {
+    renameOrcaTerminal(surface, name);
+  },
+};

package/src/detection.ts

@@ -14,6 +14,7 @@ import { appendFileSync } from "node:fs";
 import { i18n } from "./i18n.ts";
 import { isHerdrRuntimeAvailable } from "./herdr.ts";
 import { isOttyRuntimeAvailable, ottySetupHint } from "./otty.ts";
+import { isOrcaRuntimeAvailable } from "./orca.ts";
 import { hasCommand } from "./backends/shared.ts";
 
 // ── 分屏调试日志 ──
@@ -49,7 +50,7 @@ export const AGENT_MUXY_PANE_ID = process.env.MUXY_PANE_ID;
 
 // ── 后端类型 ──
 
-export type MuxBackend = "cmux" | "muxy" | "tmux" | "zellij" | "wezterm" | "herdr" | "otty";
+export type MuxBackend = "cmux" | "muxy" | "tmux" | "zellij" | "wezterm" | "herdr" | "otty" | "orca";
 
 // 命令可用性检测复用 backends/shared.ts 的 hasCommand（跨平台 + 缓存）。
 
@@ -65,7 +66,8 @@ function muxPreference(): MuxBackend | null {
     pref === "zellij" ||
     pref === "wezterm" ||
     pref === "herdr" ||
-    pref === "otty"
+    pref === "otty" ||
+    pref === "orca"
   )
     return pref;
   return null;
@@ -123,6 +125,10 @@ export function isOttyAvailable(): boolean {
   return isOttyRuntimeAvailable();
 }
 
+export function isOrcaAvailable(): boolean {
+  return isOrcaRuntimeAvailable();
+}
+
 // ── 后端探测入口 ──
 
 export function getMuxBackend(): MuxBackend | null {
@@ -134,6 +140,7 @@ export function getMuxBackend(): MuxBackend | null {
   if (pref === "wezterm") return isWezTermRuntimeAvailable() ? "wezterm" : null;
   if (pref === "herdr") return isHerdrRuntimeAvailable() ? "herdr" : null;
   if (pref === "otty") return isOttyRuntimeAvailable() ? "otty" : null;
+  if (pref === "orca") return isOrcaRuntimeAvailable() ? "orca" : null;
 
   if (isMuxyRuntimeAvailable()) return "muxy";
   if (isCmuxRuntimeAvailable()) return "cmux";
@@ -142,6 +149,7 @@ export function getMuxBackend(): MuxBackend | null {
   if (isWezTermRuntimeAvailable()) return "wezterm";
   if (isHerdrRuntimeAvailable()) return "herdr";
   if (isOttyRuntimeAvailable()) return "otty";
+  if (isOrcaRuntimeAvailable()) return "orca";
   return null;
 }
 

package/src/index.ts

@@ -1,7 +1,7 @@
 /**
  * pi-terminal-mux — 终端多路复用器统一抽象层
  *
- * 支持后端：muxy / cmux / tmux / zellij / wezterm / herdr / otty，
+ * 支持后端：muxy / cmux / tmux / zellij / wezterm / herdr / otty / orca，
  * 探测不到任何后端时自动降级为 headless（后台子进程 + 日志文件）。
  *
  * 统一 surface API（跨后端一致语义）：
@@ -61,6 +61,25 @@ export {
 } from "./otty.ts";
 export type { OttyPaneSnapshot } from "./otty.ts";
 
+// ── orca 后端原生 API ──
+export {
+  AGENT_ORCA_TERMINAL_HANDLE,
+  isOrcaRuntimeAvailable,
+  parseOrcaJson,
+  extractOrcaCreateHandle,
+  extractOrcaSplitHandle,
+  extractOrcaReadTail,
+  orcaSplitDirection,
+  createOrcaSurface,
+  splitOrcaTerminal,
+  sendOrcaCommand,
+  sendOrcaEscape,
+  readOrcaScreen,
+  closeOrcaSurface,
+  renameOrcaTerminal,
+} from "./orca.ts";
+export type { OrcaEnvelope } from "./orca.ts";
+
 // ── 便捷函数 ──
 import {
   AGENT_MUXY_PANE_ID,
@@ -69,6 +88,7 @@ import {
 } from "./mux.ts";
 import { AGENT_HERDR_PANE_ID } from "./herdr.ts";
 import { AGENT_OTTY_PANE_ID } from "./otty.ts";
+import { AGENT_ORCA_TERMINAL_HANDLE } from "./orca.ts";
 
 /**
  * 返回各后端注入 agent pane 标识的环境变量名（用于错误提示）。
@@ -90,6 +110,8 @@ export function backendAgentPaneEnvVar(backend: MuxBackend): string | null {
       return "HERDR_PANE_ID";
     case "otty":
       return null;
+    case "orca":
+      return "ORCA_TERMINAL_HANDLE";
   }
 }
 
@@ -103,6 +125,7 @@ export function getAgentPaneId(backend?: MuxBackend | null): string | null {
   if (resolved === "muxy") return AGENT_MUXY_PANE_ID ?? null;
   if (resolved === "herdr") return AGENT_HERDR_PANE_ID ?? null;
   if (resolved === "otty") return AGENT_OTTY_PANE_ID ?? null;
+  if (resolved === "orca") return AGENT_ORCA_TERMINAL_HANDLE ?? null;
   if (resolved === "tmux") return process.env.TMUX_PANE ?? null;
   if (resolved === "wezterm") return process.env.WEZTERM_PANE ?? null;
   if (resolved === "zellij") return process.env.ZELLIJ_PANE_ID ?? null;

package/src/mux.ts

@@ -20,6 +20,7 @@ export {
   isWezTermAvailable,
   isHerdrAvailable,
   isOttyAvailable,
+  isOrcaAvailable,
 } from "./detection.ts";
 
 export {

package/src/orca.ts

@@ -0,0 +1,24 @@
+/**
+ * orca.ts — orca 后端 barrel（向后兼容 subpath 导入）
+ *
+ * 所有实现已迁至 backends/orca.ts，此文件仅做 re-export。
+ * 显式列出符号（不用 export *），避免内部 BackendOps 适配器 ops 泄漏到公开 API。
+ */
+
+export {
+  AGENT_ORCA_TERMINAL_HANDLE,
+  closeOrcaSurface,
+  createOrcaSurface,
+  extractOrcaCreateHandle,
+  extractOrcaReadTail,
+  extractOrcaSplitHandle,
+  isOrcaRuntimeAvailable,
+  orcaSplitDirection,
+  parseOrcaJson,
+  readOrcaScreen,
+  renameOrcaTerminal,
+  sendOrcaCommand,
+  sendOrcaEscape,
+  splitOrcaTerminal,
+} from "./backends/orca.ts";
+export type { OrcaEnvelope } from "./backends/orca.ts";

package/src/surface.ts

@@ -45,10 +45,12 @@ import { ops as zellijOps } from "./backends/zellij.ts";
 import { ops as weztermOps } from "./backends/wezterm.ts";
 import { ops as herdrOps, AGENT_HERDR_PANE_ID, renameHerdrTab, renameHerdrWorkspace } from "./backends/herdr.ts";
 import { ops as ottyOps, AGENT_OTTY_PANE_ID } from "./backends/otty.ts";
+import { ops as orcaOps, AGENT_ORCA_TERMINAL_HANDLE } from "./backends/orca.ts";
 
 // 各后端直接引用的公开函数（非对称操作不进 BackendOps）
 import { renameHerdrPane, renameHerdrAgent, sendHerdrCommand, sendHerdrEscape, readHerdrScreen, closeHerdrSurface } from "./backends/herdr.ts";
 import { sendOttyCommand, sendOttyEscape, readOttyScreen, closeOttySurface, renameOttyTab } from "./backends/otty.ts";
+import { renameOrcaTerminal } from "./backends/orca.ts";
 
 const execFileAsync = promisify(execFile);
 
@@ -63,6 +65,7 @@ const backendOps: Record<MuxBackend, BackendOps> = {
   wezterm: weztermOps,
   herdr: herdrOps,
   otty: ottyOps,
+  orca: orcaOps,
 };
 
 // ── 内部辅助 ──
@@ -155,6 +158,9 @@ export function createSurfaceSplit(
     lastSplitSource = sourcePane;
   } else if (backend === "otty") {
     lastSplitSource = fromSurface ?? AGENT_OTTY_PANE_ID ?? null;
+  } else if (backend === "orca") {
+    // orca split 默认从 agent 自己的 terminal 拆，与 splitOrcaTerminal 的回退逻辑一致
+    lastSplitSource = fromSurface ?? AGENT_ORCA_TERMINAL_HANDLE ?? null;
   } else {
     // tmux / wezterm / zellij
     const source = backend === "tmux" ? process.env.TMUX_PANE : fromSurface;
@@ -359,6 +365,12 @@ export function renameCurrentTab(title: string): void {
     return;
   }
 
+  if (backend === "orca") {
+    if (!AGENT_ORCA_TERMINAL_HANDLE) throw new Error("ORCA_TERMINAL_HANDLE not set");
+    renameOrcaTerminal(AGENT_ORCA_TERMINAL_HANDLE, title);
+    return;
+  }
+
   // zellij: rename the agent's own pane
   const paneId = process.env.ZELLIJ_PANE_ID;
   if (paneId) {
@@ -424,6 +436,11 @@ export function renameWorkspace(title: string): void {
     return;
   }
 
+  if (backend === "orca") {
+    // orca: 无独立 workspace 概念（worktree 由 Orca 管理），跳过
+    return;
+  }
+
   // zellij: skip session rename
 }