pi-terminal-mux 0.2.0

package/README.md

@@ -0,0 +1,115 @@
+# 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.
+
+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.
+
+[中文文档](./README.zh-CN.md)
+
+## Install
+
+```bash
+npm install pi-terminal-mux
+```
+
+## Quick start
+
+```ts
+import {
+  isMuxAvailable,
+  muxSetupHint,
+  createSurface,
+  createSurfaceSplit,
+  sendCommand,
+  sendLongCommand,
+  sendEscape,
+  readScreen,
+  closeSurface,
+  pollForExit,
+} from "pi-terminal-mux";
+
+if (!isMuxAvailable()) {
+  console.warn(muxSetupHint()); // localized setup hint via pi-extensions-i18n
+}
+
+// Smart placement: split / stack / new tab depending on the backend strategy
+// (returns a headless surface when no multiplexer is available)
+const surface = createSurface("my-agent");
+
+// Long commands are written to a script file first to avoid terminal line wrapping
+const scriptPath = sendLongCommand(surface, "pi --session abc", {
+  scriptPreamble: "export MY_FLAG=1",
+});
+
+const tail = readScreen(surface, 50);
+sendEscape(surface);
+closeSurface(surface);
+```
+
+## Backend detection
+
+| Backend | Detection |
+|---------|-----------|
+| muxy | `MUXY_SOCKET_PATH` + `muxy` command |
+| cmux | `CMUX_SOCKET_PATH` + `cmux` command |
+| 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 |
+| otty | `TERM_PROGRAM=otty` + `otty` command |
+
+Default priority follows the table order (muxy first). Force a backend with:
+
+- `PI_TERMINAL_MUX` (preferred): `muxy | cmux | tmux | zellij | wezterm | herdr | otty`
+- `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.
+
+## 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: breadth-first splits), 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 |
+| `sendEscape(surface)` | Send one ESC keypress |
+| `readScreen(surface, lines?)` / `readScreenAsync` | Read the last N screen lines |
+| `closeSurface(surface)` | Close the surface |
+| `renameSurface(surface, name)` / `renameCurrentTab(title)` / `renameAgent(surface, name)` / `renameWorkspace(title)` | Naming, degrading per backend capability |
+| `pollForExit(surface, signal, opts)` | Wait for the process in a surface to exit: `.exit` sidecar file first, then a screen sentinel (`__SUBAGENT_DONE_<code>__`); headless uses child process exit |
+| `getLastSplitSource()` / `clearLastSplitSource()` | Source pane of the most recent split (for UI display) |
+
+### Detection and utilities
+
+`getMuxBackend()`, `isMuxAvailable()`, `isHeadlessMode()`, `muxSetupHint()`, `getAgentPaneId(backend?)`, `backendAgentPaneEnvVar(backend)`, `shellEscape()`, `isFishShell()`, `exitStatusVar()`, plus zellij placement planning (`selectZellijPlacement` etc.) and cmux/otty JSON parsing helpers — all pure and unit-testable.
+
+### 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`.
+
+## Headless mode
+
+When no backend is detected, `createSurface` returns a `headless:`-prefixed surface, `sendLongCommand` spawns a background child process writing to a log file, and `readScreen` / `pollForExit` / `closeSurface` keep the same semantics — callers need no special-casing.
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `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_RENAME_HERDR_WORKSPACE` | Allow renameWorkspace on herdr |
+| `PI_EXTENSIONS_LOCALE` | Hint language (`zh-CN` / `en-US` / `auto`), provided by pi-extensions-i18n |
+
+## Design constraints
+
+- **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.
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,114 @@
+# pi-terminal-mux
+
+终端多路复用器统一抽象层，供 pi 扩展复用。任何涉及终端交互（分屏、发命令、读屏、关屏、等待退出）的插件都应依赖本包，而不是各自重新实现 backend 探测与命令拼装。
+
+一套统一的 surface API 跨 **muxy、cmux、tmux、zellij、wezterm、herdr、otty** 七个后端，探测不到任何后端时自动降级为 **headless**（后台子进程 + 日志文件）。
+
+[English README](./README.md)
+
+## 安装
+
+```bash
+npm install pi-terminal-mux
+```
+
+## 快速上手
+
+```ts
+import {
+  isMuxAvailable,
+  muxSetupHint,
+  createSurface,
+  createSurfaceSplit,
+  sendCommand,
+  sendLongCommand,
+  sendEscape,
+  readScreen,
+  closeSurface,
+  pollForExit,
+} from "pi-terminal-mux";
+
+if (!isMuxAvailable()) {
+  console.warn(muxSetupHint()); // 中英文安装提示，由 pi-extensions-i18n 决定语言
+}
+
+// 智能放置：按后端策略分屏 / 堆叠 / 开 tab（headless 时返回 headless surface）
+const surface = createSurface("my-agent");
+
+// 长命令自动落脚本文件，避免终端宽度截断
+const scriptPath = sendLongCommand(surface, "pi --session abc", {
+  scriptPreamble: "export MY_FLAG=1",
+});
+
+const tail = readScreen(surface, 50);
+sendEscape(surface);
+closeSurface(surface);
+```
+
+## 后端探测
+
+| 后端 | 探测条件 |
+|------|----------|
+| muxy | `MUXY_SOCKET_PATH` + `muxy` 命令 |
+| cmux | `CMUX_SOCKET_PATH` + `cmux` 命令 |
+| tmux | `TMUX` + `tmux` 命令 |
+| zellij | `ZELLIJ` / `ZELLIJ_SESSION_NAME` + `zellij` 命令 |
+| wezterm | `WEZTERM_UNIX_SOCKET` + `wezterm` 命令 |
+| herdr | `HERDR_ENV=1` + `HERDR_PANE_ID` + `herdr` 命令 |
+| otty | `TERM_PROGRAM=otty` + `otty` 命令 |
+
+默认优先级即上表顺序（muxy 优先）。可用环境变量强制指定后端：
+
+- `PI_TERMINAL_MUX`（推荐）：`muxy | cmux | tmux | zellij | wezterm | herdr | otty`
+- `PI_SUBAGENT_MUX`：同上的向后兼容别名
+
+指定的后端运行环境不满足时 `getMuxBackend()` 返回 `null`，不会悄悄降级到其他后端。
+
+## API 概览
+
+### 统一 surface API（跨后端语义一致）
+
+| 函数 | 说明 |
+|------|------|
+| `createSurface(name)` | 智能放置新 surface（cmux 首次右分屏后续开 tab、zellij tab 感知平铺/堆叠、muxy/otty 广度优先分屏），返回 surface 标识 |
+| `createSurfaceSplit(name, direction, fromSurface?)` | 指定方向（left/right/up/down）分屏 |
+| `sendCommand(surface, command)` | 发送命令并回车执行 |
+| `sendLongCommand(surface, command, opts?)` | 长命令先写脚本文件再执行；`opts.scriptPreamble` 可注入 env export；返回脚本路径 |
+| `sendEscape(surface)` | 发送一次 ESC |
+| `readScreen(surface, lines?)` / `readScreenAsync` | 读取屏幕尾部 N 行 |
+| `closeSurface(surface)` | 关闭 surface |
+| `renameSurface(surface, name)` / `renameCurrentTab(title)` / `renameAgent(surface, name)` / `renameWorkspace(title)` | 命名（按后端能力降级或跳过） |
+| `pollForExit(surface, signal, opts)` | 等待 surface 内进程退出：优先 `.exit` sidecar 文件，其次屏幕 sentinel（`__SUBAGENT_DONE_<code>__`），headless 走子进程 exit |
+| `getLastSplitSource()` / `clearLastSplitSource()` | 最近一次分屏的来源 pane（用于 UI 展示） |
+
+### 探测与工具
+
+`getMuxBackend()`、`isMuxAvailable()`、`isHeadlessMode()`、`muxSetupHint()`、`getAgentPaneId(backend?)`、`backendAgentPaneEnvVar(backend)`、`shellEscape()`、`isFishShell()`、`exitStatusVar()`，以及 zellij 放置规划（`selectZellijPlacement` 等）与 cmux/otty JSON 解析等纯函数，均可直接引用做单元测试。
+
+### 后端原生 API
+
+各后端原生函数也从包入口透出（如 `createHerdrSurface`、`splitHerdrPane`、`readHerdrScreen`、`sendOttyCommand`、`renameOttyTab`……），子路径导入亦可：`pi-terminal-mux/mux`、`pi-terminal-mux/herdr`、`pi-terminal-mux/otty`。
+
+## Headless 模式
+
+探测不到任何后端时，`createSurface` 返回 `headless:` 前缀的 surface，`sendLongCommand` 直接 spawn 后台子进程并把输出写入日志文件，`readScreen`/`pollForExit`/`closeSurface` 语义保持不变，调用方无需特判。
+
+## 环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `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_RENAME_HERDR_WORKSPACE` | herdr 下允许 renameWorkspace |
+| `PI_EXTENSIONS_LOCALE` | 提示文案语言（`zh-CN` / `en-US` / `auto`），由 pi-extensions-i18n 提供 |
+
+## 设计约束
+
+- **不绑定具体机器**：全部后端通过运行时探测（环境变量 + 命令存在性）选择，零硬编码本机路径；外部 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` 等），不受用户后续焦点切换影响。
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1 @@
+export * from "./src/index.ts";

package/locales/mux.json

@@ -0,0 +1,46 @@
+{
+  "setupHint.none": {
+    "zh-CN": "未检测到可用的终端多路复用器。",
+    "en-US": "No supported terminal multiplexer found."
+  },
+  "setupHint.cmux": {
+    "zh-CN": "请在 cmux 中启动 pi（`cmux pi`）。",
+    "en-US": "Start pi inside cmux (`cmux pi`)."
+  },
+  "setupHint.muxy": {
+    "zh-CN": "请在 Muxy 终端中启动 pi。",
+    "en-US": "Start pi inside Muxy terminal."
+  },
+  "setupHint.tmux": {
+    "zh-CN": "请在 tmux 中启动 pi（`tmux new -A -s pi 'pi'`）。",
+    "en-US": "Start pi inside tmux (`tmux new -A -s pi 'pi'`)."
+  },
+  "setupHint.zellij": {
+    "zh-CN": "请在 zellij 中启动 pi（`zellij --session pi`，然后运行 `pi`）。",
+    "en-US": "Start pi inside zellij (`zellij --session pi`, then run `pi`)."
+  },
+  "setupHint.wezterm": {
+    "zh-CN": "请在 WezTerm 中启动 pi。",
+    "en-US": "Start pi inside WezTerm."
+  },
+  "setupHint.herdr": {
+    "zh-CN": "请在终端中运行 herdr（`herdr`），拆分一个 pane（prefix+v 或 prefix+-），然后在该 pane 中运行 `pi`。herdr 会自动注入 HERDR_ENV=1 和 HERDR_PANE_ID 供 pi 检测。",
+    "en-US": "Start herdr in your terminal (`herdr`), split a pane (prefix+v or prefix+-), then run `pi` in that pane. herdr auto-injects HERDR_ENV=1 + HERDR_PANE_ID for pi to detect."
+  },
+  "setupHint.otty": {
+    "zh-CN": "请在 Otty 中运行 pi（Otty 会自动设置 TERM_PROGRAM=otty）。",
+    "en-US": "Run pi inside Otty (Otty sets TERM_PROGRAM=otty 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)."
+  },
+  "setupHint.herdrPreferred": {
+    "zh-CN": "请在 herdr 中启动 pi（必须设置 HERDR_ENV=1；先运行 herdr，再在 pane 中启动 pi）。",
+    "en-US": "Start pi inside herdr (HERDR_ENV=1 must be set; run herdr, then start pi in a pane)."
+  },
+  "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."
+  }
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "pi-terminal-mux",
+  "version": "0.2.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",
+  "exports": {
+    ".": "./index.ts",
+    "./mux": "./src/mux.ts",
+    "./herdr": "./src/herdr.ts",
+    "./otty": "./src/otty.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "locales",
+    "README.md",
+    "README.zh-CN.md",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "test": "tsx --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit --pretty false",
+    "build": "npm run typecheck",
+    "check": "npm run typecheck && npm test && npm pack --dry-run --json > /dev/null"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "author": "maplezzk",
+  "homepage": "https://github.com/maplezzk/pi-extensions/tree/main/packages/pi-terminal-mux",
+  "bugs": "https://github.com/maplezzk/pi-extensions/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maplezzk/pi-extensions.git",
+    "directory": "packages/pi-terminal-mux"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "terminal",
+    "multiplexer",
+    "tmux",
+    "zellij",
+    "wezterm",
+    "coding-agent"
+  ],
+  "peerDependencies": {
+    "pi-extensions-i18n": ">=0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.12.4",
+    "pi-extensions-i18n": "^0.3.0",
+    "tsx": "4.23.1",
+    "typescript": "5.9.3"
+  }
+}