@dmsdc-ai/aigentry-telepty 0.3.5 → 0.4.0

package/session-state.js

@@ -203,6 +203,9 @@ class SessionStateMachine {
 
     // Strip ANSI and split into lines for pattern analysis
     const cleaned = stripAnsi(data);
+    if (cleaned.trim().length === 0) {
+      return;
+    }
     const lines = cleaned.split(/\r?\n/).filter(l => l.trim().length > 0);
 
     for (const line of lines) {
@@ -269,6 +272,16 @@ class SessionStateMachine {
     this._transition(STATES.RESTARTING, 1.0, { trigger: 'lifecycle' });
   }
 
+  markIdle(confidence = 1.0, detail = {}) {
+    if (this._state === STATES.DEAD || this._state === STATES.RESTARTING) {
+      return;
+    }
+    this._transition(STATES.IDLE, confidence, {
+      trigger: 'manual_idle',
+      ...detail,
+    });
+  }
+
   // --- Internal ---
 
   _transition(newState, confidence, detail) {
@@ -538,6 +551,16 @@ class SessionStateManager {
     if (sm) sm.markRestarting();
   }
 
+  /**
+   * Mark a session as idle from a semantic daemon event.
+   */
+  markIdle(sessionId, confidence = 1.0, detail = {}) {
+    const sm = this._machines.get(sessionId);
+    if (!sm) return false;
+    sm.markIdle(confidence, detail);
+    return true;
+  }
+
   /**
    * Unregister and cleanup a session's state machine.
    */

package/src/prompt-symbol-registry.js

@@ -94,4 +94,46 @@ function lookup(command) {
   return null;
 }
 
-module.exports = { lookup, ENTRIES };
+function commandKey(command) {
+  const entry = lookup(command);
+  if (!entry) return null;
+  for (const [key, value] of Object.entries(ENTRIES)) {
+    if (value === entry) return key;
+  }
+  return null;
+}
+
+function isKnownAiCli(command) {
+  return !!lookup(command);
+}
+
+const ANSI_RE = /\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b\][^\x07]*(?:\x07|\x1b\\)|\x1b[()][AB012]|\x1b[>=<78DMEHcNOZ~}|]/g;
+
+function stripAnsi(value) {
+  return String(value == null ? '' : value).replace(ANSI_RE, '');
+}
+
+function normalizeOutputForDetection(output) {
+  return stripAnsi(output)
+    .replace(/\r\n/g, '\n')
+    .replace(/\r/g, '\n')
+    .replace(/\n{2,}/g, '\n');
+}
+
+function detectOutput(command, output) {
+  const entry = lookup(command);
+  if (!entry) {
+    return { found: false, reason: 'unknown_cli' };
+  }
+  const screenLike = normalizeOutputForDetection(output);
+  return entry.detect(screenLike);
+}
+
+module.exports = {
+  lookup,
+  commandKey,
+  isKnownAiCli,
+  detectOutput,
+  normalizeOutputForDetection,
+  ENTRIES,
+};

package/.claude/commands/telepty-allow.md

@@ -1,58 +0,0 @@
-# telepty-allow
-
-Allow inject on an LLM CLI (or any command) via telepty.
-
-## Instructions
-
-### Usage
-```bash
-telepty allow [--id <session_id>] -- <command> [args...]
-```
-
-### Examples
-```bash
-# Claude Code with custom session ID
-telepty allow --id my-claude -- claude
-
-# Codex with auto-generated ID
-telepty allow -- codex
-
-# Gemini with custom ID
-telepty allow --id gemini-main -- gemini
-
-# Any shell command
-telepty allow --id dev-shell -- bash
-```
-
-### What it does
-1. Registers the session with the telepty daemon
-2. Spawns the command locally via `node-pty` (preserves isTTY, raw mode, colors)
-3. Connects to daemon as WebSocket owner for inject reception
-4. Sets `TELEPTY_SESSION_ID` env var inside the process
-
-### Key behaviors
-- **isTTY preserved**: TUI apps (claude, codex, gemini) work normally
-- **Daemon fault-tolerant**: if daemon dies, the CLI keeps running (inject unavailable until reconnect)
-- **Session auto-cleanup**: when the command exits, session is deregistered
-
-### After allowing, from another terminal:
-```bash
-# List sessions
-telepty list
-
-# Inject into the session
-telepty inject <session_id> "your prompt here"
-
-# Attach to watch output
-telepty attach <session_id>
-```
-
-## Execute
-If the user provides arguments, run the allow command for them:
-
-```bash
-cd /Users/duckyoungkim/projects/aigentry-telepty
-node cli.js allow $ARGUMENTS
-```
-
-If no arguments, show the usage guide above and ask what they want to run.

package/.claude/commands/telepty-attach.md

@@ -1,22 +0,0 @@
-# telepty-attach
-
-Attach to an active telepty session to observe its output in real-time.
-
-## Instructions
-
-### Execute
-```bash
-cd /Users/duckyoungkim/projects/aigentry-telepty && node cli.js attach $ARGUMENTS
-```
-
-### If no arguments
-1. List available sessions: `node cli.js list`
-2. Ask the user which session to attach to
-
-### Notes
-- For **spawned** sessions: you can both view output and send input
-- For **wrapped** sessions: input from attached clients is forwarded to the owner as inject
-- Press `Ctrl+C` to detach without killing the session
-
-## Arguments
-- `$ARGUMENTS`: session ID to attach to

package/.claude/commands/telepty-inject.md

@@ -1,72 +0,0 @@
-# telepty-inject
-
-Inject a prompt into a telepty session (spawned or wrapped).
-
-## Instructions
-
-Parse `$ARGUMENTS` to extract target session ID and prompt text.
-
-### Format
-```
-<session_id> <prompt text>
-```
-
-### Step 1: Parse Arguments
-
-If no arguments provided:
-1. List available sessions: `telepty list`
-2. Ask the user which session to target and what to inject
-
-Extract `session_id` (first word) and `prompt` (rest of the arguments).
-
-### Step 2: English-Only Enforcement
-
-Check if the prompt body contains non-English text (Korean, Japanese, Chinese, etc.).
-
-- If non-English text detected: Warn the user and auto-translate the prompt to English before proceeding.
-- Exception: Technical terms (e.g., 'hangul', 'jamo', session IDs like 'aigentry-*') used alongside English are OK.
-- The `--from` header and `[reply-to:]` metadata are exempt from this check.
-
-### Step 3: Auto --ref for Long Content
-
-Detect if the prompt is long (>500 characters OR >3 lines):
-
-- **Long content**: Use `--ref` flag automatically. This writes the prompt to a shared file and sends a SHA reference instead of inline text. Tell the user: "Using --ref (content is X chars / Y lines)."
-- **Short content**: Send inline as-is.
-
-### Step 4: Pre-Send Confirmation
-
-Before executing, show the user:
-```
-Target: <session_id>
-Prompt: <first 100 chars of prompt>... (X chars total)
-Flags: --ref (if applicable), --from (if set)
-```
-
-Then ask: "Send? (y/n)"
-
-**Skip confirmation when:**
-- User explicitly said "send it", "just send", "바로 보내", or similar
-- The command was invoked with `--yes` or `-y` flag
-- Context clearly implies immediate send (e.g., replying to an orchestrator request)
-
-### Step 5: Execute
-
-```bash
-telepty inject [--ref] [--from <from_id>] <session_id> "<prompt>"
-```
-
-If `TELEPTY_SESSION_ID` env var is set, automatically add `--from $TELEPTY_SESSION_ID`.
-
-### Multicast (multiple targets)
-```bash
-telepty multicast <id1>,<id2> "<prompt>"
-```
-
-### Broadcast (all sessions)
-```bash
-telepty broadcast "<prompt>"
-```
-
-## Arguments
-- `$ARGUMENTS`: `<session_id> "<prompt>"` or empty for interactive mode

package/.claude/commands/telepty-list.md

@@ -1,22 +0,0 @@
-# telepty-list
-
-List all active telepty sessions with their types and status.
-
-## Instructions
-
-1. Run:
-```bash
-cd /Users/duckyoungkim/projects/aigentry-telepty && node cli.js list
-```
-
-2. If the daemon is not running, tell the user and suggest `/project:telepty-start`.
-
-3. Format the output as a clear table showing:
-   - Session ID
-   - Type (spawned / wrapped)
-   - Command
-   - Active clients
-   - Created time
-
-## Arguments
-- `$ARGUMENTS`: ignored

package/.claude/commands/telepty-manual-test.md

@@ -1,73 +0,0 @@
-# telepty-manual-test
-
-Guided manual test of the telepty enable (inject) feature. Runs step-by-step verification.
-
-## Instructions
-
-Execute each step sequentially, verifying results before proceeding.
-
-### Step 1: Ensure daemon is running
-```bash
-cd /Users/duckyoungkim/projects/aigentry-telepty
-curl -s http://127.0.0.1:3848/api/sessions 2>/dev/null || node daemon.js &
-sleep 1
-```
-
-### Step 2: Register a wrapped session via API
-```bash
-TOKEN=$(cat ~/.telepty/config.json 2>/dev/null | grep authToken | cut -d '"' -f 4)
-curl -s -X POST http://127.0.0.1:3848/api/sessions/register \
-  -H "Content-Type: application/json" \
-  -H "x-telepty-token: $TOKEN" \
-  -d '{"session_id": "manual-test-1", "command": "test", "cwd": "'"$(pwd)"'"}'
-```
-**Verify**: response has `type: "wrapped"` and status 201.
-
-### Step 3: Check session listing
-```bash
-curl -s http://127.0.0.1:3848/api/sessions -H "x-telepty-token: $TOKEN" | python3 -m json.tool
-```
-**Verify**: `manual-test-1` appears with `type: "wrapped"`.
-
-### Step 4: Test inject without owner (should fail)
-```bash
-curl -s -X POST http://127.0.0.1:3848/api/sessions/manual-test-1/inject \
-  -H "Content-Type: application/json" \
-  -H "x-telepty-token: $TOKEN" \
-  -d '{"prompt": "hello"}'
-```
-**Verify**: returns 503 with "not connected" error.
-
-### Step 5: Clean up test session
-```bash
-curl -s -X DELETE http://127.0.0.1:3848/api/sessions/manual-test-1 \
-  -H "x-telepty-token: $TOKEN"
-```
-**Verify**: returns status "closing".
-
-### Step 6: Verify session removed
-```bash
-curl -s http://127.0.0.1:3848/api/sessions -H "x-telepty-token: $TOKEN"
-```
-**Verify**: `manual-test-1` no longer in the list.
-
-### Step 7: Run automated tests
-```bash
-npm test
-```
-**Verify**: all 25 tests pass.
-
-### Report
-Summarize all verification results in a table:
-
-| Step | Check | Result |
-|------|-------|--------|
-| 2 | Register returns 201 + wrapped | ? |
-| 3 | Session in list with type | ? |
-| 4 | Inject without owner = 503 | ? |
-| 5 | DELETE returns closing | ? |
-| 6 | Session removed | ? |
-| 7 | All tests pass | ? |
-
-## Arguments
-- `$ARGUMENTS`: ignored

package/.claude/commands/telepty-start.md

@@ -1,25 +0,0 @@
-# telepty-start
-
-Start the telepty daemon process.
-
-## Instructions
-
-1. Check if daemon is already running:
-```bash
-curl -s http://127.0.0.1:3848/api/sessions 2>/dev/null && echo "RUNNING" || echo "NOT RUNNING"
-```
-
-2. If not running, start it:
-```bash
-cd /Users/duckyoungkim/projects/aigentry-telepty && node daemon.js &
-```
-
-3. Verify it started:
-```bash
-sleep 1 && curl -s http://127.0.0.1:3848/api/sessions
-```
-
-4. Report status.
-
-## Arguments
-- `$ARGUMENTS`: optional port override (e.g., "3849")

package/.claude/commands/telepty-test.md

@@ -1,25 +0,0 @@
-# telepty-test
-
-Run the telepty automated test suite and report results.
-
-## Instructions
-
-1. Run the full test suite:
-```bash
-cd /Users/duckyoungkim/projects/aigentry-telepty && npm test
-```
-
-2. Parse the output and report:
-   - Total tests, passed, failed
-   - If any failures: show the failing test name and error message
-   - If all pass: confirm with count
-
-3. If tests fail, investigate:
-   - Read the failing test in `test/daemon.test.js`
-   - Check if daemon.js has related issues
-   - Suggest or apply fixes
-   - Re-run tests to confirm
-
-## Arguments
-- No arguments: run all tests
-- `$ARGUMENTS`: if provided, use as a grep filter to run specific tests (e.g., "wrap", "register", "inject")

package/.claude/commands/telepty.md

@@ -1,82 +0,0 @@
-# telepty
-
-Help the user interact with the `telepty` daemon — check session IDs, list active sessions, inject commands, send bus events, and manage terminal windows.
-
-## Trigger
-
-When the user asks about their current session ID, wants to check/list active sessions, inject a prompt into a session, send a JSON event via the bus, subscribe to the bus, rename a session, or update telepty.
-
-## Instructions
-
-### 1. Check Current Session ID
-- Run: `echo $TELEPTY_SESSION_ID`
-- If empty: this shell is NOT inside a telepty session.
-- If set: display it. This is the ID other agents use to target this session.
-
-### 2. List All Sessions
-- Run: `telepty list`
-
-### 3. Send a Message to Another Agent
-Choose ONE of three methods based on intent:
-
-**Method A: Prompt Injection (Active Interruption)**
-The receiving AI will IMMEDIATELY read and execute the message as a prompt.
-```bash
-telepty inject <target_session_id> "<prompt text>"
-```
-For multiple targets: `telepty multicast <id1>,<id2> "<prompt>"`
-
-**Method B: Log Injection (Visual Notification)**
-The message appears on the receiving terminal screen for the user to see, but the AI does NOT execute it as a prompt.
-```bash
-telepty inject <target_session_id> "echo '\x1b[33m[Message from $TELEPTY_SESSION_ID]\x1b[0m <message text>'"
-```
-
-**Method C: Background JSON Bus (Passive/Silent)**
-Structured data transfer that won't disturb the receiving terminal screen.
-```bash
-TOKEN=$(cat ~/.telepty/config.json | grep authToken | cut -d '"' -f 4)
-curl -s -X POST http://127.0.0.1:3848/api/bus/publish \
-  -H "Content-Type: application/json" \
-  -H "x-telepty-token: $TOKEN" \
-  -d '{"type": "bg_message", "payload": "..."}'
-```
-
-### 4. Subscribe to the Event Bus
-```bash
-nohup telepty listen > .telepty_bus_events.log 2>&1 &
-```
-
-### 5. Open a New Ghostty Terminal Window
-Physically spawn a new terminal window already attached to a telepty session:
-```bash
-cat << 'EOF' > /tmp/telepty-auto.command
-#!/bin/bash
-telepty spawn --id <ID> <CMD>
-EOF
-chmod +x /tmp/telepty-auto.command
-open -a Ghostty /tmp/telepty-auto.command || open /tmp/telepty-auto.command
-```
-
-### 6. Terminal Title Convention
-Each telepty session displays its ID in the Ghostty tab title:
-- Local: `⚡ telepty :: {session_id}`
-- Remote: `⚡ telepty :: {session_id} @ {host}`
-
-### 7. Allow Inject on a CLI
-Run any command with inject allowed:
-```bash
-# With custom session ID
-telepty allow --id my-claude -- claude
-telepty allow --id codex-main -- codex
-telepty allow --id gemini-1 -- gemini
-
-# Auto-generated session ID
-telepty allow -- bash
-```
-The process runs locally (isTTY preserved), but registers with the daemon so inject works.
-
-### 8. Update
-```bash
-telepty update
-```

package/AGENTS.md

@@ -1,97 +0,0 @@
-# AGENTS.md — aigentry-telepty
-
-## Overview
-
-PTY Multiplexer & Session Orchestrator — aigentry 에코시스템의 **통신 인프라**.
-npm: `@dmsdc-ai/aigentry-telepty` | 멀티 AI 세션을 생성·연결·제어하는 PTY 멀티플렉서.
-
-## Architecture
-
-```
-CLI (cli.js) ──→ HTTP/WS ──→ Daemon (daemon.js:3848)
-                                ├── Session WS (/api/sessions/:id)
-                                ├── Event Bus WS (/api/bus)
-                                └── REST API (/api/sessions/*)
-```
-
-| 파일 | 역할 |
-|------|------|
-| `cli.js` | CLI 명령 + allow-bridge (PTY 래핑) |
-| `daemon.js` | HTTP/WS 서버, 세션 상태, inject 전달 |
-| `tui.js` | blessed 기반 TUI 대시보드 |
-| `session-routing.js` | 세션 ID 해석, alias 매칭, 호스트 그룹핑 |
-| `daemon-control.js` | 싱글톤 daemon PID 관리 |
-| `auth.js` | UUID 토큰 기반 인증 |
-| `interactive-terminal.js` | raw mode stdin/stdout 관리 |
-| `skill-installer.js` | CLI별 스킬 설치 (Claude/Codex/Gemini) |
-
-## Inject 전달 경로 (wrapped session)
-
-1. **Primary**: `kitty @ send-text` (터미널 직접 전달, allow-bridge 우회)
-2. **Fallback**: WS → allow-bridge → `child.write()` (PTY)
-3. **Submit**: `osascript` Return 키 → kitty fallback → WS `\r`
-
-busy 세션: CR은 큐에 대기 중인 텍스트와 함께 큐잉 후 올바른 순서로 flush.
-
-## Commands
-
-```bash
-npm test                    # 43 tests (node:test)
-telepty daemon              # daemon 시작 (포트 3848)
-telepty allow --id <name> claude  # 세션 래핑
-telepty tui                 # TUI 대시보드
-telepty list                # 세션 목록
-telepty inject <id> "msg"   # 메시지 주입
-telepty broadcast "msg"     # 전체 브로드캐스트
-telepty session start --launch  # kitty 탭으로 다중 세션 시작
-```
-
-## Key Rules
-
-- inject 후 submit은 항상 `osascript`로 통일 (`--no-enter` + osascript keystroke)
-- inject 시 발신자 session ID (`--from`)를 항상 포함
-- PTY `\r` 직접 의존 금지
-
-## Session Communication
-
-```bash
-# List active sessions
-telepty list
-
-# Send message to another session
-telepty inject --from aigentry-telepty-{cli} <target-session> "message"
-
-# Report to orchestrator
-telepty inject --ref --from aigentry-telepty-{cli} aigentry-orchestrator-claude "report"
-```
-
-## Work Principles
-
-- **Best-First**: 항상 최선의 해결책 선택. 차선책/우회 금지.
-- **Configurable**: 설정으로 제어 가능한 구조. 하드코딩 금지.
-- **Evidence-Based**: 추측 금지. 데이터/로그/테스트 결과 기반 판단.
-- **Fail Fast**: 에러 즉시 보고. 숨기지 않음.
-- **Constitution**: ~/projects/aigentry/docs/CONSTITUTION.md 준수.
-
-## Legacy exception — `skill-installer.js`
-
-`skill-installer.js` is a **named legacy exception** grandfathered by
-**ADR 2026-05-05-telepty-devkit-boundary §6.2.1**. It is the single
-exception to the telepty/devkit boundary rule and is NOT precedent for
-new placements.
-
-- **Scope**: bugfixes, security patches, dependency upgrades only.
-- **No new feature expansion**: net-new functionality (new CLI detection,
-  new skill types, new install paths, new flags) MUST land in
-  `@dmsdc-ai/aigentry-devkit`. At migration time devkit will introduce
-  `aigentry scaffold install-skills`.
-- **Reviewer enforcement**: PR reviewers cite ADR 2026-05-05 §6.2.1 when
-  rejecting feature-expansion PRs against `skill-installer.js`.
-- **Migration triggers** (per ADR §6.2.1): ≥2 PRs in 60 days attempting
-  net-new features; devkit feature requires functionality only in
-  `skill-installer.js`; breaking change to its interface.
-
-Per-CLI hook installation, `CLAUDE.md`/`AGENTS.md`/`GEMINI.md` scaffolding,
-project-file generation, and cross-cutting installable skills are
-**devkit-owned** per ADR 2026-05-05 §3.3 — not telepty's responsibility.
-See `@dmsdc-ai/aigentry-devkit` (`aigentry scaffold …`).

package/BOUNDARY.md

@@ -1,31 +0,0 @@
-# telepty Responsibility Boundary
-
-## What telepty owns
-
-- **PTY lifecycle**: spawn, resize, kill PTY processes; emit session_spawn / session_register / session_rename events
-- **Raw stdin write**: accept inject requests and write bytes to the PTY fd (best-effort, fire-and-forget)
-- **stdout streaming**: pipe PTY output to connected WebSocket clients in real time
-- **Bus event broadcast**: publish structured events to all `/api/bus` subscribers
-- **Session lifecycle**: track active sessions, clean up on exit or owner disconnect
-- **Liveness heartbeat**: emit `session_health` every 10 seconds per active session
-
-## What telepty does NOT own
-
-- **CLI state management**: the caller owns its own state machine; telepty does not know what state an agent is in
-- **Inject processing confirmation**: telepty emits `inject_written` when bytes are handed to the OS; it cannot confirm the process consumed or acted on them
-- **Output parsing / interpretation**: telepty streams raw bytes; callers parse meaning
-- **Message guarantee / retry / ordering**: no retry logic, no queue, no ordering guarantees across multiple injects
-- **Session recovery / persistence**: sessions are in-memory; a daemon restart loses all sessions
-- **Cross-session routing**: routing logic (which session gets which message) belongs to the caller or an orchestration layer above telepty
-
-## PTY limitations
-
-- `inject_written` is **best-effort**: it confirms the write syscall to the OS PTY fd succeeded, not that the running process read or processed the input
-- The OS buffers stdin asynchronously; a process blocked, sleeping, or not reading stdin will silently queue the bytes
-- There is no read-back or echo confirmation; callers must observe stdout via the WebSocket stream to infer processing
-
-## Design principle
-
-> **telepty = stateless dumb pipe**
-
-telepty moves bytes. It does not interpret, retry, sequence, or guarantee delivery beyond the OS write call. All higher-level semantics (acknowledgement, ordering, state machines, recovery) are the responsibility of the layer above.