@covibes/zeroshot 1.0.1

package/src/attach/protocol.js

@@ -0,0 +1,220 @@
+/**
+ * Protocol - Message framing for attach/detach IPC
+ *
+ * Uses length-prefixed JSON messages over Unix sockets.
+ * Format: [4-byte length (BE)] [JSON payload]
+ *
+ * Message Types:
+ *
+ * Client → Server:
+ *   ATTACH    { type: 'attach', clientId, cols, rows }
+ *   DETACH    { type: 'detach', clientId }
+ *   RESIZE    { type: 'resize', cols, rows }
+ *   SIGNAL    { type: 'signal', signal: 'SIGINT' | 'SIGTERM' }
+ *   STDIN     { type: 'stdin', data: base64 }  (future interactive mode)
+ *
+ * Server → Client:
+ *   OUTPUT    { type: 'output', data: base64, timestamp }
+ *   HISTORY   { type: 'history', data: base64 }
+ *   STATE     { type: 'state', status, pid, ... }
+ *   EXIT      { type: 'exit', code, signal }
+ *   ERROR     { type: 'error', message }
+ */
+
+const MAX_MESSAGE_SIZE = 10 * 1024 * 1024; // 10MB max message
+
+/**
+ * Encode a message for transmission
+ * @param {object} message - Message object to encode
+ * @returns {Buffer} - Length-prefixed encoded message
+ */
+function encode(message) {
+  const json = JSON.stringify(message);
+  const payload = Buffer.from(json, 'utf8');
+
+  if (payload.length > MAX_MESSAGE_SIZE) {
+    throw new Error(`Message too large: ${payload.length} bytes (max ${MAX_MESSAGE_SIZE})`);
+  }
+
+  const frame = Buffer.alloc(4 + payload.length);
+  frame.writeUInt32BE(payload.length, 0);
+  payload.copy(frame, 4);
+
+  return frame;
+}
+
+/**
+ * MessageDecoder - Streaming decoder for framed messages
+ *
+ * Handles partial reads and message reassembly.
+ */
+class MessageDecoder {
+  constructor() {
+    this.buffer = Buffer.alloc(0);
+  }
+
+  /**
+   * Feed data into the decoder
+   * @param {Buffer} data - Received data chunk
+   * @returns {object[]} - Array of decoded messages (may be empty)
+   */
+  feed(data) {
+    this.buffer = Buffer.concat([this.buffer, data]);
+    const messages = [];
+
+    while (this.buffer.length >= 4) {
+      const length = this.buffer.readUInt32BE(0);
+
+      if (length > MAX_MESSAGE_SIZE) {
+        throw new Error(`Message too large: ${length} bytes (max ${MAX_MESSAGE_SIZE})`);
+      }
+
+      if (this.buffer.length < 4 + length) {
+        // Incomplete message, wait for more data
+        break;
+      }
+
+      const payload = this.buffer.slice(4, 4 + length);
+      this.buffer = this.buffer.slice(4 + length);
+
+      try {
+        const message = JSON.parse(payload.toString('utf8'));
+        messages.push(message);
+      } catch (e) {
+        throw new Error(`Invalid JSON in message: ${e.message}`);
+      }
+    }
+
+    return messages;
+  }
+
+  /**
+   * Reset decoder state
+   */
+  reset() {
+    this.buffer = Buffer.alloc(0);
+  }
+}
+
+// Message type constants
+const MessageType = {
+  // Client → Server
+  ATTACH: 'attach',
+  DETACH: 'detach',
+  RESIZE: 'resize',
+  SIGNAL: 'signal',
+  STDIN: 'stdin',
+
+  // Server → Client
+  OUTPUT: 'output',
+  HISTORY: 'history',
+  STATE: 'state',
+  EXIT: 'exit',
+  ERROR: 'error',
+};
+
+// Helper functions to create messages
+
+/**
+ * Create an ATTACH message
+ */
+function createAttachMessage(clientId, cols, rows) {
+  return { type: MessageType.ATTACH, clientId, cols, rows };
+}
+
+/**
+ * Create a DETACH message
+ */
+function createDetachMessage(clientId) {
+  return { type: MessageType.DETACH, clientId };
+}
+
+/**
+ * Create a RESIZE message
+ */
+function createResizeMessage(cols, rows) {
+  return { type: MessageType.RESIZE, cols, rows };
+}
+
+/**
+ * Create a SIGNAL message
+ */
+function createSignalMessage(signal) {
+  if (!['SIGINT', 'SIGTERM', 'SIGKILL', 'SIGTSTP'].includes(signal)) {
+    throw new Error(`Invalid signal: ${signal}`);
+  }
+  return { type: MessageType.SIGNAL, signal };
+}
+
+/**
+ * Create a STDIN message (for future interactive mode)
+ */
+function createStdinMessage(data) {
+  const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+  return { type: MessageType.STDIN, data: buf.toString('base64') };
+}
+
+/**
+ * Create an OUTPUT message
+ */
+function createOutputMessage(data, timestamp = Date.now()) {
+  const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+  return { type: MessageType.OUTPUT, data: buf.toString('base64'), timestamp };
+}
+
+/**
+ * Create a HISTORY message
+ */
+function createHistoryMessage(data) {
+  const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+  return { type: MessageType.HISTORY, data: buf.toString('base64') };
+}
+
+/**
+ * Create a STATE message
+ */
+function createStateMessage(state) {
+  return { type: MessageType.STATE, ...state };
+}
+
+/**
+ * Create an EXIT message
+ */
+function createExitMessage(code, signal) {
+  return { type: MessageType.EXIT, code, signal };
+}
+
+/**
+ * Create an ERROR message
+ */
+function createErrorMessage(message) {
+  return { type: MessageType.ERROR, message };
+}
+
+/**
+ * Decode base64 data field from OUTPUT/HISTORY/STDIN messages
+ */
+function decodeData(message) {
+  if (message.data) {
+    return Buffer.from(message.data, 'base64');
+  }
+  return null;
+}
+
+module.exports = {
+  encode,
+  MessageDecoder,
+  MessageType,
+  createAttachMessage,
+  createDetachMessage,
+  createResizeMessage,
+  createSignalMessage,
+  createStdinMessage,
+  createOutputMessage,
+  createHistoryMessage,
+  createStateMessage,
+  createExitMessage,
+  createErrorMessage,
+  decodeData,
+  MAX_MESSAGE_SIZE,
+};

