circuschief 0.1.0

package/packages/server/src/services/usageTracker.js

@@ -0,0 +1,69 @@
+/** @type {Map<string, {inputTokens: number, outputTokens: number, lastMessageOutput: number, cacheReadInputTokens: number, cacheCreationInputTokens: number}>}
+ * Current turn usage - accumulates across multiple messages within a turn
+ * Keyed by conversationId (Issue #175)
+ * - inputTokens: MAX seen across all messages (larger context with tool results)
+ * - outputTokens: ACCUMULATED across all messages
+ * - lastMessageOutput: Current message's output (to detect resets on message_start)
+ */
+const currentTurnUsage = new Map();
+
+/** @type {Map<string, number>} Estimated output tokens from streamed content (for real-time updates) */
+const estimatedOutputTokens = new Map();
+
+/**
+ * Rough token estimation: ~4 characters per token (standard for English text)
+ * @param {string} text
+ * @returns {number} Estimated token count
+ */
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+
+/**
+ * Update current turn usage from stream events
+ * Accumulates across multiple messages within a single turn
+ * @param {string} conversationId
+ * @param {Object} usage - Usage from stream event (snake_case)
+ * @param {string} eventType - 'message_start' or 'message_delta'
+ * @returns {Object} Total turn usage (accumulated + current message)
+ */
+function updateTurnUsage(conversationId, usage, eventType) {
+  const current = currentTurnUsage.get(conversationId) || {
+    inputTokens: 0,
+    outputTokens: 0,
+    lastMessageOutput: 0,
+    cacheReadInputTokens: 0,
+    cacheCreationInputTokens: 0,
+  };
+
+  if (eventType === 'message_start') {
+    // NEW MESSAGE STARTING
+    // 1. Finalize previous message's output
+    current.outputTokens += current.lastMessageOutput;
+    // 2. Reset tracker for new message
+    current.lastMessageOutput = 0;
+    // 3. Reset estimated output when actual message starts
+    estimatedOutputTokens.delete(conversationId);
+    // 4. For input tokens, keep the MAX (larger context with tool results)
+    current.inputTokens = Math.max(current.inputTokens, usage.input_tokens || 0);
+    current.cacheReadInputTokens = Math.max(current.cacheReadInputTokens, usage.cache_read_input_tokens || 0);
+    current.cacheCreationInputTokens = Math.max(current.cacheCreationInputTokens, usage.cache_creation_input_tokens || 0);
+  } else if (eventType === 'message_delta') {
+    // OUTPUT STREAMING - output_tokens is cumulative within this message
+    current.lastMessageOutput = usage.output_tokens || 0;
+    // Clear estimate when actual output tokens arrive
+    estimatedOutputTokens.delete(conversationId);
+  }
+
+  currentTurnUsage.set(conversationId, current);
+
+  // Return the TOTAL (accumulated + current message's output)
+  return {
+    inputTokens: current.inputTokens,
+    outputTokens: current.outputTokens + current.lastMessageOutput,
+    cacheReadInputTokens: current.cacheReadInputTokens,
+    cacheCreationInputTokens: current.cacheCreationInputTokens,
+  };
+}
+
+export { estimateTokens, updateTurnUsage, currentTurnUsage, estimatedOutputTokens };

package/packages/server/src/services/withConcurrencyGuard.js

