@dmsdc-ai/aigentry-telepty 0.1.96 → 0.1.98

package/skills/telepty/SKILL.md

@@ -1,140 +1,61 @@
 ---
 name: telepty
-description: Use telepty primarily through LLM CLI prompts and natural-language requests, with raw telepty commands as a secondary path for execution, repair, and session management.
+description: Overview of telepty — PTY multiplexer for AI session orchestration. Use this when user asks "what is telepty" or needs a getting-started guide.
 ---
 
-# telepty
+# telepty — Overview
 
-Use this skill when the user wants help operating `telepty`, recovering a broken local daemon, or managing telepty sessions through an LLM CLI prompt.
+telepty is a PTY multiplexer and session orchestrator. It creates, connects, and controls multiple AI CLI sessions (Claude, Gemini, Codex) from a single terminal.
 
-`telepty` is primarily a prompt-driven tool inside LLM CLIs. Raw `telepty ...` commands are the execution layer, not the primary user surface.
-
-## Default approach
-
-- For interactive human guidance, prefer LLM CLI prompt examples first, then the `telepty` TUI, and only then raw commands.
-- When explaining telepty usage to a user, always lead with a skill-style or natural-language example first.
-- Only show raw CLI commands after the skill-style example, as the secondary option.
-- For agent execution inside a CLI session, run the underlying `telepty` command directly.
-- When the request is about a broken or duplicated local daemon, repair the daemon before doing session work.
-
-## User-facing response order
-
-When the user asks how to do something with telepty, respond in this order:
-
-1. Show a plain-language or skill-style example first.
-2. Then show the matching CLI command.
-3. Keep maintenance commands behind the user-facing flow unless the user is clearly operating as a CLI power user.
-
-Example:
-
-- Skill-style example: "telepty에서 해당 세션에 붙어줘" 또는 "telepty에서 로컬 데몬 복구해줘"
-- CLI follow-up: `telepty attach <session_id>` 또는 `telepty cleanup-daemons`
-
-## Common actions
-
-1. Check whether the current shell is already inside a telepty session:
-
-```bash
-echo "$TELEPTY_SESSION_ID"
-```
-
-2. Inspect active sessions:
-
-```bash
-telepty list
-```
-
-3. Attach to a room:
-
-```bash
-telepty attach <session_id>
-```
-
-4. Inject a command or prompt:
+## Quick Start
 
 ```bash
-telepty inject <session_id> "<prompt text>"
-```
-
-When the same session ID exists on multiple hosts, use `session_id@host`.
-
-**Return address rule**: If you expect a reply from the target session, you MUST include your own session ID in the inject message so the recipient knows where to send the response:
-
-```bash
-telepty inject <target_session_id> "your message here. 응답은 telepty inject <your_session_id> 로 보내줘."
-```
-
-Your session ID is available via `echo $TELEPTY_SESSION_ID`.
-
-**Reliable inject pattern (2-step)**: Some CLIs (e.g. codex) do not submit on `\r` alone. For reliable delivery, use the REST API in two steps:
-
-```bash
-TOKEN=$(cat ~/.telepty/config.json | grep authToken | cut -d '"' -f 4)
-# Step 1: send content without enter
-curl -s -X POST "http://127.0.0.1:3848/api/sessions/<target_id>/inject" \
-  -H "Content-Type: application/json" -H "x-telepty-token: $TOKEN" \
-  -d '{"prompt": "<content>", "no_enter": true}'
-# Step 2: send enter separately
-curl -s -X POST "http://127.0.0.1:3848/api/sessions/<target_id>/inject" \
-  -H "Content-Type: application/json" -H "x-telepty-token: $TOKEN" \
-  -d '{"prompt": "\n"}'
-```
-
-5. Allow inject on a local CLI:
-
-```bash
-telepty allow --id <session_id> <command> [args...]
-```
+# Start daemon
+telepty daemon
 
-6. Rename a room:
+# Create a session wrapping Claude Code
+telepty allow --id my-session claude
 
