tower-studio 0.1.1 → 0.1.3

package/src/lib/pty/pty-session.ts

@@ -0,0 +1,157 @@
+import * as pty from "node-pty";
+import { ensurePathInEnv, stripClaudeNestingEnv } from "@/lib/platform";
+
+export class PtySession {
+  readonly taskId: string;
+  private readonly _pty: pty.IPty;
+  killed = false;
+  disconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Ring buffer: last 50 KB of PTY output for reconnect replay */
+  private _buffer = "";
+  private static readonly BUFFER_MAX = 50 * 1024; // 50 KB
+  /** Mutable data listener — replaced by ws-server on connect/disconnect */
+  private _onData: (data: string) => void;
+  /** Additional exit listeners — ws-server hooks in to send session_end to browser */
+  private _exitListeners: Array<(exitCode: number) => void> = [];
+
+  // Idle detection fields (NTFY-06, NTFY-07)
+  private _idleTimer: ReturnType<typeof setTimeout> | null = null;
+  private _idleThresholdMs: number;
+  private _onIdle: (() => void) | null;
+  private _idleFired = false;
+
+  constructor(
+    taskId: string,
+    command: string,
+    args: string[],
+    cwd: string,
+    onData: (data: string) => void,
+    onExit: (exitCode: number, signal?: number) => void,
+    envOverrides?: Record<string, string>,
+    onIdle?: () => void,
+    idleThresholdMs?: number
+  ) {
+    this.taskId = taskId;
+    this._onData = onData;
+    this._onIdle = onIdle ?? null;
+    this._idleThresholdMs = Math.max(idleThresholdMs ?? 180_000, 180_000);
+
+    // Build env: inherit full parent env, strip Claude nesting vars, ensure PATH exists
+    const baseEnv = stripClaudeNestingEnv(ensurePathInEnv(process.env));
+    this._pty = pty.spawn(command, args, {
+      name: "xterm-color",
+      cols: 80,
+      rows: 24,
+      cwd,
+      env: {
+        ...baseEnv,
+        TERM: "xterm-color",
+        ...envOverrides,
+      } as Record<string, string>,
+    });
+
+    this._pty.onData((data) => {
+      // Update ring buffer — keep last BUFFER_MAX bytes
+      this._buffer += data;
+      if (this._buffer.length > PtySession.BUFFER_MAX) {
+        this._buffer = this._buffer.slice(
+          this._buffer.length - PtySession.BUFFER_MAX
+        );
+      }
+      // NTFY-06: reset idle timer on every PTY output
+      this._resetIdleTimer();
+      this._onData(data);
+    });
+
+    // D-07: onExit sets killed=true but does NOT call pty.kill()
+    this._pty.onExit(({ exitCode, signal }) => {
+      this.killed = true;
+      // Clear idle timer on PTY exit — no callbacks fire after session ends
+      if (this._idleTimer) {
+        clearTimeout(this._idleTimer);
+        this._idleTimer = null;
+      }
+      onExit(exitCode, signal);
+      // Notify all registered exit listeners (ws-server uses this)
+      for (const listener of this._exitListeners) {
+        listener(exitCode);
+      }
+    });
+
+    // Start initial idle countdown
+    this._resetIdleTimer();
+  }
+
+  /**
+   * Reset the idle timer. Fires _onIdle after _idleThresholdMs of no activity.
+   * Called on PTY output and on user write() to reset the countdown.
+   */
+  private _resetIdleTimer(): void {
+    if (this._idleTimer) {
+      clearTimeout(this._idleTimer);
+      this._idleTimer = null;
+    }
+    if (this._onIdle === null || this.killed || this._idleFired) {
+      return;
+    }
+    this._idleTimer = setTimeout(() => {
+      this._idleFired = true;
+      this._onIdle?.();
+    }, this._idleThresholdMs);
+  }
+
+  /**
+   * Replace the live data listener — called by ws-server on connect/disconnect.
+   * Allows startPtyExecution to pre-create the session with a no-op onData,
+   * then the WebSocket handler wires in the real broadcaster on first connect.
+   */
+  setDataListener(fn: (data: string) => void): void {
+    this._onData = fn;
+  }
+
+  /** Register a callback for PTY exit — ws-server uses this to send session_end.
+   *  Replaces previous listeners to prevent accumulation on reconnect. */
+  setExitListener(fn: (exitCode: number | undefined) => void): void {
+    this._exitListeners = [fn];
+  }
+
+  write(data: string): void {
+    if (!this.killed) {
+      // NTFY-07: user input resets idle timer
+      this._resetIdleTimer();
+      this._pty.write(data);
+    }
+  }
+
+  resize(cols: number, rows: number): void {
+    if (!this.killed) {
+      this._pty.resize(cols, rows);
+    }
+  }
+
+  /** Returns buffered output for reconnect replay */
+  getBuffer(): string {
+    return this._buffer;
+  }
+
+  /** Returns true if the idle callback has fired — Phase 34 MCP tools use this */
+  get isIdle(): boolean {
+    return this._idleFired;
+  }
+
+  /** D-06: double-kill guard */
+  kill(): void {
+    if (this.killed) return;
+    this.killed = true;
+    // Clear idle timer when session is killed
+    if (this._idleTimer) {
+      clearTimeout(this._idleTimer);
+      this._idleTimer = null;
+    }
+    try {
+      this._pty.kill();
+    } catch {
+      // Already dead — safe to ignore
+    }
+  }
+}