@@ -0,0 +1,110 @@
+/**
+ * Concurrency guard utility.
+ * Ensures only one async operation runs per key at a time.
+ * If a second call arrives while one is in-flight, it coalesces into a single
+ * follow-up execution after the current one completes.
+ */
+
+/**
+ * Create a concurrency guard instance.
+ * Returns an object with `run` and `cleanup` methods plus access to internal state.
+ *
+ * @returns {{ run: Function, cleanup: Function, activeGenerations: Map, pendingRegenerations: Set }}
+ */
+export function createConcurrencyGuard() {
+  const activeGenerations = new Map(); // key -> Promise
+  const pendingRegenerations = new Set(); // keys that need follow-up after current completes
+
+  /**
+   * Run an async function with concurrency guard.
+   * If a function is already running for this key, the call is coalesced
+   * and a single follow-up is scheduled after the current one completes.
+   *
+   * @param {string} key - The concurrency key (e.g., sessionId)
+   * @param {Function} fn - The async function to run
+   * @param {Object} options - Options
+   * @param {boolean} options.bypass - If true, skip the concurrency check (e.g., for user-initiated actions)
+   * @param {Function} options.onFollowUp - Function to call for follow-up generation after coalesced call
+   * @returns {Promise<*>} The result of fn()
+   */
+  async function run(key, fn, options = {}) {
+    const { bypass = false, onFollowUp } = options;
+
+    // Concurrency guard: if a generation is already in-flight for this key,
+    // queue a single follow-up instead of running concurrently
+    if (activeGenerations.has(key) && !bypass) {
+      pendingRegenerations.add(key);
+      return activeGenerations.get(key);
+    }
+
+    const promise = fn();
+    activeGenerations.set(key, promise);
+
+    try {
+      return await promise;
+    } finally {
+      activeGenerations.delete(key);
+      if (pendingRegenerations.has(key)) {
+        pendingRegenerations.delete(key);
+        // Schedule follow-up generation
+        if (onFollowUp) {
+          onFollowUp(key);
+        }
+      }
+    }
+  }
+
+  /**
+   * Clean up any pending and active state for a key (e.g., on session deletion)
+   * @param {string} key - The key to clean up
+   */
+  function cleanup(key) {
+    activeGenerations.delete(key);
+    pendingRegenerations.delete(key);
+  }
+
+  /**
+   * Check if a generation is currently active for a key
+   * @param {string} key - The concurrency key
+   * @returns {boolean}
+   */
+  function isActive(key) {
+    return activeGenerations.has(key);
+  }
+
+  /**
+   * Check if a regeneration is pending for a key
+   * @param {string} key - The concurrency key
+   * @returns {boolean}
+   */
+  function isPending(key) {
+    return pendingRegenerations.has(key);
+  }
+
+  /**
+   * Get a snapshot of all active keys
+   * @returns {Array<string>}
+   */
+  function activeKeys() {
+    return Array.from(activeGenerations.keys());
+  }
+
+  /**
+   * Get a snapshot of all pending keys
+   * @returns {Array<string>}
+   */
+  function pendingKeys() {
+    return Array.from(pendingRegenerations);
+  }
+
+  return {
+    run,
+    cleanup,
+    isActive,
+    isPending,
+    activeKeys,
+    pendingKeys,
+    activeGenerations,
+    pendingRegenerations,
+  };
+}

package/packages/server/src/websocket.js

@@ -0,0 +1,10 @@
+// Re-export everything from ws module for backward compatibility
+export {
+  WebSocketManager,
+  webSocketManager,
+  initWebSocket,
+  broadcast,
+  broadcastToSession,
+  broadcastToProject,
+  getWebSocketServer,
+} from './ws/index.js';

package/packages/server/src/ws/WebSocketManager.js

