mrmd-monitor 0.1.0

package/src/execution.js

@@ -0,0 +1,261 @@
+/**
+ * Execution Handler
+ *
+ * Handles MRP runtime connections and execution streaming.
+ *
+ * @module mrmd-monitor/execution
+ */
+
+/**
+ * @typedef {Object} ExecutionCallbacks
+ * @property {function(string, string): void} [onStdout] - (chunk, accumulated)
+ * @property {function(string, string): void} [onStderr] - (chunk, accumulated)
+ * @property {function(Object): void} [onStdinRequest] - stdin request from runtime
+ * @property {function(Object): void} [onDisplay] - display data (images, HTML, etc.)
+ * @property {function(Object): void} [onResult] - final result
+ * @property {function(Object): void} [onError] - execution error
+ * @property {function(): void} [onStart] - execution started
+ * @property {function(): void} [onDone] - stream complete
+ */
+
+/**
+ * MRP execution handler
+ */
+export class ExecutionHandler {
+  constructor() {
+    /** @type {Map<string, AbortController>} */
+    this._activeExecutions = new Map();
+  }
+
+  /**
+   * Execute code on MRP runtime with streaming
+   *
+   * @param {string} runtimeUrl - MRP runtime base URL
+   * @param {string} code - Code to execute
+   * @param {Object} options
+   * @param {string} [options.session='default'] - Session ID
+   * @param {string} [options.execId] - Execution ID for tracking
+   * @param {ExecutionCallbacks} [options.callbacks] - Event callbacks
+   * @returns {Promise<Object>} Final result
+   */
+  async execute(runtimeUrl, code, options = {}) {
+    const {
+      session = 'default',
+      execId,
+      callbacks = {},
+    } = options;
+
+    // Set up abort controller
+    const abortController = new AbortController();
+    if (execId) {
+      this._activeExecutions.set(execId, abortController);
+    }
+
+    try {
+      const response = await fetch(`${runtimeUrl}/execute/stream`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          code,
+          session,
+          storeHistory: true,
+          execId, // Pass execId so mrmd-python uses the same ID for stdin coordination
+        }),
+        signal: abortController.signal,
+      });
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`MRP request failed: ${response.status} ${error}`);
+      }
+
+      callbacks.onStart?.();
+
+      // Parse SSE stream
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+
+      let currentEvent = null;
+      let buffer = '';
+      let finalResult = null;
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+
+        // Process complete lines
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || ''; // Keep incomplete line in buffer
+
+        for (const line of lines) {
+          if (line.startsWith('event: ')) {
+            currentEvent = line.slice(7).trim();
+          } else if (line.startsWith('data: ')) {
+            try {
+              const data = JSON.parse(line.slice(6));
+              finalResult = this._handleEvent(currentEvent, data, callbacks) || finalResult;
+            } catch (err) {
+              console.warn('[ExecutionHandler] Failed to parse SSE data:', err.message);
+            }
+          }
+        }
+      }
+
+      callbacks.onDone?.();
+      return finalResult || { success: true };
+
+    } catch (err) {
+      if (err.name === 'AbortError') {
+        return { success: false, error: { type: 'Aborted', message: 'Execution cancelled' } };
+      }
+      callbacks.onError?.({ type: 'ConnectionError', message: err.message });
+      throw err;
+
+    } finally {
+      if (execId) {
+        this._activeExecutions.delete(execId);
+      }
+    }
+  }
+
+  /**
+   * Handle SSE event
+   *
+   * @param {string} event
+   * @param {Object} data
+   * @param {ExecutionCallbacks} callbacks
+   * @returns {Object|null} Result if this is the result event
+   */
+  _handleEvent(event, data, callbacks) {
+    switch (event) {
+      case 'start':
+        // Execution started on server
+        break;
+
+      case 'stdout':
+        callbacks.onStdout?.(data.content, data.accumulated);
+        break;
+
+      case 'stderr':
+        callbacks.onStderr?.(data.content, data.accumulated);
+        break;
+
+      case 'stdin_request':
+        callbacks.onStdinRequest?.(data);
+        break;
+
+      case 'display':
+        callbacks.onDisplay?.(data);
+        break;
+
+      case 'asset':
+        // Asset saved on server - treat similar to display
+        callbacks.onDisplay?.({
+          mimeType: data.mimeType,
+          assetId: data.path,
+          url: data.url,
+        });
+        break;
+
+      case 'result':
+        callbacks.onResult?.(data);
+        return data;
+
+      case 'error':
+        callbacks.onError?.(data);
+        return { success: false, error: data };
+
+      case 'done':
+        // Stream complete
+        break;
+
+      default:
+        console.log('[ExecutionHandler] Unknown event:', event, data);
+    }
+
+    return null;
+  }
+
+  /**
+   * Send input to a waiting execution
+   *
+   * @param {string} runtimeUrl - MRP runtime base URL
+   * @param {string} session - Session ID
+   * @param {string} execId - Execution ID
+   * @param {string} text - Input text
+   * @returns {Promise<{accepted: boolean}>}
+   */
+  async sendInput(runtimeUrl, session, execId, text) {
+    const response = await fetch(`${runtimeUrl}/input`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        session,
+        exec_id: execId,
+        text,
+      }),
+    });
+
+    return response.json();
+  }
+
+  /**
+   * Interrupt a running execution
+   *
+   * @param {string} runtimeUrl - MRP runtime base URL
+   * @param {string} session - Session ID
+   * @returns {Promise<{interrupted: boolean}>}
+   */
+  async interrupt(runtimeUrl, session) {
+    const response = await fetch(`${runtimeUrl}/interrupt`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ session }),
+    });
+
+    return response.json();
+  }
+
+  /**
+   * Cancel execution by execId (local abort)
+   *
+   * @param {string} execId
+   */
+  cancel(execId) {
+    const controller = this._activeExecutions.get(execId);
+    if (controller) {
+      controller.abort();
+    }
+  }
+
+  /**
+   * Cancel all active executions
+   */
+  cancelAll() {
+    for (const controller of this._activeExecutions.values()) {
+      controller.abort();
+    }
+    this._activeExecutions.clear();
+  }
+
+  /**
+   * Check if execution is active
+   *
+   * @param {string} execId
+   * @returns {boolean}
+   */
+  isActive(execId) {
+    return this._activeExecutions.has(execId);
+  }
+
+  /**
+   * Get active execution count
+   *
+   * @returns {number}
+   */
+  get activeCount() {
+    return this._activeExecutions.size;
+  }
+}