package/src/lib/pty/session-store.ts

@@ -0,0 +1,67 @@
+import { PtySession } from "./pty-session";
+import { resolveSpawnTargetSync } from "@/lib/platform";
+
+// D-04: globalThis singleton — survives HMR/module re-evaluation in Next.js dev mode.
+// Without this, ws-server.ts (loaded once via instrumentation) and agent-actions.ts
+// (re-bundled on HMR) would get different Map instances, causing sessions to be invisible
+// to the WS server after creation.
+const g = globalThis as typeof globalThis & { __ptySessions?: Map<string, PtySession> };
+if (!g.__ptySessions) {
+  g.__ptySessions = new Map<string, PtySession>();
+}
+const sessions = g.__ptySessions;
+
+export function createSession(
+  taskId: string,
+  command: string,
+  args: string[],
+  cwd: string,
+  onData: (data: string) => void,
+  onExit: (exitCode: number, signal?: number) => void,
+  envOverrides?: Record<string, string>,
+  onIdle?: () => void,
+  idleThresholdMs?: number
+): PtySession {
+  // Destroy any existing session for this taskId before creating new one
+  destroySession(taskId);
+
+  // Resolve command for cross-platform PTY spawning (handles .cmd/.bat on Windows)
+  const { command: resolvedCommand, args: resolvedArgs } = resolveSpawnTargetSync(command, args);
+
+  const session = new PtySession(taskId, resolvedCommand, resolvedArgs, cwd, onData, onExit, envOverrides, onIdle, idleThresholdMs);
+  sessions.set(taskId, session);
+  return session;
+}
+
+export function getSession(taskId: string): PtySession | undefined {
+  return sessions.get(taskId);
+}
+
+export function destroySession(taskId: string): void {
+  const session = sessions.get(taskId);
+  if (!session) return;
+  sessions.delete(taskId);
+  if (session.disconnectTimer) {
+    clearTimeout(session.disconnectTimer);
+    session.disconnectTimer = null;
+  }
+  session.kill();
+}
+
+/** D-08: Called on SIGTERM — kills all sessions */
+export function destroyAllSessions(): void {
+  for (const taskId of sessions.keys()) {
+    destroySession(taskId);
+  }
+}
+
+// D-08: Register SIGTERM/SIGINT cleanup handler
+// Use once() to prevent listener accumulation across HMR reloads
+process.once("SIGTERM", () => {
+  console.error("[session-store] SIGTERM received — cleaning up PTY sessions");
+  destroyAllSessions();
+});
+process.once("SIGINT", () => {
+  console.error("[session-store] SIGINT received — cleaning up PTY sessions");
+  destroyAllSessions();
+});