@@ -0,0 +1,240 @@
+import { WebSocketServer } from 'ws';
+import { WS_MESSAGE_TYPES, parseMessage, createMessage } from '../../../shared/src/index.js';
+
+/**
+ * WebSocket manager class for handling WebSocket connections and messaging
+ */
+export class WebSocketManager {
+  /** @type {WebSocketServer|null} */
+  #wss = null;
+
+  /** @type {Set<import('ws').WebSocket>} */
+  #clients = new Set();
+
+  /** @type {Map<string, Set<import('ws').WebSocket>>} */
+  #sessionSubscriptions = new Map();
+
+  /** @type {Map<string, Set<import('ws').WebSocket>>} */
+  #projectSubscriptions = new Map();
+
+  /** @type {Map<string, Array<Object>>} */
+  #usageUpdateBuffer = new Map();
+
+  /**
+   * Initialize WebSocket server
+   * @param {import('http').Server} server - HTTP server to attach to
+   * @returns {WebSocketServer}
+   */
+  init(server) {
+    this.#wss = new WebSocketServer({ server, path: '/ws' });
+
+    this.#wss.on('connection', (ws) => {
+      this.#clients.add(ws);
+
+      ws.on('message', (data) => {
+        const message = parseMessage(data.toString());
+        if (!message) return;
+
+        this.#handleMessage(ws, message);
+      });
+
+      ws.on('close', () => {
+        this.#clients.delete(ws);
+        // Remove from all session subscriptions
+        for (const subscribers of this.#sessionSubscriptions.values()) {
+          subscribers.delete(ws);
+        }
+        // Remove from all project subscriptions
+        for (const subscribers of this.#projectSubscriptions.values()) {
+          subscribers.delete(ws);
+        }
+      });
+
+      ws.on('error', (error) => {
+        console.error('WebSocket error:', error);
+      });
+    });
+
+    return this.#wss;
+  }
+
+  /**
+   * Handle incoming WebSocket message
+   * @param {import('ws').WebSocket} ws
+   * @param {Object} message
+   */
+  #handleMessage(ws, message) {
+    const handlers = {
+      [WS_MESSAGE_TYPES.SUBSCRIBE_SESSION]: () => this.#handleSubscribeSession(ws, message),
+      [WS_MESSAGE_TYPES.UNSUBSCRIBE_SESSION]: () => this.#handleUnsubscribeSession(ws, message),
+      [WS_MESSAGE_TYPES.SUBSCRIBE_PROJECT]: () => this.#handleSubscribeProject(ws, message),
+      [WS_MESSAGE_TYPES.UNSUBSCRIBE_PROJECT]: () => this.#handleUnsubscribeProject(ws, message),
+    };
+    handlers[message.type]?.();
+  }
+
+  #handleSubscribeSession(ws, message) {
+    const { sessionId } = message;
+    if (!sessionId) return;
+
+    if (!this.#sessionSubscriptions.has(sessionId)) {
+      this.#sessionSubscriptions.set(sessionId, new Set());
+    }
+    this.#sessionSubscriptions.get(sessionId).add(ws);
+    this.#replayBufferedUsageUpdates(ws, sessionId);
+  }
+
+  #replayBufferedUsageUpdates(ws, sessionId) {
+    const buffered = this.#usageUpdateBuffer.get(sessionId);
+    if (!buffered || buffered.length === 0) return;
+
+    for (const bufferedMsg of buffered) {
+      const msg = createMessage(bufferedMsg.type, bufferedMsg);
+      if (ws.readyState === 1) {
+        ws.send(msg);
+      }
+    }
+    this.#usageUpdateBuffer.delete(sessionId);
+  }
+
+  #handleUnsubscribeSession(ws, message) {
+    const { sessionId } = message;
+    if (!sessionId) return;
+    this.#sessionSubscriptions.get(sessionId)?.delete(ws);
+  }
+
+  #handleSubscribeProject(ws, message) {
+    const { projectId } = message;
+    if (!projectId) return;
+
+    if (!this.#projectSubscriptions.has(projectId)) {
+      this.#projectSubscriptions.set(projectId, new Set());
+    }
+    this.#projectSubscriptions.get(projectId).add(ws);
+  }
+
+  #handleUnsubscribeProject(ws, message) {
+    const { projectId } = message;
+    if (!projectId) return;
+    this.#projectSubscriptions.get(projectId)?.delete(ws);
+  }
+
+  /**
+   * Broadcast message to all connected clients
+   * @param {string} type - Message type
+   * @param {Object} payload - Message payload
+   */
+  broadcast(type, payload) {
+    const message = createMessage(type, payload);
+    for (const client of this.#clients) {
+      if (client.readyState === 1) {
+        // WebSocket.OPEN
+        client.send(message);
+      }
+    }
+  }
+
+  /**
+   * Broadcast message to clients subscribed to a session
+   * @param {string} sessionId - Session ID
+   * @param {string} type - Message type
+   * @param {Object} payload - Message payload
+   */
+  broadcastToSession(sessionId, type, payload) {
+    const subscribers = this.#sessionSubscriptions.get(sessionId);
+
+    // Buffer SESSION_USAGE_UPDATE messages if no subscribers exist
+    if (type === 'session:usage_update' && (!subscribers || subscribers.size === 0)) {
+      if (!this.#usageUpdateBuffer.has(sessionId)) {
+        this.#usageUpdateBuffer.set(sessionId, []);
+      }
+      const buffer = this.#usageUpdateBuffer.get(sessionId);
+      buffer.push({ type, ...payload });
+      // Keep reasonable buffer size (max 50 messages)
+      if (buffer.length > 50) {
+        buffer.shift();
+      }
+      return;
+    }
+
+    if (!subscribers || subscribers.size === 0) {
+      return;
+    }
+
+    const message = createMessage(type, payload);
+    for (const client of subscribers) {
+      if (client.readyState === 1) {
+        // WebSocket.OPEN
+        client.send(message);
+      }
+    }
+  }
+
+  /**
+   * Broadcast message to clients subscribed to a project
+   * @param {string} projectId - Project ID
+   * @param {string} type - Message type
+   * @param {Object} payload - Message payload
+   */
+  broadcastToProject(projectId, type, payload) {
+    const subscribers = this.#projectSubscriptions.get(projectId);
+    if (!subscribers || subscribers.size === 0) return;
+
+    const message = createMessage(type, payload);
+    for (const client of subscribers) {
+      if (client.readyState === 1) {
+        // WebSocket.OPEN
+        client.send(message);
+      }
+    }
+  }
+
+  /**
+   * Get WebSocket server instance
+   * @returns {WebSocketServer|null}
+   */
+  getServer() {
+    return this.#wss;
+  }
+
+  /**
+   * Get all connected clients
+   * @returns {Set<import('ws').WebSocket>}
+   */
+  getClients() {
+    return this.#clients;
+  }
+
+  /**
+   * Get session subscriptions
+   * @returns {Map<string, Set<import('ws').WebSocket>>}
+   */
+  getSessionSubscriptions() {
+    return this.#sessionSubscriptions;
+  }
+
+  /**
+   * Get project subscriptions
+   * @returns {Map<string, Set<import('ws').WebSocket>>}
+   */
+  getProjectSubscriptions() {
+    return this.#projectSubscriptions;
+  }
+
+  /**
+   * Close the WebSocket server
+   */
+  close() {
+    if (this.#wss) {
+      this.#wss.close();
+      this.#wss = null;
+    }
+    this.#clients.clear();
+    this.#sessionSubscriptions.clear();
+    this.#projectSubscriptions.clear();
+    this.#usageUpdateBuffer.clear();
+  }
+}
+
+// Singleton instance
+export const webSocketManager = new WebSocketManager();

