mstro-app 0.1.47

package/server/cli/headless/claude-invoker.ts

@@ -0,0 +1,415 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * Claude Invoker
+ *
+ * Handles spawning and managing Claude CLI processes.
+ */
+
+import { type ChildProcess, spawn } from 'node:child_process';
+import { generateMcpConfig } from './mcp-config.js';
+import { detectErrorInStderr, } from './output-utils.js';
+import { buildMultimodalMessage } from './prompt-utils.js';
+import type {
+  ExecutionResult,
+  ResolvedHeadlessConfig, 
+  ToolUseAccumulator,
+} from './types.js';
+
+export interface ClaudeInvokerOptions {
+  config: ResolvedHeadlessConfig;
+  runningProcesses: Map<number, ChildProcess>;
+}
+
+// ========== Stream Event Handlers ==========
+
+interface StreamHandlerContext {
+  config: ResolvedHeadlessConfig;
+  accumulatedAssistantResponse: string;
+  accumulatedThinking: string;
+  accumulatedToolUse: ToolUseAccumulator[];
+  toolInputBuffers: Map<number, { name: string; id: string; inputJson: string; startTime: number }>;
+}
+
+function handleSessionCapture(
+  parsed: any,
+  captured: { claudeSessionId?: string }
+): void {
+  if (parsed.type === 'system' && parsed.subtype === 'init' && parsed.session_id) {
+    captured.claudeSessionId = parsed.session_id;
+  }
+  if (parsed.type === 'result' && parsed.session_id && !captured.claudeSessionId) {
+    captured.claudeSessionId = parsed.session_id;
+  }
+}
+
+function handleThinkingDelta(event: any, ctx: StreamHandlerContext): string {
+  if (
+    event.type !== 'content_block_delta' ||
+    event.delta?.type !== 'thinking_delta' ||
+    !event.delta?.thinking
+  ) {
+    return ctx.accumulatedThinking;
+  }
+
+  const thinking = event.delta.thinking;
+  const updated = ctx.accumulatedThinking + thinking;
+
+  if (ctx.config.thinkingCallback) {
+    ctx.config.thinkingCallback(thinking);
+  } else if (ctx.config.outputCallback) {
+    ctx.config.outputCallback(thinking);
+  } else {
+    process.stdout.write(thinking);
+  }
+
+  return updated;
+}
+
+function handleTextDelta(event: any, ctx: StreamHandlerContext): string {
+  if (
+    event.type !== 'content_block_delta' ||
+    event.delta?.type !== 'text_delta' ||
+    !event.delta?.text
+  ) {
+    return ctx.accumulatedAssistantResponse;
+  }
+
+  const text = event.delta.text;
+  const updated = ctx.accumulatedAssistantResponse + text;
+
+  if (ctx.config.outputCallback) {
+    ctx.config.outputCallback(text);
+  }
+
+  return updated;
+}
+
+function handleToolStart(event: any, ctx: StreamHandlerContext): void {
+  if (
+    event.type !== 'content_block_start' ||
+    event.content_block?.type !== 'tool_use'
+  ) {
+    return;
+  }
+
+  const toolName = event.content_block.name;
+  const toolId = event.content_block.id;
+  const index = event.index;
+
+  ctx.toolInputBuffers.set(index, {
+    name: toolName,
+    id: toolId,
+    inputJson: '',
+    startTime: Date.now()
+  });
+
+  if (ctx.config.toolUseCallback) {
+    ctx.config.toolUseCallback({ type: 'tool_start', toolName, toolId, index });
+  }
+}
+
+function handleToolInputDelta(event: any, ctx: StreamHandlerContext): void {
+  if (
+    event.type !== 'content_block_delta' ||
+    event.delta?.type !== 'input_json_delta'
+  ) {
+    return;
+  }
+
+  const index = event.index;
+  const partialJson = event.delta.partial_json;
+
+  const toolBuffer = ctx.toolInputBuffers.get(index);
+  if (toolBuffer) {
+    toolBuffer.inputJson += partialJson;
+  }
+
+  if (ctx.config.toolUseCallback) {
+    ctx.config.toolUseCallback({ type: 'tool_input_delta', partialJson, index });
+  }
+}
+
+function handleToolComplete(event: any, ctx: StreamHandlerContext): void {
+  if (event.type !== 'content_block_stop') {
+    return;
+  }
+
+  const index = event.index;
+  const toolBuffer = ctx.toolInputBuffers.get(index);
+  if (!toolBuffer) {
+    return;
+  }
+
+  let completeInput: any = {};
+  try {
+    completeInput = JSON.parse(toolBuffer.inputJson);
+  } catch (_e) {
+    // Input might not be valid JSON yet
+  }
+
+  ctx.accumulatedToolUse.push({
+    toolName: toolBuffer.name,
+    toolId: toolBuffer.id,
+    toolInput: completeInput,
+    startTime: toolBuffer.startTime
+  });
+
+  if (ctx.config.toolUseCallback) {
+    ctx.config.toolUseCallback({
+      type: 'tool_complete',
+      toolName: toolBuffer.name,
+      toolId: toolBuffer.id,
+      index,
+      completeInput
+    });
+  }
+}
+
+function handleToolResult(parsed: any, ctx: StreamHandlerContext): void {
+  if (parsed.type !== 'user' || !parsed.message?.content) {
+    return;
+  }
+
+  for (const content of parsed.message.content) {
+    if (content.type !== 'tool_result') {
+      continue;
+    }
+
+    const toolId = content.tool_use_id;
+    const result = content.content;
+    const isError = content.is_error || false;
+    const resultStr = typeof result === 'string' ? result : JSON.stringify(result);
+
+    const toolEntry = ctx.accumulatedToolUse.find(t => t.toolId === toolId);
+    if (toolEntry) {
+      toolEntry.result = resultStr;
+      toolEntry.isError = isError;
+      toolEntry.duration = Date.now() - toolEntry.startTime;
+    }
+
+    if (ctx.config.toolUseCallback) {
+      ctx.config.toolUseCallback({ type: 'tool_result', toolId, result: resultStr, isError });
+    }
+  }
+}
+
+function processStreamLines(
+  buffer: string,
+  sessionCapture: { claudeSessionId?: string },
+  ctx: StreamHandlerContext
+): string {
+  const lines = buffer.split('\n');
+  const remainder = lines.pop() || '';
+
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    try {
+      const parsed = JSON.parse(line);
+      handleSessionCapture(parsed, sessionCapture);
+      processStreamEvent(parsed, ctx);
+    } catch (_e) {
+      // Ignore parse errors
+    }
+  }
+
+  return remainder;
+}
+
+function processStreamEvent(parsed: any, ctx: StreamHandlerContext): void {
+  if (parsed.type === 'stream_event' && parsed.event) {
+    const event = parsed.event;
+    ctx.accumulatedThinking = handleThinkingDelta(event, ctx);
+    ctx.accumulatedAssistantResponse = handleTextDelta(event, ctx);
+    handleToolStart(event, ctx);
+    handleToolInputDelta(event, ctx);
+    handleToolComplete(event, ctx);
+  }
+  handleToolResult(parsed, ctx);
+}
+
+// ========== Error Handling ==========
+
+const SPAWN_ERROR_MAP: Record<string, { code: string; message: string }> = {
+  ENOENT: {
+    code: 'CLAUDE_NOT_INSTALLED',
+    message: 'Claude Code is not installed or not in PATH. Please install Claude Code: npm install -g @anthropic-ai/claude-code'
+  },
+  EACCES: {
+    code: 'PERMISSION_DENIED',
+    message: 'Permission denied when running Claude Code. Please check file permissions.'
+  }
+};
+
+function handleSpawnError(
+  error: NodeJS.ErrnoException,
+  config: ResolvedHeadlessConfig,
+  reject: (reason: Error) => void
+): void {
+  const mapped = error.code ? SPAWN_ERROR_MAP[error.code] : undefined;
+  if (!mapped) {
+    reject(error);
+    return;
+  }
+
+  const formatted = `[[MSTRO_ERROR:${mapped.code}]] ${mapped.message}`;
+  if (config.outputCallback) {
+    config.outputCallback(`\n${formatted}\n`);
+  }
+  reject(new Error(formatted));
+}
+
+// ========== Argument Building ==========
+
+function buildClaudeArgs(
+  config: ResolvedHeadlessConfig,
+  prompt: string,
+  hasImageAttachments: boolean,
+  useStreamJson: boolean,
+  mcpConfigPath: string | null
+): string[] {
+  const args = ['--print'];
+
+  if (useStreamJson) {
+    args.push('--output-format', 'stream-json', '--include-partial-messages', '--verbose');
+  }
+
+  if (hasImageAttachments) {
+    args.push('--input-format', 'stream-json');
+  }
+
+  if (config.claudeSessionId) {
+    args.push('--resume', config.claudeSessionId);
+  } else if (config.continueSession) {
+    args.push('--continue');
+  }
+
+  if (mcpConfigPath) {
+    args.push('--mcp-config', mcpConfigPath);
+    args.push('--permission-prompt-tool', 'mcp__mstro-bouncer__approval_prompt');
+  }
+
+  if (!hasImageAttachments) {
+    args.push(prompt);
+  }
+
+  return args;
+}
+
+/**
+ * Execute a Claude CLI command for a single movement
+ * Supports multimodal prompts via --input-format stream-json when image attachments are present
+ */
+export async function executeClaudeCommand(
+  prompt: string,
+  _movementId: string,
+  _sessionNumber: number,
+  options: ClaudeInvokerOptions
+): Promise<ExecutionResult> {
+  const { config, runningProcesses } = options;
+  const perfStart = Date.now();
+  if (config.verbose) {
+    console.log(`[PERF] executeMovement started`);
+  }
+
+  const hasImageAttachments = config.imageAttachments && config.imageAttachments.length > 0;
+  const useStreamJson = hasImageAttachments || config.thinkingCallback || config.outputCallback || config.toolUseCallback;
+  const mcpConfigPath = generateMcpConfig(config.workingDir, config.verbose);
+  const args = buildClaudeArgs(config, prompt, !!hasImageAttachments, !!useStreamJson, mcpConfigPath);
+
+  if (config.verbose) {
+    console.log(`[PERF] About to spawn: ${Date.now() - perfStart}ms`);
+    console.log(`[PERF] Command: ${config.claudeCommand} ${args.join(' ')}`);
+  }
+
+  const claudeProcess = spawn(config.claudeCommand, args, {
+    cwd: config.workingDir,
+    env: { ...process.env },
+    stdio: [hasImageAttachments ? 'pipe' : 'ignore', 'pipe', 'pipe']
+  });
+
+  if (hasImageAttachments && claudeProcess.stdin) {
+    const multimodalMessage = buildMultimodalMessage(prompt, config.imageAttachments!);
+    claudeProcess.stdin.write(multimodalMessage);
+    claudeProcess.stdin.end();
+  }
+
+  if (claudeProcess.pid) {
+    runningProcesses.set(claudeProcess.pid, claudeProcess);
+  }
+
+  if (config.verbose) {
+    console.log(`[PERF] Spawned: ${Date.now() - perfStart}ms`);
+  }
+
+  let stdout = '';
+  let stderr = '';
+  let thinkingBuffer = '';
+  let firstStdoutReceived = false;
+  let errorAlreadySurfaced = false;
+
+  const sessionCapture: { claudeSessionId?: string } = {};
+  const ctx: StreamHandlerContext = {
+    config,
+    accumulatedAssistantResponse: '',
+    accumulatedThinking: '',
+    accumulatedToolUse: [],
+    toolInputBuffers: new Map(),
+  };
+
+  claudeProcess.stdout!.on('data', (data) => {
+    if (!firstStdoutReceived) {
+      firstStdoutReceived = true;
+      if (config.verbose) {
+        console.log(`[PERF] First stdout data: ${Date.now() - perfStart}ms`);
+      }
+    }
+
+    const chunk = data.toString();
+    stdout += chunk;
+
+    if (useStreamJson) {
+      thinkingBuffer = processStreamLines(thinkingBuffer + chunk, sessionCapture, ctx);
+    }
+  });
+
+  claudeProcess.stderr!.on('data', async (data) => {
+    const chunk = data.toString();
+    stderr += chunk;
+
+    if (errorAlreadySurfaced) return;
+
+    const error = detectErrorInStderr(stderr);
+    if (error) {
+      errorAlreadySurfaced = true;
+      if (config.outputCallback) {
+        config.outputCallback(`\n[[MSTRO_ERROR:${error.errorCode}]] ${error.message}\n`);
+      }
+    }
+  });
+
+  return new Promise((resolve, reject) => {
+    claudeProcess.on('close', (code) => {
+      if (claudeProcess.pid) {
+        runningProcesses.delete(claudeProcess.pid);
+      }
+      resolve({
+        output: stdout,
+        error: stderr || undefined,
+        exitCode: code || 0,
+        assistantResponse: ctx.accumulatedAssistantResponse || undefined,
+        thinkingOutput: ctx.accumulatedThinking || undefined,
+        toolUseHistory: ctx.accumulatedToolUse.length > 0 ? ctx.accumulatedToolUse : undefined,
+        claudeSessionId: sessionCapture.claudeSessionId
+      });
+    });
+
+    claudeProcess.on('error', (error: NodeJS.ErrnoException) => {
+      if (claudeProcess.pid) {
+        runningProcesses.delete(claudeProcess.pid);
+      }
+      handleSpawnError(error, config, reject);
+    });
+  });
+}

