terminal-tool-for-agents 0.1.3

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "terminal-tool-for-agents",
+  "version": "0.1.3",
+  "description": "terminal-tool-for-agents (tta) — terminal tool for AI agents. Command: tta. Package: terminal-tool-for-agents.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yanggggjie/terminal-tool-for-agents.git"
+  },
+  "homepage": "https://github.com/yanggggjie/terminal-tool-for-agents#readme",
+  "bugs": {
+    "url": "https://github.com/yanggggjie/terminal-tool-for-agents/issues"
+  },
+  "keywords": [
+    "tui",
+    "pty",
+    "terminal",
+    "tool",
+    "automation",
+    "agent",
+    "cli",
+    "xterm"
+  ],
+  "bin": {
+    "tta": "./dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "skills/tta/SKILL.md",
+    "skills/tta/tta-agents-skill.md",
+    "src/watch-ui/logo.png",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/copy-watch-vendor.js && rm -rf dist && tsc && cp -r src/watch-ui dist/watch-ui && chmod +x dist/cli.js",
+    "dev": "node scripts/dev.mjs",
+    "start": "node dist/cli.js",
+    "test": "node scripts/verify.js",
+    "prepack": "npm run build",
+    "version": "node scripts/sync-skill-version.js",
+    "prepublishOnly": "npm test",
+    "release": "node scripts/release.js"
+  },
+  "dependencies": {
+    "@fastify/static": "^9.1.3",
+    "@fastify/websocket": "^11.2.0",
+    "@xterm/headless": "^6.0.0",
+    "@xterm/xterm": "^6.0.0",
+    "commander": "^15.0.0",
+    "fastify": "^5.8.5",
+    "node-pty": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/ws": "^8.18.1",
+    "concurrently": "^9.2.1",
+    "nodemon": "^3.1.11",
+    "typescript": "^6.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0 <27.0.0"
+  },
+  "allowScripts": {
+    "node-pty@1.1.0": true
+  }
+}