package/packages/server/src/ws/index.js

@@ -0,0 +1,50 @@
+export { WebSocketManager, webSocketManager } from './WebSocketManager.js';
+
+// Legacy function exports for backward compatibility
+import { webSocketManager } from './WebSocketManager.js';
+
+/**
+ * Initialize WebSocket server
+ * @param {import('http').Server} server
+ * @returns {import('ws').WebSocketServer}
+ */
+export function initWebSocket(server) {
+  return webSocketManager.init(server);
+}
+
+/**
+ * Broadcast message to all connected clients
+ * @param {string} type
+ * @param {Object} payload
+ */
+export function broadcast(type, payload) {
+  webSocketManager.broadcast(type, payload);
+}
+
+/**
+ * Broadcast message to clients subscribed to a session
+ * @param {string} sessionId
+ * @param {string} type
+ * @param {Object} payload
+ */
+export function broadcastToSession(sessionId, type, payload) {
+  webSocketManager.broadcastToSession(sessionId, type, payload);
+}
+
+/**
+ * Broadcast message to clients subscribed to a project
+ * @param {string} projectId
+ * @param {string} type
+ * @param {Object} payload
+ */
+export function broadcastToProject(projectId, type, payload) {
+  webSocketManager.broadcastToProject(projectId, type, payload);
+}
+
+/**
+ * Get WebSocket server instance
+ * @returns {import('ws').WebSocketServer|null}
+ */
+export function getWebSocketServer() {
+  return webSocketManager.getServer();
+}

package/packages/shared/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@circuschief/shared",
+  "version": "1.0.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./types": "./src/types.js",
+    "./protocol": "./src/protocol.js",
+    "./constants": "./src/constants.js",
+    "./contracts/*": "./src/contracts/*.js",
+    "./utils": "./src/utils.js",
+    "./routeParams": "./src/routeParams.js"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.16"
+  }
+}

package/packages/shared/src/constants.js

