@dmsdc-ai/aigentry-telepty 0.1.83 → 0.1.85

package/AGENTS.md

@@ -0,0 +1,74 @@
+# 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 준수.

package/GEMINI.md

@@ -0,0 +1,10 @@
+@AGENTS.md
+
+# Gemini CLI — aigentry-telepty
+
+## Gemini 전용 설정
+
+- 세션 ID: `aigentry-telepty-gemini`
+- 보고: `telepty inject --ref --from aigentry-telepty-gemini aigentry-orchestrator-claude "보고 내용"`
+- Gemini 강점 활용: upstream 이슈 검색, API 리서치, 문서화 우선
+- 헌법: `~/projects/aigentry/docs/CONSTITUTION.md`

package/cli.js

@@ -871,6 +871,7 @@ async function main() {
     }
     delete process.env.TELEPTY_SESSION_ID;
     process.env.TELEPTY_SESSION_ID = sessionId;
+    process.env.TELEPTY_AVAILABLE = 'true';
 
     await ensureDaemonRunning({ requiredCapabilities: ['wrapped-sessions'] });
 
@@ -914,7 +915,7 @@ async function main() {
     // Spawn local PTY (preserves isTTY, env, shell config)
     const pty = require('node-pty');
     const sessionCwd = process.cwd();
-    const sessionEnv = { ...process.env, TELEPTY_SESSION_ID: sessionId };
+    const sessionEnv = { ...process.env, TELEPTY_SESSION_ID: sessionId, TELEPTY_AVAILABLE: 'true' };
     let child = null;
     let sessionStartTime = Date.now();
     let crashCount = 0;

package/daemon.js

@@ -445,7 +445,7 @@ async function writeDataToSession(id, session, data) {
     // 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 payload = JSON.stringify({ action: "Inject", workspace: id, text: data }) + '\n';
         const timeout = setTimeout(() => {
           sock.destroy();
           resolve(buildErrorBody('TIMEOUT', 'UDS delivery timed out.', { httpStatus: 504 }));
@@ -528,7 +528,7 @@ async function deliverInjectionToSession(id, session, prompt, options = {}) {
     return textResult;
   }
 
-  if (!options.noEnter) {
+  if (!options.noEnter && session.type !== 'aterm') {
     const submitDelay = session.type === 'wrapped' ? 500 : 300;
     setTimeout(async () => {
       const submitResult = await writeDataToSession(id, session, '\r');

package/mcp-server/index.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+
+/**
+ * MCP Telepty Server — Session management tools for AI CLIs
+ *
+ * Tools:
+ *   telepty_list_sessions    List all active telepty sessions
+ *   telepty_inject_session   Inject text into a session
+ *   telepty_session_status   Get detailed status of a session
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import fs from "fs";
+import path from "path";
+import os from "os";
+
+const PKG_VERSION = (() => {
+  try {
+    const p = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    return p.version || "0.0.0";
+  } catch { return "0.0.0"; }
+})();
+
+// ── Config ──
+
+function getAuthToken() {
+  try {
+    const configPath = path.join(os.homedir(), ".telepty", "config.json");
+    const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    return config.authToken || "";
+  } catch { return ""; }
+}
+
+function getDaemonUrl() {
+  const port = process.env.TELEPTY_PORT || "3848";
+  const host = process.env.TELEPTY_HOST || "127.0.0.1";
+  return `http://${host}:${port}`;
+}
+
+async function daemonFetch(endpoint, options = {}) {
+  const url = `${getDaemonUrl()}${endpoint}`;
+  const token = getAuthToken();
+  const headers = {
+    "Content-Type": "application/json",
+    ...(token ? { "x-telepty-token": token } : {}),
+    ...options.headers,
+  };
+  const res = await fetch(url, { ...options, headers });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`telepty daemon ${res.status}: ${body || res.statusText}`);
+  }
+  return res.json();
+}
+
+// ── MCP Server ──
+
+const server = new McpServer({
+  name: "telepty",
+  version: PKG_VERSION,
+});
+
+// Tool: telepty_list_sessions
+server.tool(
+  "telepty_list_sessions",
+  "List all active telepty sessions with their status, type, and last activity.",
+  {},
+  async () => {
+    try {
+      const sessions = await daemonFetch("/api/sessions");
+      if (!Array.isArray(sessions) || sessions.length === 0) {
+        return { content: [{ type: "text", text: "No active sessions." }] };
+      }
+      let text = `## Active Sessions (${sessions.length})\n\n`;
+      text += "| ID | Type | Status | Last Activity |\n";
+      text += "|----|------|--------|---------------|\n";
+      for (const s of sessions) {
+        const status = s.connected ? "connected" : (s.stale ? "stale" : "disconnected");
+        const lastAct = s.lastActivityAt ? new Date(s.lastActivityAt).toLocaleString() : "—";
+        text += `| ${s.id} | ${s.type || "—"} | ${status} | ${lastAct} |\n`;
+      }
+      return { content: [{ type: "text", text }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error listing sessions: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+// Tool: telepty_session_status
+server.tool(
+  "telepty_session_status",
+  "Get detailed status of a specific telepty session.",
+  {
+    session_id: z.string().describe("Session ID to query"),
+  },
+  async ({ session_id }) => {
+    try {
+      const sessions = await daemonFetch("/api/sessions");
+      const session = Array.isArray(sessions)
+        ? sessions.find(s => s.id === session_id || s.id.startsWith(session_id))
+        : null;
+      if (!session) {
+        return { content: [{ type: "text", text: `Session "${session_id}" not found.` }] };
+      }
+      const status = session.connected ? "connected" : (session.stale ? "stale" : "disconnected");
+      let text = `## Session: ${session.id}\n\n`;
+      text += `- **Type:** ${session.type || "unknown"}\n`;
+      text += `- **Status:** ${status}\n`;
+      text += `- **Command:** ${session.command || "—"}\n`;
+      text += `- **CWD:** ${session.cwd || "—"}\n`;
+      text += `- **Backend:** ${session.backend || "—"}\n`;
+      text += `- **Created:** ${session.createdAt ? new Date(session.createdAt).toLocaleString() : "—"}\n`;
+      text += `- **Last Activity:** ${session.lastActivityAt ? new Date(session.lastActivityAt).toLocaleString() : "—"}\n`;
+      if (session.stateReport) {
+        text += `- **State Report:** ${session.stateReport}\n`;
+      }
+      return { content: [{ type: "text", text }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error querying session: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+// Tool: telepty_inject_session
+server.tool(
+  "telepty_inject_session",
+  "Inject text into a telepty session. Use this to send messages or prompts to other AI sessions.",
+  {
+    session_id: z.string().describe("Target session ID"),
+    text: z.string().describe("Text to inject"),
+    from: z.string().optional().describe("Sender session ID (return address)"),
+    no_enter: z.boolean().default(false).describe("If true, do not send Enter after text"),
+  },
+  async ({ session_id, text, from, no_enter }) => {
+    try {
+      const body = { prompt: text };
+      if (from) body.from = from;
+      if (no_enter) body.no_enter = true;
+      const result = await daemonFetch(`/api/sessions/${encodeURIComponent(session_id)}/inject`, {
+        method: "POST",
+        body: JSON.stringify(body),
+      });
+      const deliveryInfo = result.deliveryPath ? ` (via ${result.deliveryPath})` : "";
+      return { content: [{ type: "text", text: `Injected to ${session_id}${deliveryInfo}.` }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error injecting to ${session_id}: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+// ── Start ──
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("telepty MCP server fatal:", err);
+  process.exit(1);
+});

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@dmsdc-ai/aigentry-telepty",
-  "version": "0.1.83",
+  "version": "0.1.85",
   "main": "daemon.js",
   "bin": {
     "aigentry-telepty": "install.js",
     "telepty": "cli.js",
-    "telepty-install": "install.js"
+    "telepty-install": "install.js",
+    "telepty-mcp": "mcp-server/index.mjs"
   },
   "scripts": {
     "test": "node --test 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",
@@ -20,6 +21,8 @@
     "remote",
     "inject",
     "ai-cli",
+    "mcp",
+    "model-context-protocol",
     "claude",
     "codex",
     "gemini",
@@ -38,6 +41,7 @@
     "url": "https://github.com/dmsdc-ai/aigentry-telepty/issues"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "blessed": "^0.1.81",
     "cors": "^2.8.6",
     "express": "^5.2.1",
@@ -45,6 +49,7 @@
     "prompts": "^2.4.2",
     "update-notifier": "^5.1.0",
     "uuid": "^13.0.0",
-    "ws": "^8.19.0"
+    "ws": "^8.19.0",
+    "zod": "^3.24.0"
   }
 }

package/templates/AGENTS.md

@@ -0,0 +1,71 @@
+# telepty Session Communication / 세션 통신
+
+AI CLI sessions use `telepty` to communicate with other sessions.
+
+## Environment Detection / 환경 감지
+
+```bash
+# Check if telepty is available
+echo "$TELEPTY_AVAILABLE"    # "true" if telepty is installed and daemon running
+
+# Get current session ID
+echo "$TELEPTY_SESSION_ID"   # e.g., "aigentry-brain-claude"
+```
+
+If `$TELEPTY_AVAILABLE` is not set, telepty commands are unavailable.
+
+## Commands / 명령어
+
+| English action | 한국어 동작 | Command |
+|----------------|------------|---------|
+| List sessions | 세션 목록 보기 | `telepty list` |
+| Send to session | 세션에 메시지 보내기 | `telepty inject <session> 'message'` |
+| Send with return address | 발신자 포함 전송 | `telepty inject --from $TELEPTY_SESSION_ID <session> 'message'` |
+| Send without enter | 엔터 없이 전송 | `telepty inject --no-enter <session> 'message'` |
+| Broadcast to all | 전체 브로드캐스트 | `telepty broadcast 'message'` |
+| Multicast to group | 그룹 멀티캐스트 | `telepty multicast <id1,id2> 'message'` |
+| Reply to last sender | 마지막 발신자에게 답장 | `telepty reply 'message'` |
+| Check session status | 세션 상태 확인 | `telepty list` (check connected/stale) |
+| Read session screen | 세션 화면 읽기 | `curl -s http://127.0.0.1:3848/api/sessions/<id>/screen -H "x-telepty-token: $TOKEN"` |
+| Kill session | 세션 종료 | `telepty delete <session>` |
+| Clean stale sessions | 비활성 세션 정리 | `telepty clean` |
+| Rename session | 세션 이름 변경 | `telepty rename <old> <new>` |
+| Listen to event bus | 이벤트 버스 수신 | `telepty listen` |
+| Attach to session | 세션에 접속 | `telepty attach <session>` |
+
+## Natural Language → Command / 자연어 → 명령어
+
+| English request | 한국어 요청 | Command |
+|----------------|------------|---------|
+| `list sessions` | `세션 목록 보여줘` | `telepty list` |
+| `send to brain` | `brain에 메시지 보내줘` | `telepty inject aigentry-brain-claude 'msg'` |
+| `broadcast message` | `전체에 메시지 보내줘` | `telepty broadcast 'msg'` |
+| `reply to sender` | `답장해줘` | `telepty reply 'msg'` |
+| `kill session` | `세션 종료해줘` | `telepty delete <session>` |
+| `clean stale` | `비활성 정리해줘` | `telepty clean` |
+| `check status` | `상태 확인해줘` | `telepty list` |
+| `rename session` | `세션 이름 바꿔줘` | `telepty rename <old> <new>` |
+| `read screen` | `화면 읽어줘` | REST API `/api/sessions/<id>/screen` |
+
+## Cross-Machine Sessions / 크로스 머신 세션
+
+When the same session ID exists on multiple hosts, use `session_id@host`:
+
+```bash
+telepty inject brain-claude@macbook 'message'
+```
+
+## Rules / 규칙
+
+1. **Return address**: Always include `--from $TELEPTY_SESSION_ID` when expecting a reply.
+2. **Submit method**: Never rely on PTY `\r` directly. Use `telepty inject` which handles submit automatically.
+3. **Env detection**: Check `$TELEPTY_AVAILABLE` before using telepty commands.
+4. **Session ID format**: Use `<project>-<cli>` pattern (e.g., `aigentry-brain-claude`).
+
+## Reporting / 보고
+
+On task completion, report to orchestrator:
+
+```bash
+telepty inject --from $TELEPTY_SESSION_ID aigentry-orchestrator-claude 'REPORT: <summary>'
+```