claude-multi-session 1.0.0

package/src/delegate.js

@@ -0,0 +1,343 @@
+/**
+ * Delegate — The Control Loop for intelligent task delegation.
+ *
+ * This is what makes the system truly human-like. Instead of just
+ * sending messages and getting responses, the Delegate system:
+ *
+ * 1. Spawns a child session with the right permissions
+ * 2. Sends the task
+ * 3. Monitors the response for issues (permission denials, errors, going off-track)
+ * 4. Auto-handles common problems (permission retries, error recovery)
+ * 5. Returns structured output for the parent Claude to evaluate
+ * 6. Accepts follow-up instructions and continues the loop
+ *
+ * The parent Claude acts as the "brain" — it reads the structured output,
+ * decides if the work is good, and sends corrections or approvals.
+ *
+ * Usage:
+ *   const delegate = new Delegate(manager);
+ *
+ *   // Simple one-shot delegation
+ *   const result = await delegate.run('fix-auth', {
+ *     task: 'Fix the authentication bug in auth.service.ts',
+ *     model: 'sonnet',
+ *     maxCost: 0.50,
+ *   });
+ *   console.log(result.status);  // 'completed', 'needs_input', 'failed', 'budget_exceeded'
+ *   console.log(result.response); // The actual work done
+ *
+ *   // Multi-step delegation with evaluation
+ *   const r1 = await delegate.run('build-feature', { task: 'Build login page' });
+ *   // Parent evaluates r1.response...
+ *   const r2 = await delegate.continue('build-feature', 'Good, now add form validation');
+ *   // Parent evaluates r2.response...
+ *   const r3 = await delegate.continue('build-feature', 'Perfect. Now write tests.');
+ *   delegate.finish('build-feature');
+ */
+
+const SafetyNet = require('./safety-net');
+
+// Permission mode recommendations based on task type
+const PERMISSION_PRESETS = {
+  // Read-only: can search and read but not modify
+  'read-only': {
+    permissionMode: 'default',
+    allowedTools: ['Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch', 'Task', 'TaskOutput'],
+  },
+  // Code review: read + analyze
+  'review': {
+    permissionMode: 'default',
+    allowedTools: ['Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch', 'Task', 'TaskOutput'],
+  },
+  // Edit files: can read and edit but limited bash
+  'edit': {
+    permissionMode: 'acceptEdits',
+    allowedTools: [], // All tools, but auto-accept edits
+  },
+  // Full access: can do anything (use with caution)
+  'full': {
+    permissionMode: 'bypassPermissions',
+    allowedTools: [],
+  },
+  // Plan only: can explore but not execute
+  'plan': {
+    permissionMode: 'plan',
+    allowedTools: [],
+  },
+};
+
+class Delegate {
+  /**
+   * @param {SessionManager} manager - The session manager instance
+   */
+  constructor(manager) {
+    this.manager = manager;
+    this.safetyNets = new Map(); // name -> SafetyNet
+  }
+
+  /**
+   * Run a task in a new delegated session.
+   *
+   * This is the main entry point. It:
+   * 1. Creates a session with appropriate permissions
+   * 2. Attaches safety limits
+   * 3. Sends the task
+   * 4. Detects and auto-handles permission issues
+   * 5. Returns structured output
+   *
+   * @param {string} name - Session name
+   * @param {object} options - Task configuration
+   * @param {string} options.task - The task description
+   * @param {string} [options.model='sonnet'] - Model to use
+   * @param {string} [options.preset='edit'] - Permission preset
+   * @param {string} [options.workDir] - Working directory
+   * @param {number} [options.maxCost=2.00] - Max cost in USD
+   * @param {number} [options.maxTurns=50] - Max agent turns
+   * @param {string} [options.context] - Extra context to prepend
+   * @param {string} [options.systemPrompt] - System prompt append
+   * @param {string} [options.agent] - Agent to use
+   * @param {boolean} [options.safety=true] - Enable safety net (set false to disable)
+   * @returns {Promise<DelegateResult>} Structured result
+   */
+  async run(name, options = {}) {
+    const task = options.task;
+    if (!task) throw new Error('options.task is required');
+
+    // Get permission preset
+    const preset = PERMISSION_PRESETS[options.preset || 'edit'] || PERMISSION_PRESETS.edit;
+
+    // Create safety net (only if not disabled)
+    // options.safety defaults to true — pass safety: false to disable
+    const useSafety = options.safety !== false;
+    const safety = useSafety
+      ? new SafetyNet({
+          maxCostUsd: options.maxCost ?? 2.00,
+          maxTurns: options.maxTurns ?? 50,
+          maxDurationMs: options.maxDuration ?? 300000,
+          protectedPaths: options.protectedPaths,
+        })
+      : null;
+
+    // Build the full prompt with context and instructions
+    const fullPrompt = this._buildPrompt(task, options.context);
+
+    // Spawn the session
+    let spawnResult;
+    try {
+      spawnResult = await this.manager.spawn(name, {
+        prompt: fullPrompt,
+        model: options.model || 'sonnet',
+        workDir: options.workDir || process.cwd(),
+        permissionMode: preset.permissionMode,
+        allowedTools: preset.allowedTools.length > 0 ? preset.allowedTools : undefined,
+        systemPrompt: options.systemPrompt,
+        agent: options.agent,
+      });
+    } catch (err) {
+      return this._makeResult('failed', null, null, {
+        error: err.message,
+        name,
+      });
+    }
+
+    // Attach safety net to the live session (only if enabled)
+    if (safety) {
+      const session = this.manager.sessions.get(name);
+      if (session) {
+        safety.attach(session);
+        this.safetyNets.set(name, safety);
+      }
+    }
+
+    const response = spawnResult.response;
+
+    // Check if the response indicates a permission issue
+    if (response && this._isPermissionDenied(response.text)) {
+      // Auto-retry with permission granted
+      const retryResult = await this._handlePermissionRetry(name, response.text);
+      if (retryResult) {
+        return this._makeResult('completed', retryResult, safety, { name });
+      }
+    }
+
+    // Check safety violations (only if safety is enabled)
+    if (safety && safety.violations.length > 0) {
+      const lastViolation = safety.violations[safety.violations.length - 1];
+      return this._makeResult(lastViolation.type, response, safety, { name });
+    }
+
+    // Return structured result
+    return this._makeResult('completed', response, safety, { name });
+  }
+
+  /**
+   * Continue a delegated task with follow-up instructions.
+   *
+   * The parent Claude evaluates the previous result and sends corrections,
+   * additional instructions, or approval.
+   *
+   * @param {string} name - Session name
+   * @param {string} message - Follow-up instruction
+   * @returns {Promise<DelegateResult>} Structured result
+   */
+  async continue(name, message) {
+    const safety = this.safetyNets.get(name);
+
+    let response;
+    try {
+      response = await this.manager.send(name, message);
+    } catch (err) {
+      // Session might be stopped — try auto-resume
+      try {
+        response = await this.manager.resume(name, message);
+        // Re-attach safety net to new session
+        const session = this.manager.sessions.get(name);
+        if (session && safety) {
+          safety.attach(session);
+        }
+      } catch (resumeErr) {
+        return this._makeResult('failed', null, safety, {
+          error: resumeErr.message,
+          name,
+        });
+      }
+    }
+
+    // Check for permission issues
+    if (response && this._isPermissionDenied(response.text)) {
+      const retryResult = await this._handlePermissionRetry(name, response.text);
+      if (retryResult) {
+        return this._makeResult('completed', retryResult, safety, { name });
+      }
+    }
+
+    // Check safety violations
+    if (safety && safety.violations.length > 0) {
+      const lastViolation = safety.violations[safety.violations.length - 1];
+      return this._makeResult(lastViolation.type, response, safety, { name });
+    }
+
+    return this._makeResult('completed', response, safety, { name });
+  }
+
+  /**
+   * Finish a delegated task — stop the session.
+   */
+  finish(name) {
+    try {
+      this.manager.stop(name);
+    } catch (e) {
+      // Session might already be stopped
+    }
+    this.safetyNets.delete(name);
+  }
+
+  /**
+   * Kill a delegated task immediately.
+   */
+  abort(name) {
+    try {
+      this.manager.kill(name);
+    } catch (e) {}
+    this.safetyNets.delete(name);
+  }
+
+  // ===========================================================================
+  // Private
+  // ===========================================================================
+
+  /**
+   * Build the full prompt with context and structured output instructions.
+   */
+  _buildPrompt(task, context) {
+    let prompt = '';
+
+    if (context) {
+      prompt += `CONTEXT:\n${context}\n\n`;
+    }
+
+    prompt += `TASK:\n${task}\n\n`;
+    prompt += `INSTRUCTIONS:\n`;
+    prompt += `- Complete the task thoroughly\n`;
+    prompt += `- If you encounter errors, try to fix them\n`;
+    prompt += `- If you need clarification, say what you need and stop\n`;
+    prompt += `- At the end, provide a brief summary of what you did\n`;
+
+    return prompt;
+  }
+
+  /**
+   * Detect if a response text indicates a permission denial.
+   */
+  _isPermissionDenied(text) {
+    if (!text) return false;
+    const patterns = [
+      'permission to write',
+      'permission to edit',
+      'permission to create',
+      'permission to run',
+      'permission to execute',
+      'haven\'t granted',
+      'need your permission',
+      'would you like to allow',
+      'please approve',
+      'permission denied',
+    ];
+    const lower = text.toLowerCase();
+    return patterns.some(p => lower.includes(p));
+  }
+
+  /**
+   * Handle a permission denial by sending approval.
+   */
+  async _handlePermissionRetry(name, deniedText) {
+    try {
+      const response = await this.manager.send(
+        name,
+        'Yes, you have permission. Go ahead and proceed with all file operations. Do not ask for permission again — you are fully authorized.'
+      );
+      return response;
+    } catch (err) {
+      return null;
+    }
+  }
+
+  /**
+   * Build a structured DelegateResult.
+   *
+   * @typedef {object} DelegateResult
+   * @property {string} status - completed, needs_input, failed, cost_exceeded, turns_exceeded
+   * @property {string} response - The text response from the session
+   * @property {number} cost - Cost in USD
+   * @property {number} turns - Number of agent turns
+   * @property {number} duration - Duration in ms
+   * @property {string} sessionId - Claude session ID
+   * @property {string} name - Session name
+   * @property {boolean} canContinue - Whether the session can accept more messages
+   * @property {string[]} toolsUsed - Tools that were invoked
+   * @property {object} safety - Safety net summary
+   * @property {string|null} error - Error message if failed
+   */
+  _makeResult(status, response, safety, extra = {}) {
+    const result = {
+      status: status,
+      response: response?.text || '',
+      cost: response?.cost || 0,
+      turns: response?.turns || 0,
+      duration: response?.duration || 0,
+      sessionId: response?.sessionId || null,
+      name: extra.name || null,
+      canContinue: !['failed', 'cost_exceeded', 'turns_exceeded'].includes(status),
+      toolsUsed: (response?.toolCalls || []).map(t => t.name),
+      safety: safety ? safety.getSummary() : null,
+      error: extra.error || null,
+    };
+
+    return result;
+  }
+}
+
+// Export presets too so users can see/customize them
+Delegate.PERMISSION_PRESETS = PERMISSION_PRESETS;
+
+module.exports = Delegate;

