circuschief 0.1.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "circuschief",
+  "version": "0.1.0",
+  "description": "Local-first web UI for managing Claude Code sessions",
+  "type": "module",
+  "bin": {
+    "circuschief": "./packages/server/bin/cli.js"
+  },
+  "files": [
+    "packages/server/bin/",
+    "packages/server/src/",
+    "packages/shared/src/",
+    "packages/shared/package.json",
+    "packages/web/dist/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "zod": "^4.2.1",
+    "@anthropic-ai/claude-agent-sdk": "^0.1.76",
+    "@anthropic-ai/sdk": "^0.71.2",
+    "better-sqlite3": "^11.7.0",
+    "cors": "^2.8.5",
+    "express": "^4.21.2",
+    "http-proxy-middleware": "^3.0.5",
+    "liquidjs": "^10.24.0",
+    "multer": "^1.4.5-lts.1",
+    "nanoid": "^3.3.0",
+    "ws": "^8.18.0",
+    "yaml": "^2.8.2"
+  }
+}

package/packages/server/bin/cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+process.env.NODE_ENV = 'production';
+import '../src/index.js';

package/packages/server/src/agents/AgentGateway.js

@@ -0,0 +1,64 @@
+import { ClaudeCodeAdapter } from './adapters/ClaudeCodeAdapter.js';
+
+/**
+ * Factory/registry for agent adapters.
+ * Session Manager uses this to get the appropriate adapter for a session's agent type.
+ */
+export class AgentGateway {
+  constructor() {
+    /** @type {Map<string, typeof import('./BaseAgent.js').BaseAgent>} */
+    this.adapters = new Map();
+    this._registerDefaultAdapters();
+  }
+
+  _registerDefaultAdapters() {
+    this.registerAdapter('claude-code', ClaudeCodeAdapter);
+  }
+
+  /**
+   * Register an adapter class for a given agent type.
+   * @param {string} agentType
+   * @param {typeof import('./BaseAgent.js').BaseAgent} AdapterClass
+   */
+  registerAdapter(agentType, AdapterClass) {
+    this.adapters.set(agentType, AdapterClass);
+  }
+
+  /**
+   * Create an agent instance for the given type.
+   * @param {string} agentType - e.g., 'claude-code'
+   * @param {import('./types.js').AgentConfig} [config]
+   * @returns {import('./BaseAgent.js').BaseAgent}
+   */
+  createAgent(agentType, config = {}) {
+    const AdapterClass = this.adapters.get(agentType);
+    if (!AdapterClass) {
+      throw new Error(
+        `Unknown agent type: "${agentType}". Available: ${this.getAvailableAgents().join(', ')}`
+      );
+    }
+    return new AdapterClass({ ...config, agentType });
+  }
+
+  /**
+   * @returns {string[]} List of registered agent type names
+   */
+  getAvailableAgents() {
+    return Array.from(this.adapters.keys());
+  }
+
+  /**
+   * Get capabilities for an agent type (uses a static check, no instantiation).
+   * @param {string} agentType
+   * @returns {Object|null}
+   */
+  getAgentCapabilities(agentType) {
+    const AdapterClass = this.adapters.get(agentType);
+    if (!AdapterClass) return null;
+    // Capabilities are static per adapter class
+    return new AdapterClass({}).getCapabilities();
+  }
+}
+
+// Singleton instance
+export const agentGateway = new AgentGateway();

package/packages/server/src/agents/BaseAgent.js

@@ -0,0 +1,41 @@
+/**
+ * Base agent interface. All adapters must implement `execute()` which returns
+ * an async generator of SDK events.
+ */
+export class BaseAgent {
+  constructor(config = {}) {
+    this.config = config;
+  }
+
+  /**
+   * Execute a query and yield events as an async generator.
+   * This mirrors the SDK's `query()` contract: callers consume with `for await...of`.
+   *
+   * @param {import('./types.js').AgentQueryParams} queryParams - { prompt, options? }
+   * @returns {AsyncGenerator<Object>} - Yields raw SDK events
+   */
+  async *execute(_queryParams) { // eslint-disable-line require-yield
+    throw new Error('execute() must be implemented by adapter');
+  }
+
+  /**
+   * Check if agent supports session resumption via `options.resume`
+   * @returns {boolean}
+   */
+  supportsResume() {
+    return false;
+  }
+
+  /**
+   * Get agent capabilities
+   * @returns {{ streaming: boolean, thinking: boolean, toolUse: boolean, resume: boolean }}
+   */
+  getCapabilities() {
+    return {
+      streaming: false,
+      thinking: false,
+      toolUse: false,
+      resume: false,
+    };
+  }
+}