package/src/lib/pty/ws-server.ts

@@ -0,0 +1,335 @@
+import { WebSocketServer, WebSocket } from "ws";
+import type { IncomingMessage } from "http";
+import { getSession, destroySession } from "./session-store";
+import { readConfigValue } from "@/lib/config-reader";
+import { ASSISTANT_SESSION_KEY } from "@/lib/assistant-constants";
+
+function getAllowedOrigins(): Set<string> {
+  const httpPort = parseInt(process.env.PORT || "3000", 10);
+  return new Set([
+    `http://localhost:${httpPort}`,
+    `http://127.0.0.1:${httpPort}`,
+  ]);
+}
+
+// Keepalive: how long a PTY session survives after WS disconnect.
+// Process still running → 2 hours (user may switch tasks, take a break).
+// Process already exited → 5 minutes (just preserving output buffer for review).
+const KEEPALIVE_RUNNING_MS = 2 * 60 * 60 * 1000; // 2 hours
+const KEEPALIVE_EXITED_MS = 5 * 60 * 1000;        // 5 minutes
+
+// Multicast: multiple WS clients can connect to the same PTY session
+// (e.g. task detail panel + Mission Control viewing the same task)
+const sessionClients = new Map<string, Set<WebSocket>>();
+
+// Global notification channel — clients connected with taskId=__notifications__
+const NOTIFICATION_CHANNEL = "__notifications__";
+const notificationClients = new Set<WebSocket>();
+
+/**
+ * Broadcast a JSON message to all connected notification clients.
+ * Called from API routes (e.g. Stop hook) to push events to the browser.
+ */
+export function broadcastNotification(payload: object): void {
+  const msg = JSON.stringify(payload);
+  for (const client of notificationClients) {
+    if (client.readyState === WebSocket.OPEN) {
+      client.send(msg);
+    }
+  }
+}
+
+const BATCH_INTERVAL_MS = 8;
+const SEND_BUFFER_MAX = 64 * 1024;
+
+const WS_PTY_EXIT_BASE = 4000; // 4000–4255: PTY 退出码 0–255 嵌入 WebSocket 关闭码（RFC 允许 1000–4999）
+const WS_PTY_UNKNOWN_EXIT = WS_PTY_EXIT_BASE + 255;
+
+/**
+ * node-pty 在进程被信号终止时 `exitCode` 可能为 `undefined`；Windows 上可能是大于 256 的 32 位无符号数。
+ * `client.close(4000 + undefined)` 会得到 NaN 并抛错。归一化到 0–255 再 +4000。
+ */
+function webSocketCloseCodeForPtyExit(exitCode: number | null | undefined): number {
+  if (exitCode == null) {
+    return WS_PTY_UNKNOWN_EXIT;
+  }
+  const n = Number(exitCode);
+  if (!Number.isFinite(n)) {
+    return WS_PTY_UNKNOWN_EXIT;
+  }
+  // 0–255 原样；否则取低 8 位（Windows 崩溃码 HRESULT 等）
+  const b = n >= 0 && n < 256 ? n | 0 : (n >>> 0) & 0xff;
+  const code = WS_PTY_EXIT_BASE + b;
+  // `ws` 要求关闭码在合法数值范围内
+  if (code < 1000 || code > 4999) {
+    return WS_PTY_UNKNOWN_EXIT;
+  }
+  return code;
+}
+
+function isPortInUse(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const { createServer } = require("net") as typeof import("net");
+    const tester = createServer();
+    tester.once("error", () => resolve(true));
+    tester.once("listening", () => { tester.close(() => resolve(false)); });
+    tester.listen(port, "127.0.0.1");
+  });
+}
+
+const g = globalThis as typeof globalThis & {
+  __wss?: InstanceType<typeof WebSocketServer>;
+  __wsPort?: number;
+};
+
+/** Get the actual WebSocket port the server is listening on. */
+export function getActiveWsPort(): number | null {
+  return g.__wsPort ?? null;
+}
+
+export async function startWsServer(): Promise<void> {
+  // Close previous server on HMR reload so fresh code always takes effect
+  if (g.__wss) {
+    const prev = g.__wss;
+    g.__wss = undefined;
+    await new Promise<void>((resolve) => {
+      prev.close(() => resolve());
+      // Fallback timeout in case close callback never fires
+      setTimeout(resolve, 1000);
+    });
+  }
+
+  const httpPort = parseInt(process.env.PORT || "3000", 10);
+  const defaultWsPort = httpPort + 1;
+  const preferredPort = await readConfigValue<number>("terminal.wsPort", defaultWsPort);
+
+  // Try preferred port, then increment up to 10 times to find a free one
+  const MAX_RETRIES = 10;
+  let wsPort = preferredPort;
+  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+    const inUse = await isPortInUse(wsPort);
+    if (!inUse) break;
+    if (attempt === MAX_RETRIES - 1) {
+      console.error(`[ws-server] No free port found after trying ${preferredPort}–${wsPort} — skipping startup`);
+      return;
+    }
+    console.error(`[ws-server] Port ${wsPort} in use, trying ${wsPort + 1}...`);
+    wsPort++;
+  }
+
+  const wss = new WebSocketServer({ port: wsPort, host: "127.0.0.1", perMessageDeflate: false });
+  g.__wss = wss;
+  g.__wsPort = wsPort;
+  if (wsPort !== preferredPort) {
+    console.error(`[ws-server] WebSocket server listening on port ${wsPort} (preferred ${preferredPort} was occupied)`);
+  } else {
+    console.error(`[ws-server] WebSocket server listening on port ${wsPort}`);
+  }
+
+  // Close WS server on SIGINT (Ctrl+C) to release port
+  const closeWss = () => {
+    wss.close();
+    g.__wss = undefined;
+    g.__wsPort = undefined;
+  };
+  // Use once() to prevent listener accumulation across HMR reloads
+  process.once("SIGINT", closeWss);
+  process.once("SIGTERM", closeWss);
+
+  wss.on("connection", (ws: WebSocket, req: IncomingMessage) => {
+    const origin = req.headers.origin ?? "";
+    if (!getAllowedOrigins().has(origin)) {
+      console.error(`[ws-server] Rejected origin: ${origin || "(none)"}`);
+      ws.close(1008, "Forbidden");
+      return;
+    }
+
+    const url = new URL(req.url ?? "/", `http://localhost:${wsPort}`);
+    const taskId = url.searchParams.get("taskId");
+
+    if (!taskId) {
+      ws.close(1008, "Missing taskId");
+      return;
+    }
+
+    // Notification channel — lightweight listener for global events (stop, completion)
+    if (taskId === NOTIFICATION_CHANNEL) {
+      notificationClients.add(ws);
+      ws.on("close", () => notificationClients.delete(ws));
+      ws.on("error", () => notificationClients.delete(ws));
+      return;
+    }
+
+    // Security: __assistant__ is a deliberate exception to the CUID taskId convention.
+    // The assistant session uses a fixed key (not a CUID) because it has no TaskExecution
+    // DB row. Origin checking (getAllowedOrigins() above) mitigates cross-origin access.
+    // Non-existent session keys simply time out after 30s (poll loop below).
+
+    console.error(`[ws-server] Connection for task ${taskId}`);
+
+    let session = getSession(taskId);
+    let pollTimer: ReturnType<typeof setInterval> | null = null;
+
+    if (session) {
+      wireSession(session, ws, taskId);
+      console.error(`[ws-server] Attached to existing session for task ${taskId}`);
+    } else {
+      console.error(`[ws-server] No session for task ${taskId} — polling...`);
+      let waited = 0;
+      pollTimer = setInterval(() => {
+        waited += 500;
+        session = getSession(taskId);
+        if (session) {
+          clearInterval(pollTimer!); pollTimer = null;
+          wireSession(session, ws, taskId);
+          console.error(`[ws-server] Session appeared for task ${taskId} after ${waited}ms`);
+        } else if (waited >= 30_000 || ws.readyState !== WebSocket.OPEN) {
+          clearInterval(pollTimer!); pollTimer = null;
+          if (ws.readyState === WebSocket.OPEN) {
+            ws.close(1008, "No PTY session created within timeout.");
+          }
+        }
+      }, 500);
+    }
+
+    ws.on("message", (rawData) => {
+      if (!session) return;
+      const data = rawData.toString();
+      if (data.startsWith("{")) {
+        try {
+          const msg = JSON.parse(data) as { type?: string; cols?: number; rows?: number };
+          if (msg.type === "resize" && typeof msg.cols === "number" && typeof msg.rows === "number") {
+            session.resize(msg.cols, msg.rows);
+            return;
+          }
+        } catch { /* not JSON */ }
+      }
+      session.write(data);
+    });
+
+    ws.on("close", () => {
+      // Flush any pending batched data
+      (ws as WebSocket & { _batcher?: BatchedSender })._batcher?.flush();
+
+      const clients = sessionClients.get(taskId);
+      if (!clients?.has(ws)) return;
+      clients.delete(ws);
+      console.error(`[ws-server] WS disconnected for task ${taskId} (${clients.size} remaining)`);
+
+      // If other clients still connected, keep session alive
+      if (clients.size > 0) return;
+
+      sessionClients.delete(taskId);
+      const s = getSession(taskId);
+      if (!s) return;
+      s.setDataListener(() => {});
+
+      // Assistant sessions: stateless — destroy immediately on disconnect (BE-05)
+      if (taskId === ASSISTANT_SESSION_KEY) {
+        console.error(`[ws-server] Assistant session disconnected — destroying immediately`);
+        destroySession(taskId);
+        return;
+      }
+
+      const timeout = s.killed ? KEEPALIVE_EXITED_MS : KEEPALIVE_RUNNING_MS;
+      s.disconnectTimer = setTimeout(() => {
+        console.error(`[ws-server] Keepalive expired for task ${taskId}`);
+        destroySession(taskId);
+      }, timeout);
+    });
+
+    ws.on("error", (err) => {
+      console.error(`[ws-server] WS error for task ${taskId}:`, err.message);
+      // Clear polling timer if still active
+      if (pollTimer) { clearInterval(pollTimer); pollTimer = null; }
+      const clients = sessionClients.get(taskId);
+      if (!clients?.has(ws)) return;
+      clients.delete(ws);
+      if (clients.size > 0) return;
+      sessionClients.delete(taskId);
+      const s = getSession(taskId);
+      if (s && !s.killed) s.setDataListener(() => {});
+    });
+  });
+}
+
+function wireSession(session: import("./pty-session").PtySession, ws: WebSocket, taskId: string): void {
+  if (session.disconnectTimer) {
+    clearTimeout(session.disconnectTimer);
+    session.disconnectTimer = null;
+  }
+
+  // Add this WS to the client set
+  let clients = sessionClients.get(taskId);
+  if (!clients) {
+    clients = new Set();
+    sessionClients.set(taskId, clients);
+  }
+  clients.add(ws);
+
+  // Create batcher for this specific WS client
+  const batcher = makeBatchedSender(ws);
+  (ws as WebSocket & { _batcher?: BatchedSender })._batcher = batcher;
+
+  // Multicast data listener — broadcasts to ALL connected clients.
+  // setDataListener replaces the single listener (last-writer-wins by design).
+  // This is safe because `currentClients` captures the shared Set reference:
+  // when a new client connects, wireSession re-registers with the same Set,
+  // so the new lambda still broadcasts to all clients including earlier ones.
+  const currentClients = clients;
+  session.setDataListener((data: string) => {
+    for (const client of currentClients) {
+      const b = (client as WebSocket & { _batcher?: BatchedSender })._batcher;
+      if (b) {
+        b.send(data);
+      } else if (client.readyState === WebSocket.OPEN) {
+        client.send(data);
+      }
+    }
+  });
+
+  // Replay buffer for this new client
+  const buffer = session.getBuffer();
+  if (buffer && ws.readyState === WebSocket.OPEN) {
+    ws.send(buffer);
+  }
+
+  // Set up exit listener — notify ALL connected clients
+  session.setExitListener((exitCode) => {
+    const closeCode = webSocketCloseCodeForPtyExit(exitCode);
+    for (const client of currentClients) {
+      if (client.readyState === WebSocket.OPEN) {
+        client.close(closeCode, "session_end");
+      }
+    }
+  });
+}
+
+interface BatchedSender {
+  send: (data: string) => void;
+  flush: () => void;
+}
+
+function makeBatchedSender(ws: WebSocket): BatchedSender {
+  let pending = "";
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const flush = () => {
+    if (timer) { clearTimeout(timer); timer = null; }
+    if (pending && ws.readyState === WebSocket.OPEN && ws.bufferedAmount < SEND_BUFFER_MAX) {
+      ws.send(pending);
+    }
+    pending = "";
+  };
+  const send = (data: string) => {
+    pending += data;
+    if (timer) return;
+    timer = setTimeout(() => {
+      timer = null;
+      if (ws.readyState === WebSocket.OPEN && ws.bufferedAmount < SEND_BUFFER_MAX) {
+        ws.send(pending);
+      }
+      pending = "";
+    }, BATCH_INTERVAL_MS);
+  };
+  return { send, flush };
+}