package/src/attach/ring-buffer.js

@@ -0,0 +1,121 @@
+/**
+ * RingBuffer - Fixed-size circular buffer for output history
+ *
+ * Used by AttachServer to store recent output for late-joining clients.
+ * When buffer fills, oldest data is overwritten.
+ *
+ * Design:
+ * - Fixed allocation (no dynamic resizing)
+ * - O(1) write and read operations
+ * - Thread-safe for single writer (Node.js is single-threaded)
+ */
+
+class RingBuffer {
+  /**
+   * @param {number} maxSize - Maximum buffer size in bytes (default 1MB)
+   */
+  constructor(maxSize = 1024 * 1024) {
+    if (maxSize <= 0) {
+      throw new Error('RingBuffer maxSize must be positive');
+    }
+    this.buffer = Buffer.alloc(maxSize);
+    this.maxSize = maxSize;
+    this.writePos = 0; // Next write position
+    this.size = 0; // Current data size (0 to maxSize)
+  }
+
+  /**
+   * Write data to the buffer
+   * @param {Buffer|string} data - Data to write
+   */
+  write(data) {
+    const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+
+    if (buf.length === 0) return;
+
+    // If data is larger than buffer, only keep the last maxSize bytes
+    if (buf.length >= this.maxSize) {
+      buf.copy(this.buffer, 0, buf.length - this.maxSize);
+      this.writePos = 0;
+      this.size = this.maxSize;
+      return;
+    }
+
+    // Calculate how much wraps around
+    const spaceToEnd = this.maxSize - this.writePos;
+
+    if (buf.length <= spaceToEnd) {
+      // No wrap needed
+      buf.copy(this.buffer, this.writePos);
+      this.writePos += buf.length;
+    } else {
+      // Wrap around
+      buf.copy(this.buffer, this.writePos, 0, spaceToEnd);
+      buf.copy(this.buffer, 0, spaceToEnd);
+      this.writePos = buf.length - spaceToEnd;
+    }
+
+    // Update size (capped at maxSize)
+    this.size = Math.min(this.size + buf.length, this.maxSize);
+  }
+
+  /**
+   * Read all buffered data
+   * @returns {Buffer} - All data currently in buffer
+   */
+  read() {
+    if (this.size === 0) {
+      return Buffer.alloc(0);
+    }
+
+    const result = Buffer.alloc(this.size);
+
+    if (this.size < this.maxSize) {
+      // Buffer not full yet, data starts at 0
+      this.buffer.copy(result, 0, 0, this.size);
+    } else {
+      // Buffer is full, data starts at writePos (oldest data)
+      const startPos = this.writePos;
+      const firstChunkSize = this.maxSize - startPos;
+
+      this.buffer.copy(result, 0, startPos, this.maxSize);
+      this.buffer.copy(result, firstChunkSize, 0, startPos);
+    }
+
+    return result;
+  }
+
+  /**
+   * Clear the buffer
+   */
+  clear() {
+    this.writePos = 0;
+    this.size = 0;
+  }
+
+  /**
+   * Get current data size
+   * @returns {number}
+   */
+  getSize() {
+    return this.size;
+  }
+
+  /**
+   * Check if buffer is empty
+   * @returns {boolean}
+   */
+  isEmpty() {
+    return this.size === 0;
+  }
+
+  /**
+   * Check if buffer is full
+   * @returns {boolean}
+   */
+  isFull() {
+    return this.size === this.maxSize;
+  }
+}
+
+module.exports = RingBuffer;

