@kevinhao/pi-terminal-mux 0.0.0-stage → 0.7.0

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# @kevinhao/pi-terminal-mux
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Terminal surface API for Pi extensions, supporting **tmux**, **Orca**, and **headless** background processes.
+
+[中文文档](./README.zh-CN.md)
+
+## Install
+
+```bash
+npm install @kevinhao/pi-terminal-mux
+```
+
+## Create and start a command
+
+```ts
+import { createSurface, createSurfaceSplit, readScreen, closeSurface } from "@kevinhao/pi-terminal-mux";
+
+const surface = createSurface("my-agent", {
+  command: "pi --session /tmp/child.jsonl",
+});
+
+const sibling = createSurfaceSplit("review", "right", surface, {
+  command: "pi --session /tmp/review.jsonl",
+});
+
+const tail = readScreen(surface, 50);
+closeSurface(sibling);
+closeSurface(surface);
+```
+
+`command` is an optional, non-empty **shell command string**, including its arguments. Quote dynamic values with `shellEscape()` for POSIX shells. There is no separate `sendCommand()` call or library-side shell-ready sleep on this path:
+
+- **tmux:** supplies the command to `tmux split-window` while creating the pane.
+- **Orca:** supplies `--command` to `terminal create` or `terminal split`. Orca itself starts a shell and submits the command; this is not a direct argv process spawn.
+- **Headless:** starts the command with `bash -c`, writing stdout/stderr to a log file.
+
+Returning a handle confirms creation/submission, not application readiness or successful completion. Use your application's ready signal, logs, or exit protocol for that. Creation errors propagate to the caller. Orca input/read errors also propagate instead of appearing successful.
+
+Existing calls without options keep their previous behavior:
+
+```ts
+import { createSurface, sendLongCommand } from "@kevinhao/pi-terminal-mux";
+
+const surface = createSurface("my-agent");
+const scriptPath = sendLongCommand(surface, "pi --session /tmp/child.jsonl", {
+  scriptPreamble: "export MY_FLAG=1",
+});
+```
+
+`sendLongCommand` writes a script first and then submits `bash <script>` to the terminal. It remains available for existing callers and long commands. Do not also submit the startup command after passing it to `createSurface`, or it will run twice.
+
+## Detection
+
+| Backend | Requirements |
+|---------|--------------|
+| tmux | `TMUX` environment variable and the `tmux` executable |
+| Orca | `TERM_PROGRAM=Orca`, the `orca` executable, and a reachable runtime |
+| Headless | Neither terminal backend is available |
+
+Automatic detection prefers tmux, then Orca. Force a backend with `PI_TERMINAL_MUX=tmux|orca`; `PI_SUBAGENT_MUX` remains a compatibility alias. An unavailable forced backend does not select another terminal backend. Unknown or removed backend preferences throw an explicit error.
+
+## API
+
+| Function | Behavior |
+|----------|----------|
+| `createSurface(name, options?)` | tmux and Orca both breadth-first split from the caller's pane into a grid; Orca opens a new tab without a caller handle; headless fallback. `options.command` starts work during creation |
+| `createSurfaceSplit(name, direction, fromSurface?, options?)` | Explicit split; `direction` is left/right/up/down, `options.command` is optional. Requires tmux or Orca; headless has no pane layout |
+| `sendCommand(surface, command)` | Send input followed by Enter to an existing terminal |
+| `sendLongCommand(surface, command, options?)` | Write a script, then execute it. Supports `scriptPath`, `scriptPreamble`, and `interpreter: "bash" | "powershell"` |
+| `sendEscape(surface)` | Send Escape; headless uses SIGINT |
+| `readScreen(surface, lines?)` / `readScreenAsync` | Read terminal output or headless logs |
+| `closeSurface(surface)` | Close a pane or headless process |
+| `renameSurface(surface, name)` | Rename the backend's corresponding window/tab |
+| `getLastSplitSource()` / `clearLastSplitSource()` | Track the most recent split source |
+| `pollForExit(surface, signal, options)` | Wait for an `.exit` sidecar, sentinel, or headless process exit |
+
+Types `CreateSurfaceOptions` and `CreateSurfaceSplitOptions` both expose `command?: string`. The existing first three split arguments are unchanged.
+
+Detection helpers include `getMuxBackend`, `isMuxAvailable`, `isHeadlessMode`, `muxSetupHint`, `getAgentPaneId`, and `backendAgentPaneEnvVar`. Shell helpers include `shellEscape`, `isFishShell`, and `exitStatusVar`.
+
+The shared API is also exported through `@kevinhao/pi-terminal-mux/mux`; Orca-native helpers are exported through `@kevinhao/pi-terminal-mux/orca`.
+
+## Naming ownership
+
+`createSurfaceRenameContext(surface)` produces the `PI_TERMINAL_RENAME_CONTEXT` protocol for a child launcher. Replace inherited context on every launch and resume.
+
+A child pane does not prove exclusive ownership of its tmux window or Orca tab. Child contexts therefore grant neither shared window/tab renaming nor workspace renaming. Invalid contexts never fall back to parent permissions.
+
+For ordinary sessions, `resolveTerminalRenameTargets({ tab, workspace })` resolves explicit identities, and `renameTerminalTarget(reference, title)` operates on those captured targets, never on UI focus:
+
+- tmux: window for `tab`, session for `workspace`.
+- Orca: terminal tab for `tab`; `workspace` is unsupported.
+- Headless: naming is unsupported.
+
+Legacy `renameCurrentTab` / `renameWorkspace` return discriminated success, unsupported, disabled, or failed results. tmux's legacy operations require `PI_SUBAGENT_RENAME_TMUX_WINDOW=1` / `PI_SUBAGENT_RENAME_TMUX_SESSION=1`; explicit-ID resolution ignores those switches.
+
+## Migration
+
+Only tmux and Orca remain in `MuxBackend`. Other backend implementations, native exports/subpaths, WezTerm's `activate` option, and Herdr's read-source options have been removed. Update old backend preferences and imports. This is a breaking reduction of the supported backend/API surface; tmux/Orca calls without startup options remain compatible.
+
+No local executable paths are hardcoded. Orca's caller handle is captured at module load so later UI focus changes cannot redirect splits. Headless keeps the existing Bash default; `sendLongCommand({ interpreter: "powershell" })` explicitly selects PowerShell where available.
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,105 @@
+# @kevinhao/pi-terminal-mux
+
+供 Pi 扩展使用的终端 surface API，仅支持 **tmux**、**Orca** 和 **headless** 后台进程。
+
+[English README](./README.md)
+
+## 安装
+
+```bash
+npm install @kevinhao/pi-terminal-mux
+```
+
+## 创建时启动命令
+
+```ts
+import { createSurface, createSurfaceSplit, readScreen, closeSurface } from "@kevinhao/pi-terminal-mux";
+
+const surface = createSurface("my-agent", {
+  command: "pi --session /tmp/child.jsonl",
+});
+
+const sibling = createSurfaceSplit("review", "right", surface, {
+  command: "pi --session /tmp/review.jsonl",
+});
+
+const tail = readScreen(surface, 50);
+closeSurface(sibling);
+closeSurface(surface);
+```
+
+`command` 是可选的、非空的 **shell 命令字符串**，包含启动参数。动态值在 POSIX shell 中使用 `shellEscape()` 转义。这条路径不再另外调用 `sendCommand()`，也没有库内固定的 shell-ready 等待：
+
+- **tmux**：将命令直接传给 `tmux split-window`，在创建 pane 时启动。
+- **Orca**：传给 `terminal create` / `terminal split` 的 `--command`。Orca 自己启动 shell 并提交命令，不等同于直接按 argv spawn 程序。
+- **Headless**：用 `bash -c` 启动命令，stdout/stderr 写入日志文件。
+
+返回 handle 只证明创建/提交成功，不保证应用已就绪或任务成功。仍需使用应用自身的就绪信号、日志或退出协议。创建错误向上抛出；Orca 输入和读屏错误也会抛出，不再伪报成功。
+
+不传 options 的既有调用保持原来的行为：
+
+```ts
+import { createSurface, sendLongCommand } from "@kevinhao/pi-terminal-mux";
+
+const surface = createSurface("my-agent");
+const scriptPath = sendLongCommand(surface, "pi --session /tmp/child.jsonl", {
+  scriptPreamble: "export MY_FLAG=1",
+});
+```
+
+`sendLongCommand` 先写脚本，再向终端提交 `bash <script>`，仍供旧调用和长命令使用。已经在创建时传入的启动命令不要再发送一次，否则会重复执行。
+
+## 后端探测
+
+| 后端 | 条件 |
+|------|------|
+| tmux | 存在 `TMUX` 环境变量及 `tmux` 可执行文件 |
+| Orca | `TERM_PROGRAM=Orca`、存在 `orca` 可执行文件，且 runtime 可达 |
+| Headless | 上述终端后端均不可用 |
+
+自动探测优先 tmux，其次 Orca。可用 `PI_TERMINAL_MUX=tmux|orca` 强制指定；保留 `PI_SUBAGENT_MUX` 兼容别名。强制指定的后端不可用时不改选另一终端后端；未知或已移除的后端配置明确报错。
+
+## API
+
+| 函数 | 行为 |
+|------|------|
+| `createSurface(name, options?)` | tmux 与 Orca 一致：从调用方 pane 出发做 BFS 网格分屏；Orca 没有调用方 handle 时新建 tab；无后端时 headless。`options.command` 在创建时启动任务 |
+| `createSurfaceSplit(name, direction, fromSurface?, options?)` | 指定方向 left/right/up/down 分屏；可传 `options.command`。要求 tmux 或 Orca，headless 没有布局 |
+| `sendCommand(surface, command)` | 向现有终端发送文本并回车 |
+| `sendLongCommand(surface, command, options?)` | 先写脚本再执行；支持 `scriptPath`、`scriptPreamble` 和 `interpreter: "bash" | "powershell"` |
+| `sendEscape(surface)` | 发送 Escape；headless 使用 SIGINT |
+| `readScreen(surface, lines?)` / `readScreenAsync` | 读取终端输出或 headless 日志 |
+| `closeSurface(surface)` | 关闭 pane 或 headless 进程 |
+| `renameSurface(surface, name)` | 修改后端对应的 window/tab 名称 |
+| `getLastSplitSource()` / `clearLastSplitSource()` | 最近一次分屏来源 |
+| `pollForExit(surface, signal, options)` | 等待 `.exit` sidecar、sentinel 或 headless 进程退出 |
+
+`CreateSurfaceOptions` 和 `CreateSurfaceSplitOptions` 均提供 `command?: string`。分屏的前三个位置参数保持不变。
+
+探测工具包括 `getMuxBackend`、`isMuxAvailable`、`isHeadlessMode`、`muxSetupHint`、`getAgentPaneId`、`backendAgentPaneEnvVar`；shell 工具包括 `shellEscape`、`isFishShell`、`exitStatusVar`。
+
+统一 API 同样从 `@kevinhao/pi-terminal-mux/mux` 导出；Orca 原生工具从 `@kevinhao/pi-terminal-mux/orca` 导出。
+
+## 改名归属
+
+`createSurfaceRenameContext(surface)` 为子进程启动方生成 `PI_TERMINAL_RENAME_CONTEXT` 协议。每次启动和恢复都替换继承值。
+
+子 pane 不能证明独占 tmux window 或 Orca tab，因此子进程不获得共享 window/tab 或 workspace 改名权限。协议损坏时不退回父会话权限。
+
+普通会话使用 `resolveTerminalRenameTargets({ tab, workspace })` 解析明确身份，再通过 `renameTerminalTarget(reference, title)` 对捕获的目标执行，而不是使用 UI 焦点：
+
+- tmux：`tab` 对应 window，`workspace` 对应 session。
+- Orca：`tab` 对应终端 tab，不支持 `workspace`。
+- Headless：不支持终端改名。
+
+旧 `renameCurrentTab` / `renameWorkspace` 返回可判别的成功、不支持、禁用或失败结果。tmux 的旧入口分别要求 `PI_SUBAGENT_RENAME_TMUX_WINDOW=1` / `PI_SUBAGENT_RENAME_TMUX_SESSION=1`；明确 ID 的解析不受这两个开关影响。
+
+## 迁移
+
+`MuxBackend` 仅保留 tmux 和 Orca。其他后端实现、原生导出/子路径、WezTerm 的 `activate` 参数、Herdr 的读屏 source 参数已移除。请更新旧后端环境配置和导入路径。这是支持范围/API 的不兼容精简；既有 tmux/Orca 调用不传启动参数时保持兼容。
+
+代码不硬编码本地可执行文件路径；Orca 调用方 handle 在模块加载时捕获，后续焦点变化不会改变分屏来源。Headless 保留 Bash 默认运行时；需要 PowerShell 时显式使用 `sendLongCommand({ interpreter: "powershell" })`。
+
+## License
+
+MIT

package/index.ts

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

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@kevinhao/pi-terminal-mux",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.7.0",
+  "description": "Terminal surface API for tmux and Orca, with native startup commands and headless fallback",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./package.json": "./package.json",
+    "./mux": "./src/mux.ts",
+    "./orca": "./src/orca.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "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/haoyiqiang/pi-extensions/tree/main/packages/pi-terminal-mux",
+  "bugs": "https://github.com/haoyiqiang/pi-extensions/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/haoyiqiang/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",
+    "orca",
+    "headless",
+    "coding-agent"
+  ],
+  "dependencies": {
+    "@kevinhao/pi-utils": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.12.4",
+    "tsx": "4.23.1",
+    "typescript": "5.9.3"
+  }
+}