terminal-tool-for-agents 0.1.4 → 0.1.6

package/README.md

@@ -31,12 +31,13 @@ Copy this block into your agent:
 Install tta CLI:
 npm install -g terminal-tool-for-agents
 
-Install the tta skill from:
-https://github.com/yanggggjie/terminal-tool-for-agents/tree/main/skills/tta
+Install tta skills (English only — do NOT install *.zh.md):
+- https://raw.githubusercontent.com/yanggggjie/terminal-tool-for-agents/main/skills/tta/SKILL.md
+- https://raw.githubusercontent.com/yanggggjie/terminal-tool-for-agents/main/skills/tta/tta-agents-skill.md
 
-(includes bundled tta-agents-skill; no separate install)
+tta-agents-skill ships with tta skill in the same folder; no separate install.
 
-Confirm both are installed.
+Confirm CLI and both skill files are installed.
 ```
 
 Then ask your agent to run a task:
@@ -61,13 +62,11 @@ Copy this block into your agent:
 Update tta CLI:
 npm update -g terminal-tool-for-agents
 
-Update the tta skill from:
-https://github.com/yanggggjie/terminal-tool-for-agents/tree/main/skills/tta
+Update tta skills (English only — do NOT install *.zh.md):
+- https://raw.githubusercontent.com/yanggggjie/terminal-tool-for-agents/main/skills/tta/SKILL.md
+- https://raw.githubusercontent.com/yanggggjie/terminal-tool-for-agents/main/skills/tta/tta-agents-skill.md
 
-Kill all tta sessions so the background service restarts on next use:
-tta sess killall
-
-Confirm both are updated.
+Confirm CLI and both skills are updated.
 ```
 
 ## When to use tta vs shell
@@ -121,19 +120,26 @@ Operational details: [`skills/tta/SKILL.md`](./skills/tta/SKILL.md).
 ## Requirements
 
 - **Node.js** 22.x–26.x (`engines`: `>=22.0.0 <27.0.0`); repo includes `.nvmrc` (`24`) for local dev
-- After `npm install` or `npm install -g`, if npm warns about allow-scripts for `node-pty`, run `npm approve-scripts node-pty` or `npm approve-scripts --allow-scripts-pending`, then reinstall so the PTY native module installs correctly.
+- Install runs `postinstall` automatically: copies node-pty prebuilds into `build/Release` and verifies the PTY works; no manual `approve-scripts` needed
 
 ## Development
 
+After code changes, reinstall globally and test:
+
+```bash
+just install
+tta sess list
+```
+
+Watch UI only (static files from `src/watch-ui/`):
+
 ```bash
 just dev
-just link        # link for global testing
-just unlink      # remove link after testing
-tta sess watch   # open http://127.0.0.1:7654 to observe
+tta sess watch   # http://127.0.0.1:7654
 ```
 
-- **Backend** (`src/*.ts`): save → tsc recompiles → nodemon restarts server → refresh browser.
-- **Watch UI** (`src/watch-ui/*`): save → refresh browser (served from `src/` in dev).
+- **Backend** (`src/*.ts`): change → `just install` → run `tta`
+- **Watch UI** (`src/watch-ui/*`): under `just dev`, save → refresh browser
 
 ## License
 

package/README.zh.md

