clearctx 3.0.0

package/src/store.js

@@ -0,0 +1,131 @@
+/**
+ * Store — JSON file persistence for session metadata.
+ *
+ * Sessions are kept alive in-memory (as StreamSession objects) by the Manager,
+ * but their metadata is persisted here so sessions can survive process restarts.
+ *
+ * The store saves:
+ *   - Session config (name, model, workDir, etc.)
+ *   - Claude session ID (for resuming after restart)
+ *   - Interaction history (prompts + responses)
+ *   - Cost tracking
+ *
+ * Data location: ~/.clearctx/ (user home directory)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { atomicWriteJson } = require('./atomic-io');
+
+// Default data directory in user's home
+const DEFAULT_DATA_DIR = path.join(os.homedir(), '.clearctx');
+
+class Store {
+  /**
+   * @param {string} [dataDir] - Override data directory path
+   */
+  constructor(dataDir) {
+    this.dataDir = dataDir || DEFAULT_DATA_DIR;
+    this.sessionsFile = path.join(this.dataDir, 'sessions.json');
+
+    // Ensure directory exists
+    if (!fs.existsSync(this.dataDir)) {
+      fs.mkdirSync(this.dataDir, { recursive: true });
+    }
+  }
+
+  /**
+   * Load all session records from disk.
+   * @returns {Object<string, object>} Map of name -> session data
+   */
+  loadAll() {
+    if (!fs.existsSync(this.sessionsFile)) {
+      return {};
+    }
+    try {
+      return JSON.parse(fs.readFileSync(this.sessionsFile, 'utf-8'));
+    } catch (err) {
+      return {};
+    }
+  }
+
+  /**
+   * Save all session records to disk.
+   * @param {Object<string, object>} sessions
+   */
+  saveAll(sessions) {
+    atomicWriteJson(this.sessionsFile, sessions);
+  }
+
+  /**
+   * Get a single session record.
+   * @param {string} name
+   * @returns {object|null}
+   */
+  get(name) {
+    const all = this.loadAll();
+    return all[name] || null;
+  }
+
+  /**
+   * Save/update a single session record.
+   * @param {string} name
+   * @param {object} data
+   */
+  set(name, data) {
+    const all = this.loadAll();
+    all[name] = { ...data, lastSaved: new Date().toISOString() };
+    this.saveAll(all);
+  }
+
+  /**
+   * Delete a session record.
+   * @param {string} name
+   */
+  delete(name) {
+    const all = this.loadAll();
+    delete all[name];
+    this.saveAll(all);
+  }
+
+  /**
+   * List all session records.
+   * @param {string} [statusFilter] - Optional status filter
+   * @returns {object[]}
+   */
+  list(statusFilter) {
+    const all = this.loadAll();
+    let list = Object.values(all);
+    if (statusFilter) {
+      list = list.filter(s => s.status === statusFilter);
+    }
+    return list;
+  }
+
+  /**
+   * Clean up old sessions (completed/failed/killed older than N days).
+   * @param {number} days
+   * @returns {string[]} Names of removed sessions
+   */
+  cleanup(days = 7) {
+    const all = this.loadAll();
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - days);
+    const cutoffISO = cutoff.toISOString();
+    const removed = [];
+
+    for (const [name, session] of Object.entries(all)) {
+      const lastActive = session.lastSaved || session.created;
+      if (lastActive < cutoffISO && ['completed', 'failed', 'killed', 'stopped'].includes(session.status)) {
+        removed.push(name);
+        delete all[name];
+      }
+    }
+
+    this.saveAll(all);
+    return removed;
+  }
+}
+
+module.exports = Store;

package/src/stream-session.js

