@dmsdc-ai/aigentry-telepty 0.1.51 → 0.1.53

package/BUS_EVENT_SCHEMA.md

@@ -0,0 +1,199 @@
+# Telepty Bus Event Schema Standard
+
+Version: 2.0 (2026-03-15)
+Agreed by: telepty, deliberation, devkit, brain, orchestrator
+
+## Transport
+
+- **HTTP**: `POST /api/bus/publish` with JSON body
+- **WebSocket**: `ws://HOST:3848/api/bus` send JSON message
+- Both paths trigger bus auto-router for routable events
+
+## Envelope Structure (All Events)
+
+```json
+{
+  "version": 1,
+  "message_id": "string (UUID or prefixed ID)",
+  "kind": "string (event type)",
+  "source": "string (sender identifier)",
+  "source_host": "string (machine_id of sender, e.g. hostname or Tailscale IP)",
+  "target": "string | null (target session ID, optional @host suffix)",
+  "ts": "ISO 8601 timestamp"
+}
+```
+
+### Canonical Field Names
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `version` | number | Envelope schema version (currently 1) |
+| `kind` | string | Event type (NOT `type` — `kind` is canonical) |
+| `target` | string | Target telepty session ID. May include `@host` suffix for remote |
+| `source` | string | Sender identifier (format: `project:session_id`) |
+| `source_host` | string | Machine ID of sender (hostname or TELEPTY_MACHINE_ID) |
+| `message_id` | string | Unique message identifier |
+| `ts` | string | ISO 8601 timestamp |
+
+## Cross-Machine Addressing
+
+### Session Locator
+Every session is uniquely identified by a locator triple:
+```json
+{ "machine_id": "hostname", "session_id": "aigentry-devkit-001", "project_id": "aigentry-devkit" }
+```
+
+### Remote Target Format
+`target` field supports `@host` suffix: `aigentry-devkit-001@100.100.100.5`
+- Router strips suffix, resolves session on local daemon
+- For cross-machine relay (P3), daemon forwards to target host
+
+### Machine ID
+- Default: `os.hostname()`
+- Override: `TELEPTY_MACHINE_ID` env var
+- Exposed in: `GET /api/meta` (`machine_id` field), session `locator` object, bus event `source_host`
+
+### Peer Auth
+- Localhost: always trusted
+- Tailscale (100.x.y.z): trusted by default
+- Custom peers: `TELEPTY_PEER_ALLOWLIST=ip1,ip2` env var
+- All others: require `x-telepty-token` header
+
+## Routable Events (Auto-Router)
+
+### `turn_request`
+
+Published by deliberation to request a turn from a session. Telepty daemon auto-routes to target session PTY.
+
+```json
+{
+  "message_id": "turn_request-<uuid>",
+  "session_id": "<deliberation_session_id>",
+  "project": "<project_name>",
+  "kind": "turn_request",
+  "source": "deliberation:<deliberation_session_id>",
+  "target": "<telepty_session_id>[@<host>]",
+  "reply_to": "<deliberation_session_id>",
+  "trace": ["project:<name>", "speaker:<id>", "turn:<turn_id>"],
+  "payload": {
+    "turn_id": "string",
+    "round": "number",
+    "max_rounds": "number",
+    "speaker": "string (target telepty session ID)",
+    "role": "string | null",
+    "prompt": "string (full prompt text — inject as-is to PTY)",
+    "prompt_sha1": "string (40-char SHA1)",
+    "history_entries": "number",
+    "transport_timeout_ms": "number",
+    "semantic_timeout_ms": "number"
+  },
+  "ts": "ISO 8601"
+}
+```
+
+**Important Notes:**
+- `session_id` is the DELIBERATION session ID, NOT the target telepty session
+- `target` is the telepty session ID to inject into
+- `payload.prompt` is the full text to write to PTY (no further processing needed)
+- `@host` suffix on target: strip before resolving, use for remote routing
+
+**Auto-Router Behavior:**
+1. Daemon receives turn_request via HTTP POST or WS
+2. Extracts `target` field, strips `@host` suffix
+3. Resolves session via `resolveSessionAlias()`
+4. Delivers `payload.prompt` to session PTY (kitty primary, WS fallback)
+5. Emits `inject_written` ack on bus
+
+### `inject_written` (ACK)
+
+Emitted by telepty after successful auto-route delivery.
+
+```json
+{
+  "type": "inject_written",
+  "inject_id": "UUID",
+  "sender": "daemon",
+  "target_agent": "<session_id>",
+  "source_type": "bus_auto_route",
+  "delivered": true,
+  "timestamp": "ISO 8601"
+}
+```
+
+## Session Lifecycle Events
+
+### `session_register`
+```json
+{ "type": "session_register", "sender": "daemon", "session_id": "string", "command": "string", "cwd": "string", "timestamp": "ISO 8601" }
+```
+
+### `session.replaced`
+```json
+{ "type": "session.replaced", "sender": "daemon", "old_id": "string", "new_id": "string", "alias": "string", "timestamp": "ISO 8601" }
+```
+
+### `session.idle`
+```json
+{ "type": "session.idle", "session_id": "string", "idleSeconds": "number", "lastActivityAt": "ISO 8601", "timestamp": "ISO 8601" }
+```
+
+### `session_health` (periodic, every 10s)
+```json
+{ "type": "session_health", "session_id": "string", "payload": { "alive": true, "pid": "number|null", "type": "string", "clients": "number", "idleSeconds": "number|null" }, "timestamp": "ISO 8601" }
+```
+
+## Inject Events
+
+### `inject_written`
+```json
+{ "type": "inject_written", "inject_id": "UUID", "sender": "daemon", "target_agent": "string", "content": "string", "from": "string|null", "reply_to": "string|null", "thread_id": "string|null", "reply_expected": "boolean", "timestamp": "ISO 8601" }
+```
+
+### `message_routed`
+```json
+{ "type": "message_routed", "message_id": "UUID", "from": "string", "to": "string", "reply_to": "string", "inject_id": "UUID", "deliberation_session_id": "string|null", "thread_id": "string|null", "timestamp": "ISO 8601" }
+```
+
+## Handoff Events
+
+### `handoff.created` / `handoff.claimed` / `handoff.executing` / `handoff.completed`
+```json
+{ "type": "handoff.<status>", "handoff_id": "UUID", "source_session_id": "string|null", "deliberation_id": "string|null", "auto_execute": "boolean", "task_count": "number", "timestamp": "ISO 8601" }
+```
+
+## Thread Events
+
+### `thread.opened`
+```json
+{ "type": "thread.opened", "thread_id": "UUID", "topic": "string", "orchestrator_session_id": "string|null", "participant_session_ids": ["string"], "timestamp": "ISO 8601" }
+```
+
+### `thread.closed`
+```json
+{ "type": "thread.closed", "thread_id": "UUID", "topic": "string", "message_count": "number", "timestamp": "ISO 8601" }
+```
+
+## Termination Signal Detection
+
+Messages containing these strings suppress auto-reply guide footer:
+- `no further reply needed`
+- `thread closed` / `closed on X side`
+- `ack received` / `ack-only`
+- `회신 불필요` / `스레드 종료`
+
+## Inject API Reference
+
+### `POST /api/sessions/:id/inject`
+
+```json
+{
+  "prompt": "string (REQUIRED — canonical body field)",
+  "from": "string (sender session ID)",
+  "reply_to": "string (defaults to from if omitted)",
+  "thread_id": "string (optional)",
+  "reply_expected": "boolean (optional)",
+  "no_enter": "boolean (skip Enter after inject)"
+}
+```
+
+**Note:** The canonical body field is `prompt`, NOT `text`, `content`, or `message`.