@@ -31,12 +31,13 @@ Fork 自 [tui-use](https://github.com/onesuper/tui-use) 并改造为 `tta`。感
 Install tta CLI:
 npm install -g terminal-tool-for-agents
 
-Install the tta skill from:
-https://github.com/yanggggjie/terminal-tool-for-agents/tree/main/skills/tta
+Install tta skills (English only — do NOT install *.zh.md):
+- https://raw.githubusercontent.com/yanggggjie/terminal-tool-for-agents/main/skills/tta/SKILL.md
+- https://raw.githubusercontent.com/yanggggjie/terminal-tool-for-agents/main/skills/tta/tta-agents-skill.md
 
-(includes bundled tta-agents-skill; no separate install)
+tta-agents-skill ships with tta skill in the same folder; no separate install.
 
-Confirm both are installed.
+Confirm CLI and both skill files are installed.
 ```
 
 然后让 Agent 执行任务：
@@ -61,13 +62,11 @@ tta sess watch
 Update tta CLI:
 npm update -g terminal-tool-for-agents
 
-Update the tta skill from:
-https://github.com/yanggggjie/terminal-tool-for-agents/tree/main/skills/tta
+Update tta skills (English only — do NOT install *.zh.md):
+- https://raw.githubusercontent.com/yanggggjie/terminal-tool-for-agents/main/skills/tta/SKILL.md
+- https://raw.githubusercontent.com/yanggggjie/terminal-tool-for-agents/main/skills/tta/tta-agents-skill.md
 
-Kill all tta sessions so the background service restarts on next use:
-tta sess killall
-
-Confirm both are updated.
+Confirm CLI and both skills are updated.
 ```
 
 ## 何时用 tta vs shell
@@ -121,19 +120,26 @@ tta sess start -> (tta act ... -> tta obs screen stable)* -> tta sess kill
 ## 环境要求
 
 - **Node.js** 22.x–26.x（`engines`：`>=22.0.0 <27.0.0`）；仓库含 `.nvmrc`（`24`）供本地开发
-- `npm install` 或 `npm install -g` 后，若 npm 对 `node-pty` 提示 allow-scripts，请运行 `npm approve-scripts node-pty` 或 `npm approve-scripts --allow-scripts-pending`，然后重新安装，以便 PTY 原生模块正确安装。
+- 安装时会自动运行 `postinstall`，将 node-pty prebuild 复制到 `build/Release` 并验证 PTY 可用；无需手动 `approve-scripts`
 
 ## 开发
 
+改代码后重新全局安装再测：
+
+```bash
+just install
+tta sess list
+```
+
+仅开发 Watch UI 时（静态文件从 `src/watch-ui/` 提供）：
+
 ```bash
-just dev 
-just link        # 链接以便全局测试
-just unlink        # 测试完成删除链接
-tta sess watch        # 打开 http://127.0.0.1:7654 观察
+just dev
+tta sess watch   # http://127.0.0.1:7654
 ```
 
-- **后端**（`src/*.ts`）：保存 → tsc 重编译 → nodemon 重启 server → 刷新浏览器。
-- **Watch UI**（`src/watch-ui/*`）：保存 → 刷新浏览器（开发模式下直接从 `src/` 提供）。
+- **后端**（`src/*.ts`）：改完 → `just install` → 再跑 `tta`
+- **Watch UI**（`src/watch-ui/*`）：`just dev` 下保存 → 刷新浏览器
 
 ## 许可证
 

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAc/C,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAazD;AAED,wBAAsB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAWjE"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAU/C,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAKzD;AAED,wBAAsB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAWjE"}

package/dist/client.js

@@ -48,17 +48,9 @@ const HEALTH_TIMEOUT_MS = 500;
 function info(msg) {
     process.stderr.write(`tta: ${msg}\n`);
 }
-function isDevMode() {
-    return fs.existsSync(path.join(__dirname, "..", ".tta-dev"));
-}
 async function ensureServerRunning() {
     if (await isServerReachable())
         return;
-    if (isDevMode()) {
-        throw new Error("Dev server is not running.\n" +
-            "  Start it in the project root: just dev\n" +
-            "  Then run tta commands in another terminal.");
-    }
     info("starting server...");
     await spawnServer();
 }

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "terminal-tool-for-agents",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "terminal-tool-for-agents (tta) — terminal tool for AI agents. Command: tta. Package: terminal-tool-for-agents.",
   "license": "MIT",
   "repository": {
@@ -26,6 +26,8 @@
   },
   "files": [
     "dist/",
+    ".npmrc",
+    "scripts/install.js",
     "skills/tta/SKILL.md",
     "skills/tta/tta-agents-skill.md",
     "src/watch-ui/logo.png",
@@ -37,10 +39,10 @@
     "dev": "node scripts/dev.mjs",
     "start": "node dist/cli.js",
     "test": "node scripts/verify.js",
+    "postinstall": "node scripts/install.js",
     "prepack": "npm run build",
-    "version": "node scripts/sync-skill-version.js",
     "prepublishOnly": "npm test",
-    "release": "node scripts/release.js"
+    "release": "release-it"
   },
   "dependencies": {
     "@fastify/static": "^9.1.3",
@@ -56,12 +58,10 @@
     "@types/ws": "^8.18.1",
     "concurrently": "^9.2.1",
     "nodemon": "^3.1.11",
+    "release-it": "^20.2.0",
     "typescript": "^6.0.0"
   },
   "engines": {
     "node": ">=22.0.0 <27.0.0"
-  },
-  "allowScripts": {
-    "node-pty@1.1.0": true
   }
 }