package/src/lib/schemas.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+
+// Shared ID validator
+const cuid = z.string().min(1, "ID is required");
+
+// ── Workspace schemas ──
+export const createWorkspaceSchema = z.object({
+  name: z.string().min(1, "Name is required").max(100),
+  description: z.string().max(500).optional(),
+});
+
+export const updateWorkspaceSchema = z.object({
+  name: z.string().min(1).max(100).optional(),
+  description: z.string().max(500).optional(),
+});
+
+// ── Project schemas ──
+export const createProjectSchema = z.object({
+  name: z.string().min(1, "Name is required").max(100),
+  alias: z.string().max(100).optional(),
+  description: z.string().max(5000).optional(),
+  gitUrl: z.string().max(500).optional().or(z.literal("")),
+  localPath: z.string().optional(),
+  workspaceId: cuid,
+  projectType: z.enum(["FRONTEND", "BACKEND"]).optional(),
+  previewCommand: z.string().max(500).nullable().optional(),
+});
+
+export const updateProjectSchema = z.object({
+  name: z.string().min(1).max(100).optional(),
+  alias: z.string().max(100).optional(),
+  description: z.string().max(5000).optional(),
+  localPath: z.string().optional(),
+  projectType: z.enum(["FRONTEND", "BACKEND"]).optional(),
+  previewCommand: z.string().max(500).nullable().optional(),
+  previewPort: z.number().int().min(1).max(65535).nullable().optional(),
+});
+
+// ── Task schemas ──
+export const createTaskSchema = z.object({
+  title: z.string().min(1, "Title is required").max(200),
+  description: z.string().max(5000).optional(),
+  projectId: cuid,
+  priority: z.enum(["LOW", "MEDIUM", "HIGH", "CRITICAL"]).optional(),
+  status: z.enum(["TODO", "IN_PROGRESS", "IN_REVIEW", "DONE", "CANCELLED"]).optional(),
+  labelIds: z.array(cuid).optional(),
+  baseBranch: z.string().max(200).optional(),
+  subPath: z.string().max(500).optional(),
+});
+
+export const updateTaskSchema = z.object({
+  title: z.string().min(1).max(200).optional(),
+  description: z.string().max(5000).optional(),
+  priority: z.enum(["LOW", "MEDIUM", "HIGH", "CRITICAL"]).optional(),
+  labelIds: z.array(cuid).optional(),
+  baseBranch: z.string().max(200).optional(),
+  subPath: z.string().max(500).optional(),
+});
+
+export const taskStatusSchema = z.enum(["TODO", "IN_PROGRESS", "IN_REVIEW", "DONE", "CANCELLED"]);
+
+// ── Label schemas ──
+export const createLabelSchema = z.object({
+  name: z.string().min(1, "Name is required").max(50),
+  color: z.string().regex(/^#[0-9a-fA-F]{6}$/, "Invalid hex color"),
+  workspaceId: cuid,
+});