@dmsdc-ai/aigentry-telepty 0.4.3 → 0.4.5

package/src/bridge/j3-shim.js

@@ -0,0 +1,264 @@
+'use strict';
+
+// J3 shim — 0.3.x daemon-shape requests (inject/output/list) translated to
+// NDJSON Frames against the per-session Rust supervisor.
+//
+// Scope (P2 per dispatch §Goal): inject / output (stream) / list only. Spawn /
+// kill / delete remain on daemon.js for the migration window. Reads
+// ~/.telepty/sessions/<sid>/manifest.json directly to discover supervisor-
+// managed sessions (mirrors the supervisor binary's `--list` mode but avoids
+// the subprocess hop for cli.js call sites).
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { randomUUID } = require('node:crypto');
+
+const { connect } = require('./supervisor-ipc');
+
+const READY_STATUSES = new Set(['ready', 'draining']);
+
+// Resolved lazily so tests (and operators) can redirect via
+// TELEPTY_SESSIONS_DIR without re-requiring the module.
+function sessionsRoot() {
+  return process.env.TELEPTY_SESSIONS_DIR || path.join(os.homedir(), '.telepty', 'sessions');
+}
+
+function sessionDir(sid) {
+  return path.join(sessionsRoot(), sid);
+}
+
+function manifestPath(sid) {
+  return path.join(sessionDir(sid), 'manifest.json');
+}
+
+function socketPath(sid) {
+  return path.join(sessionDir(sid), 'supervisor.sock');
+}
+
+function readManifest(sid) {
+  try {
+    const raw = fs.readFileSync(manifestPath(sid), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || parsed.id !== sid) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Locate a usable supervisor manifest for the session. Returns null when no
+ * manifest exists, the manifest is malformed, or the status is not in
+ * {ready, draining} — the caller should then fall back to the daemon.js path.
+ * @param {string} sid
+ * @returns {?object}
+ */
+function findSupervisorManifest(sid) {
+  const m = readManifest(sid);
+  if (!m) return null;
+  if (!m.ipc || typeof m.ipc.path !== 'string' || m.ipc.path.length === 0) return null;
+  if (!READY_STATUSES.has(m.status)) return null;
+  return m;
+}
+
+/**
+ * Inject text into a supervisor-managed session via the bridge.
+ *
+ * Request shape (0.3.x compat): (sessionId, prompt, options) where options
+ * carries optional `from`, `reply_to`, `reply_expected`, `idempotency_key`,
+ * `trace_id`, `connectTimeoutMs`, `errorWindowMs`.
+ *
+ * Response shape: `{ success: true, trace_id }` or
+ * `{ success: false, code, error, trace_id? }`. Inject is fire-and-forget on
+ * the wire (per supervisor.rs dispatch_ingest), so success = no error frame
+ * arrived within `errorWindowMs` (default 150ms — catches B3 trace_id /
+ * duplicate-op / shutting-down rejections).
+ *
+ * @param {string} sessionId
+ * @param {string} prompt
+ * @param {object} [options]
+ */
+async function inject(sessionId, prompt, options = {}) {
+  const manifest = findSupervisorManifest(sessionId);
+  if (!manifest) {
+    return {
+      success: false,
+      code: 'ERR_NO_SUPERVISOR',
+      error: `no supervisor manifest for session '${sessionId}'`,
+    };
+  }
+
+  let client;
+  try {
+    client = await connect(manifest.ipc.path, {
+      connectTimeoutMs: options.connectTimeoutMs ?? 1500,
+    });
+  } catch (err) {
+    return {
+      success: false,
+      code: err.code || 'ERR_NOT_REACHABLE',
+      error: err.message,
+    };
+  }
+
+  const trace_id = options.trace_id || randomUUID();
+  const op_id = options.idempotency_key || trace_id;
+  const data = String(prompt ?? '');
+
+  const frame = {
+    kind: 'inject',
+    sid: sessionId,
+    trace_id,
+    op_id,
+    data,
+  };
+
+  try {
+    await client.send(frame);
+  } catch (err) {
+    try { await client.close(); } catch {}
+    return {
+      success: false,
+      code: err.code || 'ERR_BAD_FRAME',
+      error: err.message,
+      trace_id,
+    };
+  }
+
+  const errorWindowMs = options.errorWindowMs ?? 150;
+  const earlyError = await waitForCorrelatedError(client, sessionId, trace_id, errorWindowMs);
+  try { await client.close(); } catch {}
+
+  if (earlyError) {
+    return {
+      success: false,
+      code: earlyError.code || 'ERR_BAD_FRAME',
+      error: earlyError.data || 'supervisor rejected inject',
+      trace_id,
+    };
+  }
+  return { success: true, trace_id };
+}
+
+async function waitForCorrelatedError(client, sessionId, trace_id, timeoutMs) {
+  const ac = new AbortController();
+  const tm = setTimeout(() => ac.abort(), timeoutMs);
+  let found = null;
+  try {
+    for await (const frame of client.subscribe({ sid: sessionId, signal: ac.signal })) {
+      if (frame.kind === 'error' && frame.trace_id === trace_id) {
+        found = frame;
+        break;
+      }
+    }
+  } finally {
+    clearTimeout(tm);
+  }
+  return found;
+}
+
+/**
+ * Enumerate supervisor-managed sessions by scanning manifest files. Mirrors
+ * the binary's `--list` output but as in-process Node — avoids the subprocess
+ * hop for cli.js list path.
+ * @returns {Array<object>}
+ */
+function list() {
+  let entries;
+  try {
+    entries = fs.readdirSync(sessionsRoot(), { withFileTypes: true });
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return [];
+    return [];
+  }
+  const sessions = [];
+  for (const dirent of entries) {
+    if (!dirent.isDirectory()) continue;
+    const manifest = readManifest(dirent.name);
+    if (!manifest) continue;
+    // Surface only live sessions — tombstones (status: stopped|error) lack a
+    // usable IPC socket and would mislead callers using this for inject
+    // routing. Operators still see them via `telepty-supervisor-bin --list`.
+    if (!READY_STATUSES.has(manifest.status)) continue;
+    sessions.push(toSessionInfo(manifest));
+  }
+  return sessions;
+}
+
+function toSessionInfo(manifest) {
+  const info = {
+    id: manifest.id,
+    host: '127.0.0.1',
+    transport: 'supervisor',
+    supervisor_pid: manifest.pid,
+    status: manifest.status,
+    ipc: manifest.ipc,
+    createdAt: manifest.created_at,
+  };
+  if (manifest.exit_reason) info.exit_reason = manifest.exit_reason;
+  if (manifest.exit_code != null) info.exit_code = manifest.exit_code;
+  if (manifest.exit_signal) info.exit_signal = manifest.exit_signal;
+  return info;
+}
+
+/**
+ * Live PTY output stream for a supervisor-managed session.
+ *
+ * Returns an async generator yielding `{ data, seq }` per Frame::output (and
+ * a final `{ exit, ... }` on shutdown_drain). Consumer cancellation:
+ * `for await (...) { ...; break; }` or `signal.abort()` both unwind cleanly.
+ *
+ * Optional `fromSeq` triggers an A5 Resume frame so the supervisor replays
+ * log.jsonl entries with seq > fromSeq before live broadcast — useful when
+ * the caller reconnects after a brief disconnect.
+ *
+ * @param {string} sessionId
+ * @param {{fromSeq?: ?number, signal?: AbortSignal|null, connectTimeoutMs?: number}} [options]
+ */
+async function* output(sessionId, options = {}) {
+  const manifest = findSupervisorManifest(sessionId);
+  if (!manifest) {
+    const err = new Error(`no supervisor manifest for session '${sessionId}'`);
+    err.code = 'ERR_NO_SUPERVISOR';
+    throw err;
+  }
+  const { fromSeq = null, signal = null, connectTimeoutMs = 1500 } = options;
+  const client = await connect(manifest.ipc.path, { connectTimeoutMs });
+  try {
+    if (fromSeq != null) {
+      await client.send({ kind: 'resume', sid: sessionId, from_seq: fromSeq });
+    }
+    for await (const frame of client.subscribe({ sid: sessionId, signal })) {
+      if (frame.kind === 'output' && typeof frame.data === 'string') {
+        yield { data: frame.data, seq: typeof frame.seq === 'number' ? frame.seq : null };
+      } else if (frame.kind === 'shutdown_drain') {
+        yield {
+          data: '',
+          seq: null,
+          exit: {
+            reason: frame.exit_reason || null,
+            code: typeof frame.exit_code === 'number' ? frame.exit_code : null,
+            escalated: frame.escalated === true,
+          },
+        };
+        break;
+      }
+    }
+  } finally {
+    try { await client.close(); } catch {}
+  }
+}
+
+module.exports = {
+  inject,
+  output,
+  list,
+  findSupervisorManifest,
+  readManifest,
+  toSessionInfo,
+  sessionDir,
+  manifestPath,
+  socketPath,
+  sessionsRoot,
+};

package/src/bridge/supervisor-ipc.js

@@ -0,0 +1,330 @@
+'use strict';
+
+// Node↔Rust supervisor bridge — NDJSON over a per-session UDS.
+//
+// Wire schema mirror: crates/telepty-supervisor-core/src/wire.rs (v=1).
+// Per synthesis ADR §6.2 (B3): inject/output/signal/kill/delete frames MUST
+// carry a non-empty trace_id; the supervisor rejects with ERR_BAD_FRAME
+// otherwise. This client auto-fills trace_id for those kinds if the caller
+// omits it. Pong reflects trace_id back so request() correlates by trace_id.
+//
+// Stdlib only (Constitution §17). NDJSON parsing via readline.
+
+const net = require('node:net');
+const readline = require('node:readline');
+const { randomUUID } = require('node:crypto');
+
+const WIRE_VERSION = 1;
+const DEFAULT_REQUEST_TIMEOUT_MS = 3000;
+const DEFAULT_CONNECT_TIMEOUT_MS = 1500;
+const KINDS_REQUIRING_TRACE_ID = new Set(['inject', 'output', 'signal', 'kill', 'delete']);
+const CORRELATED_RESPONSE_KINDS = new Set(['pong', 'error']);
+
+class BridgeClientError extends Error {
+  constructor(code, message, frame = null) {
+    super(message);
+    this.code = code;
+    this.frame = frame;
+    this.name = 'BridgeClientError';
+  }
+}
+
+class BridgeClient {
+  constructor(socket) {
+    this._socket = socket;
+    this._pending = new Map();
+    this._subscribers = new Set();
+    this._closed = false;
+    this._closePromise = null;
+
+    const rl = readline.createInterface({ input: socket, crlfDelay: Infinity });
+    rl.on('line', (line) => this._handleLine(line));
+    socket.once('close', () => this._handleClose(null));
+    socket.once('error', (err) => this._handleError(err));
+    this._rl = rl;
+  }
+
+  /** @returns {boolean} */
+  isClosed() {
+    return this._closed;
+  }
+
+  /**
+   * Send a frame without awaiting a correlated reply. Resolves once the bytes
+   * are flushed to the OS write buffer. Auto-fills wire version and trace_id
+   * for kinds where the supervisor mandates trace_id (B3).
+   * @param {object} frame
+   * @returns {Promise<{trace_id: ?string}>}
+   */
+  send(frame) {
+    if (this._closed) {
+      return Promise.reject(new BridgeClientError('ERR_SUPERVISOR_GONE', 'client closed'));
+    }
+    const out = this._prepareFrame(frame);
+    const line = JSON.stringify(out) + '\n';
+    return new Promise((resolve, reject) => {
+      this._socket.write(line, (err) => {
+        if (err) reject(new BridgeClientError('ERR_NOT_REACHABLE', err.message));
+        else resolve({ trace_id: out.trace_id || null });
+      });
+    });
+  }
+
+  /**
+   * Send a frame and await a correlated response (pong | error) carrying the
+   * same trace_id. Rejects with ERR_TIMEOUT on drift beyond `timeoutMs`. Error
+   * frames reject with the supervisor's ERR_* code preserved.
+   * @param {object} frame
+   * @param {{timeoutMs?: number}} [options]
+   * @returns {Promise<object>}
+   */
+  request(frame, { timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS } = {}) {
+    if (this._closed) {
+      return Promise.reject(new BridgeClientError('ERR_SUPERVISOR_GONE', 'client closed'));
+    }
+    const out = this._prepareFrame(frame);
+    if (!out.trace_id) {
+      out.trace_id = randomUUID();
+    }
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        if (this._pending.delete(out.trace_id)) {
+          reject(new BridgeClientError(
+            'ERR_TIMEOUT',
+            `no response within ${timeoutMs}ms (trace_id=${out.trace_id})`,
+          ));
+        }
+      }, timeoutMs);
+      this._pending.set(out.trace_id, { resolve, reject, timer });
+      const line = JSON.stringify(out) + '\n';
+      this._socket.write(line, (err) => {
+        if (err && this._pending.delete(out.trace_id)) {
+          clearTimeout(timer);
+          reject(new BridgeClientError('ERR_NOT_REACHABLE', err.message));
+        }
+      });
+    });
+  }
+
+  /**
+   * Subscribe to incoming frames. Returns an AsyncIterator yielding every
+   * frame the supervisor emits (output broadcast, shutdown_drain, error,
+   * pong) optionally filtered by `sid`. Frames lacking a sid (error, pong)
+   * always pass through so callers can observe rejections.
+   *
+   * Cancellation: pass an AbortSignal, call `iterator.return()`, or `break`
+   * the for-await loop — all cleanly remove the subscription.
+   *
+   * @param {{sid?: string|null, signal?: AbortSignal|null}} [options]
+   */
+  subscribe({ sid = null, signal = null } = {}) {
+    const queue = [];
+    const waiters = [];
+    let ended = false;
+
+    const sub = {
+      push: (frame) => {
+        if (ended) return;
+        if (sid && frame.sid != null && frame.sid !== sid) return;
+        const waiter = waiters.shift();
+        if (waiter) {
+          waiter({ value: frame, done: false });
+        } else {
+          queue.push(frame);
+        }
+      },
+      end: () => {
+        if (ended) return;
+        ended = true;
+        while (waiters.length > 0) {
+          waiters.shift()({ value: undefined, done: true });
+        }
+      },
+    };
+
+    this._subscribers.add(sub);
+
+    const cleanup = () => {
+      this._subscribers.delete(sub);
+      sub.end();
+    };
+
+    if (signal) {
+      if (signal.aborted) {
+        cleanup();
+      } else {
+        const onAbort = () => cleanup();
+        signal.addEventListener('abort', onAbort, { once: true });
+      }
+    }
+
+    const iter = {
+      [Symbol.asyncIterator]() {
+        return this;
+      },
+      next() {
+        if (queue.length > 0) {
+          return Promise.resolve({ value: queue.shift(), done: false });
+        }
+        if (ended) {
+          return Promise.resolve({ value: undefined, done: true });
+        }
+        return new Promise((resolve) => {
+          waiters.push(resolve);
+        });
+      },
+      return() {
+        cleanup();
+        return Promise.resolve({ value: undefined, done: true });
+      },
+      throw(err) {
+        cleanup();
+        return Promise.reject(err);
+      },
+    };
+    return iter;
+  }
+
+  /**
+   * Close the socket and reject any pending requests with ERR_SUPERVISOR_GONE.
+   * Idempotent.
+   * @returns {Promise<void>}
+   */
+  close() {
+    if (this._closePromise) return this._closePromise;
+    this._closePromise = new Promise((resolve) => {
+      if (this._closed) {
+        resolve();
+        return;
+      }
+      const finalize = () => {
+        resolve();
+      };
+      this._socket.once('close', finalize);
+      try {
+        this._socket.end();
+      } catch {
+        // already destroyed
+      }
+      const grace = setTimeout(() => {
+        if (!this._closed) {
+          try { this._socket.destroy(); } catch {}
+        }
+      }, 200);
+      grace.unref();
+    });
+    return this._closePromise;
+  }
+
+  _handleLine(line) {
+    if (!line) return;
+    let frame;
+    try {
+      frame = JSON.parse(line);
+    } catch {
+      // Protocol violation on incoming line — surface as a synthetic error to
+      // subscribers; do not tear down the connection (supervisor may still
+      // emit valid frames after malformed garbage in a misbehaving client).
+      const err = {
+        v: WIRE_VERSION,
+        kind: 'error',
+        code: 'ERR_BAD_FRAME',
+        data: 'client_parse_error',
+      };
+      for (const sub of this._subscribers) sub.push(err);
+      return;
+    }
+    if (!frame || typeof frame !== 'object' || typeof frame.kind !== 'string') return;
+
+    if (frame.trace_id && CORRELATED_RESPONSE_KINDS.has(frame.kind) && this._pending.has(frame.trace_id)) {
+      const pending = this._pending.get(frame.trace_id);
+      this._pending.delete(frame.trace_id);
+      clearTimeout(pending.timer);
+      if (frame.kind === 'error') {
+        pending.reject(new BridgeClientError(
+          frame.code || 'ERR_BAD_FRAME',
+          frame.data || 'supervisor error',
+          frame,
+        ));
+      } else {
+        pending.resolve(frame);
+      }
+    }
+
+    for (const sub of this._subscribers) sub.push(frame);
+  }
+
+  _handleClose(_err) {
+    if (this._closed) return;
+    this._closed = true;
+    const goneErr = new BridgeClientError('ERR_SUPERVISOR_GONE', 'supervisor socket closed');
+    for (const [, pending] of this._pending) {
+      clearTimeout(pending.timer);
+      pending.reject(goneErr);
+    }
+    this._pending.clear();
+    for (const sub of this._subscribers) sub.end();
+    this._subscribers.clear();
+    this._rl.close();
+  }
+
+  _handleError(_err) {
+    if (!this._closed) {
+      try { this._socket.destroy(); } catch {}
+    }
+  }
+
+  _prepareFrame(frame) {
+    const out = { v: WIRE_VERSION, ...frame };
+    if (KINDS_REQUIRING_TRACE_ID.has(out.kind) && !out.trace_id) {
+      out.trace_id = randomUUID();
+    }
+    return out;
+  }
+}
+
+/**
+ * Connect to the per-session supervisor UDS socket.
+ * @param {string} socketPath
+ * @param {{connectTimeoutMs?: number}} [options]
+ * @returns {Promise<BridgeClient>}
+ */
+function connect(socketPath, { connectTimeoutMs = DEFAULT_CONNECT_TIMEOUT_MS } = {}) {
+  return new Promise((resolve, reject) => {
+    if (typeof socketPath !== 'string' || socketPath.length === 0) {
+      reject(new BridgeClientError('ERR_BAD_FRAME', 'socketPath required'));
+      return;
+    }
+    const socket = net.createConnection({ path: socketPath });
+    const timer = setTimeout(() => {
+      socket.destroy();
+      reject(new BridgeClientError(
+        'ERR_NOT_REACHABLE',
+        `connect timeout ${connectTimeoutMs}ms (${socketPath})`,
+      ));
+    }, connectTimeoutMs);
+
+    const onConnect = () => {
+      clearTimeout(timer);
+      socket.removeListener('error', onError);
+      resolve(new BridgeClient(socket));
+    };
+    const onError = (err) => {
+      clearTimeout(timer);
+      socket.removeListener('connect', onConnect);
+      try { socket.destroy(); } catch {}
+      reject(new BridgeClientError('ERR_NOT_REACHABLE', err.message));
+    };
+    socket.once('connect', onConnect);
+    socket.once('error', onError);
+  });
+}
+
+module.exports = {
+  connect,
+  BridgeClient,
+  BridgeClientError,
+  WIRE_VERSION,
+  DEFAULT_REQUEST_TIMEOUT_MS,
+  DEFAULT_CONNECT_TIMEOUT_MS,
+};