package/src/attach/socket-discovery.js

@@ -0,0 +1,242 @@
+/**
+ * Socket Discovery - Utilities for socket path management
+ *
+ * Socket locations:
+ * - Tasks: ~/.zeroshot/sockets/task-<id>.sock
+ * - Clusters: ~/.zeroshot/sockets/cluster-<id>.sock (cluster-level, future)
+ * - Agents: ~/.zeroshot/sockets/cluster-<id>/<agent-id>.sock
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const net = require('net');
+
+const CREW_DIR = path.join(os.homedir(), '.zeroshot');
+const SOCKET_DIR = path.join(CREW_DIR, 'sockets');
+
+/**
+ * Ensure socket directory exists
+ */
+function ensureSocketDir() {
+  if (!fs.existsSync(SOCKET_DIR)) {
+    fs.mkdirSync(SOCKET_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Get socket path for a task
+ * @param {string} taskId - Task ID (e.g., 'task-swift-falcon')
+ * @returns {string} - Socket path
+ */
+function getTaskSocketPath(taskId) {
+  ensureSocketDir();
+  return path.join(SOCKET_DIR, `${taskId}.sock`);
+}
+
+/**
+ * Get socket path for a cluster agent
+ * @param {string} clusterId - Cluster ID (e.g., 'cluster-bold-eagle')
+ * @param {string} agentId - Agent ID (e.g., 'worker')
+ * @returns {string} - Socket path
+ */
+function getAgentSocketPath(clusterId, agentId) {
+  const clusterDir = path.join(SOCKET_DIR, clusterId);
+  if (!fs.existsSync(clusterDir)) {
+    fs.mkdirSync(clusterDir, { recursive: true });
+  }
+  return path.join(clusterDir, `${agentId}.sock`);
+}
+
+/**
+ * Get socket path for any ID (auto-detects task vs cluster)
+ * @param {string} id - Task or cluster ID
+ * @param {string} [agentId] - Optional agent ID for clusters
+ * @returns {string} - Socket path
+ */
+function getSocketPath(id, agentId = null) {
+  if (id.startsWith('task-')) {
+    return getTaskSocketPath(id);
+  }
+  if (id.startsWith('cluster-')) {
+    if (agentId) {
+      return getAgentSocketPath(id, agentId);
+    }
+    // Cluster-level socket (future use)
+    ensureSocketDir();
+    return path.join(SOCKET_DIR, `${id}.sock`);
+  }
+  // Unknown format, treat as task
+  return getTaskSocketPath(id);
+}
+
+/**
+ * Check if a socket exists and is connectable
+ * @param {string} socketPath - Path to socket file
+ * @returns {Promise<boolean>} - True if socket is live
+ */
+function isSocketAlive(socketPath) {
+  if (!fs.existsSync(socketPath)) {
+    return Promise.resolve(false);
+  }
+
+  return new Promise((resolve) => {
+    const socket = net.createConnection(socketPath);
+    const timeout = setTimeout(() => {
+      socket.destroy();
+      resolve(false);
+    }, 1000);
+
+    socket.on('connect', () => {
+      clearTimeout(timeout);
+      socket.end();
+      resolve(true);
+    });
+
+    socket.on('error', () => {
+      clearTimeout(timeout);
+      resolve(false);
+    });
+  });
+}
+
+/**
+ * Remove stale socket file if not connectable
+ * @param {string} socketPath - Path to socket file
+ * @returns {Promise<boolean>} - True if socket was removed (stale)
+ */
+async function cleanupStaleSocket(socketPath) {
+  if (!fs.existsSync(socketPath)) {
+    return false;
+  }
+
+  const alive = await isSocketAlive(socketPath);
+  if (!alive) {
+    try {
+      fs.unlinkSync(socketPath);
+      return true;
+    } catch {
+      // Ignore errors (file may have been removed already)
+    }
+  }
+  return false;
+}
+
+/**
+ * List all attachable tasks
+ * Task sockets are .sock files directly in SOCKET_DIR (not in subdirectories)
+ * Excludes cluster-level sockets (cluster-xxx.sock) since those aren't tasks
+ * @returns {Promise<string[]>} - Array of task IDs with live sockets
+ */
+async function listAttachableTasks() {
+  ensureSocketDir();
+  const entries = fs.readdirSync(SOCKET_DIR, { withFileTypes: true });
+  const tasks = [];
+
+  for (const entry of entries) {
+    // Check socket files (Unix sockets report isSocket(), not isFile())
+    // Also accept regular files for compatibility
+    const isSocketFile = (entry.isSocket() || entry.isFile()) && entry.name.endsWith('.sock');
+    if (isSocketFile && !entry.isDirectory()) {
+      const id = entry.name.slice(0, -5); // Remove .sock
+
+      // Skip cluster-level sockets (cluster-xxx.sock)
+      if (id.startsWith('cluster-')) {
+        continue;
+      }
+
+      const socketPath = path.join(SOCKET_DIR, entry.name);
+      if (await isSocketAlive(socketPath)) {
+        tasks.push(id);
+      }
+    }
+  }
+
+  return tasks;
+}
+
+/**
+ * List all attachable agents for a cluster
+ * @param {string} clusterId - Cluster ID
+ * @returns {Promise<string[]>} - Array of agent IDs with live sockets
+ */
+async function listAttachableAgents(clusterId) {
+  const clusterDir = path.join(SOCKET_DIR, clusterId);
+  if (!fs.existsSync(clusterDir)) {
+    return [];
+  }
+
+  const files = fs.readdirSync(clusterDir);
+  const agents = [];
+
+  for (const file of files) {
+    if (file.endsWith('.sock')) {
+      const agentId = file.slice(0, -5); // Remove .sock
+      const socketPath = path.join(clusterDir, file);
+      if (await isSocketAlive(socketPath)) {
+        agents.push(agentId);
+      }
+    }
+  }
+
+  return agents;
+}
+
+/**
+ * List all attachable clusters
+ * @returns {Promise<string[]>} - Array of cluster IDs with at least one live agent socket
+ */
+async function listAttachableClusters() {
+  ensureSocketDir();
+  const entries = fs.readdirSync(SOCKET_DIR, { withFileTypes: true });
+  const clusters = [];
+
+  for (const entry of entries) {
+    if (entry.isDirectory() && entry.name.startsWith('cluster-')) {
+      const agents = await listAttachableAgents(entry.name);
+      if (agents.length > 0) {
+        clusters.push(entry.name);
+      }
+    }
+  }
+
+  return clusters;
+}
+
+/**
+ * Cleanup all sockets for a cluster (on cluster stop)
+ * @param {string} clusterId - Cluster ID
+ */
+function cleanupClusterSockets(clusterId) {
+  const clusterDir = path.join(SOCKET_DIR, clusterId);
+  if (fs.existsSync(clusterDir)) {
+    const files = fs.readdirSync(clusterDir);
+    for (const file of files) {
+      try {
+        fs.unlinkSync(path.join(clusterDir, file));
+      } catch {
+        // Ignore
+      }
+    }
+    try {
+      fs.rmdirSync(clusterDir);
+    } catch {
+      // Ignore
+    }
+  }
+}
+
+module.exports = {
+  CREW_DIR,
+  SOCKET_DIR,
+  ensureSocketDir,
+  getTaskSocketPath,
+  getAgentSocketPath,
+  getSocketPath,
+  isSocketAlive,
+  cleanupStaleSocket,
+  listAttachableTasks,
+  listAttachableAgents,
+  listAttachableClusters,
+  cleanupClusterSockets,
+};