package/packages/server/src/agents/LoggingAgentWrapper.js

@@ -0,0 +1,73 @@
+import { agentCallLogger } from '../services/agentCallLogger.js';
+
+/**
+ * Extract usage data from a result event
+ * @param {Object} event - The result event
+ * @returns {Object|null} Usage data or null
+ */
+function extractUsageFromEvent(event) {
+  const modelUsageEntry = event.modelUsage
+    ? Object.values(event.modelUsage)[0]
+    : null;
+
+  if (!modelUsageEntry && !event.usage) {
+    return null;
+  }
+
+  return {
+    inputTokens: modelUsageEntry?.inputTokens || event.usage?.input_tokens || 0,
+    outputTokens: modelUsageEntry?.outputTokens || event.usage?.output_tokens || 0,
+    thinkingTokens: 0,
+    cacheReadInputTokens: modelUsageEntry?.cacheReadInputTokens || event.usage?.cache_read_input_tokens || 0,
+    cacheCreationInputTokens: modelUsageEntry?.cacheCreationInputTokens || event.usage?.cache_creation_input_tokens || 0,
+  };
+}
+
+/**
+ * Decorator that wraps a BaseAgent's execute() to log call start/end/errors.
+ * The wrapper is transparent to the consumer -- it yields the same events.
+ */
+export class LoggingAgentWrapper {
+  /**
+   * @param {import('./BaseAgent.js').BaseAgent} agent - The agent to wrap
+   */
+  constructor(agent) {
+    this.agent = agent;
+  }
+
+  /**
+   * Wraps agent.execute() with logging.
+   * @param {import('./types.js').AgentQueryParams} queryParams
+   * @param {import('./types.js').AgentCallMeta} meta - Logging metadata (sessionId, callType, etc.)
+   * @returns {AsyncGenerator<Object>} Same events as the inner agent
+   */
+  async *execute(queryParams, meta) {
+    const callId = agentCallLogger.startCall(meta);
+
+    try {
+      for await (const event of this.agent.execute(queryParams, meta)) {
+        // Capture final usage from 'result' events
+        const usage = (event.type === 'result' && event.subtype !== 'error')
+          ? extractUsageFromEvent(event)
+          : null;
+        if (usage) agentCallLogger.updateUsage(callId, usage);
+
+        yield event;
+      }
+
+      agentCallLogger.completeCall(callId, { success: true });
+    } catch (error) {
+      agentCallLogger.completeCall(callId, { success: false, error });
+      throw error;
+    }
+  }
+
+  // Proxy capability methods
+  supportsResume() {
+    return this.agent.supportsResume();
+  }
+
+  getCapabilities() {
+    return this.agent.getCapabilities();
+  }
+}

package/packages/server/src/agents/adapters/ClaudeCodeAdapter.js

@@ -0,0 +1,33 @@
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { BaseAgent } from '../BaseAgent.js';
+
+/**
+ * Adapter for Claude Code SDK. Wraps the SDK's `query()` function
+ * which returns an async generator of events.
+ *
+ * The adapter does NOT transform events -- it passes through raw SDK events.
+ * Event handling remains in sessionManager's handleStreamEvent().
+ */
+export class ClaudeCodeAdapter extends BaseAgent {
+  /**
+   * Execute a query against the Claude Code SDK.
+   * @param {import('../types.js').AgentQueryParams} queryParams - { prompt, options? }
+   * @yields {Object} Raw SDK events (system, assistant, tool_result, stream_event, result)
+   */
+  async *execute(queryParams) {
+    yield* query(queryParams);
+  }
+
+  supportsResume() {
+    return true;
+  }
+
+  getCapabilities() {
+    return {
+      streaming: true,
+      thinking: true,
+      toolUse: true,
+      resume: true,
+    };
+  }
+}

package/packages/server/src/agents/adapters/CodexAdapter.js

