clawmatrix 0.1.22 → 0.2.0

package/src/terminal.ts

@@ -0,0 +1,566 @@
+/**
+ * TerminalManager — manages interactive PTY sessions over the WebSocket mesh.
+ *
+ * Receiver side: spawns PTY processes and streams output to requester.
+ * Requester side: buffers remote terminal output for agent tool consumption.
+ */
+
+import { randomUUID } from "node:crypto";
+import type { PeerManager } from "./peer-manager.ts";
+import type { ClawMatrixConfig } from "./config.ts";
+import { spawnPty, isPtyAvailable, type PtyHandle } from "./compat.ts";
+import { debug } from "./debug.ts";
+import type {
+  TerminalOpenRequest,
+  TerminalOpenResponse,
+  TerminalData,
+  TerminalResize,
+  TerminalCloseRequest,
+  TerminalCloseResponse,
+} from "./types.ts";
+
+const DEFAULT_SESSION_TTL = 1_800_000; // 30 min
+const DEFAULT_MAX_SESSIONS = 3;
+const OUTPUT_BATCH_MS = 50; // batch output to reduce frame count
+const CLEANUP_INTERVAL = 60_000;
+const MAX_OUTPUT_BUFFER = 256 * 1024; // 256 KB per session
+
+// ── Receiver: local PTY session ─────────────────────────────────
+
+interface PtySession {
+  sessionId: string;
+  requesterId: string; // nodeId of the requester
+  frameId: string;     // original terminal_open frame id (for correlation)
+  pty: PtyHandle;
+  lastActivity: number;
+  pendingOutput: string; // batched output before flush
+  flushTimer: ReturnType<typeof setTimeout> | null;
+}
+
+// ── Requester: remote terminal session ──────────────────────────
+
+interface RemoteSession {
+  sessionId: string;
+  nodeId: string;
+  frameId: string;
+  outputBuffer: string;     // accumulated output (base64 decoded)
+  lastActivity: number;
+  closed: boolean;
+  exitCode?: number;
+}
+
+interface PendingOpen {
+  resolve: (sessionId: string) => void;
+  reject: (err: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export class TerminalManager {
+  private config: ClawMatrixConfig;
+  private peerManager: PeerManager;
+
+  // Receiver side
+  private sessions = new Map<string, PtySession>();
+
+  // Requester side
+  private remoteSessions = new Map<string, RemoteSession>();
+  private pendingOpens = new Map<string, PendingOpen>(); // keyed by frame id
+
+  private cleanupTimer: ReturnType<typeof setTimeout>;
+
+  constructor(config: ClawMatrixConfig, peerManager: PeerManager) {
+    this.config = config;
+    this.peerManager = peerManager;
+
+    // Periodic cleanup of idle sessions
+    this.cleanupTimer = setInterval(() => this.cleanup(), CLEANUP_INTERVAL);
+    if (this.cleanupTimer.unref) this.cleanupTimer.unref();
+  }
+
+  // ── Receiver: handle incoming terminal_open ─────────────────────
+
+  async handleOpenRequest(frame: TerminalOpenRequest): Promise<void> {
+    const nodeId = this.config.nodeId;
+    const termConfig = this.config.terminal;
+
+    // Check if terminal is explicitly disabled (enabled by default when config is omitted)
+    if (termConfig?.enabled === false) {
+      this.peerManager.sendTo(frame.from, {
+        type: "terminal_open_res",
+        id: frame.id,
+        from: nodeId,
+        to: frame.from,
+        timestamp: Date.now(),
+        payload: { success: false, error: "Terminal not enabled on this node" },
+      } as TerminalOpenResponse);
+      return;
+    }
+
+    // Check PTY availability
+    if (!isPtyAvailable()) {
+      this.peerManager.sendTo(frame.from, {
+        type: "terminal_open_res",
+        id: frame.id,
+        from: nodeId,
+        to: frame.from,
+        timestamp: Date.now(),
+        payload: { success: false, error: "node-pty not available on this node" },
+      } as TerminalOpenResponse);
+      return;
+    }
+
+    // Check allowFrom
+    if (termConfig?.allowFrom && termConfig.allowFrom.length > 0) {
+      if (!termConfig.allowFrom.includes(frame.from)) {
+        this.peerManager.sendTo(frame.from, {
+          type: "terminal_open_res",
+          id: frame.id,
+          from: nodeId,
+          to: frame.from,
+          timestamp: Date.now(),
+          payload: { success: false, error: "Terminal access denied for this node" },
+        } as TerminalOpenResponse);
+        return;
+      }
+    }
+
+    // Check max sessions
+    const maxSessions = termConfig?.maxSessions ?? DEFAULT_MAX_SESSIONS;
+    if (this.sessions.size >= maxSessions) {
+      this.peerManager.sendTo(frame.from, {
+        type: "terminal_open_res",
+        id: frame.id,
+        from: nodeId,
+        to: frame.from,
+        timestamp: Date.now(),
+        payload: { success: false, error: `Max terminal sessions reached (${maxSessions})` },
+      } as TerminalOpenResponse);
+      return;
+    }
+
+    // Spawn PTY
+    const shell = frame.payload.shell ?? termConfig?.shell ?? process.env.SHELL ?? "/bin/sh";
+    const sessionId = randomUUID();
+
+    try {
+      const pty = spawnPty(shell, [], {
+        cols: frame.payload.cols ?? 80,
+        rows: frame.payload.rows ?? 24,
+        cwd: frame.payload.cwd,
+        env: frame.payload.env,
+      });
+
+      const session: PtySession = {
+        sessionId,
+        requesterId: frame.from,
+        frameId: frame.id,
+        pty,
+        lastActivity: Date.now(),
+        pendingOutput: "",
+        flushTimer: null,
+      };
+
+      this.sessions.set(sessionId, session);
+
+      // Stream PTY output back to requester (batched)
+      pty.onData((data: string) => {
+        session.lastActivity = Date.now();
+        session.pendingOutput += data;
+
+        if (!session.flushTimer) {
+          session.flushTimer = setTimeout(() => {
+            this.flushOutput(session);
+          }, OUTPUT_BATCH_MS);
+        }
+      });
+
+      // Handle PTY exit
+      pty.onExit(({ exitCode }) => {
+        // Flush any remaining output
+        if (session.pendingOutput) {
+          this.flushOutput(session);
+        }
+
+        this.peerManager.sendTo(session.requesterId, {
+          type: "terminal_close",
+          id: session.frameId,
+          from: nodeId,
+          to: session.requesterId,
+          timestamp: Date.now(),
+          payload: { sessionId, exitCode },
+        } as TerminalCloseRequest);
+
+        this.cleanupSession(sessionId);
+      });
+
+      debug("terminal", `PTY session ${sessionId} opened for ${frame.from} (shell=${shell}, pid=${pty.pid})`);
+
+      this.peerManager.sendTo(frame.from, {
+        type: "terminal_open_res",
+        id: frame.id,
+        from: nodeId,
+        to: frame.from,
+        timestamp: Date.now(),
+        payload: { success: true, sessionId },
+      } as TerminalOpenResponse);
+    } catch (err) {
+      this.peerManager.sendTo(frame.from, {
+        type: "terminal_open_res",
+        id: frame.id,
+        from: nodeId,
+        to: frame.from,
+        timestamp: Date.now(),
+        payload: { success: false, error: `Failed to spawn PTY: ${err instanceof Error ? err.message : String(err)}` },
+      } as TerminalOpenResponse);
+    }
+  }
+
+  private flushOutput(session: PtySession) {
+    if (session.flushTimer) {
+      clearTimeout(session.flushTimer);
+      session.flushTimer = null;
+    }
+    if (!session.pendingOutput) return;
+
+    const data = Buffer.from(session.pendingOutput).toString("base64");
+    session.pendingOutput = "";
+
+    this.peerManager.sendTo(session.requesterId, {
+      type: "terminal_data",
+      id: session.frameId,
+      from: this.config.nodeId,
+      to: session.requesterId,
+      timestamp: Date.now(),
+      payload: { sessionId: session.sessionId, data, direction: "output" },
+    } as TerminalData);
+  }
+
+  // ── Receiver: handle incoming data (stdin from requester) ───────
+
+  handleDataReceiver(frame: TerminalData): void {
+    if (frame.payload.direction !== "input") return;
+
+    const session = this.sessions.get(frame.payload.sessionId);
+    if (!session) {
+      debug("terminal", `Data for unknown session ${frame.payload.sessionId}`);
+      return;
+    }
+
+    session.lastActivity = Date.now();
+    const decoded = Buffer.from(frame.payload.data, "base64").toString();
+    session.pty.write(decoded);
+  }
+
+  // ── Receiver: handle resize ────────────────────────────────────
+
+  handleResizeReceiver(frame: TerminalResize): void {
+    const session = this.sessions.get(frame.payload.sessionId);
+    if (!session) return;
+
+    session.lastActivity = Date.now();
+    session.pty.resize(frame.payload.cols, frame.payload.rows);
+    debug("terminal", `Session ${frame.payload.sessionId} resized to ${frame.payload.cols}x${frame.payload.rows}`);
+  }
+
+  // ── Receiver: handle close request from requester ──────────────
+
+  handleCloseReceiver(frame: TerminalCloseRequest): void {
+    const session = this.sessions.get(frame.payload.sessionId);
+    if (!session) {
+      this.peerManager.sendTo(frame.from, {
+        type: "terminal_close_res",
+        id: frame.id,
+        from: this.config.nodeId,
+        to: frame.from,
+        timestamp: Date.now(),
+        payload: { success: false, error: "Session not found" },
+      } as TerminalCloseResponse);
+      return;
+    }
+
+    session.pty.kill();
+    this.cleanupSession(frame.payload.sessionId);
+
+    this.peerManager.sendTo(frame.from, {
+      type: "terminal_close_res",
+      id: frame.id,
+      from: this.config.nodeId,
+      to: frame.from,
+      timestamp: Date.now(),
+      payload: { success: true },
+    } as TerminalCloseResponse);
+  }
+
+  // ── Requester: open a remote terminal session ──────────────────
+
+  async open(
+    nodeId: string,
+    opts: { shell?: string; cols?: number; rows?: number; cwd?: string; env?: Record<string, string> } = {},
+  ): Promise<string> {
+    const frameId = randomUUID();
+
+    return new Promise<string>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingOpens.delete(frameId);
+        reject(new Error("Terminal open timeout"));
+      }, 30_000);
+
+      this.pendingOpens.set(frameId, { resolve, reject, timer });
+
+      this.peerManager.sendTo(nodeId, {
+        type: "terminal_open",
+        id: frameId,
+        from: this.config.nodeId,
+        to: nodeId,
+        timestamp: Date.now(),
+        payload: {
+          shell: opts.shell,
+          cols: opts.cols ?? 80,
+          rows: opts.rows ?? 24,
+          cwd: opts.cwd,
+          env: opts.env,
+        },
+      } as TerminalOpenRequest);
+    });
+  }
+
+  // ── Requester: handle open response ────────────────────────────
+
+  handleOpenResponse(frame: TerminalOpenResponse): void {
+    const pending = this.pendingOpens.get(frame.id);
+    if (!pending) return;
+
+    clearTimeout(pending.timer);
+    this.pendingOpens.delete(frame.id);
+
+    if (frame.payload.success && frame.payload.sessionId) {
+      const remoteSession: RemoteSession = {
+        sessionId: frame.payload.sessionId,
+        nodeId: frame.from,
+        frameId: frame.id,
+        outputBuffer: "",
+        lastActivity: Date.now(),
+        closed: false,
+      };
+      this.remoteSessions.set(frame.payload.sessionId, remoteSession);
+      pending.resolve(frame.payload.sessionId);
+    } else {
+      pending.reject(new Error(frame.payload.error ?? "Terminal open failed"));
+    }
+  }
+
+  // ── Requester: handle output data from remote ──────────────────
+
+  handleDataRequester(frame: TerminalData): void {
+    if (frame.payload.direction !== "output") return;
+
+    const session = this.remoteSessions.get(frame.payload.sessionId);
+    if (!session) return;
+
+    session.lastActivity = Date.now();
+    const decoded = Buffer.from(frame.payload.data, "base64").toString();
+
+    // Cap output buffer
+    session.outputBuffer += decoded;
+    if (session.outputBuffer.length > MAX_OUTPUT_BUFFER) {
+      session.outputBuffer = session.outputBuffer.slice(-MAX_OUTPUT_BUFFER);
+    }
+  }
+
+  // ── Requester: handle remote close notification ────────────────
+
+  handleCloseRequester(frame: TerminalCloseRequest): void {
+    const session = this.remoteSessions.get(frame.payload.sessionId);
+    if (!session) return;
+
+    session.closed = true;
+    session.exitCode = frame.payload.exitCode;
+  }
+
+  handleCloseResponse(frame: TerminalCloseResponse): void {
+    // Just acknowledgement, no action needed
+    debug("terminal", `Close response: success=${frame.payload.success}`);
+  }
+
+  // ── Requester: send input to remote terminal ───────────────────
+
+  sendInput(sessionId: string, data: string): void {
+    const session = this.remoteSessions.get(sessionId);
+    if (!session || session.closed) {
+      throw new Error(`Terminal session ${sessionId} not found or closed`);
+    }
+
+    session.lastActivity = Date.now();
+    const encoded = Buffer.from(data).toString("base64");
+
+    this.peerManager.sendTo(session.nodeId, {
+      type: "terminal_data",
+      id: session.frameId,
+      from: this.config.nodeId,
+      to: session.nodeId,
+      timestamp: Date.now(),
+      payload: { sessionId, data: encoded, direction: "input" },
+    } as TerminalData);
+  }
+
+  // ── Requester: resize remote terminal ──────────────────────────
+
+  resize(sessionId: string, cols: number, rows: number): void {
+    const session = this.remoteSessions.get(sessionId);
+    if (!session || session.closed) return;
+
+    session.lastActivity = Date.now();
+
+    this.peerManager.sendTo(session.nodeId, {
+      type: "terminal_resize",
+      id: session.frameId,
+      from: this.config.nodeId,
+      to: session.nodeId,
+      timestamp: Date.now(),
+      payload: { sessionId, cols, rows },
+    } as TerminalResize);
+  }
+
+  // ── Requester: close remote terminal ───────────────────────────
+
+  close(sessionId: string): void {
+    const session = this.remoteSessions.get(sessionId);
+    if (!session) return;
+
+    this.peerManager.sendTo(session.nodeId, {
+      type: "terminal_close",
+      id: randomUUID(),
+      from: this.config.nodeId,
+      to: session.nodeId,
+      timestamp: Date.now(),
+      payload: { sessionId },
+    } as TerminalCloseRequest);
+
+    this.remoteSessions.delete(sessionId);
+  }
+
+  // ── Requester: read buffered output ────────────────────────────
+
+  readOutput(sessionId: string): { data: string; closed: boolean; exitCode?: number } {
+    const session = this.remoteSessions.get(sessionId);
+    if (!session) {
+      return { data: "", closed: true, exitCode: undefined };
+    }
+
+    const data = session.outputBuffer;
+    session.outputBuffer = "";
+
+    return { data, closed: session.closed, exitCode: session.exitCode };
+  }
+
+  // ── Requester: list active remote sessions ─────────────────────
+
+  listSessions(): Array<{ sessionId: string; nodeId: string; closed: boolean; exitCode?: number }> {
+    return Array.from(this.remoteSessions.values()).map((s) => ({
+      sessionId: s.sessionId,
+      nodeId: s.nodeId,
+      closed: s.closed,
+      exitCode: s.exitCode,
+    }));
+  }
+
+  // ── Frame dispatch helper (called from ClusterRuntime) ─────────
+
+  dispatchFrame(frame: TerminalOpenRequest | TerminalOpenResponse | TerminalData | TerminalResize | TerminalCloseRequest | TerminalCloseResponse): void {
+    switch (frame.type) {
+      case "terminal_open":
+        this.handleOpenRequest(frame as TerminalOpenRequest).catch((err) => {
+          debug("terminal", `Open request error: ${err}`);
+        });
+        break;
+      case "terminal_open_res":
+        this.handleOpenResponse(frame as TerminalOpenResponse);
+        break;
+      case "terminal_data": {
+        const df = frame as TerminalData;
+        if (df.payload.direction === "input") {
+          this.handleDataReceiver(df);
+        } else {
+          this.handleDataRequester(df);
+        }
+        break;
+      }
+      case "terminal_resize":
+        this.handleResizeReceiver(frame as TerminalResize);
+        break;
+      case "terminal_close":
+        // Could be from requester (asking to close) or from receiver (PTY exited)
+        if (this.sessions.has((frame as TerminalCloseRequest).payload.sessionId)) {
+          // We are the receiver, requester asked to close
+          this.handleCloseReceiver(frame as TerminalCloseRequest);
+        } else {
+          // We are the requester, receiver notified PTY exit
+          this.handleCloseRequester(frame as TerminalCloseRequest);
+        }
+        break;
+      case "terminal_close_res":
+        this.handleCloseResponse(frame as TerminalCloseResponse);
+        break;
+    }
+  }
+
+  // ── Cleanup ────────────────────────────────────────────────────
+
+  private cleanup() {
+    const ttl = this.config.terminal?.sessionTTL ?? DEFAULT_SESSION_TTL;
+    const now = Date.now();
+
+    // Cleanup idle receiver sessions
+    for (const [sessionId, session] of this.sessions) {
+      if (now - session.lastActivity > ttl) {
+        debug("terminal", `Session ${sessionId} timed out (idle ${Math.floor((now - session.lastActivity) / 1000)}s)`);
+        session.pty.kill();
+
+        this.peerManager.sendTo(session.requesterId, {
+          type: "terminal_close",
+          id: session.frameId,
+          from: this.config.nodeId,
+          to: session.requesterId,
+          timestamp: Date.now(),
+          payload: { sessionId, exitCode: -1 },
+        } as TerminalCloseRequest);
+
+        this.cleanupSession(sessionId);
+      }
+    }
+
+    // Cleanup closed remote sessions
+    for (const [sessionId, session] of this.remoteSessions) {
+      if (session.closed && now - session.lastActivity > 60_000) {
+        this.remoteSessions.delete(sessionId);
+      }
+    }
+  }
+
+  private cleanupSession(sessionId: string) {
+    const session = this.sessions.get(sessionId);
+    if (session?.flushTimer) {
+      clearTimeout(session.flushTimer);
+    }
+    this.sessions.delete(sessionId);
+  }
+
+  destroy() {
+    clearInterval(this.cleanupTimer);
+
+    // Kill all local PTY sessions
+    for (const [sessionId, session] of this.sessions) {
+      if (session.flushTimer) clearTimeout(session.flushTimer);
+      try { session.pty.kill(); } catch { /* ignore */ }
+      this.sessions.delete(sessionId);
+    }
+
+    // Clear requester state
+    for (const [, pending] of this.pendingOpens) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error("Terminal manager destroyed"));
+    }
+    this.pendingOpens.clear();
+    this.remoteSessions.clear();
+  }
+}