package/src/index.js

@@ -0,0 +1,14 @@
+/**
+ * mrmd-monitor
+ *
+ * Headless Yjs peer for monitoring and executing code in mrmd notebooks.
+ * Ensures long-running executions survive browser disconnects.
+ *
+ * @module mrmd-monitor
+ */
+
+export { RuntimeMonitor, createMonitor } from './monitor.js';
+export { ExecutionHandler } from './execution.js';
+export { DocumentWriter } from './document.js';
+export { CoordinationProtocol, EXECUTION_STATUS } from './coordination.js';
+export { TerminalBuffer, processTerminalOutput } from './terminal.js';

package/src/monitor.js

@@ -0,0 +1,420 @@
+/**
+ * Runtime Monitor
+ *
+ * Main monitor class that connects to mrmd-sync as a Yjs peer
+ * and handles execution requests.
+ *
+ * @module mrmd-monitor/monitor
+ */
+
+import * as Y from 'yjs';
+import { WebsocketProvider } from 'y-websocket';
+import { CoordinationProtocol, EXECUTION_STATUS } from './coordination.js';
+import { DocumentWriter } from './document.js';
+import { ExecutionHandler } from './execution.js';
+import { TerminalBuffer } from './terminal.js';
+
+/**
+ * @typedef {Object} MonitorOptions
+ * @property {string} [name='mrmd-monitor'] - Monitor name for Awareness
+ * @property {string} [color='#10b981'] - Monitor color for Awareness
+ * @property {Function} [log] - Logger function
+ */
+
+/**
+ * Runtime Monitor
+ *
+ * Connects to mrmd-sync as a Yjs peer and handles execution requests.
+ */
+export class RuntimeMonitor {
+  /**
+   * @param {string} syncUrl - WebSocket URL for mrmd-sync
+   * @param {string} docPath - Document path/room name
+   * @param {MonitorOptions} [options]
+   */
+  constructor(syncUrl, docPath, options = {}) {
+    /** @type {string} */
+    this.syncUrl = syncUrl;
+
+    /** @type {string} */
+    this.docPath = docPath;
+
+    /** @type {MonitorOptions} */
+    this.options = {
+      name: 'mrmd-monitor',
+      color: '#10b981',
+      log: console.log,
+      ...options,
+    };
+
+    /** @type {Y.Doc} */
+    this.ydoc = new Y.Doc();
+
+    /** @type {WebsocketProvider|null} */
+    this.provider = null;
+
+    /** @type {CoordinationProtocol|null} */
+    this.coordination = null;
+
+    /** @type {DocumentWriter|null} */
+    this.writer = null;
+
+    /** @type {ExecutionHandler} */
+    this.executor = new ExecutionHandler();
+
+    /** @type {boolean} */
+    this._connected = false;
+
+    /** @type {boolean} */
+    this._synced = false;
+
+    /** @type {Function|null} */
+    this._unsubscribe = null;
+
+    /** @type {Set<string>} */
+    this._processingExecutions = new Set();
+  }
+
+  /**
+   * Log helper
+   * @param {string} level
+   * @param {string} message
+   * @param {Object} [data]
+   */
+  _log(level, message, data = {}) {
+    const entry = {
+      timestamp: new Date().toISOString(),
+      level,
+      component: 'monitor',
+      message,
+      ...data,
+    };
+    this.options.log(JSON.stringify(entry));
+  }
+
+  /**
+   * Connect to mrmd-sync
+   *
+   * @returns {Promise<void>} Resolves when connected and synced
+   */
+  connect() {
+    return new Promise((resolve, reject) => {
+      this._log('info', 'Connecting to sync server', { url: this.syncUrl, doc: this.docPath });
+
+      this.provider = new WebsocketProvider(this.syncUrl, this.docPath, this.ydoc, {
+        connect: true,
+      });
+
+      // Set up awareness
+      this.provider.awareness.setLocalStateField('user', {
+        name: this.options.name,
+        color: this.options.color,
+        type: 'monitor',
+      });
+
+      // Track connection status
+      this.provider.on('status', ({ status }) => {
+        const wasConnected = this._connected;
+        this._connected = status === 'connected';
+
+        if (this._connected && !wasConnected) {
+          this._log('info', 'Connected to sync server');
+        } else if (!this._connected && wasConnected) {
+          this._log('warn', 'Disconnected from sync server');
+        }
+      });
+
+      // Wait for sync
+      // Note: y-websocket 2.x uses 'sync' event with boolean parameter
+      this.provider.on('sync', (isSynced) => {
+        if (isSynced && !this._synced) {
+          this._synced = true;
+          this._log('info', 'Document synced');
+
+          // Initialize coordination and writer
+          this.coordination = new CoordinationProtocol(this.ydoc, this.ydoc.clientID);
+          this.writer = new DocumentWriter(this.ydoc);
+
+          // Start watching for execution requests
+          this._startWatching();
+
+          resolve();
+        }
+      });
+
+      // Handle connection errors
+      this.provider.on('connection-error', (err) => {
+        this._log('error', 'Connection error', { error: err.message });
+        reject(err);
+      });
+    });
+  }
+
+  /**
+   * Start watching for execution requests
+   */
+  _startWatching() {
+    this._log('info', 'Starting execution watcher');
+
+    this._unsubscribe = this.coordination.observe((execId, exec, action) => {
+      if (!exec) return;
+
+      // Handle new requests
+      if (exec.status === EXECUTION_STATUS.REQUESTED) {
+        this._handleRequest(execId, exec);
+      }
+
+      // Handle ready (output block created)
+      if (exec.status === EXECUTION_STATUS.READY && exec.claimedBy === this.ydoc.clientID) {
+        this._handleReady(execId, exec);
+      }
+
+      // Handle stdin responses
+      if (exec.stdinResponse && exec.claimedBy === this.ydoc.clientID) {
+        this._handleStdinResponse(execId, exec);
+      }
+    });
+
+    // Also check for any existing requests we might have missed
+    this._checkExistingRequests();
+  }
+
+  /**
+   * Check for existing requests on startup
+   */
+  _checkExistingRequests() {
+    const requested = this.coordination.getExecutionsByStatus(EXECUTION_STATUS.REQUESTED);
+    for (const exec of requested) {
+      this._handleRequest(exec.id, exec);
+    }
+
+    // Also check for any we claimed but didn't start (e.g., after restart)
+    const ready = this.coordination.getExecutionsByStatus(EXECUTION_STATUS.READY);
+    for (const exec of ready) {
+      if (exec.claimedBy === this.ydoc.clientID) {
+        this._handleReady(exec.id, exec);
+      }
+    }
+  }
+
+  /**
+   * Handle execution request
+   *
+   * @param {string} execId
+   * @param {Object} exec
+   */
+  _handleRequest(execId, exec) {
+    // Don't claim if already processing
+    if (this._processingExecutions.has(execId)) return;
+
+    this._log('info', 'New execution request', { execId, language: exec.language });
+
+    // Try to claim it
+    const claimed = this.coordination.claimExecution(execId);
+    if (claimed) {
+      this._log('info', 'Claimed execution', { execId });
+      this._processingExecutions.add(execId);
+    } else {
+      this._log('debug', 'Could not claim execution (already claimed)', { execId });
+    }
+  }
+
+  /**
+   * Handle execution ready (output block created)
+   *
+   * @param {string} execId
+   * @param {Object} exec
+   */
+  async _handleReady(execId, exec) {
+    // Don't start twice
+    if (this.executor.isActive(execId)) return;
+
+    // Wait for output block to be synced to our ydoc
+    // The browser created the output block, but Yjs sync may not have propagated it yet
+    let attempts = 0;
+    const maxAttempts = 50; // 5 seconds max
+    while (!this.writer.hasOutputBlock(execId) && attempts < maxAttempts) {
+      await new Promise(resolve => setTimeout(resolve, 100));
+      attempts++;
+    }
+
+    if (!this.writer.hasOutputBlock(execId)) {
+      this._log('error', 'Output block not synced after timeout', { execId, attempts });
+      this.coordination.setError(execId, {
+        type: 'SyncError',
+        message: 'Output block not synced to monitor. Try again.',
+      });
+      this._processingExecutions.delete(execId);
+      return;
+    }
+
+    if (attempts > 0) {
+      this._log('debug', 'Waited for output block sync', { execId, attempts, ms: attempts * 100 });
+    }
+
+    this._log('info', 'Starting execution', { execId, language: exec.language });
+
+    // Mark as running
+    this.coordination.setRunning(execId);
+
+    try {
+      // Use TerminalBuffer to process output (handles \r, ANSI, progress bars)
+      const buffer = new TerminalBuffer();
+
+      await this.executor.execute(exec.runtimeUrl, exec.code, {
+        session: exec.session,
+        execId,
+        callbacks: {
+          onStdout: (chunk, accumulated) => {
+            // Process through terminal buffer for proper cursor/ANSI handling
+            buffer.write(chunk);
+            // Write processed output to document
+            this.writer.replaceOutput(execId, buffer.toString());
+          },
+
+          onStderr: (chunk, accumulated) => {
+            // Process stderr through buffer too
+            buffer.write(chunk);
+            this.writer.replaceOutput(execId, buffer.toString());
+          },
+
+          onStdinRequest: (request) => {
+            this._log('info', 'Stdin request received from runtime', {
+              execId,
+              prompt: request.prompt,
+              password: request.password
+            });
+            this.coordination.requestStdin(execId, {
+              prompt: request.prompt,
+              password: request.password,
+            });
+            this._log('info', 'Stdin request stored in Y.Map', { execId });
+          },
+
+          onDisplay: (display) => {
+            this._log('debug', 'Display data', { execId, mimeType: display.mimeType });
+            this.coordination.addDisplayData(execId, display);
+          },
+
+          onResult: (result) => {
+            this._log('info', 'Execution completed', { execId, success: result.success });
+            this.coordination.setCompleted(execId, {
+              result: result.result,
+              displayData: result.displayData,
+            });
+          },
+
+          onError: (error) => {
+            this._log('error', 'Execution error', { execId, error: error.message });
+            this.coordination.setError(execId, error);
+          },
+        },
+      });
+
+    } catch (err) {
+      this._log('error', 'Execution failed', { execId, error: err.message });
+      this.coordination.setError(execId, {
+        type: 'MonitorError',
+        message: err.message,
+      });
+
+    } finally {
+      this._processingExecutions.delete(execId);
+    }
+  }
+
+  /**
+   * Handle stdin response from browser
+   *
+   * @param {string} execId
+   * @param {Object} exec
+   */
+  async _handleStdinResponse(execId, exec) {
+    if (!exec.stdinResponse) return;
+
+    this._log('info', 'Stdin response received, sending to runtime', {
+      execId,
+      text: exec.stdinResponse.text
+    });
+
+    try {
+      const result = await this.executor.sendInput(
+        exec.runtimeUrl,
+        exec.session,
+        execId,
+        exec.stdinResponse.text
+      );
+
+      this._log('info', 'Stdin sent to runtime', { execId, result });
+
+      // Clear the request
+      this.coordination.clearStdinRequest(execId);
+
+    } catch (err) {
+      this._log('error', 'Failed to send stdin', { execId, error: err.message });
+    }
+  }
+
+  /**
+   * Disconnect from sync server
+   */
+  disconnect() {
+    this._log('info', 'Disconnecting');
+
+    // Cancel active executions
+    this.executor.cancelAll();
+
+    // Stop watching
+    if (this._unsubscribe) {
+      this._unsubscribe();
+      this._unsubscribe = null;
+    }
+
+    // Clean up coordination
+    if (this.coordination) {
+      this.coordination.destroy();
+      this.coordination = null;
+    }
+
+    // Disconnect provider
+    if (this.provider) {
+      this.provider.disconnect();
+      this.provider = null;
+    }
+
+    this._connected = false;
+    this._synced = false;
+  }
+
+  /**
+   * Check if connected
+   *
+   * @returns {boolean}
+   */
+  get isConnected() {
+    return this._connected && this._synced;
+  }
+
+  /**
+   * Get active execution count
+   *
+   * @returns {number}
+   */
+  get activeExecutions() {
+    return this.executor.activeCount;
+  }
+}
+
+/**
+ * Create and connect a monitor
+ *
+ * @param {string} syncUrl - WebSocket URL for mrmd-sync
+ * @param {string} docPath - Document path/room name
+ * @param {MonitorOptions} [options]
+ * @returns {Promise<RuntimeMonitor>}
+ */
+export async function createMonitor(syncUrl, docPath, options = {}) {
+  const monitor = new RuntimeMonitor(syncUrl, docPath, options);
+  await monitor.connect();
+  return monitor;
+}