@@ -0,0 +1,44 @@
+export const DEFAULT_SERVER_PORT = 5000;
+
+export const API_PREFIX = '/api';
+export const WS_PATH = '/ws';
+
+/**
+ * Default token cost weights for calculating Billable Token Equivalent (BTE)
+ * These weights represent relative costs compared to input tokens (1.0 = base rate)
+ */
+export const DEFAULT_TOKEN_COST_WEIGHTS = {
+  input: 1.0,        // Base rate
+  output: 5.0,       // 5x input cost (output tokens are more expensive)
+  cacheRead: 0.1,    // 90% discount for cache reads
+  cacheCreation: 1.25 // 25% premium for cache creation
+};
+
+export const MAX_JSON_SIZE = '50mb';
+
+export const WS_RECONNECT_BASE_DELAY = 2000;
+export const WS_RECONNECT_MAX_DELAY = 30000;
+
+export const TOAST_DURATION = 5000;
+
+export const DEFAULT_SYSTEM_PROMPT = `You are Claude Code, an AI coding assistant. You help users with software engineering tasks including writing code, debugging, refactoring, and explaining code. You have full access to the shell and can execute any commands needed to assist the user. Be helpful, accurate, and thorough.
+
+IMPORTANT: Your working directory is already set correctly for this session. NEVER use \`cd\` to change to a hardcoded project path before running commands (e.g., \`cd /path/to/project && git status\`). This bypasses git worktree isolation and causes commands to run in the wrong directory. Always run commands directly without changing directory.
+
+## Canvas Behavior
+IMPORTANT: NEVER proactively put artifacts on the canvas unless the user explicitly requests it. Do not put images, markdown documents, code snippets, data visualizations, PDFs, or other artifacts on the canvas without being asked. Only use the canvas when the user specifically asks you to display or share something.
+
+## Plan Files
+When creating plan files or design documents, always write them to a temporary directory:
+- Use \`~/.claude/plans/<descriptive-name>.md\` for plan files
+- Use the Write tool to create these files
+- This keeps plans organized and separate from the main codebase`;
+
+/**
+ * Default prompt for generating session titles
+ */
+export const DEFAULT_SESSION_TITLE_PROMPT = `Guidelines for generating session titles:
+- state the goal of the session - ignore the goal of the conversation, we're interested in the goal of the session as a whole
+- If a PR was created, format as "PR #N: <strategic goal>"
+- Only change the title if the session's fundamental purpose has changed
+- Keep titles concise (max 60 characters)`;

package/packages/shared/src/contracts/canvas.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+
+export const CreateCanvasItemRequest = z.object({
+  filePath: z.string(),
+});
+
+export const CanvasItemResponse = z.object({
+  id: z.string().uuid(),
+  sessionId: z.string().uuid().nullable(),
+  type: z.enum(['image', 'markdown', 'text', 'json', 'pdf', 'code']),
+  content: z.string().nullable(),
+  data: z.string().nullable(),
+  mimeType: z.string().nullable(),
+  filename: z.string().nullable(),
+  width: z.number().nullable(),
+  height: z.number().nullable(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+});
+
+export const UpdateCanvasItemRequest = z.object({
+  content: z.string().min(0),
+});
+
+export const CanvasListResponse = z.array(CanvasItemResponse);

package/packages/shared/src/contracts/commandButtons.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+
+export const CreateCommandButtonRequest = z.object({
+  label: z.string().min(1, 'Label is required'),
+  command: z.string().min(1, 'Command is required'),
+  sortOrder: z.number().int().optional().default(0),
+  showOnList: z.boolean().optional().default(false),
+});
+
+export const UpdateCommandButtonRequest = z.object({
+  label: z.string().min(1).optional(),
+  command: z.string().min(1).optional(),
+  sortOrder: z.number().int().optional(),
+  showOnList: z.boolean().optional(),
+}).refine(obj => Object.keys(obj).length > 0, 'At least one field must be provided for update');
+
+export const CommandButtonResponse = z.object({
+  id: z.string(),
+  projectId: z.string(),
+  label: z.string(),
+  command: z.string(),
+  sortOrder: z.number().int(),
+  showOnList: z.boolean(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+});
+
+export const CommandButtonListResponse = z.array(CommandButtonResponse);
+
+export const CommandRunResponse = z.object({
+  runId: z.string(),
+  buttonId: z.string(),
+  status: z.enum(['running', 'success', 'error', 'killed']),
+  exitCode: z.number().int().nullable(),
+  output: z.string().optional(),
+});