package/src/index.js

@@ -0,0 +1,35 @@
+/**
+ * claude-multi-session — Main exports
+ *
+ * Programmatic API for managing multiple Claude Code sessions.
+ *
+ * Usage:
+ *   const { SessionManager, Delegate, StreamSession, SafetyNet } = require('claude-multi-session');
+ *
+ *   // High-level: delegate tasks with safety and control
+ *   const mgr = new SessionManager();
+ *   const delegate = new Delegate(mgr);
+ *   const result = await delegate.run('fix-bug', { task: 'Fix the auth bug', maxCost: 0.50 });
+ *
+ *   // Mid-level: manage sessions directly
+ *   const { response } = await mgr.spawn('my-task', { prompt: 'Fix the auth bug' });
+ *
+ *   // Low-level: single streaming session
+ *   const session = new StreamSession({ name: 'direct', model: 'haiku' });
+ *   session.start();
+ *   const r = await session.send('Hello');
+ */
+
+const SessionManager = require('./manager');
+const StreamSession = require('./stream-session');
+const Store = require('./store');
+const Delegate = require('./delegate');
+const SafetyNet = require('./safety-net');
+
+module.exports = {
+  SessionManager,
+  StreamSession,
+  Store,
+  Delegate,
+  SafetyNet,
+};