clearctx 3.0.0

package/src/manager.js

@@ -0,0 +1,510 @@
+/**
+ * SessionManager — Multi-session orchestrator.
+ *
+ * Manages multiple StreamSession instances. Provides a high-level API for:
+ *   - Spawning new sessions (stream or resume mode)
+ *   - Sending messages to sessions
+ *   - Pausing, resuming, forking, killing sessions
+ *   - Tracking costs and interaction history
+ *   - Persisting session state for restart recovery
+ *
+ * Usage (programmatic):
+ *   const { SessionManager } = require('clearctx');
+ *   const mgr = new SessionManager();
+ *
+ *   // Spawn and interact
+ *   const session = await mgr.spawn('fix-auth', { prompt: 'Fix the auth bug', model: 'sonnet' });
+ *   const r1 = await mgr.send('fix-auth', 'Also add input validation');
+ *   const r2 = await mgr.send('fix-auth', 'Now write tests');
+ *
+ *   // Parallel tasks
+ *   await Promise.all([
+ *     mgr.spawn('task-a', { prompt: 'Build login page' }),
+ *     mgr.spawn('task-b', { prompt: 'Build signup page' }),
+ *   ]);
+ *
+ *   // Check status
+ *   console.log(mgr.list());
+ *   mgr.stopAll();
+ */
+
+const StreamSession = require('./stream-session');
+const Store = require('./store');
+const { spawn: spawnProcess, execSync } = require('child_process');
+
+class SessionManager {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.dataDir] - Override store data directory
+   * @param {string} [options.defaultModel='sonnet'] - Default model for new sessions
+   * @param {string} [options.defaultPermissionMode='default'] - Default permission mode
+   * @param {number} [options.defaultTimeout=600000] - Default response timeout
+   */
+  constructor(options = {}) {
+    this.store = new Store(options.dataDir);
+    this.defaultModel = options.defaultModel || 'sonnet';
+    this.defaultPermissionMode = options.defaultPermissionMode || 'default';
+    this.defaultTimeout = options.defaultTimeout || 600000;
+
+    // Live sessions (in-memory StreamSession instances)
+    this.sessions = new Map();
+  }
+
+  /**
+   * Spawn a new session and optionally send the first message.
+   *
+   * @param {string} name - Unique session name
+   * @param {object} options - Session config
+   * @param {string} [options.prompt] - Initial prompt (if provided, sends immediately)
+   * @param {string} [options.model] - Model to use
+   * @param {string} [options.workDir] - Working directory
+   * @param {string} [options.permissionMode] - Permission mode
+   * @param {string[]} [options.allowedTools] - Restrict tools
+   * @param {string} [options.systemPrompt] - System prompt append
+   * @param {number} [options.maxBudget] - Max budget USD
+   * @param {string} [options.agent] - Agent to use
+   * @param {number} [options.timeout] - Response timeout
+   * @param {string[]} [options.tags] - Tags for organizing
+   * @returns {Promise<object>} { session, response? } — response is included if prompt was given
+   */
+  async spawn(name, options = {}) {
+    // Check for name collision
+    if (this.sessions.has(name)) {
+      throw new Error(`Session "${name}" already exists and is alive. Kill it first or use a different name.`);
+    }
+
+    const existingRecord = this.store.get(name);
+    if (existingRecord && !['stopped', 'killed', 'failed'].includes(existingRecord.status)) {
+      throw new Error(`Session "${name}" exists in store with status "${existingRecord.status}". Kill or delete it first.`);
+    }
+
+    // Create StreamSession
+    const session = new StreamSession({
+      name,
+      model: options.model || this.defaultModel,
+      workDir: options.workDir || process.cwd(),
+      permissionMode: options.permissionMode || this.defaultPermissionMode,
+      allowedTools: options.allowedTools || [],
+      systemPrompt: options.systemPrompt || '',
+      maxBudget: options.maxBudget || null,
+      agent: options.agent || null,
+      timeout: options.timeout || this.defaultTimeout,
+    });
+
+    // Wire up events for persistence
+    this._wireEvents(session);
+
+    // Start the process (just spawns it, no waiting)
+    session.start();
+
+    // Store in memory
+    this.sessions.set(name, session);
+
+    // Persist to store
+    this._persist(name);
+
+    // If a prompt was given, send it right away
+    // The first send() triggers init + gets the response
+    let response = null;
+    if (options.prompt) {
+      response = await session.send(options.prompt);
+      this._persist(name);
+    }
+
+    return { session: session.toJSON(), initData: session.initData, response };
+  }
+
+  /**
+   * Send a message to an existing session.
+   *
+   * @param {string} name - Session name
+   * @param {string} message - The message to send
+   * @param {number} [timeout] - Override timeout
+   * @returns {Promise<object>} Response { text, cost, turns, duration, sessionId }
+   */
+  async send(name, message, timeout) {
+    const session = this._getSession(name);
+
+    // If session is paused, auto-resume
+    if (session.status === 'paused') {
+      session.resume();
+    }
+
+    const response = await session.send(message, timeout);
+    this._persist(name);
+    return response;
+  }
+
+  /**
+   * Pause a session (stops accepting messages but keeps process alive).
+   */
+  pause(name) {
+    const session = this._getSession(name);
+    session.pause();
+    this._persist(name);
+  }
+
+  /**
+   * Resume a paused session (can optionally send a message).
+   *
+   * @param {string} name - Session name
+   * @param {string} [message] - Optional message to send after resuming
+   * @returns {Promise<object|null>} Response if message was sent
+   */
+  async resume(name, message) {
+    // First check if session is alive in memory
+    if (this.sessions.has(name)) {
+      const session = this.sessions.get(name);
+      if (session.status === 'paused') {
+        session.resume();
+      }
+      if (message) {
+        const response = await session.send(message);
+        this._persist(name);
+        return response;
+      }
+      this._persist(name);
+      return null;
+    }
+
+    // Session not alive — try to restore from store using --resume
+    const record = this.store.get(name);
+    if (!record) {
+      throw new Error(`Session "${name}" not found.`);
+    }
+    if (!record.claudeSessionId) {
+      throw new Error(`Session "${name}" has no session ID. Cannot restore.`);
+    }
+
+    // Spawn a new StreamSession that resumes the old one
+    const session = new StreamSession({
+      name,
+      model: record.model || this.defaultModel,
+      workDir: record.workDir || process.cwd(),
+      permissionMode: record.permissionMode || this.defaultPermissionMode,
+      allowedTools: record.allowedTools || [],
+      systemPrompt: record.systemPrompt || '',
+      maxBudget: record.maxBudget || null,
+      agent: record.agent || null,
+      sessionId: record.claudeSessionId, // Resume existing conversation
+      timeout: record.timeout || this.defaultTimeout,
+    });
+
+    this._wireEvents(session);
+    session.start(); // Just spawns process, no await needed
+    this.sessions.set(name, session);
+
+    // Merge interaction history from store
+    session.interactions = record.interactions || [];
+    session.totalCostUsd = record.totalCostUsd || 0;
+    session.totalTurns = record.totalTurns || 0;
+
+    if (message) {
+      const response = await session.send(message);
+      this._persist(name);
+      return response;
+    }
+
+    this._persist(name);
+    return null;
+  }
+
+  /**
+   * Fork a session — creates a new session with the parent's context.
+   *
+   * @param {string} sourceName - Source session name
+   * @param {string} newName - New session name
+   * @param {object} [options] - Override options for the fork
+   * @param {string} [options.message] - Initial message for the fork
+   * @returns {Promise<object>} { session, response? }
+   */
+  async fork(sourceName, newName, options = {}) {
+    // Get the source session ID (from live session or store)
+    let sourceSessionId;
+    let sourceRecord;
+
+    if (this.sessions.has(sourceName)) {
+      const source = this.sessions.get(sourceName);
+      sourceSessionId = source.id;
+      sourceRecord = source.toJSON();
+    } else {
+      sourceRecord = this.store.get(sourceName);
+      if (!sourceRecord) {
+        throw new Error(`Source session "${sourceName}" not found.`);
+      }
+      sourceSessionId = sourceRecord.claudeSessionId;
+    }
+
+    if (!sourceSessionId) {
+      throw new Error(`Source session "${sourceName}" has no session ID.`);
+    }
+
+    // Use the resume-mode approach for fork (--resume + --fork-session)
+    // because stream mode doesn't support --fork-session natively
+    const model = options.model || sourceRecord.model || this.defaultModel;
+    const workDir = options.workDir || sourceRecord.workDir || process.cwd();
+    const message = options.message || 'Continue from the forked conversation.';
+
+    // Use single-shot resume with fork
+    const args = [
+      '-p',
+      '--output-format', 'json',
+      '--model', model,
+      '--resume', sourceSessionId,
+      '--fork-session',
+    ];
+
+    if (sourceRecord.permissionMode && sourceRecord.permissionMode !== 'default') {
+      args.push('--permission-mode', sourceRecord.permissionMode);
+    }
+
+    args.push(message);
+
+    try {
+      const result = execSync(
+        `claude ${args.map(a => `"${a.replace(/"/g, '\\"')}"`).join(' ')}`,
+        { cwd: workDir, encoding: 'utf-8', maxBuffer: 50 * 1024 * 1024, timeout: 600000, windowsHide: true }
+      );
+
+      const parsed = JSON.parse(result);
+
+      // Now spawn a new stream session that resumes the forked ID
+      const forked = new StreamSession({
+        name: newName,
+        model,
+        workDir,
+        permissionMode: sourceRecord.permissionMode || this.defaultPermissionMode,
+        sessionId: parsed.session_id, // The forked session's ID
+      });
+
+      this._wireEvents(forked);
+      forked.start(); // Just spawns process
+      this.sessions.set(newName, forked);
+
+      // Record the fork's first interaction
+      forked.interactions.push({
+        prompt: message,
+        response: parsed.result || '',
+        cost: parsed.cost_usd || 0,
+        turns: parsed.num_turns || 0,
+        duration: parsed.duration_ms || 0,
+        timestamp: new Date().toISOString(),
+        type: 'fork',
+      });
+      forked.totalCostUsd = parsed.cost_usd || 0;
+      forked.totalTurns = parsed.num_turns || 0;
+
+      this._persist(newName);
+
+      return {
+        session: forked.toJSON(),
+        response: {
+          text: parsed.result || '',
+          cost: parsed.cost_usd || 0,
+          turns: parsed.num_turns || 0,
+          duration: parsed.duration_ms || 0,
+          sessionId: parsed.session_id,
+        },
+      };
+
+    } catch (err) {
+      throw new Error(`Fork failed: ${err.message}`);
+    }
+  }
+
+  /**
+   * Stop a session gracefully (closes stdin, process exits).
+   */
+  stop(name) {
+    const session = this._getSession(name);
+    session.stop();
+    this._persist(name);
+    this.sessions.delete(name);
+  }
+
+  /**
+   * Force kill a session.
+   */
+  kill(name) {
+    if (this.sessions.has(name)) {
+      const session = this.sessions.get(name);
+      session.kill();
+      this.sessions.delete(name);
+    }
+
+    // Update store
+    const record = this.store.get(name);
+    if (record) {
+      record.status = 'killed';
+      this.store.set(name, record);
+    }
+  }
+
+  /**
+   * Stop all live sessions.
+   */
+  stopAll() {
+    for (const [name, session] of this.sessions) {
+      session.stop();
+      this._persist(name);
+    }
+    this.sessions.clear();
+  }
+
+  /**
+   * Get status of a session.
+   */
+  status(name) {
+    // Check live session first
+    if (this.sessions.has(name)) {
+      return this.sessions.get(name).toJSON();
+    }
+    // Fall back to store
+    const record = this.store.get(name);
+    if (!record) {
+      throw new Error(`Session "${name}" not found.`);
+    }
+    return record;
+  }
+
+  /**
+   * List all sessions (live + stored).
+   * @param {string} [statusFilter]
+   * @returns {object[]}
+   */
+  list(statusFilter) {
+    const result = new Map();
+
+    // Load from store first
+    const stored = this.store.list();
+    for (const record of stored) {
+      result.set(record.name, record);
+    }
+
+    // Override with live session data
+    for (const [name, session] of this.sessions) {
+      result.set(name, session.toJSON());
+    }
+
+    let list = Array.from(result.values());
+    if (statusFilter) {
+      list = list.filter(s => s.status === statusFilter);
+    }
+
+    return list;
+  }
+
+  /**
+   * Get interaction history for a session.
+   */
+  history(name) {
+    if (this.sessions.has(name)) {
+      return this.sessions.get(name).interactions;
+    }
+    const record = this.store.get(name);
+    if (!record) {
+      throw new Error(`Session "${name}" not found.`);
+    }
+    return record.interactions || [];
+  }
+
+  /**
+   * Get the last response from a session.
+   */
+  lastOutput(name) {
+    const hist = this.history(name);
+    if (hist.length === 0) return null;
+    return hist[hist.length - 1];
+  }
+
+  /**
+   * Delete a session from store permanently.
+   */
+  delete(name) {
+    if (this.sessions.has(name)) {
+      this.sessions.get(name).kill();
+      this.sessions.delete(name);
+    }
+    this.store.delete(name);
+  }
+
+  /**
+   * Clean up old sessions.
+   */
+  cleanup(days = 7) {
+    return this.store.cleanup(days);
+  }
+
+  /**
+   * Batch spawn — start multiple sessions from a spec array.
+   *
+   * @param {object[]} specs - Array of { name, prompt, model?, ... }
+   * @returns {Promise<object[]>} Results for each spawn
+   */
+  async batch(specs) {
+    // Spawn all in parallel
+    const promises = specs.map(spec =>
+      this.spawn(spec.name, spec).catch(err => ({
+        session: { name: spec.name, status: 'failed' },
+        error: err.message,
+      }))
+    );
+    return Promise.all(promises);
+  }
+
+  // ===========================================================================
+  // Private
+  // ===========================================================================
+
+  /**
+   * Get a live session or throw.
+   */
+  _getSession(name) {
+    const session = this.sessions.get(name);
+    if (!session) {
+      throw new Error(`Session "${name}" is not alive. Use resume() to restore it.`);
+    }
+    return session;
+  }
+
+  /**
+   * Wire session events for logging/persistence.
+   */
+  _wireEvents(session) {
+    session.on('error', (err) => {
+      this._persist(session.name);
+    });
+
+    session.on('close', (code) => {
+      this._persist(session.name);
+      this.sessions.delete(session.name);
+    });
+  }
+
+  /**
+   * Persist a session's current state to store.
+   */
+  _persist(name) {
+    const session = this.sessions.get(name);
+    if (!session) return;
+
+    this.store.set(name, {
+      name: session.name,
+      claudeSessionId: session.id,
+      status: session.status,
+      model: session.model,
+      workDir: session.workDir,
+      permissionMode: session.permissionMode,
+      allowedTools: session.allowedTools,
+      systemPrompt: session.systemPrompt,
+      maxBudget: session.maxBudget,
+      agent: session.agent,
+      totalCostUsd: session.totalCostUsd,
+      totalTurns: session.totalTurns,
+      interactions: session.interactions,
+      created: session.interactions[0]?.timestamp || new Date().toISOString(),
+    });
+  }
+}
+
+module.exports = SessionManager;