package/server/cli/headless/index.ts

@@ -0,0 +1,39 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * Headless Runner Module
+ *
+ * Re-exports all headless runner components for backward compatibility.
+ */
+
+export type { ClaudeInvokerOptions } from './claude-invoker.js';
+export { executeClaudeCommand } from './claude-invoker.js';
+
+// Utilities (for advanced usage)
+export { generateMcpConfig } from './mcp-config.js';
+export {
+  detectErrorInStderr,
+  ERROR_PATTERNS, 
+  estimateTokensFromOutput,
+  extractCleanOutput,
+  extractModifiedFiles
+} from './output-utils.js';
+export {
+  buildMultimodalMessage, 
+  enrichPromptWithContext,
+  isApprovalPrompt
+} from './prompt-utils.js';
+// Main runner class
+export { HeadlessRunner } from './runner.js';
+// Types
+export type {
+  ExecutionResult,
+  HeadlessConfig,
+  ImageAttachment,
+  ResolvedHeadlessConfig, 
+  SessionResult,
+  SessionState,
+  ToolUseAccumulator,
+  ToolUseEvent
+} from './types.js';

package/server/cli/headless/mcp-config.ts

@@ -0,0 +1,87 @@
+/**
+ * MCP Configuration Generator
+ *
+ * Generates MCP config with bouncer + user's MCP servers from ~/.claude.json.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { MCP_SERVER_PATH, MSTRO_ROOT } from '../../utils/paths.js';
+
+/**
+ * Load user's MCP servers from ~/.claude.json (global + project-level)
+ */
+function loadUserMcpServers(workingDir: string, verbose: boolean): Record<string, any> {
+  const servers: Record<string, any> = {};
+  const claudeConfigPath = join(homedir(), '.claude.json');
+
+  if (!existsSync(claudeConfigPath)) {
+    return servers;
+  }
+
+  try {
+    const claudeConfig = JSON.parse(readFileSync(claudeConfigPath, 'utf-8'));
+
+    if (claudeConfig.mcpServers && typeof claudeConfig.mcpServers === 'object') {
+      Object.assign(servers, claudeConfig.mcpServers);
+    }
+
+    if (claudeConfig.projects && typeof claudeConfig.projects === 'object') {
+      for (const [projectPath, projectConfig] of Object.entries(claudeConfig.projects)) {
+        const projectServers = (projectConfig as any)?.mcpServers;
+        if (workingDir.startsWith(projectPath) && typeof projectServers === 'object') {
+          Object.assign(servers, projectServers);
+        }
+      }
+    }
+
+    if (verbose) {
+      console.log(`[${new Date().toISOString()}] Loaded ${Object.keys(servers).length} user MCP servers from ~/.claude.json`);
+    }
+  } catch (parseError: any) {
+    console.error(`[${new Date().toISOString()}] Failed to parse ~/.claude.json: ${parseError.message}`);
+  }
+
+  return servers;
+}
+
+/**
+ * Generate MCP config with bouncer + user's MCP servers from ~/.claude.json.
+ * Writes to ~/.mstro/mcp-config.json for use with --mcp-config flag.
+ */
+export function generateMcpConfig(workingDir: string, verbose: boolean = false): string | null {
+  try {
+    if (!existsSync(MCP_SERVER_PATH)) {
+      console.error(`[${new Date().toISOString()}] MCP server not found at ${MCP_SERVER_PATH}`);
+      return null;
+    }
+
+    const mcpServers: Record<string, any> = {
+      'mstro-bouncer': {
+        command: 'npx',
+        args: ['tsx', MCP_SERVER_PATH],
+        description: 'Mstro security bouncer for approving/denying Claude Code tool use',
+        env: { BOUNCER_USE_AI: 'true', MSTRO_ROOT: MSTRO_ROOT }
+      },
+      ...loadUserMcpServers(workingDir, verbose)
+    };
+
+    const configDir = join(homedir(), '.mstro');
+    if (!existsSync(configDir)) {
+      mkdirSync(configDir, { recursive: true });
+    }
+
+    const configPath = join(configDir, 'mcp-config.json');
+    writeFileSync(configPath, JSON.stringify({ mcpServers }, null, 2));
+
+    if (verbose) {
+      console.log(`[${new Date().toISOString()}] Generated MCP config at ${configPath} (${Object.keys(mcpServers).length} servers)`);
+    }
+
+    return configPath;
+  } catch (error: any) {
+    console.error(`[${new Date().toISOString()}] Failed to generate MCP config: ${error.message}`);
+    return null;
+  }
+}