@@ -0,0 +1,26 @@
+import { BaseAgent } from '../BaseAgent.js';
+
+/**
+ * Stub adapter for OpenAI Codex / future agents.
+ * When implemented, this would:
+ * 1. Transform AgentQueryParams into Codex API format
+ * 2. Call the Codex API
+ * 3. Yield events normalized to the SDK event format (system, assistant, tool_result, stream_event, result)
+ *
+ * Phase 7 note: A NormalizedEvent format should be introduced at this point,
+ * along with refactoring handleStreamEvent to consume normalized events.
+ */
+export class CodexAdapter extends BaseAgent {
+  async *execute(_queryParams) { // eslint-disable-line require-yield
+    throw new Error('CodexAdapter is not yet implemented');
+  }
+
+  getCapabilities() {
+    return {
+      streaming: true,
+      thinking: false, // Codex doesn't have explicit thinking
+      toolUse: true,
+      resume: false, // Codex may not support session resume
+    };
+  }
+}

package/packages/server/src/agents/types.js

@@ -0,0 +1,43 @@
+/**
+ * Agent abstraction layer type definitions.
+ *
+ * @typedef {Object} AgentConfig
+ * @property {string} agentType - 'claude-code' | 'codex' | etc.
+ * @property {string} [model] - Model identifier
+ * @property {Object} [providerConfig] - Provider-specific configuration
+ */
+
+/**
+ * @typedef {Object} AgentQueryParams
+ * @property {string} prompt - The prompt text (may include attachments/context)
+ * @property {AgentQueryOptions} [options] - SDK options (omitted in mock mode)
+ */
+
+/**
+ * @typedef {Object} AgentQueryOptions
+ * @property {string} cwd - Working directory
+ * @property {AbortController} abortController - Abort controller
+ * @property {boolean} includePartialMessages - Whether to include partial messages
+ * @property {string} permissionMode - 'default' | 'bypassPermissions'
+ * @property {string[]} settingSources - e.g., ['project']
+ * @property {string} [resume] - Claude session ID for resumption
+ * @property {Object} env - Environment variables
+ * @property {Function} spawnClaudeCodeProcess - Process spawner function
+ * @property {string} [model] - Model to use
+ * @property {string} systemPrompt - System prompt string
+ */
+
+/**
+ * Agent call metadata for logging purposes
+ * @typedef {Object} AgentCallMeta
+ * @property {string} sessionId
+ * @property {string} [conversationId]
+ * @property {string} callType - 'runSession' | 'continueSession' | 'continueSessionWithExistingMessage'
+ * @property {string} [agentType]
+ * @property {string} [model]
+ * @property {string} [effortLevel] - Effort level for the call
+ * @property {boolean} [isResume] - Whether this call uses SDK session resume
+ * @property {number} promptLength - Character length of prompt
+ */
+
+export {};

package/packages/server/src/agents/vcr/CassetteStore.js