@@ -0,0 +1,463 @@
+/**
+ * StreamSession — A single long-lived Claude Code session with streaming I/O.
+ *
+ * This is the CORE of the system. Instead of spawning a new process for each
+ * message (like the resume approach), StreamSession keeps ONE claude process
+ * alive and pipes messages in/out through stream-json protocol.
+ *
+ * IMPORTANT DISCOVERY: Claude CLI with stream-json mode buffers all output
+ * until the first user message is sent. The "init" event only arrives AFTER
+ * you send the first message. So start() just spawns the process, and the
+ * first send() handles both init and response.
+ *
+ * Protocol (NDJSON — newline-delimited JSON):
+ *
+ *   INPUT (stdin):
+ *     { "type": "user", "message": { "role": "user", "content": "your message" } }
+ *
+ *   OUTPUT (stdout) — arrives after each user message:
+ *     { "type": "system", "subtype": "init", "session_id": "...", "tools": [...] }
+ *     { "type": "assistant", "message": { "content": [{ "type": "text", "text": "..." }] } }
+ *     { "type": "result", "subtype": "success", "result": "full text", "session_id": "..." }
+ *
+ * Usage:
+ *   const session = new StreamSession({ name: 'my-task', model: 'sonnet' });
+ *   session.start();  // Just spawns process, returns immediately
+ *   const r1 = await session.send('Fix the auth bug');   // First message triggers init too
+ *   const r2 = await session.send('Now add tests');      // Instant follow-up
+ *   session.stop();
+ */
+
+const { spawn } = require('child_process');
+const { EventEmitter } = require('events');
+
+// How many milliseconds to wait for a response before timing out
+const DEFAULT_TIMEOUT = 600000; // 10 minutes
+
+class StreamSession extends EventEmitter {
+  /**
+   * Create a new StreamSession.
+   *
+   * @param {object} options - Session configuration
+   * @param {string} options.name - Human-readable session name
+   * @param {string} [options.model='sonnet'] - Model to use
+   * @param {string} [options.workDir] - Working directory for claude
+   * @param {string} [options.permissionMode='default'] - Permission mode
+   * @param {string[]} [options.allowedTools] - Restrict available tools
+   * @param {string} [options.systemPrompt] - Append to system prompt
+   * @param {number} [options.maxBudget] - Max budget in USD
+   * @param {string} [options.agent] - Agent to use
+   * @param {string} [options.sessionId] - Resume existing session
+   * @param {number} [options.timeout] - Response timeout in ms
+   */
+  constructor(options = {}) {
+    super();
+
+    this.name = options.name || `session-${Date.now()}`;
+    this.model = options.model || 'sonnet';
+    this.workDir = options.workDir || process.cwd();
+    this.permissionMode = options.permissionMode || 'default';
+    this.allowedTools = options.allowedTools || [];
+    this.systemPrompt = options.systemPrompt || '';
+    this.maxBudget = options.maxBudget || null;
+    this.agent = options.agent || null;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT;
+
+    // Session state
+    this.id = options.sessionId || null;       // Claude's session UUID (set after init)
+    this.process = null;                        // The child process
+    this.status = 'created';                    // created, ready, busy, paused, stopped, error
+    this.interactions = [];                     // History of all send/receive pairs
+    this.totalCostUsd = 0;                      // Running cost total
+    this.totalTurns = 0;                        // Running turn total
+    this.initData = null;                       // Data from init event
+
+    // Internal streaming state
+    this._buffer = '';                          // Incomplete line buffer
+    this._pendingResolve = null;                // Resolve function for current send()
+    this._pendingReject = null;                 // Reject function for current send()
+    this._pendingTimeout = null;                // Timeout handle
+    this._pendingPrompt = '';                   // The prompt we're waiting for a response to
+    this._partialText = '';                     // Accumulate partial assistant text
+    this._toolCalls = [];                       // Tool calls in current turn
+    this._gotInit = false;                      // Whether init event has been received
+  }
+
+  /**
+   * Start the Claude process. Just spawns it — does NOT wait for init.
+   * The init event arrives when the first message is sent.
+   *
+   * Call send() after this to interact.
+   */
+  start() {
+    if (this.status !== 'created') {
+      throw new Error(`Cannot start: session is "${this.status}"`);
+    }
+
+    // Build claude CLI arguments
+    const args = this._buildArgs();
+
+    // Spawn the process with piped I/O
+    this.process = spawn('claude', args, {
+      cwd: this.workDir,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+
+    // Handle stdout (NDJSON stream)
+    this.process.stdout.on('data', (chunk) => {
+      this._handleData(chunk.toString());
+    });
+
+    // Handle stderr
+    this.process.stderr.on('data', (chunk) => {
+      const msg = chunk.toString().trim();
+      if (msg) {
+        this.emit('stderr', msg);
+      }
+    });
+
+    // Handle process exit
+    this.process.on('close', (code) => {
+      this.status = 'stopped';
+      this.process = null;
+
+      this.emit('close', code);
+
+      // Reject any pending send() promise
+      if (this._pendingReject) {
+        this._pendingReject(new Error(`Process exited while waiting for response (code: ${code})`));
+        this._pendingResolve = null;
+        this._pendingReject = null;
+      }
+      if (this._pendingTimeout) {
+        clearTimeout(this._pendingTimeout);
+        this._pendingTimeout = null;
+      }
+    });
+
+    this.process.on('error', (err) => {
+      this.status = 'error';
+      this.emit('error', err);
+
+      if (this._pendingReject) {
+        this._pendingReject(err);
+        this._pendingResolve = null;
+        this._pendingReject = null;
+      }
+    });
+
+    // Mark as ready to accept send() calls
+    this.status = 'ready';
+    this.emit('started');
+  }
+
+  /**
+   * Send a message and wait for the complete response.
+   *
+   * On the first call, this also triggers the init event from Claude.
+   * Subsequent calls get instant responses (no process restart).
+   *
+   * @param {string} message - The message to send
+   * @param {number} [timeout] - Override timeout for this message
+   * @returns {Promise<object>} Response { text, cost, turns, duration, sessionId, isError, toolCalls, raw }
+   */
+  send(message, timeout) {
+    return new Promise((resolve, reject) => {
+      if (this.status === 'paused') {
+        // Auto-resume if paused
+        this.status = 'ready';
+      }
+
+      if (this.status !== 'ready') {
+        reject(new Error(`Cannot send: session is "${this.status}" (must be "ready")`));
+        return;
+      }
+
+      if (!this.process || !this.process.stdin.writable) {
+        reject(new Error('Process is not running or stdin is closed.'));
+        return;
+      }
+
+      this.status = 'busy';
+      this._partialText = '';
+      this._toolCalls = [];
+      this._pendingPrompt = message;
+      this._pendingResolve = resolve;
+      this._pendingReject = reject;
+
+      // Set timeout
+      const timeoutMs = timeout || this.timeout;
+      this._pendingTimeout = setTimeout(() => {
+        if (this._pendingReject) {
+          this._pendingReject(new Error(`Response timeout after ${timeoutMs}ms`));
+          this._pendingResolve = null;
+          this._pendingReject = null;
+          this.status = 'ready';
+        }
+      }, timeoutMs);
+
+      // Send the message in stream-json format
+      const payload = JSON.stringify({
+        type: 'user',
+        message: { role: 'user', content: message },
+      }) + '\n';
+
+      this.process.stdin.write(payload);
+      this.emit('sent', { message });
+    });
+  }
+
+  /**
+   * Stop the session gracefully.
+   * Closes stdin, which tells claude to exit.
+   */
+  stop() {
+    if (this.process) {
+      this.status = 'stopped';
+      if (this.process.stdin && this.process.stdin.writable) {
+        this.process.stdin.end();
+      }
+    }
+  }
+
+  /**
+   * Force kill the session.
+   */
+  kill() {
+    if (this.process) {
+      this.status = 'stopped';
+      this.process.kill('SIGTERM');
+    }
+  }
+
+  /**
+   * Pause the session (marks it, doesn't kill the process).
+   */
+  pause() {
+    if (this.status === 'ready') {
+      this.status = 'paused';
+      this.emit('paused');
+    }
+  }
+
+  /**
+   * Resume a paused session.
+   */
+  resume() {
+    if (this.status === 'paused') {
+      this.status = 'ready';
+      this.emit('resumed');
+    }
+  }
+
+  /**
+   * Get session info as a plain object.
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      id: this.id,
+      status: this.status,
+      model: this.model,
+      workDir: this.workDir,
+      totalCostUsd: this.totalCostUsd,
+      totalTurns: this.totalTurns,
+      interactionCount: this.interactions.length,
+      pid: this.process ? this.process.pid : null,
+    };
+  }
+
+  // ===========================================================================
+  // Private methods
+  // ===========================================================================
+
+  /**
+   * Build claude CLI arguments for stream-json mode.
+   */
+  _buildArgs() {
+    const args = [
+      '-p',                              // Non-interactive print mode
+      '--input-format', 'stream-json',   // Streaming input
+      '--output-format', 'stream-json',  // Streaming output
+      '--verbose',                       // Required for stream-json output
+      '--model', this.model,
+    ];
+
+    // Resume existing session
+    if (this.id) {
+      args.push('--resume', this.id);
+    }
+
+    // Permission mode
+    if (this.permissionMode && this.permissionMode !== 'default') {
+      args.push('--permission-mode', this.permissionMode);
+    }
+
+    // Allowed tools
+    if (this.allowedTools.length > 0) {
+      args.push('--allowedTools', ...this.allowedTools);
+    }
+
+    // System prompt
+    if (this.systemPrompt) {
+      args.push('--append-system-prompt', this.systemPrompt);
+    }
+
+    // Budget limit
+    if (this.maxBudget) {
+      args.push('--max-budget-usd', String(this.maxBudget));
+    }
+
+    // Agent
+    if (this.agent) {
+      args.push('--agent', this.agent);
+    }
+
+    return args;
+  }
+
+  /**
+   * Handle incoming data from stdout.
+   * Parses NDJSON (newline-delimited JSON) events.
+   */
+  _handleData(data) {
+    this._buffer += data;
+
+    // Split on newlines, keeping incomplete last line in buffer
+    const lines = this._buffer.split('\n');
+    this._buffer = lines.pop();
+
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const event = JSON.parse(line);
+        this._handleEvent(event);
+      } catch (e) {
+        this.emit('parse-error', { line, error: e.message });
+      }
+    }
+  }
+
+  /**
+   * Handle a parsed event from the stream.
+   */
+  _handleEvent(event) {
+    this.emit('event', event);
+
+    switch (event.type) {
+      case 'system':
+        this._handleSystemEvent(event);
+        break;
+      case 'assistant':
+        this._handleAssistantEvent(event);
+        break;
+      case 'result':
+        this._handleResultEvent(event);
+        break;
+      default:
+        this.emit('unknown-event', event);
+    }
+  }
+
+  /**
+   * Handle system events (init, hooks, etc.).
+   */
+  _handleSystemEvent(event) {
+    if (event.subtype === 'init') {
+      this.id = event.session_id;
+      this._gotInit = true;
+
+      this.initData = {
+        sessionId: event.session_id,
+        tools: event.tools || [],
+        model: event.model,
+        mcpServers: event.mcp_servers || [],
+        agents: event.agents || [],
+        skills: event.skills || [],
+      };
+
+      this.emit('init', this.initData);
+    }
+  }
+
+  /**
+   * Handle assistant message events.
+   */
+  _handleAssistantEvent(event) {
+    if (event.message && event.message.content) {
+      for (const block of event.message.content) {
+        if (block.type === 'text') {
+          this._partialText += block.text;
+          this.emit('text', block.text);
+        }
+        if (block.type === 'tool_use') {
+          this._toolCalls.push({
+            id: block.id,
+            name: block.name,
+            input: block.input,
+          });
+          this.emit('tool-use', { id: block.id, name: block.name, input: block.input });
+        }
+      }
+    }
+  }
+
+  /**
+   * Handle result events (final response for a turn).
+   * This is what resolves the send() promise.
+   */
+  _handleResultEvent(event) {
+    // Clear timeout
+    if (this._pendingTimeout) {
+      clearTimeout(this._pendingTimeout);
+      this._pendingTimeout = null;
+    }
+
+    // Update session ID
+    if (event.session_id) {
+      this.id = event.session_id;
+    }
+
+    // Build response object
+    const response = {
+      text: event.result || this._partialText || '',
+      cost: event.total_cost_usd || 0,
+      turns: event.num_turns || 0,
+      duration: event.duration_ms || 0,
+      sessionId: event.session_id,
+      isError: event.is_error || false,
+      usage: event.usage || null,
+      toolCalls: [...this._toolCalls],
+      raw: event,
+    };
+
+    // Update running totals
+    this.totalCostUsd = event.total_cost_usd || this.totalCostUsd;
+    this.totalTurns += event.num_turns || 0;
+
+    // Record the interaction
+    this.interactions.push({
+      prompt: this._pendingPrompt || '',
+      response: response.text,
+      cost: response.cost,
+      turns: response.turns,
+      duration: response.duration,
+      timestamp: new Date().toISOString(),
+    });
+
+    // Back to ready for next message
+    this.status = 'ready';
+
+    this.emit('result', response);
+
+    // Resolve the send() promise
+    if (this._pendingResolve) {
+      this._pendingResolve(response);
+      this._pendingResolve = null;
+      this._pendingReject = null;
+    }
+  }
+}
+
+module.exports = StreamSession;