package/server/cli/headless/output-utils.ts

@@ -0,0 +1,109 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * Output Utilities
+ *
+ * Utilities for processing and parsing Claude CLI output.
+ */
+
+/**
+ * Extract clean output from Claude response
+ */
+export function extractCleanOutput(rawOutput: string): string {
+  // When using stream-json format, filter out all JSON lines
+  // since we already streamed the actual content via callbacks
+  const lines = rawOutput.split('\n');
+  const cleanLines = lines.filter(line => {
+    const trimmed = line.trim();
+    // Filter out JSON lines (system, stream_event, assistant, user, result)
+    if (trimmed.startsWith('{') && trimmed.includes('"type"')) {
+      return false;
+    }
+    return trimmed.length > 0;
+  });
+
+  return cleanLines.join('\n')
+    .replace(/\x1b\[[0-9;]*m/g, '') // ANSI color codes
+    .replace(/\r\n/g, '\n') // Normalize line endings
+    .trim();
+}
+
+/**
+ * Estimate tokens from output
+ */
+export function estimateTokensFromOutput(output: string): number {
+  return Math.floor(output.length / 4);
+}
+
+/**
+ * Extract modified files from output (simplified)
+ */
+export function extractModifiedFiles(output: string): string[] {
+  // This is a simplified version. In production, would parse actual file operations
+  const filePattern = /(?:wrote|modified|created|edited)\s+(?:file\s+)?['"]?([^\s'"]+\.[a-z0-9]+)['"]?/gi;
+  const matches = output.matchAll(filePattern);
+  const files = new Set<string>();
+
+  for (const match of matches) {
+    files.add(match[1]);
+  }
+
+  return Array.from(files);
+}
+
+/**
+ * Error patterns for detecting Claude Code errors in stderr
+ */
+export const ERROR_PATTERNS = [
+  // Authentication errors - most common user-facing issue
+  { pattern: /not logged in|login required|must be authenticated|session.*expired|token.*invalid|token.*expired/i,
+    message: 'Claude Code authentication required. Please run "claude login" in your terminal to authenticate.',
+    errorCode: 'AUTH_REQUIRED' },
+  { pattern: /account.*not.*found|user.*not.*found/i,
+    message: 'Claude account not found. Please verify your account at claude.ai.',
+    errorCode: 'ACCOUNT_NOT_FOUND' },
+  // API/subscription errors
+  { pattern: /api key|invalid key|unauthorized|forbidden.*api/i,
+    message: 'API key error. Please check your Claude Code configuration.',
+    errorCode: 'API_KEY_INVALID' },
+  { pattern: /quota exceeded|usage.*limit|billing.*issue|payment.*required|subscription.*expired/i,
+    message: 'Usage quota or subscription issue. Please check your account billing at claude.ai.',
+    errorCode: 'QUOTA_EXCEEDED' },
+  { pattern: /rate limit|too many requests|429|throttl/i,
+    message: 'Rate limit exceeded. Please wait a moment before trying again.',
+    errorCode: 'RATE_LIMITED' },
+  // Network errors
+  { pattern: /no internet|network error|connection refused|ENOTFOUND|ECONNREFUSED|ETIMEDOUT|socket hang up/i,
+    message: 'Network error. Please check your internet connection.',
+    errorCode: 'NETWORK_ERROR' },
+  { pattern: /SSL|certificate|TLS|CERT_/i,
+    message: 'SSL/TLS certificate error. Please check your network configuration.',
+    errorCode: 'SSL_ERROR' },
+  // Model/service errors
+  { pattern: /model not found|model unavailable|service unavailable|503|502|504/i,
+    message: 'Claude service temporarily unavailable. Please try again in a few moments.',
+    errorCode: 'SERVICE_UNAVAILABLE' },
+  { pattern: /internal server error|500/i,
+    message: 'Claude service encountered an internal error. Please try again.',
+    errorCode: 'INTERNAL_ERROR' },
+  // Context/session errors
+  { pattern: /context.*too.*long|context.*limit|token.*limit.*exceeded/i,
+    message: 'Context too long. Please start a new session or reduce prompt size.',
+    errorCode: 'CONTEXT_TOO_LONG' },
+  { pattern: /session.*not.*found|invalid.*session/i,
+    message: 'Session not found. Starting a new session may help.',
+    errorCode: 'SESSION_NOT_FOUND' },
+];
+
+/**
+ * Check stderr for known error patterns and return the first match
+ */
+export function detectErrorInStderr(stderrBuffer: string): { message: string; errorCode: string } | null {
+  for (const { pattern, message, errorCode } of ERROR_PATTERNS) {
+    if (pattern.test(stderrBuffer)) {
+      return { message, errorCode };
+    }
+  }
+  return null;
+}