-```bash
-telepty rename <old_id> <new_id>
-```
-
-7. Listen to the event bus:
+# Send a message to the session
+telepty inject my-session "analyze the auth module"
 
-```bash
-telepty listen
-```
+# List all sessions
+telepty list
 
-8. Update telepty:
+# Attach to a session interactively
+telepty attach my-session
 
-```bash
-telepty update
+# Open TUI dashboard
+telepty tui
 ```
 
-## Local daemon recovery
-
-When the user reports any of these symptoms, repair the local daemon first:
+## Core Concepts
 
-- `Failed to connect to local daemon`
-- local sessions do not appear but remote sessions do
-- duplicate or stale daemon processes
-- install/update completed but `spawn` or `allow` still fails locally
+- **Session**: A PTY-wrapped CLI process managed by telepty (spawned or wrapped via `allow`)
+- **Daemon**: Background HTTP/WS server on port 3848 managing all sessions
+- **Inject**: Send text to a session's PTY input
+- **Allow-bridge**: Wraps an existing CLI for remote control via telepty
 
-### Human-facing path
+## Environment
 
-Tell the user to run `telepty` and choose `Repair local daemon`.
+- `TELEPTY_SESSION_ID` — set inside telepty-managed sessions; use to identify yourself
+- `TELEPTY_AVAILABLE=true` — set when running inside a telepty allow session
 
-### Agent execution path
+## Default Approach
 
-Use the maintenance command directly:
+- For humans: prefer natural-language examples and TUI, then raw CLI commands
+- For AI agents: use raw `telepty` commands directly for execution
+- When daemon is broken: repair first with `telepty cleanup-daemons && telepty daemon`
 
-```bash
-telepty cleanup-daemons
-telepty daemon
-```
-
-If the daemon still does not come up, rerun the installer.
-
-## Notes
-
-- `TELEPTY_SESSION_ID` is only set inside telepty-managed sessions.
-- For non-interactive `telepty allow` use cases, set terminal dimensions if the environment does not provide them:
-
-```bash
-COLUMNS=120 LINES=40 telepty allow --id <session_id> <command>
-```
+## Related Skills
 
-- For interactive users, keep explanations centered on TUI actions instead of raw maintenance commands whenever possible.
+Each telepty feature has its own detailed skill:
+- `telepty-inject` — send messages to sessions
+- `telepty-allow` — create and manage sessions
+- `telepty-list` — discover sessions and check status
+- `telepty-attach` — attach interactively to a session
+- `telepty-broadcast` — send to multiple sessions
+- `telepty-daemon` — daemon management, repair, update
+- `telepty-rename` — rename, delete, clean sessions
+- `telepty-listen` — monitor events and read screen
+- `telepty-session` — multi-session start and layout

package/skills/telepty-allow/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: telepty-allow
+description: Create telepty sessions by wrapping CLI processes. Covers the allow/enable/wrap command for session creation and PTY management.
+---
+
+# telepty-allow — Create and Manage Sessions
+
+## allow — Wrap a CLI for remote control
+
+```bash
+telepty allow --id <session_id> <command> [args...]
+```
+
+Natural-language: "세션 만들어줘", "create a new Claude session", "wrap this CLI"
+
+Wraps a CLI process (Claude, Gemini, Codex, or any command) so telepty can inject messages, monitor output, and manage it remotely.
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--id <name>` | Session identifier (required) |
+| `--auto-restart` | Automatically restart if the CLI crashes (up to 3 times) |
+
+### Examples
+
+```bash
+# Wrap Claude Code
+telepty allow --id my-claude claude
+
+# Wrap Gemini CLI
+telepty allow --id my-gemini gemini
+
+# Wrap Codex with auto-restart
+telepty allow --id my-codex --auto-restart codex
+
+# Wrap any command
+telepty allow --id my-shell bash
+
+# Non-interactive (headless) — set terminal dimensions
+COLUMNS=120 LINES=40 telepty allow --id headless-session claude
+```
+
+### What happens
+
+1. Daemon auto-starts if not running
+2. Session registers with daemon via WebSocket
+3. Child process spawns in a PTY (preserves isTTY, env, shell config)
+4. Allow-bridge relays: daemon WS inject → child PTY write
+5. Output streams back to daemon for monitoring
+6. Prompt-ready detection gates inject delivery (safe idle-aware injection)
+
+### Environment inside the session
+
+| Variable | Value |
+|----------|-------|
+| `TELEPTY_SESSION_ID` | The session ID you specified |
+| `TELEPTY_AVAILABLE` | `true` |
+
+### Aliases
+
+`telepty enable` and `telepty wrap` are aliases for `telepty allow`.
+
+## spawn — Create a daemon-managed PTY session
+
+```bash
+telepty spawn --id <session_id> --command <cmd>
+```
+
+Creates a session managed entirely by the daemon (no allow-bridge). Useful for background processes.
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Failed to start daemon` | Port 3848 in use or permission issue | `telepty cleanup-daemons` then retry |
+| `Session ID already active` | Duplicate ID | Use a different ID or delete the existing session |
+| `Terminal input interrupted` | PTY EIO error | Session auto-recovers; restart if persistent |