package/skills/tta/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: tta
+version: 0.1.3
+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
+
+`terminal-tool-for-agents` provides the `tta` command. Use shell for plain non-interactive commands. Use `tta` for interactive programs that need a PTY.
+
+Idea: start background terminals as `sess`, send keys or text as `act`, then wait for a stable screen and read results as `obs`.
+
+## Session
+
+All tta work happens inside a **session** (PTY-backed terminal instance): `tta sess start/kill/list`, `--sess=`.
+
+## tta-agents (bundled sub-skill)
+
+`skills/tta/tta-agents-skill.md` ships **with the tta skill** — **no separate install**.
+
+**When to enable:** If the user wants tta to drive coding agent CLIs (Claude Code, Codex, Cursor Agent, OpenCode, Pi, etc.) or mentions Orchestrator / Worker / multi-agent coordination, read and follow [`tta-agents-skill.md`](./tta-agents-skill.md). For other interactive terminals (TUI, wizards, dev servers), this skill alone is enough.
+
+## When to use
+
+**Use `tta` for:**
+
+- REPLs, e.g. `GDB`, `IPython`
+- Interactive setup, e.g. `npm create vite@latest`
+- TUIs, e.g. `lazygit`
+- Long-running processes whose output must be observed over time, e.g. `npm run dev`
+- Coding agent CLIs → enable bundled [`tta-agents-skill.md`](./tta-agents-skill.md)
+
+**Do not use `tta` for:**
+
+- Plain bash commands that run to completion without interaction
+- Human session observation (use `tta sess watch`; agents must not)
+
+## Standard workflow
+
+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>`
+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:
+
+   ```bash
+   tta act send text --sess=<name> <<'EOF'
+   <your input>
+   EOF
+   tta act send key --sess=<name> --key=enter
+   ```
+
+   Must use `<<'EOF'` (quoted delimiter), not `<<EOF`, or `$`, `()`, and backticks will be expanded by the shell.
+4. **After every `act`** — `tta obs screen stable --sess=<name>` to confirm the screen updated
+5. **Kill by session type** — kill one-shot CLI/TUI when done with `tta sess kill`; keep dev-server sessions until observation ends (see **Session lifecycle** table)
+6. **Process exited** — still use `obs` for errors and final output, then `tta sess kill`
+
+```text
+sess start -> obs screen stable -> (act -> obs screen stable)* -> [sess kill]
+```
+
+## Three APIs
+
+| API | Commands | Role | stdout |
+|-----|----------|------|--------|
+| **sess** | `start`, `kill`, `killall`, `list`, `keys`, `watch` | Create, stop, list sessions; human watch UI | `success` (start/kill); list: `name running` / `name exited exit_code=N` |
+| **act** | `send text`, `send key` | Send input to a **running** session | `success` |
+| **obs** | `screen now`, `screen stable`, `screen scroll` | Read a session's screen (running or exited) | screen text |
+
+On failure: one line `error: <reason>` (exit 1).
+
+## Session lifecycle
+
+| Session usage | Examples | Kill when done? |
+|---------------|----------|-----------------|
+| One-shot interactive CLI | `npm create vite@latest` | **Yes** |
+| One-shot interactive TUI | `lazygit` | **Yes** |
+| Long-running + observe | `npm run dev` | **No** while observing; kill when done |
+
+Coding agent workers (multi-turn context) — see [`tta-agents-skill.md`](./tta-agents-skill.md).
+
+**Naming:** one lowercase word, or 2–3 words joined by `-`, e.g. `dev`, `vite-once`.
+
+**Exited sessions:** after the PTY process exits, the session stays `exited` in `sess list` until `tta sess kill`. `obs` still works; `act` fails. Read errors with `obs`, then `kill`.
+
+**Rules:**
+
+- `act` / `obs` require `--sess=` and an existing session
+- Send text: `tta act send text --sess=<name> <<'EOF'` … `EOF` (quoted heredoc, `<<'EOF'`)
+- Do not background `tta` calls; wait for each to finish
+- Do not rely on `act` stdout; use `obs` to read the screen
+- Do not use `tta sess watch`
+
+## Parameter quoting
+
+| Flag | Used by | Quoting |
+|------|---------|---------|
+| `--cmd=` | sess start (**required**) | always `--cmd="..."` |
+| `--cwd=` | sess start (**required**) | always `--cwd="..."`; prefer absolute paths |
+| `--sess=` | sess start/kill, act, obs | not required |
+| `--key=` | act send key | not required |
+| `--dire=` | obs screen scroll | not required |
+| send text input | act send text | always `<<'EOF'` |
+
+**`sess start` template:**
+
+```bash
+tta sess start --sess=<name> --cmd="<command>" --cwd="/absolute/path/to/project"
+```
+
+Examples:
+
+```bash
+tta sess start --sess=dev --cmd="npm run dev" --cwd="/Users/you/project"
+tta sess start --sess=vite-once --cmd="npm create vite@latest" --cwd="/Users/you/project"
+tta sess start --sess=lazy --cmd="lazygit" --cwd="/Users/you/project"
+```
+
+**Common mistake:** an unquoted multi-word command is split by the shell; tta reports `too many arguments`:
+
+```bash
+# wrong
+tta sess start --sess=dev --cmd=npm run dev --cwd="/tmp"
+# correct
+tta sess start --sess=dev --cmd="npm run dev" --cwd="/tmp"
+```
+
+### `--cmd=` and `--cwd=`
+
+`sess start` runs `--cmd=` in a PTY under `--cwd=` — the same command line you would type in a terminal. tta handles platform details; do not pick or configure a shell.
+
+## Prompts, choices, and confirmations
+
+**TUI menus, numbered options, yes/no prompts — use `send key` only.** Do not use `send text` to pick TUI options.
+
+| Screen | Use |
+|--------|-----|
+| TUI menu, list, `[Y/n]`, numbered choices | `send key` — `arrow_up` / `arrow_down` to move, `enter` to select or confirm |
+| Free-form shell input | `tta act send text --sess=<name> <<'EOF'` … `EOF`, then `send key --key=enter` |
+
+### Send text (heredoc)
+
+Same pattern for short and long input; `<<'EOF'` sends content literally to the PTY:
+
+```bash
+tta act send text --sess=vite-once <<'EOF'
+my-project-name
+EOF
+```
+
+**Must use `<<'EOF'` (quoted delimiter)** — not `<<EOF`, or `$()`, backticks, and `$var` will be expanded by the shell.
+
+After every `act`, run `obs screen stable`.
+
+```bash
+# TUI menu
+tta act send key --sess=vite-once --key=arrow_down
+tta act send key --sess=vite-once --key=enter
+tta obs screen stable --sess=vite-once
+```
+
+Run `tta sess keys` for supported key names.
+
+## Fallbacks
+
+**Screen stuck (menu/confirm not advancing):**
+
+1. Try `send key --key=enter` first (accept default / confirm)
+2. Still stuck → try `arrow_up` / `arrow_down` or `tab`
+3. Run `obs screen stable` again to confirm progress
+
+**`act` failed:**
+
+1. `tta sess list` — check `running` vs `exited`
+2. If `exited` → `obs screen stable` for errors, then `sess kill`
+3. If `running` but screen unchanged → check whether `send text` was used on a TUI menu by mistake
+
+**Start failed (command not found, quoting error, etc.):**
+
+```bash
+tta sess start --sess=bad --cmd="this-command-does-not-exist" --cwd="/Users/you/project"
+tta sess list
+tta obs screen stable --sess=bad
+tta sess kill --sess=bad
+```
+
+## Commands
+
+```bash
+tta sess start --sess=<name> --cmd="<command>" --cwd="/absolute/path/to/project"
+tta sess kill --sess=<name>
+tta sess killall
+tta sess list
+tta sess keys
+tta sess watch   # human-only
+
+# send text: quoted heredoc
+tta act send text --sess=<name> <<'EOF'
+<text>
+EOF
+tta act send key  --sess=<name> --key=<key>
+
+tta obs screen now    --sess=<name>
+tta obs screen stable --sess=<name>
+tta obs screen scroll --sess=<name> --dire=<up|down|top|bottom>
+```
+
+## Examples
+
+```bash
+# One-shot: kill when done
+tta sess start --sess=vite-once --cmd="npm create vite@latest" --cwd="/Users/you/project"
+tta obs screen stable --sess=vite-once
+tta act send key --sess=vite-once --key=enter
+tta obs screen stable --sess=vite-once
+tta sess kill --sess=vite-once
+
+# Dev server: keep, use obs
+tta sess start --sess=dev --cmd="npm run dev" --cwd="/Users/you/project"
+tta obs screen stable --sess=dev
+tta sess kill --sess=dev
+```
+
+Coding agent worker examples — see [`tta-agents-skill.md`](./tta-agents-skill.md).

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

@@ -0,0 +1,200 @@
+---
+name: tta-agents
+version: 0.1.3
+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
+
+**This file is a bundled sub-skill of the [tta skill](./SKILL.md).** When read, **immediately adopt the Orchestrator role**.
+
+**Prerequisites:** `tta` CLI installed and tta skill loaded. Architecture: [`docs/tta-agents-docs.md`](../../docs/tta-agents-docs.md).
+
+## You are the Orchestrator
+
+**The agent using tta is the Orchestrator.** **You** are the Orchestrator, not a worker.
+
+| Role | Who | Can use tta? |
+|------|-----|--------------|
+| **Orchestrator** | **You** | **Yes** |
+| **Worker** | Coding agent CLI you start with `tta sess start` | **No** |
+
+Workers must not call tta, load tta skill, or spawn sub-workers.
+
+## Orchestrator workflow (required reading)
+
+The Orchestrator **manages workers** via tta and may **use tta on ordinary sessions** in the same task (TUI, dev server, etc.; see tta skill).
+
+For **long, multi-step** tasks:
+
+1. Split into **phases** (e.g. phase one: implement → review → fix → test; phase two: …)
+2. Use **multiple workers for separated concerns** (e.g. `worker-coder`, `worker-reviewer`, `worker-test`)
+3. **Serial scheduling** — on one task chain, **advance only one worker step at a time**; after it completes and you summarize, assign the next step
+
+**Workers do not talk to each other.** The flow is always:
+
+```text
+Assign → obs until worker completes → Orchestrator reads screen, summarizes
+    → Orchestrator decides next step
+    → Assign to next worker (or send feedback back to previous worker)
+    → loop until phase/task completes
+```
+
+Example phase one:
+
+- Assign “implement” to **coding worker** → wait → **you** summarize changes
+- Send summary to **review worker** → wait → **you** summarize review feedback
+- **Relay** review feedback to **coding worker** to fix → wait → **you** summarize
+- Send summary to **test worker** → wait → **you** summarize test results → decide phase two or revisit a step
+
+You may keep multiple worker **sessions** open (each keeps context), but **scheduling must be serial**: review starts only after coding finishes and **you relay**; **forbid** two workers parallelizing the same step.
+
+## Worker constraints
+
+1. **Workers cannot use tta**
+2. **Workers default to auto mode** — start commands below; prompt is authorization
+3. **Every prompt must include:** forbid tta, task, directory, Allowed / Forbidden
+
+## Permissions
+
+The Orchestrator **must** obey the user’s permission scope; **fully write** Allowed / Forbidden when assigning workers; read screens to **prevent worker overreach**; stop and report if overreach occurs. Information passed between workers must stay within user authorization (e.g. if review is read-only, do not let coder worker include unauthorized actions in feedback).
+
+**Assignment prompt template:**
+
+```bash
+tta act send text --sess=worker-coder-claude <<'EOF'
+You are a coding worker. Do NOT use tta or spawn sub-agents.
+
+Task: <concrete step task>
+Working directory: /absolute/path/to/project
+
+Allowed:
+- ...
+
+Forbidden:
+- ...
+- Using tta
+
+When done, summarize what you did (files changed, test status).
+EOF
+tta act send key --sess=worker-coder-claude --key=enter
+```
+
+When **relaying review feedback to coder**, state in the prompt that feedback comes from the Orchestrator and paste your summarized review points; do not let workers assume they can contact the reviewer directly.
+
+## Session and Worker
+
+**Worker ⊆ Session.** Naming: `worker-coder-claude`, `worker-reviewer-codex`, `worker-test-pi`.
+
+## Orchestrator responsibilities
+
+1. Start / maintain worker sessions (avoid kill until task ends, keep context)
+2. Serial loop: assign → `obs screen stable` → summarize → think → next assignment
+3. **Relay** results and feedback between workers (do not assume workers know each other)
+4. When needed, use tta on **non-worker** sessions (e.g. `npm run dev` to observe logs)
+5. Enforce permissions; do not act beyond user authorization
+
+## Standard workflow (single step)
+
+1. Confirm you are Orchestrator; clarify user permissions and task phases
+2. `tta sess start --sess=worker-<role>-<name> --cmd="..." --cwd="/absolute/path"`
+3. `tta obs screen stable`
+4. `tta act send text` (heredoc) + Enter
+5. `obs screen stable` → **summarize** → decide next worker or send back
+6. Repeat until phase completes
+
+## Worker start commands (auto mode)
+
+| Coding Agent | `--cmd="..."` |
+|--------------|---------------|
+| Claude Code | `claude --dangerously-skip-permissions` |
+| Codex | `codex --sandbox workspace-write --ask-for-approval never` |
+| Cursor Agent | `agent --yolo --sandbox disabled` |
+| OpenCode | `opencode --yolo` |
+| Pi | `pi` |
+| Kimi Code | `kimi --auto` |
+
+## Example: single worker (simple task)
+
+```bash
+tta sess start --sess=worker-coder-claude --cmd="claude --dangerously-skip-permissions" --cwd="/Users/you/project"
+tta obs screen stable --sess=worker-coder-claude
+tta act send text --sess=worker-coder-claude <<'EOF'
+You are a worker. Do NOT use tta.
+Task: Fix auth bug, run npm test, summarize.
+Working directory: /Users/you/project
+Allowed: edit src/, run npm test
+Forbidden: git push, deploy, using tta
+EOF
+tta act send key --sess=worker-coder-claude --key=enter
+tta obs screen stable --sess=worker-coder-claude
+# Orchestrator reads screen and summarizes; sess kill when task ends
+```
+
+## Example: multiple workers serial (implement → review → fix → test)
+
+**Separated concerns, serial Orchestrator scheduling.** Workers do not talk; feedback is **relayed by you**.
+
+```bash
+# --- 0. Optionally start multiple worker sessions upfront (each keeps context) ---
+tta sess start --sess=worker-coder-claude --cmd="claude --dangerously-skip-permissions" --cwd="/Users/you/project"
+tta sess start --sess=worker-reviewer-codex --cmd="codex --sandbox workspace-write --ask-for-approval never" --cwd="/Users/you/project"
+tta sess start --sess=worker-test-pi --cmd="pi" --cwd="/Users/you/project"
+
+# --- 1. Implement (only coding worker active; others wait) ---
+tta obs screen stable --sess=worker-coder-claude
+tta act send text --sess=worker-coder-claude <<'EOF'
+Do NOT use tta. Implement feature X in src/. Summarize changes when done.
+Allowed: edit src/, run npm test
+Forbidden: git push, using tta
+EOF
+tta act send key --sess=worker-coder-claude --key=enter
+tta obs screen stable --sess=worker-coder-claude
+# Orchestrator: read screen, draft change summary; do not touch reviewer yet
+
+# --- 2. Review (coding done; Orchestrator sends summary to reviewer) ---
+tta obs screen stable --sess=worker-reviewer-codex
+tta act send text --sess=worker-reviewer-codex <<'EOF'
+Do NOT use tta. Review the following changes (from Orchestrator, not from another agent):
+
+<paste Orchestrator's summarized change summary>
+
+List issues and suggestions. Summarize when done.
+Forbidden: editing files, using tta
+EOF
+tta act send key --sess=worker-reviewer-codex --key=enter
+tta obs screen stable --sess=worker-reviewer-codex
+# Orchestrator: read screen, draft review feedback
+
+# --- 3. Fix (Orchestrator relays review to coder; wait until step 2 completes) ---
+tta obs screen stable --sess=worker-coder-claude
+tta act send text --sess=worker-coder-claude <<'EOF'
+Do NOT use tta. Address the following review feedback (from Orchestrator):
+
+<paste Orchestrator's summarized review feedback>
+
+Summarize what you fixed.
+EOF
+tta act send key --sess=worker-coder-claude --key=enter
+tta obs screen stable --sess=worker-coder-claude
+
+# --- 4. Test (Orchestrator sends summary to test worker) ---
+tta obs screen stable --sess=worker-test-pi
+tta act send text --sess=worker-test-pi <<'EOF'
+Do NOT use tta. Run npm test and report results.
+Context from Orchestrator: <change and fix summary>
+EOF
+tta act send key --sess=worker-test-pi --key=enter
+tta obs screen stable --sess=worker-test-pi
+# Orchestrator: summarize test results → phase two or revisit a step
+
+# When full task ends: tta sess kill --sess=worker-coder-claude etc.
+```
+
+## Failures and fallbacks
+
+- **Worker unresponsive:** `sess list` → `obs screen stable`
+- **Worker overreach:** stop / kill, report user
+- **No parallel step stealing:** do not assign reviewer while coding is incomplete
+
+**Split:** ordinary TUI / dev server → tta skill; coding agent task chains → this skill, **serial** Orchestrator loop.