@@ -0,0 +1,111 @@
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+
+/**
+ * CassetteStore handles reading/writing VCR cassette files.
+ * Uses atomic writes to prevent corruption from parallel test workers.
+ *
+ * Cassette format:
+ * {
+ *   "key": "runSession-a1b2c3d4e5f6g7h8",
+ *   "prompt": "<original user prompt (truncated)>",
+ *   "model": "claude-haiku-4-5-20251001",
+ *   "recordedAt": "2025-07-15T...",
+ *   "events": [...]
+ * }
+ */
+
+export class CassetteStore {
+  /**
+   * Load a cassette by key
+   * @param {string} cassetteDir - Directory containing cassettes
+   * @param {string} key - Cassette key
+   * @returns {object|null} Cassette object or null if not found
+   */
+  static load(cassetteDir, key) {
+    const filePath = path.join(cassetteDir, `${key}.json`);
+
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      return JSON.parse(content);
+    } catch (error) {
+      console.error(`Failed to load cassette ${key}:`, error.message);
+      return null;
+    }
+  }
+
+  /**
+   * Save a cassette with atomic write (temp file + rename)
+   * @param {string} cassetteDir - Directory to save cassette
+   * @param {string} key - Cassette key
+   * @param {object} cassette - Cassette data to save
+   */
+  static save(cassetteDir, key, cassette) {
+    // Ensure directory exists
+    if (!fs.existsSync(cassetteDir)) {
+      fs.mkdirSync(cassetteDir, { recursive: true });
+    }
+
+    const targetPath = path.join(cassetteDir, `${key}.json`);
+    const tempPath = `${targetPath}.tmp`;
+
+    // Prepare cassette with metadata
+    const cassetteWithMeta = {
+      ...cassette,
+      key,
+      recordedAt: new Date().toISOString(),
+    };
+
+    try {
+      // Atomic write: write to temp file, then rename
+      fs.writeFileSync(tempPath, JSON.stringify(cassetteWithMeta, null, 2), 'utf-8');
+      fs.renameSync(tempPath, targetPath);
+    } catch (error) {
+      // Clean up temp file if write failed
+      if (fs.existsSync(tempPath)) {
+        fs.unlinkSync(tempPath);
+      }
+      throw new Error(`Failed to save cassette ${key}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Build a cassette key from a call type and prompt text
+   * Keys on callType + hash of the original user prompt only
+   * (excludes system prompt, UUIDs, ports, and conversation context)
+   *
+   * @param {string} callType - Type of call (e.g., 'runSession', 'summary')
+   * @param {string} promptText - The raw user prompt text
+   * @returns {string} Cassette key
+   */
+  static buildKey(callType, promptText) {
+    const hash = crypto.createHash('sha256').update(promptText).digest('hex').substring(0, 16);
+    return `${callType}-${hash}`;
+  }
+
+  /**
+   * Deep copy an event for storage
+   * Handles non-cloneable objects with shallow-copy fallback
+   *
+   * @param {any} event - Event to copy
+   * @returns {any} Copied event
+   */
+  static deepCopyEvent(event) {
+    // Handle null and undefined explicitly
+    if (event === null || event === undefined) {
+      return event;
+    }
+
+    try {
+      return JSON.parse(JSON.stringify(event));
+    } catch {
+      // Fallback to shallow copy for objects with non-cloneable refs
+      return { ...event };
+    }
+  }
+}

package/packages/server/src/agents/vcr/VCRAgentAdapter.js

@@ -0,0 +1,126 @@
+import { CassetteStore } from './CassetteStore.js';
+
+/**
+ * VCR (Video Cassette Recorder) Agent Adapter
+ *
+ * A decorator/wrapper around any agent that provides record/replay functionality.
+ * Same pattern as LoggingAgentWrapper — does NOT extend BaseAgent.
+ *
+ * Modes:
+ * - 'auto': Replay if cassette exists, record if not (default for E2E)
+ * - 'record': Always record (overwrite existing cassettes)
+ * - 'replay': Always replay (fail if cassette missing)
+ * - unset: VCR disabled — pass through to inner agent
+ *
+ * Environment variable: VCR_MODE=auto|record|replay
+ */
+export class VCRAgentAdapter {
+  /**
+   * @param {object} innerAgent - The real agent to wrap
+   * @param {object} options - Configuration options
+   * @param {string} options.cassetteDir - Directory for cassette files
+   */
+  constructor(innerAgent, options = {}) {
+    this.innerAgent = innerAgent;
+    this.cassetteDir = options.cassetteDir || 'tests/e2e/cassettes';
+    // Only enable VCR if VCR_MODE is explicitly set
+    this.mode = process.env.VCR_MODE || undefined;
+  }
+
+  /**
+   * Execute query with record/replay behavior
+   * @param {object} queryParams - Query parameters
+   * @param {object} meta - Metadata (includes callType)
+   * @returns {AsyncGenerator} Generator yielding events
+   */
+  async *execute(queryParams, meta) {
+    const key = this.buildCassetteKey(queryParams, meta);
+
+    if (this.mode === 'record') {
+      yield* this.record(key, queryParams, meta);
+    } else if (this.mode === 'replay') {
+      const cassette = CassetteStore.load(this.cassetteDir, key);
+      if (!cassette) {
+        throw new Error(`VCR replay: no cassette found for "${key}"`);
+      }
+      yield* this.replay(cassette);
+    } else if (this.mode === 'auto') {
+      const cassette = CassetteStore.load(this.cassetteDir, key);
+      if (cassette) {
+        yield* this.replay(cassette);
+      } else {
+        yield* this.record(key, queryParams, meta);
+      }
+    } else {
+      // VCR disabled — pass through to inner agent
+      yield* this.innerAgent.execute(queryParams, meta);
+    }
+  }
+
+  /**
+   * Build cassette key from query parameters
+   * Uses callType + hash of original user prompt only
+   *
+   * @param {object} queryParams - Query parameters
+   * @param {object} meta - Metadata
+   * @returns {string} Cassette key
+   */
+  buildCassetteKey(queryParams, meta) {
+    const callType = meta?.callType || 'unknown';
+    const promptText = queryParams.prompt || '';
+    return CassetteStore.buildKey(callType, promptText);
+  }
+
+  /**
+   * Replay from a cassette
+   * @param {object} cassette - Cassette to replay
+   * @returns {AsyncGenerator} Generator yielding events
+   */
+  async *replay(cassette) {
+    for (const event of cassette.events) {
+      // Small delay to simulate streaming
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      yield event;
+    }
+  }
+
+  /**
+   * Record to a cassette
+   * @param {string} key - Cassette key
+   * @param {object} queryParams - Query parameters
+   * @param {object} meta - Metadata
+   * @returns {AsyncGenerator} Generator yielding events
+   */
+  async *record(key, queryParams, meta) {
+    const events = [];
+
+    // Execute real query and collect events
+    for await (const event of this.innerAgent.execute(queryParams, meta)) {
+      events.push(CassetteStore.deepCopyEvent(event));
+      yield event;
+    }
+
+    // Save cassette
+    CassetteStore.save(this.cassetteDir, key, {
+      prompt: queryParams.prompt?.substring(0, 500),
+      model: queryParams.options?.model,
+      events,
+    });
+  }
+
+  /**
+   * Proxy resume support to inner agent
+   * @returns {boolean}
+   */
+  supportsResume() {
+    return this.innerAgent.supportsResume?.() ?? false;
+  }
+
+  /**
+   * Proxy capabilities to inner agent
+   * @returns {object}
+   */
+  getCapabilities() {
+    return this.innerAgent.getCapabilities?.() ?? {};
+  }
+}

package/packages/server/src/agents/vcr/VCRSummaryWrapper.js

@@ -0,0 +1,71 @@
+import { CassetteStore } from './CassetteStore.js';
+
+/**
+ * Build cassette key for summary calls
+ * Summary prompts are built from a fixed template + message content, so these are stable
+ *
+ * @param {object} queryParams - Query parameters
+ * @param {string|null} keyHint - Optional stable key hint to use instead of prompt text.
+ *   When provided, the cassette key is derived from keyHint rather than the dynamic prompt,
+ *   ensuring stable keys across test runs even when prompt content changes.
+ * @returns {string} Cassette key
+ */
+function buildSummaryKey(queryParams, keyHint = null) {
+  const keySource = keyHint || queryParams.prompt || '';
+  return CassetteStore.buildKey('summary', keySource);
+}
+
+/**
+ * Create a VCR-wrapped query function for summary service
+ *
+ * The summary service calls the SDK query() directly rather than going through
+ * the agent gateway. This wrapper provides the same record/replay behavior.
+ *
+ * @param {function} realQueryFn - The real query function to wrap
+ * @param {string} cassetteDir - Directory for cassette files
+ * @param {string|null} keyHint - Optional stable key hint for cassette key generation.
+ *   When provided, overrides the default prompt-based key, ensuring stable cassette
+ *   keys across test runs even when prompt content is dynamic.
+ * @returns {function} VCR-wrapped query function
+ */
+export function createVCRQueryFn(realQueryFn, cassetteDir, keyHint = null) {
+  // Only enable VCR if VCR_MODE is explicitly set
+  const mode = process.env.VCR_MODE || undefined;
+
+  return async function* vcrQuery(queryParams) {
+    const key = buildSummaryKey(queryParams, keyHint);
+    const cassette = CassetteStore.load(cassetteDir, key);
+
+    // VCR disabled - pass through to real query
+    if (!mode) {
+      yield* realQueryFn(queryParams);
+      return;
+    }
+
+    if (mode === 'record' || (mode === 'auto' && !cassette)) {
+      // Record mode
+      const events = [];
+      for await (const event of realQueryFn(queryParams)) {
+        events.push(CassetteStore.deepCopyEvent(event));
+        yield event;
+      }
+      CassetteStore.save(cassetteDir, key, {
+        prompt: queryParams.prompt?.substring(0, 200),
+        model: queryParams.options?.model,
+        events,
+      });
+    } else if (cassette) {
+      // Replay mode (cassette exists)
+      for (const event of cassette.events) {
+        // Small delay to simulate streaming
+        await new Promise((resolve) => setTimeout(resolve, 5));
+        yield event;
+      }
+    } else {
+      // Replay mode but no cassette
+      throw new Error(
+        `VCR replay: summary cassette not found for "${key}". Run with VCR_MODE=record to create it.`
+      );
+    }
+  };
+}