package/skills/telepty-attach/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: telepty-attach
+description: Attach interactively to a telepty session to view output and send input in real-time.
+---
+
+# telepty-attach — Interactive Session Attachment
+
+## attach — Connect to a session
+
+```bash
+telepty attach <session_id>
+```
+
+Natural-language: "세션에 붙어줘", "attach to my claude session", "show me what's happening in that session"
+
+Opens an interactive terminal connection to a running session. You see its output in real-time and can type input directly.
+
+### Behavior
+
+- Multiple viewers can attach to the same session simultaneously
+- The session owner (allow-bridge) receives your input as inject
+- Output is relayed from the session to all attached clients
+- Press `Ctrl+C` to detach (session continues running)
+
+### Examples
+
+```bash
+# Attach to a local session
+telepty attach my-claude
+
+# Attach to a remote session
+telepty attach analyst-claude@remote-host
+
+# Interactive selection (from TUI)
+telepty tui
+# Then select a session and press Enter
+```
+
+### Cross-host attach
+
+When the session is on a remote host:
+
+```bash
+telepty attach session_id@user@hostname
+```
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Session not found` | Session ID doesn't exist | Check `telepty list` |
+| `Connection closed` | Session ended or daemon restarted | Re-attach after daemon recovers |

package/skills/telepty-broadcast/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: telepty-broadcast
+description: Send messages to multiple telepty sessions at once. Covers broadcast (all sessions) and multicast (selected targets).
+---
+
+# telepty-broadcast — Multi-Target Messaging
+
+## broadcast — Send to ALL sessions
+
+```bash
+telepty broadcast "<message>"
+telepty broadcast --ref "<message>"
+```
+
+Natural-language: "모든 세션에 보내줘", "broadcast to all sessions", "tell everyone to stop"
+
+Sends a message to every active local session simultaneously.
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--from <id>` | Set sender session ID |
+| `--ref` | Store payload in shared file (one file reused for all sessions) |
+| `--ref <file>` | Store file contents in shared reference |
+
+### Examples
+
+```bash
+# Broadcast a message to all sessions
+telepty broadcast "context window 높아지면 /compact 실행해"
+
+# Broadcast with shared reference (efficient for large payloads)
+telepty broadcast --ref "review the updated spec at the shared path"
+
+# Broadcast file contents
+telepty broadcast --ref ./updated-spec.md "review this updated spec"
+```
+
+## multicast — Send to selected sessions
+
+```bash
+telepty multicast --targets <id1>,<id2>,... "<message>"
+```
+
+Natural-language: "이 세션들에만 보내줘", "send to analyst and brain only"
+
+### Examples
+
+```bash
+# Send to specific sessions
+telepty multicast --targets analyst-claude,brain-claude "coordinate on the auth refactor"
+
+# With return address
+telepty multicast --targets analyst-claude,brain-claude "report status" --from orchestrator-claude
+```
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `No active sessions` | No sessions running | Start sessions first |
+| `Partial failure` | Some targets unreachable | Check individual session status |

