pi-terminal-mux 0.3.2 → 0.4.1

package/README.md

@@ -56,7 +56,7 @@ closeSurface(surface);
 | tmux | `TMUX` + `tmux` command |
 | zellij | `ZELLIJ` / `ZELLIJ_SESSION_NAME` + `zellij` command |
 | wezterm | `WEZTERM_UNIX_SOCKET` + `wezterm` command |
-| herdr | `HERDR_ENV=1` + `HERDR_PANE_ID` + `herdr` command |
+| herdr | `HERDR_ENV=1` + `HERDR_PANE_ID` + `herdr` command (`tab` mode also requires `HERDR_WORKSPACE_ID`) |
 | otty | `TERM_PROGRAM=otty` + `otty` command |
 | orca | `TERM_PROGRAM=Orca` + `orca` command + reachable Orca runtime |
 
@@ -67,13 +67,21 @@ Default priority follows the table order (muxy first). Force a backend with:
 
 If the forced backend's runtime is unavailable, `getMuxBackend()` returns `null` — it never silently falls back to another backend.
 
+### Herdr surface mode
+
+Herdr keeps the backward-compatible breadth-first split mode by default. Set `PI_SUBAGENT_HERDR_MODE=tab` to create one background tab per subagent, or `split` to select the original pane layout explicitly. `createSurfaceSplit()` always remains an explicit pane split.
+
+```bash
+export PI_SUBAGENT_HERDR_MODE=tab
+```
+
 ## API overview
 
 ### Unified surface API (same semantics across backends)
 
 | Function | Description |
 |----------|-------------|
-| `createSurface(name)` | Smart placement (cmux: first right-split then tabs; zellij: tab-aware tiled/stacked; muxy/otty/orca: breadth-first splits; orca falls back to a new tab without an agent handle), returns a surface handle |
+| `createSurface(name)` | Smart placement (herdr: breadth-first splits by default, or one background tab per surface with `PI_SUBAGENT_HERDR_MODE=tab`; cmux: first right-split then tabs; zellij: tab-aware tiled/stacked; muxy/otty/orca: breadth-first splits; orca falls back to a new tab without an agent handle), returns a surface handle |
 | `createSurfaceSplit(name, direction, fromSurface?, options?)` | Split in an explicit direction (left/right/up/down). `options.activate` (WezTerm only, default `false`) focuses the new pane after splitting |
 | `sendCommand(surface, command)` | Send a command and press Enter |
 | `sendLongCommand(surface, command, opts?)` | Write long commands to a script file first. `opts.scriptPreamble` injects leading lines; `opts.interpreter` (`"bash"` default, or `"powershell"` on Windows) selects the scripting runtime; returns the script path |
