@dmsdc-ai/aigentry-telepty 0.1.79 → 0.1.81

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

@@ -2711,43 +2711,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

@@ -13,6 +13,7 @@ const terminalBackend = require('./terminal-backend');
 const config = getConfig();
 const EXPECTED_TOKEN = config.authToken;
 const MACHINE_ID = process.env.TELEPTY_MACHINE_ID || os.hostname();
+const net = require('net');
 const fs = require('fs');
 const SESSION_PERSIST_PATH = require('path').join(os.homedir(), '.config', 'aigentry-telepty', 'sessions.json');
 const SESSION_STALE_SECONDS = Math.max(1, Number(process.env.TELEPTY_SESSION_STALE_SECONDS || 60));
@@ -34,6 +35,8 @@ function persistSessions() {
         cmuxSurfaceId: s.cmuxSurfaceId || null,
         termProgram: s.termProgram || null,
         term: s.term || null,
+        delivery: s.delivery || null,
+        deliveryEndpoint: s.deliveryEndpoint || null,
         createdAt: s.createdAt,
         lastActivityAt: s.lastActivityAt || null,
         lastConnectedAt: s.lastConnectedAt || null,
@@ -219,7 +222,7 @@ function getSessionHealthStatus(session, options = {}) {
   }
 
   if (session.type === 'aterm') {
-    if (session.deliveryEndpoint) {
+    if (session.deliveryEndpoint || (session.delivery && session.delivery.address)) {
       return 'CONNECTED';
     }
     if (disconnectedMs !== null && disconnectedMs >= staleMs) {
@@ -426,6 +429,33 @@ function emitInjectFailureEvent(sessionId, code, error, extra = {}, session = nu
 
 async function writeDataToSession(id, session, data) {
   if (session.type === 'aterm') {
+    // UDS delivery via net.connect()
+    if (session.delivery && session.delivery.transport === 'unix_socket' && session.delivery.address) {
+      return new Promise((resolve) => {
+        const payload = JSON.stringify({ text: data, session_id: id }) + '\n';
+        const timeout = setTimeout(() => {
+          sock.destroy();
+          resolve(buildErrorBody('TIMEOUT', 'UDS delivery timed out.', { httpStatus: 504 }));
+        }, DELIVERY_TIMEOUT_MS);
+        const sock = net.connect(session.delivery.address, () => {
+          sock.end(payload);
+        });
+        sock.on('data', () => {}); // drain
+        sock.on('end', () => {
+          clearTimeout(timeout);
+          resolve({ success: true });
+        });
+        sock.on('error', (err) => {
+          clearTimeout(timeout);
+          resolve(buildErrorBody('DISCONNECTED', 'UDS endpoint is unreachable.', {
+            httpStatus: 503,
+            detail: err.message
+          }));
+        });
+      });
+    }
+
+    // HTTP delivery (backward compat)
     if (!session.deliveryEndpoint) {
       return buildErrorBody('DISCONNECTED', 'Delivery endpoint is missing.', { httpStatus: 503 });
     }
@@ -504,7 +534,7 @@ async function deliverInjectionToSession(id, session, prompt, options = {}) {
     strategy: session.type === 'wrapped'
       ? 'ws_split_cr'
       : session.type === 'aterm'
-        ? 'aterm_endpoint'
+        ? (session.delivery && session.delivery.transport === 'unix_socket' ? 'aterm_uds' : 'aterm_endpoint')
         : 'pty_split_cr',
     submit: options.noEnter ? 'skipped' : 'deferred'
   };
@@ -568,6 +598,7 @@ function serializeSession(id, session, options = {}) {
     idleSeconds,
     active_clients: session.clients ? session.clients.size : 0,
     ready: session.ready || false,
+    delivery: session.delivery || null,
     deliveryEndpoint: session.deliveryEndpoint || null,
     healthStatus,
     healthReason,
@@ -787,6 +818,12 @@ app.post('/api/sessions/register', (req, res) => {
     if (Object.prototype.hasOwnProperty.call(req.body, 'term')) existing.term = term || null;
     if (req.body.delivery_type) existing.type = req.body.delivery_type;
     if (req.body.delivery_endpoint) existing.deliveryEndpoint = req.body.delivery_endpoint;
+    if (req.body.delivery) {
+      existing.delivery = req.body.delivery;
+      if (!existing.deliveryEndpoint && req.body.delivery.address) {
+        existing.deliveryEndpoint = req.body.delivery.address;
+      }
+    }
     if (req.body.delivery_type === 'aterm') {
       existing.ready = true;
       markSessionConnected(existing);
@@ -795,7 +832,8 @@ app.post('/api/sessions/register', (req, res) => {
     return res.status(200).json({ session_id, type: existing.type, command: existing.command, cwd: existing.cwd, reregistered: true });
   }
 
-  const { delivery_type, delivery_endpoint } = req.body;
+  const { delivery_type, delivery_endpoint, delivery } = req.body;
+  const resolvedEndpoint = delivery_endpoint || (delivery && delivery.address) || null;
   const sessionRecord = {
     id: session_id,
     type: delivery_type || 'wrapped',
@@ -808,7 +846,8 @@ app.post('/api/sessions/register', (req, res) => {
     cmuxSurfaceId: cmux_surface_id || null,
     termProgram: term_program || null,
     term: term || null,
-    deliveryEndpoint: delivery_endpoint || null,
+    delivery: delivery || null,
+    deliveryEndpoint: resolvedEndpoint,
     createdAt: new Date().toISOString(),
     lastActivityAt: new Date().toISOString(),
     lastConnectedAt: delivery_type === 'aterm' ? new Date().toISOString() : null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dmsdc-ai/aigentry-telepty",
-  "version": "0.1.79",
+  "version": "0.1.81",
   "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",