package/skills/telepty-daemon/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: telepty-daemon
+description: Manage the telepty daemon — start, stop, repair, update, and TUI dashboard. Use when daemon is broken or needs maintenance.
+---
+
+# telepty-daemon — Daemon Management
+
+## daemon — Start the daemon
+
+```bash
+telepty daemon
+```
+
+Starts the telepty daemon on port 3848. The daemon manages all sessions, handles inject delivery, and serves the HTTP/WS API.
+
+The daemon auto-starts when needed (e.g., `telepty allow` starts it automatically). Manual start is rarely needed.
+
+## cleanup-daemons — Kill stale daemon processes
+
+```bash
+telepty cleanup-daemons
+```
+
+Natural-language: "데몬 복구해줘", "fix the broken daemon", "kill stale daemons"
+
+Finds and kills ALL telepty daemon processes (by PID file and process scan), then clears the state file. Use this when:
+- `Failed to connect to local daemon` errors
+- Duplicate daemon processes running
+- Version mismatch after update
+- Port 3848 already in use
+
+### Full recovery sequence
+
+```bash
+telepty cleanup-daemons
+telepty daemon
+```
+
+## tui — Interactive dashboard
+
+```bash
+telepty tui
+```
+
+Natural-language: "대시보드 열어줘", "show the TUI", "open dashboard"
+
+Opens a blessed-based TUI with session list, health status, and quick actions:
+- `s` — start a new session
+- `k` — kill selected session
+- `p` — purge stale sessions
+- `Enter` — attach to selected session
+
+## update — Self-update telepty
+
+```bash
+telepty update
+```
+
+Runs `npm install -g @dmsdc-ai/aigentry-telepty@latest` and restarts the daemon with the new version.
+
+## delete — Remove a session
+
+```bash
+telepty delete <session_id>
+```
+
+Forcefully removes a session from the daemon registry and kills its PTY process.
+
+## clean — Remove ghost sessions
+
+```bash
+telepty clean
+```
+
+Finds and removes sessions with `STALE` or `DISCONNECTED` health status.
+
+## API Health Check
+
+```bash
+curl http://127.0.0.1:3848/api/health
+# → {"status":"ok","version":"0.1.96"}
+
+curl http://127.0.0.1:3848/api/meta
+# → {"name":"...","version":"...","capabilities":[...],"pid":...}
+```
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Port 3848 already in use` | Another daemon or process on port | `telepty cleanup-daemons` |
+| `Daemon version mismatch` | Old daemon after npm update | Auto-restarts; if stuck: `telepty cleanup-daemons && telepty daemon` |
+| `ECONNREFUSED` | Daemon not running | `telepty daemon` |
+| `Singleton lock held` | Another daemon owns the lock | `telepty cleanup-daemons` |

package/skills/telepty-inject/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: telepty-inject
+description: Send messages, commands, and keystrokes to telepty sessions. Covers inject, enter, send-key, and reply commands.
+---
+
+# telepty-inject — Send Messages to Sessions
+
+## inject — Send text to a session
+
+```bash
+telepty inject <session_id> "<prompt text>"
+```
+
+Natural-language: "이 세션에 메시지 보내줘", "send this to the analyst session"
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--from <id>` | Set sender session ID (auto-set inside telepty sessions via `$TELEPTY_SESSION_ID`) |
+| `--reply-to <id>` | Set reply-to address (defaults to `--from`) |
+| `--submit` | Use terminal-level Enter (osascript/cmux) instead of PTY CR |
+| `--ref` | Store payload in shared file, inject only a pointer prompt |
+| `--ref <file>` | Store file contents + message in shared file |
+| `--reply-expected` | Mark that you expect a reply from the target |
+
+### Examples
+
+```bash
+# Basic inject
+telepty inject my-claude "analyze the auth module"
+
+# With return address (so target knows where to reply)
+telepty inject analyst-claude "review this PR. 응답은 telepty inject orchestrator-claude 로 보내줘." --from orchestrator-claude
+
+# Large payload via shared reference file
+telepty inject brain-claude --ref "analyze this codebase for security issues"
+
+# Inject file contents
+telepty inject analyst-claude --ref ./report.md "summarize this report"
+
+# Inject with terminal-level submit (for CLIs that need it)
+telepty inject codex-session "fix the build" --submit
+```
+
+### Return Address Rule
+
+If you expect a reply, ALWAYS include `--from` so the target knows where to respond:
+
+```bash
+telepty inject <target> "your message" --from $(echo $TELEPTY_SESSION_ID)
+```
+
+### Cross-host inject
+
+When the same session ID exists on multiple hosts:
+
+```bash
+telepty inject session_id@remote-host "message"
+```
+
+## enter — Send Enter keystroke only
+
+```bash
+telepty enter <session_id>
+```
+
+Sends a bare Enter to the session. Useful when text was injected with `no_enter` and you need to submit separately.
+
+## send-key — Send terminal-level keystroke
+
+```bash
+telepty send-key <session_id> [key]
+```
+
+Sends a terminal-level keystroke (default: Enter) via osascript or cmux backend. Bypasses PTY entirely.
+
+## reply — Reply to the last inject sender
+
+```bash
+telepty reply "<message>"
+```
+
+Automatically targets the session that last injected into yours (uses stored `lastInjectFrom`).
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Session not found` | Target session doesn't exist | Check `telepty list` |
+| `Session owner is disconnected` | allow-bridge not running | Restart the target session |
+| `STALE` | Session idle too long | Restart or clean: `telepty clean` |
+| `DELIVERY_REJECTED` | Target rejected the payload | Check target session logs |

package/skills/telepty-list/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: telepty-list
+description: Discover telepty sessions, check status and health. Covers list, session info, and status commands.
+---
+
+# telepty-list — Discover Sessions and Check Status
+
+## list — Show all active sessions
+
+```bash
+telepty list
+telepty list --json
+```
+
+Natural-language: "세션 목록 보여줘", "what sessions are running", "show active sessions"
+
+### Output fields
+
+| Field | Description |
+|-------|-------------|
+| ID | Session identifier |
+| Host | `Local` or remote hostname |
+| Command | The wrapped CLI command |
+| Status | `CONNECTED`, `DISCONNECTED`, `STALE` |
+| Terminal | `ghostty`, `kitty`, `aterm`, `daemon-pty` |
+| Clients | Number of attached viewers |
+| CWD | Working directory |
+
+### Examples
+
+```bash
+# Human-readable list
+telepty list
+
+# JSON output (for scripting)
+telepty list --json
+
+# Pipe to jq for filtering
+telepty list --json | jq '.[] | select(.healthStatus == "CONNECTED")'
+```
+
+## session info — Detailed session information
+
+```bash
+telepty session info <session_id>
+```
+
+Shows detailed metadata including terminal type, delivery endpoint, semantic state, and transport info.
+
+## status — Quick health check
+
+```bash
+telepty status <session_id>
+```
+
+Returns session health status: `CONNECTED`, `DISCONNECTED`, or `STALE` with reason codes.
+
+### Health Status Reference
+
+| Status | Reason | Meaning |
+|--------|--------|---------|
+| `CONNECTED` | `OWNER_CONNECTED` | Allow-bridge active |
+| `CONNECTED` | `DELIVERY_ENDPOINT_AVAILABLE` | aterm UDS socket reachable |
+| `CONNECTED` | `PTY_RUNNING` | Daemon-managed PTY alive |
+| `DISCONNECTED` | `OWNER_DISCONNECTED` | Allow-bridge lost connection |
+| `STALE` | `OWNER_DISCONNECTED_STALE` | Disconnected > 60s |
+
+## status-report — Publish semantic self-report
+
+```bash
+telepty status-report --phase <phase> [--task "<task>"] [--blocker "<blocker>"]
+```
+
+Publishes a semantic state report for the current session to the event bus.
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `No active sessions found` | Daemon not running or no sessions | Start daemon: `telepty daemon` |
+| `Failed to discover sessions` | Network/daemon issue | Check `telepty cleanup-daemons` |