package/scripts/install.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+/**
+ * Post-install: set up node-pty native bindings.
+ * Copies bundled prebuilds into build/Release (+ chmod on Unix), or rebuilds from source.
+ * Does not rely on node-pty install scripts (npm 11 may block dependency scripts).
+ */
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execSync } = require("child_process");
+
+const PKG = "tta";
+const root = path.join(__dirname, "..");
+const platformKey = `${process.platform}-${process.arch}`;
+
+function findNodePtyRoot(fromDir = root) {
+  try {
+    return path.dirname(require.resolve("node-pty/package.json", { paths: [fromDir] }));
+  } catch {
+    return null;
+  }
+}
+
+function log(msg) {
+  process.stdout.write(`[${PKG}] ${msg}\n`);
+}
+
+function testNodePty(nodePtyDir) {
+  const tmpScript = path.join(os.tmpdir(), `${PKG}-test-pty-${process.pid}.js`);
+  try {
+    fs.writeFileSync(
+      tmpScript,
+      `
+const pty = require(${JSON.stringify(nodePtyDir)});
+const shell = process.platform === "win32" ? (process.env.ComSpec || "cmd.exe") : "/bin/sh";
+const args = process.platform === "win32" ? ["/c", "exit /b 0"] : ["-c", "exit 0"];
+const p = pty.spawn(shell, args, { name: "xterm", cols: 80, rows: 24 });
+p.kill();
+`
+    );
+    execSync(`node ${JSON.stringify(tmpScript)}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  } finally {
+    try {
+      fs.unlinkSync(tmpScript);
+    } catch {
+      // ignore
+    }
+  }
+}
+
+function copyEntry(src, dest, entry) {
+  if (entry.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const child of fs.readdirSync(src, { withFileTypes: true })) {
+      copyEntry(path.join(src, child.name), path.join(dest, child.name), child);
+    }
+    return;
+  }
+  fs.copyFileSync(src, dest);
+  if (process.platform !== "win32") {
+    const mode = fs.statSync(dest).mode;
+    if ((mode & 0o111) === 0 && (entry.name.endsWith(".node") || entry.name === "spawn-helper")) {
+      fs.chmodSync(dest, mode | 0o755);
+    }
+  }
+}
+
+function installPrebuild(nodePtyDir) {
+  const prebuildDir = path.join(nodePtyDir, "prebuilds", platformKey);
+  const prebuildPty = path.join(prebuildDir, "pty.node");
+  if (!fs.existsSync(prebuildPty)) {
+    log(`No prebuild for ${platformKey}`);
+    return false;
+  }
+
+  const targetDir = path.join(nodePtyDir, "build", "Release");
+  try {
+    fs.mkdirSync(targetDir, { recursive: true });
+    for (const entry of fs.readdirSync(prebuildDir, { withFileTypes: true })) {
+      copyEntry(path.join(prebuildDir, entry.name), path.join(targetDir, entry.name), entry);
+    }
+    log(`Installed prebuilt binary for ${platformKey}`);
+    return true;
+  } catch (err) {
+    process.stderr.write(`[${PKG}] Failed to install prebuild: ${err.message}\n`);
+    return false;
+  }
+}
+
+function buildFromSource(nodePtyDir) {
+  log("Building node-pty from source (this may take a minute)...");
+  try {
+    execSync("npx node-gyp rebuild", { stdio: "inherit", cwd: nodePtyDir });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function exitWithBuildError() {
+  const fixes = {
+    darwin: "  xcode-select --install\n  npm install -g terminal-tool-for-agents",
+    linux:
+      "  sudo apt-get install build-essential python3 g++\n  npm install -g terminal-tool-for-agents",
+  };
+  const fix = fixes[process.platform] ?? "  npm install -g terminal-tool-for-agents";
+  process.stderr.write(
+    `[${PKG}] node-pty native binding failed to load.\n\n[${PKG}] To fix:\n${fix}\n`
+  );
+  process.exit(1);
+}
+
+function killallSessions() {
+  try {
+    execSync("tta sess killall", { stdio: "ignore" });
+  } catch {
+    // no server or nothing to kill
+  }
+}
+
+function ensureNodePty(nodePtyDir) {
+  log(`Platform: ${platformKey}`);
+
+  if (testNodePty(nodePtyDir)) {
+    log("node-pty is ready");
+    return;
+  }
+
+  if (installPrebuild(nodePtyDir) && testNodePty(nodePtyDir)) {
+    log("Prebuilt binary works");
+    return;
+  }
+
+  if (buildFromSource(nodePtyDir) && testNodePty(nodePtyDir)) {
+    log("node-pty built successfully");
+    return;
+  }
+
+  exitWithBuildError();
+}
+
+if (require.main === module) {
+  const nodePtyDir = findNodePtyRoot();
+  if (!nodePtyDir) {
+    process.stderr.write(`[${PKG}] node-pty not found\n`);
+    process.exit(1);
+  }
+  ensureNodePty(nodePtyDir);
+  killallSessions();
+}
+
+module.exports = { findNodePtyRoot, testNodePty, ensureNodePty, killallSessions };

package/skills/tta/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: tta
-version: 0.1.4
-description: Operate interactive CLI, TUI, and dev-server sessions through a PTY. Use when a command needs keystrokes, redraws a terminal UI, step-by-step screen reads, or for npm create, lazygit, npm run dev, etc. Not for plain non-interactive bash. APIs: sess, act, obs. Bundled tta-agents sub-skill when the user uses tta with coding agents.
+version: 0.1.6
+description: "Operate interactive CLI, TUI, and dev-server sessions through a PTY. Use when a command needs keystrokes, redraws a terminal UI, step-by-step screen reads, or for npm create, lazygit, npm run dev, etc. Not for plain non-interactive bash. APIs: sess, act, obs. Bundled tta-agents sub-skill when the user uses tta with coding agents."
 ---
 
 # tta - terminal tool for agents
@@ -40,7 +40,7 @@ All tta work happens inside a **session** (PTY-backed terminal instance): `tta s
 Follow in order; do not skip steps:
 
 1. **Pick the tool** — interactive / TUI / needs step-by-step screen reads → `tta`; otherwise shell
-2. **Start and read** — `tta sess start` (see **Parameter quoting**), then `tta obs screen stable --sess=<name>`
+2. **Start and read** — `tta sess start` (see **Command writing** and **Parameter quoting**), then `tta obs screen stable --sess=<name>`
 3. **Choose input by screen**
    - TUI menu, numbered options, `[Y/n]` → `tta act send key` (keys only, not text)
    - Free-form shell input → quoted heredoc, then Enter:
@@ -93,6 +93,12 @@ Coding agent workers (multi-turn context) — see [`tta-agents-skill.md`](./tta-
 - Do not rely on `act` stdout; use `obs` to read the screen
 - Do not use `tta sess watch`
 
+## Command writing
+
+- Each `tta` command on **one line**; do not use `\` line continuation
+- **No shell variables** in `--cmd=`, `--cwd=`, etc. (`$VAR`); use absolute paths and full command literals
+- `act send text` must use **`<<'EOF'`**; do not use `<<EOF`
+
 ## Parameter quoting
 
 | Flag | Used by | Quoting |

package/skills/tta/tta-agents-skill.md

@@ -1,7 +1,7 @@
 ---
 name: tta-agents
-version: 0.1.4
-description: Bundled tta sub-skill. When triggered: current agent is Orchestrator; serially schedules multiple workers (separated concerns, e.g. code/review/test). Workers cannot use tta; feedback relayed by Orchestrator. Must obey user permission scope. Use when driving coding agents via tta or when user mentions Orchestrator/Worker.
+version: 0.1.6
+description: "Bundled tta sub-skill. When triggered: current agent is Orchestrator; serially schedules multiple workers (separated concerns, e.g. code/review/test). Workers cannot use tta; feedback relayed by Orchestrator. Must obey user permission scope. Use when driving coding agents via tta or when user mentions Orchestrator/Worker."
 ---
 
 # tta-agents - orchestrate coding agents with tta