package/daemon.js

@@ -10,18 +10,54 @@ const { claimDaemonState, clearDaemonState } = require('./daemon-control');
 
 const config = getConfig();
 const EXPECTED_TOKEN = config.authToken;
+const MACHINE_ID = process.env.TELEPTY_MACHINE_ID || os.hostname();
+const fs = require('fs');
+const SESSION_PERSIST_PATH = require('path').join(os.homedir(), '.config', 'aigentry-telepty', 'sessions.json');
+
+function persistSessions() {
+  try {
+    const data = {};
+    for (const [id, s] of Object.entries(sessions)) {
+      data[id] = { id, type: s.type, command: s.command, cwd: s.cwd, createdAt: s.createdAt, lastActivityAt: s.lastActivityAt || null };
+    }
+    fs.mkdirSync(require('path').dirname(SESSION_PERSIST_PATH), { recursive: true });
+    fs.writeFileSync(SESSION_PERSIST_PATH, JSON.stringify(data, null, 2));
+  } catch {}
+}
+
+function loadPersistedSessions() {
+  try {
+    if (!fs.existsSync(SESSION_PERSIST_PATH)) return {};
+    return JSON.parse(fs.readFileSync(SESSION_PERSIST_PATH, 'utf8'));
+  } catch { return {}; }
+}
 
 const app = express();
 app.use(cors());
 app.use(express.json());
 