@@ -113,6 +121,7 @@ These are opt-in capabilities — existing Bash callers and `pi-interactive-suba
 | `PI_TERMINAL_MUX` / `PI_SUBAGENT_MUX` | Force a backend |
 | `PI_SUBAGENT_ZELLIJ_MIN_COLUMNS` / `PI_SUBAGENT_ZELLIJ_MIN_ROWS` | Minimum usable size for zellij splits (default 50x10; stacks instead when smaller) |
 | `PI_SUBAGENT_RENAME_TMUX_WINDOW` / `PI_SUBAGENT_RENAME_TMUX_SESSION` | Allow renameCurrentTab / renameWorkspace on tmux (user naming untouched by default) |
+| `PI_SUBAGENT_HERDR_MODE` | Herdr surface placement: `split` (default) or `tab` |
 | `PI_SUBAGENT_RENAME_HERDR_WORKSPACE` | Allow renameWorkspace on herdr |
 | `PI_EXTENSIONS_LOCALE` | Hint language (`zh-CN` / `en-US` / `auto`), provided by pi-extensions-i18n |
 

package/README.zh-CN.md

@@ -55,7 +55,7 @@ closeSurface(surface);
 | tmux | `TMUX` + `tmux` 命令 |
 | zellij | `ZELLIJ` / `ZELLIJ_SESSION_NAME` + `zellij` 命令 |
 | wezterm | `WEZTERM_UNIX_SOCKET` + `wezterm` 命令 |
-| herdr | `HERDR_ENV=1` + `HERDR_PANE_ID` + `herdr` 命令 |
+| herdr | `HERDR_ENV=1` + `HERDR_PANE_ID` + `herdr` 命令（`tab` 模式还需要 `HERDR_WORKSPACE_ID`） |
 | otty | `TERM_PROGRAM=otty` + `otty` 命令 |
 | orca | `TERM_PROGRAM=Orca` + `orca` 命令 + Orca runtime 可达 |
 
@@ -66,13 +66,21 @@ closeSurface(surface);
 
 指定的后端运行环境不满足时 `getMuxBackend()` 返回 `null`，不会悄悄降级到其他后端。
 
+### Herdr surface 模式
+
+Herdr 默认保持向后兼容的广度优先分屏模式。设置 `PI_SUBAGENT_HERDR_MODE=tab` 后，每个 subagent 会创建独立后台 Tab；设置为 `split` 可显式选择原有分屏布局。`createSurfaceSplit()` 始终保留显式 pane 分屏语义。
+
+```bash
+export PI_SUBAGENT_HERDR_MODE=tab
+```
+
 ## API 概览
 
 ### 统一 surface API（跨后端语义一致）
 
 | 函数 | 说明 |
 |------|------|
-| `createSurface(name)` | 智能放置新 surface（cmux 首次右分屏后续开 tab、zellij tab 感知平铺/堆叠、muxy/otty/orca 广度优先分屏；orca 缺少 agent handle 时新建 tab），返回 surface 标识 |
+| `createSurface(name)` | 智能放置新 surface（herdr 默认广度优先分屏，设置 `PI_SUBAGENT_HERDR_MODE=tab` 后每个 surface 创建独立后台 Tab；cmux 首次右分屏后续开 tab、zellij tab 感知平铺/堆叠、muxy/otty/orca 广度优先分屏；orca 缺少 agent handle 时新建 tab），返回 surface 标识 |
 | `createSurfaceSplit(name, direction, fromSurface?, options?)` | 指定方向（left/right/up/down）分屏；`options.activate`（仅 wezterm，默认 false）分屏后聚焦新 pane |
 | `sendCommand(surface, command)` | 发送命令并回车执行 |
 | `sendLongCommand(surface, command, opts?)` | 长命令先写脚本文件再执行；`opts.scriptPreamble` 可注入前置片段；`opts.interpreter`（默认 `"bash"`，Windows 可显式 `"powershell"`）选择脚本运行时；返回脚本路径 |
@@ -112,6 +120,7 @@ closeSurface(surface);
 | `PI_TERMINAL_MUX` / `PI_SUBAGENT_MUX` | 强制指定后端 |
 | `PI_SUBAGENT_ZELLIJ_MIN_COLUMNS` / `PI_SUBAGENT_ZELLIJ_MIN_ROWS` | zellij 分屏最小可用尺寸（默认 50×10，不满足时改堆叠） |
 | `PI_SUBAGENT_RENAME_TMUX_WINDOW` / `PI_SUBAGENT_RENAME_TMUX_SESSION` | tmux 下允许 renameCurrentTab / renameWorkspace（默认不动用户命名） |
+| `PI_SUBAGENT_HERDR_MODE` | herdr surface 放置模式：`split`（默认）或 `tab` |
 | `PI_SUBAGENT_RENAME_HERDR_WORKSPACE` | herdr 下允许 renameWorkspace |
 | `PI_EXTENSIONS_LOCALE` | 提示文案语言（`zh-CN` / `en-US` / `auto`），由 pi-extensions-i18n 提供 |
 

package/locales/mux.json

@@ -46,5 +46,9 @@
   "setupHint.ottySendKeys": {
     "zh-CN": "Otty 的 `ipc-allow-send-keys` 未启用。如需让 pi 驱动子 agent 分屏，请在 ~/.config/otty/config.toml 中添加 `ipc-allow-send-keys = true` 并重新加载 Otty。",
     "en-US": "Otty's `ipc-allow-send-keys` is disabled. To let pi drive subagent panes, add `ipc-allow-send-keys = true` to ~/.config/otty/config.toml and reload Otty."
+  },
+  "error.invalidHerdrMode": {
+    "zh-CN": "不支持的 Herdr surface 模式：{value}。可选值：split、tab。",
+    "en-US": "Unsupported Herdr surface mode: {value}. Choose split or tab."
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-terminal-mux",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "Terminal multiplexer abstraction for pi extensions — unified surface API across muxy, cmux, tmux, zellij, wezterm, herdr, otty and orca, with headless fallback",
   "type": "module",
   "main": "./index.ts",
@@ -54,7 +54,7 @@
     "coding-agent"
   ],
   "dependencies": {
-    "pi-extensions-i18n": "^0.3.1"
+    "pi-extensions-i18n": "^0.4.0"
   },
   "devDependencies": {
     "@types/node": "24.12.4",

package/src/backends/herdr.ts

@@ -8,7 +8,7 @@
  *   HERDR_TAB_ID（公开 id，如 "1:1"）
  *   HERDR_PANE_ID（公开 id，如 "1-1"）
  *
- * 所有 pane 操作通过 `herdr` CLI 完成，详见 SKILL.md。
+ * 所有 tab / pane 操作通过 `herdr` CLI 完成，详见 SKILL.md。
  * 日志、文件锁、BFS 分屏状态机、命令检测复用 backends/shared.ts。
  */
 
@@ -19,6 +19,32 @@ import { createBackendLogger, withFileLock, BfsSplitStateManager, hasCommand } f
 
 // ── 日志（统一格式，写入 /tmp/pi-mux-herdr.log） ──
 const herdrLog = createBackendLogger("herdr", "/tmp/pi-mux-herdr.log");
+const HERDR_TAB_CLOSE_COMMAND = ["tab", "close"] as const;
+const HERDR_PANE_SPLIT_COMMAND = ["pane", "split"] as const;
+const HERDR_PANE_CLOSE_COMMAND = ["pane", "close"] as const;
+const HERDR_SPLIT_DIRECTION_FLAG = "--direction";
+const HERDR_NO_FOCUS_FLAG = "--no-focus";
+const HERDR_SPLIT_RIGHT = "right";
+const HERDR_SPLIT_DOWN = "down";
+const HERDR_SPLIT_UP = "up";
+const HERDR_MARKER_PATH_PREFIX = "/tmp/herdr-subagent-pane-";
+const HERDR_MARKER_DEFAULT_ID = "default";
+const HERDR_LOCK_SUFFIX = ".lock";
+export const HERDR_SURFACE_MODE_SPLIT = "split";
+export const HERDR_SURFACE_MODE_TAB = "tab";
+const DEFAULT_HERDR_SURFACE_MODE = HERDR_SURFACE_MODE_SPLIT;
+
+export type HerdrSurfaceMode =
+  | typeof HERDR_SURFACE_MODE_SPLIT
+  | typeof HERDR_SURFACE_MODE_TAB;
+
+/** 解析 Herdr surface 放置模式；未配置时保持旧版 split，非法显式值直接报错。 */
+export function resolveHerdrSurfaceMode(value = process.env.PI_SUBAGENT_HERDR_MODE): HerdrSurfaceMode {
+  const normalized = value?.trim().toLowerCase();
+  if (!normalized || normalized === HERDR_SURFACE_MODE_SPLIT) return DEFAULT_HERDR_SURFACE_MODE;
+  if (normalized === HERDR_SURFACE_MODE_TAB) return HERDR_SURFACE_MODE_TAB;
+  throw new Error(i18n.t("error.invalidHerdrMode", { value }));
+}
 
 /**
  * 捕获于模块加载时的 agent pane id。
@@ -33,18 +59,20 @@ export const AGENT_HERDR_TAB_ID = process.env.HERDR_TAB_ID;
  * 检测 herdr backend 是否可用：
  *   1. `herdr` 命令在 PATH 中
  *   2. 当前进程在 herdr pane 内运行（HERDR_ENV=1）
- *   3. HERDR_PANE_ID 已注入
+ *   3. HERDR_PANE_ID 已注入；tab 模式还要求 HERDR_WORKSPACE_ID
  *
  * 注意：即使 socket 暂时不通，只要命令存在且 env 注入，就认为"runtime available"。
- * 子 agent 创建时会用 `herdr pane split` 触发 socket 调用，那时报错即可。
+ * 子 agent 创建时再通过对应的 pane split / tab create 命令触发 socket 调用。
  */
 export function isHerdrRuntimeAvailable(): boolean {
-  return (
-    !!process.env.HERDR_ENV &&
-    process.env.HERDR_ENV === "1" &&
-    !!process.env.HERDR_PANE_ID &&
-    hasCommand("herdr")
-  );
+  if (
+    process.env.HERDR_ENV !== "1" ||
+    !process.env.HERDR_PANE_ID ||
+    !hasCommand("herdr")
+  ) {
+    return false;
+  }
+  return resolveHerdrSurfaceMode() === HERDR_SURFACE_MODE_SPLIT || !!process.env.HERDR_WORKSPACE_ID;
 }
 
 // ── herdr CLI 调用的薄封装 ──
@@ -103,19 +131,34 @@ function extractPaneId(json: unknown): string | null {
 
 /** herdr BFS 分屏状态 marker 文件路径（按 agent pane id 区分） */
 function herdrMarkerPath(): string {
-  return `/tmp/herdr-subagent-pane-${(AGENT_HERDR_PANE_ID ?? "default").replace(/[^a-zA-Z0-9_-]/g, "_")}.json`;
+  const paneId = (AGENT_HERDR_PANE_ID ?? HERDR_MARKER_DEFAULT_ID).replace(/[^a-zA-Z0-9_-]/g, "_");
+  return `${HERDR_MARKER_PATH_PREFIX}${paneId}.json`;
+}
+
+interface CreatedHerdrTab {
+  tabId: string;
+  paneId: string;
 }
 
+/** 从 `herdr tab create` 响应提取新 tab 与 root pane 的公开 id。 */
+function extractCreatedHerdrTab(json: unknown): CreatedHerdrTab | null {
+  if (!json || typeof json !== "object") return null;
+  const result = (json as Record<string, unknown>).result;
+  if (!result || typeof result !== "object") return null;
+  const record = result as Record<string, unknown>;
+  const tab = record.tab as Record<string, unknown> | undefined;
+  const rootPane = record.root_pane as Record<string, unknown> | undefined;
+  if (typeof tab?.tab_id !== "string" || typeof rootPane?.pane_id !== "string") return null;
+  return { tabId: tab.tab_id, paneId: rootPane.pane_id };
+}
+
+/** 记录由本进程创建的 tab surface，使 rename / close 操作作用于整个 tab。 */
+const createdHerdrTabIds = new Map<string, string>();
+
 // ── 对外 API：createSurface 系列 ──
 
-/**
- * 创建一个新的 subagent pane。
- *
- * 实现：split 当前 agent pane 右侧（--no-focus 保持 agent 焦点不变）。
- * 后续 subagent 按 breadth-first 模式轮转 right/down/right/down…（与 cmux/muxy 行为一致）。
- * 锁与 BFS 状态机复用 shared.ts。
- */
-export function createHerdrSurface(name: string): string {
+/** 使用原有 BFS 策略创建 subagent 分屏。 */
+function createHerdrSplitSurface(name: string): string {
   if (!AGENT_HERDR_PANE_ID) {
     throw new Error(
       "HERDR_PANE_ID not set; cannot determine parent pane for subagent split. " +
@@ -124,20 +167,18 @@ export function createHerdrSurface(name: string): string {
   }
 
   const markerFile = herdrMarkerPath();
-  const lockPath = `${markerFile}.lock`;
+  const lockPath = `${markerFile}${HERDR_LOCK_SUFFIX}`;
 
   return withFileLock(lockPath, {}, () => {
     const state = new BfsSplitStateManager(markerFile);
 
-    // 首次 split
     if (state.panes().length === 0) {
       const output = herdrExec([
-        "pane",
-        "split",
-        AGENT_HERDR_PANE_ID!,
-        "--direction",
-        "right",
-        "--no-focus",
+        ...HERDR_PANE_SPLIT_COMMAND,
+        AGENT_HERDR_PANE_ID,
+        HERDR_SPLIT_DIRECTION_FLAG,
+        HERDR_SPLIT_RIGHT,
+        HERDR_NO_FOCUS_FLAG,
       ]);
       const newPaneId = extractPaneId(parseHerdrJson(output));
       if (newPaneId) {
@@ -152,22 +193,31 @@ export function createHerdrSurface(name: string): string {
       return "";
     }
 
-    // 后续：BFS 分屏
     const next = state.next();
     if (!next) return "";
 
     let { source } = next;
     const { direction } = next;
-
-    // 若 source 过期（pane 被关闭 / session 重启），重置状态从 agent pane 重新分屏
     let output: string;
     try {
-      output = herdrExec(["pane", "split", source, "--direction", direction, "--no-focus"]);
+      output = herdrExec([
+        ...HERDR_PANE_SPLIT_COMMAND,
+        source,
+        HERDR_SPLIT_DIRECTION_FLAG,
+        direction,
+        HERDR_NO_FOCUS_FLAG,
+      ]);
     } catch {
       try { rmSync(markerFile); } catch { /* ignore */ }
       herdrLog(`[split] pane ${source} gone, resetting from agent pane ${AGENT_HERDR_PANE_ID}`);
-      source = AGENT_HERDR_PANE_ID!;
-      output = herdrExec(["pane", "split", source, "--direction", "right", "--no-focus"]);
+      source = AGENT_HERDR_PANE_ID;
+      output = herdrExec([
+        ...HERDR_PANE_SPLIT_COMMAND,
+        source,
+        HERDR_SPLIT_DIRECTION_FLAG,
+        HERDR_SPLIT_RIGHT,
+        HERDR_NO_FOCUS_FLAG,
+      ]);
     }
 
     const newPaneId = extractPaneId(parseHerdrJson(output));
@@ -185,6 +235,46 @@ export function createHerdrSurface(name: string): string {
   });
 }
 
+/** 在当前 workspace 中创建独立后台 tab，并返回 root pane id。 */
+function createHerdrTabSurface(name: string): string {
+  if (!AGENT_HERDR_WORKSPACE_ID) {
+    throw new Error(
+      "HERDR_WORKSPACE_ID not set; cannot determine workspace for subagent tab. " +
+        "Start pi inside herdr so HERDR_WORKSPACE_ID is injected at launch.",
+    );
+  }
+
+  const tabLabel = herdrSurfaceLabel(name);
+  const output = herdrExec([
+    "tab",
+    "create",
+    "--workspace",
+    AGENT_HERDR_WORKSPACE_ID,
+    "--cwd",
+    process.cwd(),
+    "--label",
+    tabLabel,
+    "--no-focus",
+  ]);
+  const createdTab = extractCreatedHerdrTab(parseHerdrJson(output));
+  if (!createdTab) {
+    throw new Error(`Unexpected herdr tab create output: ${output.trim() || "(empty)"}`);
+  }
+
+  createdHerdrTabIds.set(createdTab.paneId, createdTab.tabId);
+  herdrLog(
+    `[tab create] workspace=${AGENT_HERDR_WORKSPACE_ID} tab=${createdTab.tabId} pane=${createdTab.paneId} name=${JSON.stringify(name)}`,
+  );
+  return createdTab.paneId;
+}
+
+/** 按 PI_SUBAGENT_HERDR_MODE 选择兼容分屏或独立 tab；默认保持 split。 */
+export function createHerdrSurface(name: string): string {
+  return resolveHerdrSurfaceMode() === HERDR_SURFACE_MODE_TAB
+    ? createHerdrTabSurface(name)
+    : createHerdrSplitSurface(name);
+}
+
 /**
  * 从指定 pane 直接分屏（不走广度优先状态机），供 createSurfaceSplit 使用。
  * herdr 文档仅明确 right/down，left/up 分别归一到 right/down。
@@ -195,8 +285,16 @@ export function splitHerdrPane(
   direction: "left" | "right" | "up" | "down",
   name?: string,
 ): string {
-  const dir = direction === "down" || direction === "up" ? "down" : "right";
-  const output = herdrExec(["pane", "split", fromPane, "--direction", dir, "--no-focus"]);
+  const dir = direction === HERDR_SPLIT_DOWN || direction === HERDR_SPLIT_UP
+    ? HERDR_SPLIT_DOWN
+    : HERDR_SPLIT_RIGHT;
+  const output = herdrExec([
+    ...HERDR_PANE_SPLIT_COMMAND,
+    fromPane,
+    HERDR_SPLIT_DIRECTION_FLAG,
+    dir,
+    HERDR_NO_FOCUS_FLAG,
+  ]);
   const newPaneId = extractPaneId(parseHerdrJson(output));
   if (!newPaneId) {
     throw new Error(`Unexpected herdr pane split output: ${output.trim() || "(empty)"}`);
@@ -250,6 +348,12 @@ function getWorkspaceLabel(): string | null {
   }
 }
 
+/** 生成 herdr pane / tab 的统一显示标签。 */
+function herdrSurfaceLabel(name: string): string {
+  const workspaceLabel = getWorkspaceLabel();
+  return workspaceLabel ? `${workspaceLabel}[${name}]` : name;
+}
+
 /**
  * 用 herdr CLI 重命名 pane 对应的 tab。
  * tab label 格式: workspace_label[name]
@@ -258,8 +362,7 @@ export function renameHerdrTab(paneId: string, name: string): void {
   const ws = parseWorkspaceIdFromPaneId(paneId);
   if (!ws) return;
   try {
-    const wsLabel = getWorkspaceLabel();
-    const tabLabel = wsLabel ? `${wsLabel}[${name}]` : name;
+    const tabLabel = herdrSurfaceLabel(name);
     const tabsJson = herdrExec(["tab", "list", "--workspace", ws]);
     const parsed = parseHerdrJson(tabsJson);
     if (!parsed || typeof parsed !== "object") return;
@@ -331,13 +434,19 @@ export function readHerdrScreen(paneId: string, lines = 50, source: "visible" |
 }
 
 /**
- * 关闭 pane。
- * `herdr pane close <id>` 是 herdr CLI 子命令。
+ * 关闭 surface。本进程创建的 tab surface 关闭整个 tab；其他 pane id 仍按 pane 关闭。
  */
 export function closeHerdrSurface(paneId: string): void {
-  herdrExecSilent(["pane", "close", paneId]);
+  const tabId = createdHerdrTabIds.get(paneId);
+  if (tabId) {
+    herdrExecSilent([...HERDR_TAB_CLOSE_COMMAND, tabId]);
+    createdHerdrTabIds.delete(paneId);
+    herdrLog(`[close] tab=${tabId} pane=${paneId}`);
+    return;
+  }
+
+  herdrExecSilent([...HERDR_PANE_CLOSE_COMMAND, paneId]);
 
-  // 从 BFS 状态移除已关闭的 subagent，避免僵尸 ID 累积
   const state = new BfsSplitStateManager(herdrMarkerPath());
   const beforePanes = state.panes();
   state.remove(paneId);
@@ -408,6 +517,18 @@ export const ops: BackendOps = {
     closeHerdrSurface(surface);
   },
   rename(surface: string, name: string): void {
-    renameHerdrPane(surface, name);
+    const tabId = createdHerdrTabIds.get(surface);
+    if (!tabId) {
+      renameHerdrPane(surface, name);
+      return;
+    }
+    try {
+      const tabLabel = herdrSurfaceLabel(name);
+      herdrExecSilent(["tab", "rename", tabId, tabLabel]);
+    } catch (error) {
+      herdrLog(
+        `[rename tab] tab=${tabId} pane=${surface} name=${JSON.stringify(name)} failed: ${(error as Error).message}`,
+      );
+    }
   },
 };