@the-open-engine/zeroshot 6.38.0 → 6.39.0

package/src/attach/protocol.ts

@@ -0,0 +1,181 @@
+/**
+ * Protocol - Message framing for attach/detach IPC
+ *
+ * Uses length-prefixed JSON messages over Unix sockets.
+ * Format: [4-byte length (BE)] [JSON payload]
+ */
+
+const MAX_MESSAGE_SIZE = 10 * 1024 * 1024; // 10MB max message
+
+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',
+} as const;
+
+type BinaryData = Buffer | string;
+type MessageWithData = { data?: string | null };
+type AttachMessage = {
+  type: typeof MessageType.ATTACH;
+  clientId: string;
+  cols: number;
+  rows: number;
+};
+type DetachMessage = { type: typeof MessageType.DETACH; clientId: string };
+type ResizeMessage = { type: typeof MessageType.RESIZE; cols: number; rows: number };
+type SignalMessage = { type: typeof MessageType.SIGNAL; signal: string };
+type DataMessage<T extends string> = { type: T; data: string };
+type OutputMessage = DataMessage<typeof MessageType.OUTPUT> & { timestamp: number };
+type ExitMessage = {
+  type: typeof MessageType.EXIT;
+  code: number | null;
+  signal: string | number | undefined | null;
+};
+type ErrorMessage = { type: typeof MessageType.ERROR; message: string };
+
+/** Encode a message for transmission. */
+function encode(message: object): Buffer {
+  const json = JSON.stringify(message) as string;
+  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;
+}
+
+/** Streaming decoder for framed messages. */
+class MessageDecoder {
+  buffer: Buffer;
+
+  constructor() {
+    this.buffer = Buffer.alloc(0);
+  }
+
+  /** Feed a received data chunk into the decoder. */
+  feed(data: Buffer): unknown[] {
+    this.buffer = Buffer.concat([this.buffer, data]);
+    const messages: unknown[] = [];
+
+    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: unknown = JSON.parse(payload.toString('utf8'));
+        messages.push(message);
+      } catch (error: unknown) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid JSON in message: ${reason}`);
+      }
+    }
+
+    return messages;
+  }
+
+  /** Reset decoder state. */
+  reset(): void {
+    this.buffer = Buffer.alloc(0);
+  }
+}
+
+function createAttachMessage(clientId: string, cols: number, rows: number): AttachMessage {
+  return { type: MessageType.ATTACH, clientId, cols, rows };
+}
+
+function createDetachMessage(clientId: string): DetachMessage {
+  return { type: MessageType.DETACH, clientId };
+}
+
+function createResizeMessage(cols: number, rows: number): ResizeMessage {
+  return { type: MessageType.RESIZE, cols, rows };
+}
+
+function createSignalMessage(signal: string): SignalMessage {
+  if (!['SIGINT', 'SIGTERM', 'SIGKILL', 'SIGTSTP'].includes(signal)) {
+    throw new Error(`Invalid signal: ${signal}`);
+  }
+  return { type: MessageType.SIGNAL, signal };
+}
+
+function createStdinMessage(data: BinaryData): DataMessage<typeof MessageType.STDIN> {
+  const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+  return { type: MessageType.STDIN, data: buf.toString('base64') };
+}
+
+function createOutputMessage(data: BinaryData, timestamp = Date.now()): OutputMessage {
+  const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+  return { type: MessageType.OUTPUT, data: buf.toString('base64'), timestamp };
+}
+
+function createHistoryMessage(data: BinaryData): DataMessage<typeof MessageType.HISTORY> {
+  const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+  return { type: MessageType.HISTORY, data: buf.toString('base64') };
+}
+
+function createStateMessage(state: Record<string, unknown>): Record<string, unknown> {
+  return { type: MessageType.STATE, ...state };
+}
+
+function createExitMessage(
+  code: number | null,
+  signal: string | number | undefined | null
+): ExitMessage {
+  return { type: MessageType.EXIT, code, signal };
+}
+
+function createErrorMessage(message: string): ErrorMessage {
+  return { type: MessageType.ERROR, message };
+}
+
+/** Decode the base64 data field from OUTPUT/HISTORY/STDIN messages. */
+function decodeData(message: MessageWithData): Buffer | null {
+  if (message.data) {
+    return Buffer.from(message.data, 'base64');
+  }
+  return null;
+}
+
+export = {
+  encode,
+  MessageDecoder,
+  MessageType,
+  createAttachMessage,
+  createDetachMessage,
+  createResizeMessage,
+  createSignalMessage,
+  createStdinMessage,
+  createOutputMessage,
+  createHistoryMessage,
+  createStateMessage,
+  createExitMessage,
+  createErrorMessage,
+  decodeData,
+  MAX_MESSAGE_SIZE,
+};

package/src/attach/ring-buffer.js

@@ -1,3 +1,4 @@
+"use strict";
 /**
  * RingBuffer - Fixed-size circular buffer for output history
  *
@@ -9,113 +10,86 @@
  * - 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');
+    buffer;
+    maxSize;
+    writePos;
+    size;
+    /**
+     * @param 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)
     }
-    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;
+    /** Write data to the buffer. */
+    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);
     }
-
-    // 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;
+    /** Read all buffered data. */
+    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;
     }
-
-    // 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);
+    /** Clear the buffer. */
+    clear() {
+        this.writePos = 0;
+        this.size = 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);
+    /** Get current data size. */
+    getSize() {
+        return this.size;
+    }
+    /** Check if buffer is empty. */
+    isEmpty() {
+        return this.size === 0;
+    }
+    /** Check if buffer is full. */
+    isFull() {
+        return this.size === this.maxSize;
     }
-
-    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/ring-buffer.ts

@@ -0,0 +1,109 @@
+/**
+ * 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 {
+  buffer: Buffer;
+  maxSize: number;
+  writePos: number;
+  size: number;
+
+  /**
+   * @param 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. */
+  write(data: Buffer | string): void {
+    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. */
+  read(): Buffer {
+    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(): void {
+    this.writePos = 0;
+    this.size = 0;
+  }
+
+  /** Get current data size. */
+  getSize(): number {
+    return this.size;
+  }
+
+  /** Check if buffer is empty. */
+  isEmpty(): boolean {
+    return this.size === 0;
+  }
+
+  /** Check if buffer is full. */
+  isFull(): boolean {
+    return this.size === this.maxSize;
+  }
+}
+
+export = RingBuffer;

package/src/attach/send-input.js

@@ -1,88 +1,77 @@
+"use strict";
 /**
  * sendInput - write stdin data to a live attach socket
  *
  * Uses the attach protocol's STDIN message to forward input to the PTY.
  * Returns { ok, error } instead of throwing on transport failures.
  */
-
-const net = require('net');
-const fs = require('fs');
-const protocol = require('./protocol');
-
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_net_1 = __importDefault(require("node:net"));
+const protocol_1 = __importDefault(require("./protocol"));
 const DEFAULT_TIMEOUT_MS = 1500;
-
-/**
- * Send input to an attach socket via STDIN message.
- * @param {object} options
- * @param {string} options.socketPath - Unix socket path
- * @param {Buffer|string} options.data - Data to send
- * @param {number} [options.timeoutMs=1500] - Timeout in ms
- * @returns {Promise<{ok: boolean, error: string|null}>}
- */
+/** Send input to an attach socket via STDIN message. */
 function sendInput(options = {}) {
-  const { socketPath, data, timeoutMs = DEFAULT_TIMEOUT_MS } = options;
-
-  if (!socketPath) {
-    throw new Error('sendInput: socketPath is required');
-  }
-
-  if (data === undefined || data === null) {
-    throw new Error('sendInput: data is required');
-  }
-
-  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
-    throw new Error(`sendInput: timeoutMs must be positive (got ${timeoutMs})`);
-  }
-
-  if (!fs.existsSync(socketPath)) {
-    return { ok: false, error: `Socket not found: ${socketPath}` };
-  }
-
-  return new Promise((resolve) => {
-    let settled = false;
-    let timeout;
-    const socket = net.createConnection(socketPath);
-
-    const finish = (result) => {
-      if (settled) return;
-      settled = true;
-      if (timeout) {
-        clearTimeout(timeout);
-      }
-      try {
-        socket.end();
-        socket.destroy();
-      } catch (cleanupError) {
-        console.warn('[sendInput] socket cleanup failed:', cleanupError);
-      }
-      resolve(result);
-    };
-
-    timeout = setTimeout(() => {
-      finish({ ok: false, error: 'Timeout waiting for socket connection' });
-    }, timeoutMs);
-
-    socket.on('connect', () => {
-      try {
-        const encoded = protocol.encode(protocol.createStdinMessage(data));
-        socket.write(encoded, (err) => {
-          if (err) {
-            finish({ ok: false, error: err.message });
-          } else {
-            finish({ ok: true, error: null });
-          }
+    const { socketPath, data, timeoutMs = DEFAULT_TIMEOUT_MS } = options;
+    if (!socketPath) {
+        throw new Error('sendInput: socketPath is required');
+    }
+    if (data === undefined || data === null) {
+        throw new Error('sendInput: data is required');
+    }
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new Error(`sendInput: timeoutMs must be positive (got ${timeoutMs})`);
+    }
+    if (!node_fs_1.default.existsSync(socketPath)) {
+        return { ok: false, error: `Socket not found: ${socketPath}` };
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        let timeout;
+        const socket = node_net_1.default.createConnection(socketPath);
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeout) {
+                clearTimeout(timeout);
+            }
+            try {
+                socket.end();
+                socket.destroy();
+            }
+            catch (cleanupError) {
+                console.warn('[sendInput] socket cleanup failed:', cleanupError);
+            }
+            resolve(result);
+        };
+        timeout = setTimeout(() => {
+            finish({ ok: false, error: 'Timeout waiting for socket connection' });
+        }, timeoutMs);
+        socket.on('connect', () => {
+            try {
+                const encoded = protocol_1.default.encode(protocol_1.default.createStdinMessage(data));
+                socket.write(encoded, (error) => {
+                    if (error) {
+                        finish({ ok: false, error: error.message });
+                    }
+                    else {
+                        finish({ ok: true, error: null });
+                    }
+                });
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                finish({ ok: false, error: reason });
+            }
+        });
+        socket.on('error', (error) => {
+            finish({ ok: false, error: error.message });
         });
-      } catch (err) {
-        finish({ ok: false, error: err.message });
-      }
-    });
-
-    socket.on('error', (err) => {
-      finish({ ok: false, error: err.message });
     });
-  });
 }
-
 module.exports = {
-  sendInput,
+    sendInput,
 };