@dmsdc-ai/aigentry-telepty 0.1.80 → 0.1.82

package/README.md

@@ -1,92 +1,151 @@
-# @dmsdc-ai/aigentry-telepty
+# telepty
 
-**Cross-machine PTY-based remote prompt injection daemon for AI CLIs.**
+**Connect any terminal to any terminal, any machine.**
 
-`telepty` (Tele-Prompt) is a lightweight background daemon that bridges the gap between the network and interactive AI command-line interfaces. It allows you to seamlessly share, attach to, and inject commands into terminal sessions across different machines.
+telepty is a lightweight PTY multiplexer and session bridge. It lets you spawn, attach to, and inject commands into terminal sessions — locally or across machines via Tailscale.
 
-Its primary user experience is prompt-driven operation inside LLM CLIs and the built-in TUI. Raw `telepty ...` commands are the lower-level control surface.
+Built for AI CLI workflows (Claude Code, Codex, Gemini CLI), but works with any interactive terminal program.
 
-## One-Click Installation & Update
+## Install
 
-To install or update `telepty` on any machine (macOS, Linux, or Windows), just run the command for your OS. (Node.js will be automatically installed if you don't have it).
-
-### For macOS and Linux (Ubuntu, CentOS, etc.)
-Open your terminal and run:
 ```bash
+# macOS / Linux
 curl -fsSL https://raw.githubusercontent.com/dmsdc-ai/aigentry-telepty/main/install.sh | bash
-```
 
-### For Windows (PowerShell)
-Open PowerShell as Administrator and run:
-```powershell
+# Windows (PowerShell as Admin)
 iwr -useb https://raw.githubusercontent.com/dmsdc-ai/aigentry-telepty/main/install.ps1 | iex
+
+# Or via npm
+npm install -g @dmsdc-ai/aigentry-telepty
 ```
 
-You can also launch the installer through npm without downloading the script first:
+The installer sets up telepty as a background service (`launchd` on macOS, `systemd` on Linux, detached process on Windows).
+
+## Quick Start
 
 ```bash
-npx --yes @dmsdc-ai/aigentry-telepty@latest
-```
+# 1. Start the daemon
+telepty daemon
+
+# 2. Wrap an existing CLI session for remote control
+telepty allow --id my-session claude
+
+# 3. List active sessions (local + Tailnet)
+telepty list
 
-*These single commands will install the package globally and automatically configure it to run as a background service specific to your OS (`systemd` for Linux, `launchd` for macOS, or a detached background process for Windows).*
-The installer now stops older local telepty daemons before starting the new one, so updates do not leave duplicate background processes behind.
+# 4. Inject a prompt into a session
+telepty inject my-session "explain this codebase"
 
-## Seamless Usage
+# 5. Attach to a session interactively
+telepty attach my-session
 
-1. **Start a background session:**
-   ```bash
-   telepty spawn --id "my-session" bash
-   ```
+# 6. Broadcast to all sessions
+telepty broadcast "status report"
+```
 
-2. **Attach to a session (Local or Remote):**
-   ```bash
-   telepty attach
-   ```
-   *telepty will automatically discover active sessions on your local machine and across your Tailscale network!*
+## Core Commands
+
+| Command | Description |
+|---------|-------------|
+| `telepty daemon` | Start the background daemon (port 3848) |
+| `telepty allow --id <name> <cmd>` | Wrap a CLI for inject control |
+| `telepty spawn --id <name> <cmd>` | Spawn a new background session |
+| `telepty list [--json]` | List sessions across all discovered hosts |
+| `telepty attach [id[@host]]` | Attach to a session (interactive picker if no ID) |
+| `telepty inject <id[@host]> "text"` | Inject text into a session |
+| `telepty enter <id[@host]>` | Send Enter/Return to a session |
+| `telepty multicast <id1,id2> "text"` | Inject into multiple sessions |
+| `telepty broadcast "text"` | Inject into ALL sessions |
+| `telepty rename <old> <new>` | Rename a session |
+| `telepty read-screen <id> [--lines N]` | Read session screen buffer |
+| `telepty reply "text"` | Reply to the last injector |
+| `telepty monitor` | Real-time event billboard |
+| `telepty listen` | Stream event bus as JSON |
+| `telepty tui` | Full TUI dashboard |
+| `telepty layout [grid\|tall\|stack]` | Arrange kitty windows |
+| `telepty update` | Update to latest version |
+
+## Cross-Machine Sessions
+
+telepty auto-discovers sessions across your Tailnet. All commands (`list`, `attach`, `inject`, `rename`, `multicast`, `broadcast`) work seamlessly across machines.
+
+When the same session ID exists on multiple hosts, disambiguate with `session_id@host`:
 
-3. **Inject commands remotely:**
-   ```bash
-   telepty inject my-session "echo 'Hello from nowhere!'"
-   ```
+```bash
+telepty inject my-session@macbook "hello"
+telepty attach worker@server-01
+```
 
-4. **Universal CLI submit (split_cr):**
+## How It Works
 
-   All AI CLIs (Claude, Codex, Gemini) submit reliably via the `split_cr` strategy — text is injected first, then `\r` is sent separately after a 300ms delay. This works universally across all CLIs without any per-CLI workarounds.
+```
+CLI (telepty) ──> HTTP/WS ──> Daemon (:3848)
+                                 ├── Session WebSocket (/api/sessions/:id)
+                                 ├── Event Bus WebSocket (/api/bus)
+                                 └── REST API (/api/sessions/*)
+```
 
-   ```bash
-   # The inject API handles split_cr automatically
-   curl -X POST http://127.0.0.1:3848/api/sessions/my-session/inject \
-     -H "Content-Type: application/json" \
-     -d '{"prompt": "your command here"}'
-   ```
+- **`allow`** wraps a CLI process in a PTY bridge, enabling remote inject
+- **`inject`** delivers text via the fastest available path: kitty terminal API, WebSocket, or UDS (Unix Domain Socket for embedded integrations)
+- **`submit`** is handled separately from text injection for reliability across all AI CLIs
 
-CLI commands such as `list`, `attach`, `inject`, `rename`, `multicast`, and `broadcast` now auto-discover sessions across your Tailnet by default. If the same session ID exists on multiple hosts, disambiguate with `session_id@host`.
+## Inject Delivery Paths
 
-## Testing
+| Priority | Method | When |
+|----------|--------|------|
+| 1 | `kitty @ send-text` | Terminal supports kitty protocol |
+| 2 | UDS (Unix Domain Socket) | Embedded IPC sessions (e.g. aterm) |
+| 3 | WebSocket PTY write | Wrapped sessions via allow-bridge |
+
+## AI CLI Integration
 
-Run the full regression suite locally:
+telepty works as a session bridge for AI CLIs. Use `allow` to wrap any CLI:
 
 ```bash
-npm test
+# Claude Code
+telepty allow --id claude-main claude
+
+# Codex
+telepty allow --id codex-main codex
+
+# Gemini CLI
+telepty allow --id gemini-main gemini
 ```
 
-Keep the suite running while you work:
+Then inject prompts, read output, or attach from anywhere:
 
 ```bash
-npm run test:watch
+telepty inject claude-main "refactor the auth module"
+telepty read-screen claude-main --lines 50
+telepty attach claude-main
 ```
 
-The automated suite covers config generation, daemon HTTP APIs, WebSocket attach/output flow, bus events, session deletion regressions, and CLI smoke tests against a real daemon process.
+## Deliberation (Multi-Session Discussion)
 
-If the local daemon ever gets stuck or duplicated, open `telepty` and choose `Repair local daemon`.
+Coordinate structured discussions across multiple AI sessions:
+
+```bash
+telepty deliberate --topic "API design for v2" --sessions claude-1,claude-2,codex-1
+telepty deliberate status
+telepty deliberate end <thread_id>
+```
 
 ## Skill Installation
 
-The package installer opens the telepty skill TUI automatically when you run it in a terminal.
+telepty ships with packaged skills for Claude Code, Codex, and Gemini CLI. Run the interactive installer:
+
+```bash
+telepty
+# Choose "Install telepty skills"
+```
+
+## Testing
+
+```bash
+npm test              # 70 tests (node:test)
+npm run test:watch    # Watch mode
+```
 
-To reopen it later, run `telepty` and choose `Install telepty skills`.
+## License
 
-The TUI lets you choose:
-- which packaged skills to install
-- which target clients to install into (`Claude Code`, `Codex`, `Gemini`)
-- whether each target uses a global path, the current project path, or a custom path
+ISC

package/cli.js

@@ -1819,6 +1819,39 @@ async function main() {
     return;
   }
 
+  if (cmd === 'delete') {
+    const sessionRef = args[1];
+    if (!sessionRef) { console.error('❌ Usage: telepty delete <session-id>'); process.exit(1); }
+    try {
+      const target = await resolveSessionTarget(sessionRef);
+      if (!target) { console.error(`❌ Session '${sessionRef}' not found.`); process.exit(1); }
+      const res = await fetchWithAuth(`http://${target.host}:${PORT}/api/sessions/${encodeURIComponent(target.id)}`, { method: 'DELETE' });
+      const data = await res.json();
+      if (!res.ok) { console.error(`❌ Error: ${data.error}`); return; }
+      console.log(`✅ Session '\x1b[36m${target.id}\x1b[0m' deleted.`);
+    } catch (e) { console.error(`❌ ${e.message || 'Failed to delete session.'}`); }
+    return;
+  }
+
+  if (cmd === 'clean') {
+    try {
+      const sessions = await discoverSessions({ silent: true });
+      if (sessions.length === 0) { console.log('No sessions found.'); return; }
+      let cleaned = 0;
+      for (const s of sessions) {
+        if (s.healthStatus === 'STALE' || s.healthStatus === 'DISCONNECTED') {
+          try {
+            const host = s.host || '127.0.0.1';
+            const res = await fetchWithAuth(`http://${host}:${PORT}/api/sessions/${encodeURIComponent(s.id)}`, { method: 'DELETE' });
+            if (res.ok) { console.log(`  🗑  Removed ghost: \x1b[36m${s.id}\x1b[0m (${s.healthStatus})`); cleaned++; }
+          } catch (_) {}
+        }
+      }
+      console.log(cleaned > 0 ? `✅ Cleaned ${cleaned} ghost session(s).` : '✅ No ghost sessions found.');
+    } catch (e) { console.error(`❌ ${e.message || 'Failed to clean sessions.'}`); }
+    return;
+  }
+
   if (cmd === 'rename') {
     const oldId = args[1]; const newId = args[2];
     if (!oldId || !newId) { console.error('❌ Usage: telepty rename <old_id> <new_id>'); process.exit(1); }
@@ -2711,43 +2744,66 @@ Discuss the following topic from your project's perspective. Engage with other s
   }
 
   console.log(`
-\x1b[1maigentry-telepty\x1b[0m - Remote PTY Control
-
-Usage:
-  telepty daemon                                 Start the background daemon
-  telepty spawn --id <id> <command> [args...]    Spawn a new background CLI
-  telepty allow [--id <id>] [--auto-restart] <command> [args...]  Allow inject on a CLI (auto-restart on crash)
-  telepty list [--json]                          List all active sessions across discovered hosts
-  telepty attach [id[@host]]                     Attach to a session (Interactive picker if no ID)
-  telepty inject [--ref [file]] [--from <id>] [--reply-to <id>] <id[@host]> "<prompt>"    Inject text into a single session
-  telepty enter <id[@host]>                      Send only Enter/Return to a single session
-  telepty read-screen <id[@host]> [--lines N] [--raw]                  Read session screen buffer
-  telepty reply "<text>"                         Reply to the session that last injected into $TELEPTY_SESSION_ID
-  telepty status-report [--id <id>] --phase <phase> [--task <text>] [--blocker <text>] [--needs-input] [--thread-id <id>] [--seq N]
-  telepty multicast <id1[@host],id2[@host]> "<prompt>"  Inject text into multiple specific sessions
-  telepty broadcast [--ref [file]] "<prompt>"    Inject text into ALL active sessions
-  telepty rename <old_id[@host]> <new_id>        Rename a session (updates terminal title too)
-  telepty session info <id[@host]> [--json]      Show detailed session metadata
-  telepty connect <user@host> [--name N] [--port P]  Connect to a remote machine via SSH tunnel
-  telepty disconnect <name> | --all              Disconnect from a remote machine
-  telepty peers [--remove <name>]                List connected and known peers
-  telepty listen                                 Listen to the event bus and print JSON to stdout
-  telepty monitor                                Human-readable real-time billboard of bus events
-  telepty update                                 Update telepty to the latest version
-  telepty layout [grid|tall|stack]               Arrange kitty windows on screen (default: grid)
-
-  Handoff Commands:
-    handoff list [--status=S]        List handoffs (filter: pending/claimed/executing/completed)
-    handoff drop [options]           Create handoff from synthesis (pipe JSON or use --summary/--tasks)
-    handoff claim <id> [--agent=S]   Claim a pending handoff
-    handoff status <id> [status]     Get or update handoff status
-    handoff get <id>                 Get full synthesis JSON (for piping)
-
-  Deliberation Commands:
-    deliberate --topic "..." [--sessions s1,s2] [--context file]
-                                       Start multi-session deliberation
-    deliberate status [thread_id]      List threads or show thread details
-    deliberate end <thread_id>         Close a deliberation thread
+\x1b[1mtelepty\x1b[0m — Connect any terminal to any terminal, any machine.
+
+\x1b[1mSession Management:\x1b[0m
+  telepty daemon                                 Start the background daemon (port 3848)
+  telepty spawn --id <id> <command> [args...]    Spawn a new background session
+  telepty allow [--id <id>] [--auto-restart] <command> [args...]  Wrap a CLI for remote control
+  telepty list [--json]                          List sessions (local + Tailnet)
+  telepty attach [id[@host]]                     Attach interactively (picker if no ID)
+  telepty rename <old_id[@host]> <new_id>        Rename a session
+  telepty session info <id[@host]> [--json]      Show session metadata
+
+\x1b[1mInject & Communicate:\x1b[0m
+  telepty inject [--ref [file]] [--from <id>] <id[@host]> "<prompt>"  Inject text
+  telepty enter <id[@host]>                      Send Enter/Return
+  telepty reply "<text>"                         Reply to last injector
+  telepty multicast <id1,id2> "<prompt>"         Inject into multiple sessions
+  telepty broadcast [--ref [file]] "<prompt>"    Inject into ALL sessions
+  telepty read-screen <id[@host]> [--lines N]    Read session screen buffer
+
+\x1b[1mCross-Machine:\x1b[0m
+  telepty connect <user@host> [--name N] [--port P]  SSH tunnel to remote host
+  telepty disconnect <name> | --all              Disconnect remote host
+  telepty peers [--remove <name>]                List connected peers
+
+\x1b[1mMonitoring:\x1b[0m
+  telepty tui                                    Full TUI dashboard
+  telepty monitor                                Real-time event billboard
+  telepty listen                                 Stream event bus as JSON
+
+\x1b[1mHandoff:\x1b[0m
+  telepty handoff list [--status=S]              List handoffs
+  telepty handoff drop [options]                 Create handoff from synthesis
+  telepty handoff claim <id> [--agent=S]         Claim a pending handoff
+  telepty handoff status <id> [status]           Get/update handoff status
+
+\x1b[1mDeliberation:\x1b[0m
+  telepty deliberate --topic "..." [--sessions s1,s2]  Start multi-session discussion
+  telepty deliberate status [thread_id]          Show thread details
+  telepty deliberate end <thread_id>             Close a thread
+
+\x1b[1mOther:\x1b[0m
+  telepty update                                 Update to latest version
+  telepty layout [grid|tall|stack]               Arrange terminal windows
+  telepty status-report --phase <p> [options]    Emit structured status event
+
+\x1b[1mExamples:\x1b[0m
+  \x1b[2m# Wrap Claude Code for remote control\x1b[0m
+  telepty allow --id my-claude claude
+
+  \x1b[2m# Send a prompt to a session\x1b[0m
+  telepty inject my-claude "explain the auth module"
+
+  \x1b[2m# Read what a session is showing\x1b[0m
+  telepty read-screen my-claude --lines 30
+
+  \x1b[2m# Broadcast to all sessions\x1b[0m
+  telepty broadcast "status report please"
+
+  \x1b[2m# Inject into a session on another machine\x1b[0m
+  telepty inject my-claude@server-01 "run the tests"
 `);
 }
 

package/daemon.js

@@ -1478,18 +1478,20 @@ app.delete('/api/sessions/:id', (req, res) => {
   try {
     session.isClosing = true;
     if (session.type === 'wrapped') {
-      session.clients.forEach(ws => ws.close(1000, 'Session destroyed'));
-      delete sessions[id];
-      console.log(`[KILL] Wrapped session ${id} removed`);
-      persistSessions();
-    } else {
+      if (session.clients) session.clients.forEach(ws => ws.close(1000, 'Session destroyed'));
+    } else if (session.ptyProcess) {
       session.ptyProcess.kill();
-      console.log(`[KILL] Session ${id} forcefully closed`);
-      persistSessions();
     }
+    delete sessions[id];
+    console.log(`[KILL] Session ${id} removed`);
+    persistSessions();
     res.json({ success: true, status: 'closing' });
   } catch (err) {
-    res.status(500).json({ error: err.message });
+    // Even if kill fails, remove from registry
+    delete sessions[id];
+    persistSessions();
+    console.log(`[KILL] Session ${id} force-removed (process cleanup error: ${err.message})`);
+    res.json({ success: true, status: 'force-removed' });
   }
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dmsdc-ai/aigentry-telepty",
-  "version": "0.1.80",
+  "version": "0.1.82",
   "main": "daemon.js",
   "bin": {
     "aigentry-telepty": "install.js",
@@ -12,10 +12,31 @@
     "test:watch": "node --test --watch test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js",
     "test:ci": "node --test --test-reporter=spec test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js"
   },
-  "keywords": [],
-  "author": "",
+  "keywords": [
+    "pty",
+    "terminal",
+    "session",
+    "multiplexer",
+    "remote",
+    "inject",
+    "ai-cli",
+    "claude",
+    "codex",
+    "gemini",
+    "cross-machine",
+    "tailscale"
+  ],
+  "author": "dmsdc-ai",
   "license": "ISC",
-  "description": "",
+  "description": "Universal terminal session bridge — connect any terminal to any terminal, any machine",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dmsdc-ai/aigentry-telepty.git"
+  },
+  "homepage": "https://github.com/dmsdc-ai/aigentry-telepty#readme",
+  "bugs": {
+    "url": "https://github.com/dmsdc-ai/aigentry-telepty/issues"
+  },
   "dependencies": {
     "blessed": "^0.1.81",
     "cors": "^2.8.6",