+// Peer allowlist: comma-separated IPs/CIDRs in TELEPTY_PEER_ALLOWLIST env
+const PEER_ALLOWLIST = (process.env.TELEPTY_PEER_ALLOWLIST || '').split(',').map(s => s.trim()).filter(Boolean);
+
+function isAllowedPeer(ip) {
+  if (!ip) return false;
+  const cleanIp = ip.replace('::ffff:', '');
+  // Localhost always allowed
+  if (cleanIp === '127.0.0.1' || ip === '::1') return true;
+  // Tailscale range (100.x.y.z)
+  if (cleanIp.startsWith('100.')) return true;
+  // Peer allowlist
+  if (PEER_ALLOWLIST.length > 0) return PEER_ALLOWLIST.includes(cleanIp);
+  // No allowlist = allow all authenticated
+  return false;
+}
+
 // Authentication Middleware
 app.use((req, res, next) => {
-  const isLocalhost = req.ip === '127.0.0.1' || req.ip === '::1' || req.ip === '::ffff:127.0.0.1';
-  const isTailscale = req.ip && req.ip.startsWith('100.');
-  
-  if (isLocalhost || isTailscale) {
-    return next(); // Trust local and Tailscale networks
+  const clientIp = req.ip;
+
+  if (isAllowedPeer(clientIp)) {
+    return next(); // Trust local, Tailscale, and allowlisted peers
   }
 
   const token = req.headers['x-telepty-token'] || req.query.token;
@@ -29,7 +65,7 @@ app.use((req, res, next) => {
     return next();
   }
 
-  console.warn(`[AUTH] Rejected unauthorized request from ${req.ip}`);
+  console.warn(`[AUTH] Rejected unauthorized request from ${clientIp}`);
   res.status(401).json({ error: 'Unauthorized: Invalid or missing token.' });
 });
 
@@ -48,6 +84,21 @@ if (!daemonClaim.claimed) {
 const sessions = {};
 const handoffs = {};
 const threads = {};
+
+// Restore persisted session metadata (wrapped sessions await reconnect)
+const _persisted = loadPersistedSessions();
+for (const [id, meta] of Object.entries(_persisted)) {
+  if (meta.type === 'wrapped') {
+    sessions[id] = {
+      id, type: 'wrapped', ptyProcess: null, ownerWs: null,
+      command: meta.command || 'wrapped', cwd: meta.cwd || process.cwd(),
+      createdAt: meta.createdAt || new Date().toISOString(),
+      lastActivityAt: meta.lastActivityAt || new Date().toISOString(),
+      clients: new Set(), isClosing: false
+    };
+    console.log(`[PERSIST] Restored session ${id} (awaiting reconnect)`);
+  }
+}
 const STRIPPED_SESSION_ENV_KEYS = [
   'CLAUDECODE',
   'CODEX_CI',
@@ -185,6 +236,7 @@ app.post('/api/sessions/spawn', (req, res) => {
     });
 
     console.log(`[SPAWN] Created session ${session_id} (${command})`);
+    persistSessions();
     res.status(201).json({ session_id, command, cwd });
   } catch (err) {
     res.status(500).json({ error: err.message });
@@ -250,6 +302,7 @@ app.post('/api/sessions/register', (req, res) => {
   });
 
   console.log(`[REGISTER] Registered wrapped session ${session_id}`);
+  persistSessions();
   res.status(201).json({ session_id, type: 'wrapped', command: sessionRecord.command, cwd });
 });
 
@@ -258,8 +311,10 @@ app.get('/api/sessions', (req, res) => {
   const now = Date.now();
   let list = Object.entries(sessions).map(([id, session]) => {
     const idleSeconds = session.lastActivityAt ? Math.floor((now - new Date(session.lastActivityAt).getTime()) / 1000) : null;
+    const projectId = session.cwd ? session.cwd.split('/').pop() : null;
     return {
       id,
+      locator: { machine_id: MACHINE_ID, session_id: id, project_id: projectId },
       type: session.type || 'spawned',
       command: session.command,
       cwd: session.cwd,
@@ -281,8 +336,10 @@ app.get('/api/sessions/:id', (req, res) => {
   if (!resolvedId) return res.status(404).json({ error: 'Session not found' });
   const session = sessions[resolvedId];
   const idleSeconds = session.lastActivityAt ? Math.floor((Date.now() - new Date(session.lastActivityAt).getTime()) / 1000) : null;
+  const projectId = session.cwd ? session.cwd.split('/').pop() : null;
   res.json({
     id: resolvedId,
+    locator: { machine_id: MACHINE_ID, session_id: resolvedId, project_id: projectId },
     alias: requestedId !== resolvedId ? requestedId : null,
     type: session.type || 'spawned',
     command: session.command,
@@ -303,6 +360,7 @@ app.get('/api/meta', (req, res) => {
     pid: process.pid,
     host: HOST,
     port: Number(PORT),
+    machine_id: MACHINE_ID,
     capabilities: ['sessions', 'wrapped-sessions', 'skill-installer', 'singleton-daemon', 'handoff-inbox', 'deliberation-threads']
   });
 });
@@ -814,9 +872,11 @@ app.delete('/api/sessions/:id', (req, res) => {
       session.clients.forEach(ws => ws.close(1000, 'Session destroyed'));
       delete sessions[id];
       console.log(`[KILL] Wrapped session ${id} removed`);
+      persistSessions();
     } else {
       session.ptyProcess.kill();
       console.log(`[KILL] Session ${id} forcefully closed`);
+      persistSessions();
     }
     res.json({ success: true, status: 'closing' });
   } catch (err) {
@@ -885,6 +945,7 @@ function busAutoRoute(msg) {
     type: 'inject_written',
     inject_id,
     sender: 'daemon',
+    source_host: MACHINE_ID,
     target_agent: targetId,
     source_type: 'bus_auto_route',
     delivered,
@@ -1340,10 +1401,7 @@ server.on('upgrade', (req, socket, head) => {
   const url = new URL(req.url, 'http://' + req.headers.host);
   const token = url.searchParams.get('token');
   
-  const isLocalhost = req.socket.remoteAddress === '127.0.0.1' || req.socket.remoteAddress === '::1' || req.socket.remoteAddress === '::ffff:127.0.0.1';
-  const isTailscale = req.socket.remoteAddress && req.socket.remoteAddress.startsWith('100.');
-  
-  if (!isLocalhost && !isTailscale && token !== EXPECTED_TOKEN) {
+  if (!isAllowedPeer(req.socket.remoteAddress) && token !== EXPECTED_TOKEN) {
     socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
     socket.destroy();
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dmsdc-ai/aigentry-telepty",
-  "version": "0.1.51",
+  "version": "0.1.53",
   "main": "daemon.js",
   "bin": {
     "aigentry-telepty": "install.js",