mstro-app 0.5.0 → 0.5.5

package/server/engines/claude/ClaudeCodeEngine.ts

@@ -0,0 +1,404 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * ClaudeCodeEngine
+ *
+ * Thin adapter that wraps the existing Claude Code subprocess path
+ * (claude-invoker) behind the CodingAgentEngine interface. All stdout
+ * parsing, watchdog, stall detection, and process spawning stays in the
+ * headless runner modules — this file only translates HeadlessRunner
+ * callbacks into EngineEvents and owns its own process-group map for
+ * cancellation.
+ */
+
+import type { ChildProcess } from 'node:child_process';
+import { executeClaudeCommand } from '../../cli/headless/claude-invoker.js';
+import { killProcessGroup } from '../../cli/headless/runner.js';
+import type {
+  ExecutionResult,
+  ImageAttachment,
+  ResolvedHeadlessConfig,
+  ToolUseEvent,
+} from '../../cli/headless/types.js';
+import type {
+  EngineEvent,
+  EngineId,
+} from '../EngineEvent.js';
+import type {
+  CodingAgentEngine,
+  EngineUsage,
+  PromptAttachment,
+  StartSessionOptions,
+} from '../types.js';
+
+type Resolver = (r: IteratorResult<EngineEvent>) => void;
+
+/**
+ * Implementation of CodingAgentEngine backed by the Claude Code headless
+ * runner. The engine holds a single logical conversation — subsequent
+ * prompts automatically continue the Claude session via --resume.
+ */
+export class ClaudeCodeEngine implements CodingAgentEngine {
+  readonly engineId: EngineId = 'claude-code';
+
+  private sessionOptions: StartSessionOptions | null = null;
+  private claudeSessionId: string | undefined;
+  /**
+   * Live child processes spawned by the current prompt. Keyed by pid; values
+   * are the raw ChildProcess handles. executeClaudeCommand registers the
+   * spawned process here and removes it on 'close'. cancel() iterates this
+   * map and SIGTERMs each process group — matching the pre-engine behavior
+   * from HeadlessRunner.cleanup().
+   */
+  private readonly runningProcesses: Map<number, ChildProcess> = new Map();
+  private currentRunPromise: Promise<ExecutionResult> | null = null;
+
+  private disposed = false;
+  private iteratorDone = false;
+  private readonly queue: EngineEvent[] = [];
+  private readonly pending: Resolver[] = [];
+
+  private usage: EngineUsage = {
+    inputTokens: 0,
+    outputTokens: 0,
+    lastUpdatedAt: Date.now(),
+  };
+
+  async startSession(options: StartSessionOptions): Promise<void> {
+    if (this.sessionOptions) {
+      throw new Error('ClaudeCodeEngine: startSession called more than once');
+    }
+    if (this.disposed) {
+      throw new Error('ClaudeCodeEngine: cannot start a disposed engine');
+    }
+    this.sessionOptions = options;
+    this.claudeSessionId = options.resumeSessionId;
+    this.usage = {
+      inputTokens: 0,
+      outputTokens: 0,
+      lastUpdatedAt: Date.now(),
+    };
+  }
+
+  async sendPrompt(prompt: string, attachments?: PromptAttachment[]): Promise<void> {
+    if (!this.sessionOptions) {
+      throw new Error('ClaudeCodeEngine: sendPrompt called before startSession');
+    }
+    if (this.disposed) {
+      throw new Error('ClaudeCodeEngine: sendPrompt called after dispose');
+    }
+    if (this.currentRunPromise) {
+      throw new Error('ClaudeCodeEngine: another prompt is already in flight');
+    }
+
+    const opts = this.sessionOptions;
+    const imageAttachments = convertImageAttachments(attachments);
+
+    const toolStartTimes = new Map<string, number>();
+    const toolNames = new Map<string, string>();
+    const toolInputs = new Map<string, Record<string, unknown>>();
+
+    const config: ResolvedHeadlessConfig = {
+      workingDir: opts.workingDir,
+      tokenBudgetThreshold: 170_000,
+      maxSessions: 50,
+      maxRetries: 3,
+      claudeCommand: process.env.CLAUDE_COMMAND || 'claude',
+      verbose: false,
+      noColor: false,
+      improvisationMode: false,
+      movementNumber: 0,
+      directPrompt: prompt,
+      promptContext: { accumulatedKnowledge: '', filesModified: [] },
+      stallWarningMs: 300_000,
+      stallKillMs: 1_800_000,
+      stallAssessEnabled: true,
+      stallMaxExtensions: 3,
+      stallHardCapMs: 3_600_000,
+      enableToolWatchdog: true,
+      maxAutoRetries: 2,
+      model: opts.model,
+      effortLevel: opts.effortLevel,
+      continueSession: !!this.claudeSessionId,
+      claudeSessionId: this.claudeSessionId,
+      imageAttachments,
+      disallowedTools: opts.disallowedTools,
+      deployMode: opts.deployMode,
+      extraEnv: opts.extraEnv,
+      outputCallback: (text: string) => {
+        this.emit({
+          kind: 'message.delta',
+          sessionId: this.sessionIdForEvent(),
+          timestamp: Date.now(),
+          text,
+        });
+      },
+      thinkingCallback: (text: string) => {
+        this.emit({
+          kind: 'message.thinking',
+          sessionId: this.sessionIdForEvent(),
+          timestamp: Date.now(),
+          text,
+        });
+      },
+      toolUseCallback: (event: ToolUseEvent) => {
+        this.handleToolUseEvent(event, toolStartTimes, toolNames, toolInputs);
+      },
+      tokenUsageCallback: (usage: { inputTokens: number; outputTokens: number }) => {
+        this.usage = {
+          inputTokens: usage.inputTokens,
+          outputTokens: usage.outputTokens,
+          lastUpdatedAt: Date.now(),
+        };
+        this.emit({
+          kind: 'usage.update',
+          sessionId: this.sessionIdForEvent(),
+          timestamp: Date.now(),
+          inputTokens: usage.inputTokens,
+          outputTokens: usage.outputTokens,
+        });
+      },
+    };
+
+    const runPromise = executeClaudeCommand(prompt, 'engine', 1, {
+      config,
+      runningProcesses: this.runningProcesses,
+    });
+    this.currentRunPromise = runPromise;
+
+    runPromise.then(
+      (result) => this.onRunCompleted(result),
+      (err) => this.onRunFailed(err),
+    );
+  }
+
+  async cancel(): Promise<void> {
+    if (this.runningProcesses.size === 0 && !this.currentRunPromise) return;
+    this.killAllRunningProcesses();
+    if (this.currentRunPromise) {
+      await this.currentRunPromise.catch(() => { /* surfaced as engine.error */ });
+    }
+  }
+
+  getUsage(): EngineUsage {
+    return { ...this.usage };
+  }
+
+  async dispose(): Promise<void> {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.killAllRunningProcesses();
+    if (this.currentRunPromise) {
+      await this.currentRunPromise.catch(() => { /* surfaced as engine.error */ });
+    }
+    this.closeIterator();
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<EngineEvent> {
+    return {
+      next: (): Promise<IteratorResult<EngineEvent>> => {
+        if (this.queue.length > 0) {
+          return Promise.resolve({ value: this.queue.shift() as EngineEvent, done: false });
+        }
+        if (this.iteratorDone) {
+          return Promise.resolve({ value: undefined, done: true });
+        }
+        return new Promise<IteratorResult<EngineEvent>>((resolve) => {
+          this.pending.push(resolve);
+        });
+      },
+      return: (): Promise<IteratorResult<EngineEvent>> => {
+        this.closeIterator();
+        return Promise.resolve({ value: undefined, done: true });
+      },
+    };
+  }
+
+  // ---------- private ----------
+
+  private sessionIdForEvent(): string {
+    return this.claudeSessionId ?? 'pending';
+  }
+
+  /**
+   * SIGTERM every tracked child process group; schedule a SIGKILL fallback
+   * for any that haven't exited in 5s. Mirrors HeadlessRunner.cleanup().
+   */
+  private killAllRunningProcesses(): void {
+    if (this.runningProcesses.size === 0) return;
+    const pids = new Set<number>();
+    for (const pid of this.runningProcesses.keys()) {
+      pids.add(pid);
+      killProcessGroup(pid, 'SIGTERM');
+    }
+    setTimeout(() => {
+      for (const [pid, proc] of this.runningProcesses) {
+        if (pids.has(pid) && !proc.killed) {
+          killProcessGroup(pid, 'SIGKILL');
+        }
+      }
+    }, 5000).unref?.();
+  }
+
+  private emit(event: EngineEvent): void {
+    if (this.iteratorDone) return;
+    const resolver = this.pending.shift();
+    if (resolver) {
+      resolver({ value: event, done: false });
+    } else {
+      this.queue.push(event);
+    }
+    if (event.kind === 'engine.error' && event.fatal) {
+      this.closeIterator();
+    }
+  }
+
+  private closeIterator(): void {
+    if (this.iteratorDone) return;
+    this.iteratorDone = true;
+    const waiting = this.pending.splice(0);
+    for (const resolve of waiting) {
+      resolve({ value: undefined, done: true });
+    }
+  }
+
+  private onRunCompleted(result: ExecutionResult): void {
+    this.currentRunPromise = null;
+    if (result.claudeSessionId) {
+      this.claudeSessionId = result.claudeSessionId;
+    }
+    // Fall back to the definitive end-of-run usage — the streaming callback
+    // may have missed the final numbers if the result event arrived after
+    // the last message_delta.
+    if (result.apiTokenUsage) {
+      const u = result.apiTokenUsage;
+      if (u.inputTokens > this.usage.inputTokens || u.outputTokens > this.usage.outputTokens) {
+        this.usage = {
+          inputTokens: Math.max(u.inputTokens, this.usage.inputTokens),
+          outputTokens: Math.max(u.outputTokens, this.usage.outputTokens),
+          lastUpdatedAt: Date.now(),
+        };
+      }
+    }
+    this.emit({
+      kind: 'session.idle',
+      sessionId: this.sessionIdForEvent(),
+      timestamp: Date.now(),
+      stopReason: result.stopReason,
+    });
+    if (result.exitCode !== 0 && !result.assistantResponse && !result.toolUseHistory?.length) {
+      const message = result.error || `Claude exited with code ${result.exitCode}`;
+      this.emit({
+        kind: 'engine.error',
+        sessionId: this.sessionIdForEvent(),
+        timestamp: Date.now(),
+        code: 'CLAUDE_RUN_ERROR',
+        message,
+        fatal: false,
+      });
+    }
+  }
+
+  private onRunFailed(err: unknown): void {
+    this.currentRunPromise = null;
+    const message = err instanceof Error ? err.message : String(err);
+    this.emit({
+      kind: 'engine.error',
+      sessionId: this.sessionIdForEvent(),
+      timestamp: Date.now(),
+      code: 'CLAUDE_SPAWN_ERROR',
+      message,
+      fatal: true,
+    });
+  }
+
+  private handleToolUseEvent(
+    event: ToolUseEvent,
+    starts: Map<string, number>,
+    names: Map<string, string>,
+    inputs: Map<string, Record<string, unknown>>,
+  ): void {
+    if (!event.toolId) return;
+    if (event.type === 'tool_start') {
+      this.onToolStart(event, starts, names);
+    } else if (event.type === 'tool_complete') {
+      this.onToolComplete(event, names, inputs);
+    } else if (event.type === 'tool_result') {
+      this.onToolResult(event, starts, names, inputs);
+    }
+  }
+
+  private onToolStart(
+    event: ToolUseEvent,
+    starts: Map<string, number>,
+    names: Map<string, string>,
+  ): void {
+    const ts = Date.now();
+    const toolId = event.toolId as string;
+    starts.set(toolId, ts);
+    if (event.toolName) names.set(toolId, event.toolName);
+    this.emit({
+      kind: 'tool.start',
+      sessionId: this.sessionIdForEvent(),
+      timestamp: ts,
+      toolCallId: toolId,
+      toolName: event.toolName ?? '',
+      input: {},
+    });
+  }
+
+  private onToolComplete(
+    event: ToolUseEvent,
+    names: Map<string, string>,
+    inputs: Map<string, Record<string, unknown>>,
+  ): void {
+    const toolId = event.toolId as string;
+    if (event.completeInput) inputs.set(toolId, event.completeInput);
+    if (event.toolName) names.set(toolId, event.toolName);
+    // tool.end is emitted on tool_result so the result payload is included.
+  }
+
+  private onToolResult(
+    event: ToolUseEvent,
+    starts: Map<string, number>,
+    names: Map<string, string>,
+    inputs: Map<string, Record<string, unknown>>,
+  ): void {
+    const ts = Date.now();
+    const toolId = event.toolId as string;
+    const start = starts.get(toolId) ?? ts;
+    this.emit({
+      kind: 'tool.end',
+      sessionId: this.sessionIdForEvent(),
+      timestamp: ts,
+      toolCallId: toolId,
+      toolName: names.get(toolId) ?? '',
+      input: inputs.get(toolId) ?? {},
+      result: event.result ?? '',
+      isError: event.isError ?? false,
+      durationMs: ts - start,
+    });
+    starts.delete(toolId);
+    names.delete(toolId);
+    inputs.delete(toolId);
+  }
+}
+
+function convertImageAttachments(
+  attachments?: PromptAttachment[],
+): ImageAttachment[] | undefined {
+  if (!attachments || attachments.length === 0) return undefined;
+  const images: ImageAttachment[] = [];
+  for (const a of attachments) {
+    if (!a.isImage || !a.base64Content) continue;
+    images.push({
+      fileName: a.fileName,
+      filePath: a.filePath ?? a.fileName,
+      content: a.base64Content,
+      isImage: true,
+      mimeType: a.mimeType,
+    });
+  }
+  return images.length > 0 ? images : undefined;
+}

package/server/engines/factory.ts

@@ -0,0 +1,176 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * Engine factory — returns a concrete CodingAgentEngine for the requested
+ * EngineId. Callers pass the value of `settings.engine` and the factory
+ * dispatches to the matching implementation:
+ *
+ *   - 'claude-code' → ClaudeCodeEngine (headless runner, stdout JSON)
+ *   - 'opencode'    → OpenCodeEngine   (OpenCode SDK + SSE)
+ *
+ * The OpenCode path is backed by a single process-lifetime
+ * OpenCodeServerManager that owns the `opencode serve` subprocess. The
+ * factory itself stays synchronous; manager startup is awaited inside
+ * `startSession` via `LazyOpenCodeEngine` (below) so callers observe the
+ * same lifecycle as ClaudeCodeEngine.
+ */
+
+import { isEngineSwapEnabled } from '../services/settings.js';
+import { ClaudeCodeEngine } from './claude/ClaudeCodeEngine.js';
+import { OpenCodeEngine } from './opencode/OpenCodeEngine.js';
+import { OpenCodeServerManager } from './opencode/OpenCodeServerManager.js';
+import type {
+  CodingAgentEngine,
+  EngineEvent,
+  EngineId,
+  EngineUsage,
+  PromptAttachment,
+  StartSessionOptions,
+} from './types.js';
+
+/**
+ * Process-lifetime singleton for the `opencode serve` subprocess. Created
+ * lazily on the first request for an opencode engine so Claude-only
+ * deployments never spawn the binary. `registerProcessHandlers` is set so
+ * the subprocess exits with the CLI — no orphan processes on SIGINT.
+ */
+let sharedOpenCodeManager: OpenCodeServerManager | null = null;
+
+function getSharedOpenCodeServerManager(): OpenCodeServerManager {
+  if (!sharedOpenCodeManager) {
+    sharedOpenCodeManager = new OpenCodeServerManager({
+      registerProcessHandlers: true,
+    });
+  }
+  return sharedOpenCodeManager;
+}
+
+/**
+ * Reset the cached OpenCode manager. Primarily for tests — never called
+ * by production code. Does not shut down the previous manager; callers
+ * that need a clean state should `shutdown()` first.
+ */
+export function __resetSharedOpenCodeServerManagerForTests(): void {
+  sharedOpenCodeManager = null;
+}
+
+/**
+ * Thin adapter that defers `OpenCodeEngine` construction until
+ * `startSession` runs. The real engine requires an already-bound
+ * `OpencodeClient`, but the underlying HTTP server is spawned
+ * asynchronously by `OpenCodeServerManager`. `startSession` is the first
+ * async call on the engine lifecycle, so we await `manager.start()`
+ * there, then construct the inner engine once the client is available
+ * and forward every subsequent call to it.
+ *
+ * The wrapper preserves the public `CodingAgentEngine` contract:
+ *   - `engineId` is stable at `'opencode'` from construction.
+ *   - Methods called before `startSession` resolve reject with the same
+ *     error wording the inner engine would have produced.
+ *   - `dispose()` is idempotent and tolerates the uninitialized case.
+ */
+class LazyOpenCodeEngine implements CodingAgentEngine {
+  readonly engineId: EngineId = 'opencode';
+
+  private inner: OpenCodeEngine | null = null;
+  private started = false;
+  private disposed = false;
+
+  constructor(private readonly manager: OpenCodeServerManager) {}
+
+  async startSession(options: StartSessionOptions): Promise<void> {
+    if (this.disposed) {
+      throw new Error('OpenCodeEngine: cannot start a disposed engine');
+    }
+    if (this.started) {
+      throw new Error('OpenCodeEngine: startSession called more than once');
+    }
+    await this.manager.start();
+    const client = this.manager.getClient();
+    this.inner = new OpenCodeEngine({
+      client,
+      directory: options.workingDir,
+    });
+    await this.inner.startSession(options);
+    this.started = true;
+  }
+
+  sendPrompt(
+    prompt: string,
+    attachments?: PromptAttachment[],
+  ): Promise<void> {
+    if (this.disposed) {
+      return Promise.reject(
+        new Error('OpenCodeEngine: sendPrompt called after dispose'),
+      );
+    }
+    if (!this.inner) {
+      return Promise.reject(
+        new Error('OpenCodeEngine: sendPrompt called before startSession'),
+      );
+    }
+    return this.inner.sendPrompt(prompt, attachments);
+  }
+
+  cancel(): Promise<void> {
+    if (!this.inner) return Promise.resolve();
+    return this.inner.cancel();
+  }
+
+  getUsage(): EngineUsage {
+    if (!this.inner) {
+      return { inputTokens: 0, outputTokens: 0, lastUpdatedAt: Date.now() };
+    }
+    return this.inner.getUsage();
+  }
+
+  async dispose(): Promise<void> {
+    if (this.disposed) return;
+    this.disposed = true;
+    if (this.inner) {
+      await this.inner.dispose();
+    }
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<EngineEvent> {
+    // The contract only allows iteration after `startSession` has resolved,
+    // so `this.inner` is guaranteed to be set when consumers begin the
+    // for-await loop. We delegate directly to the inner engine's iterator
+    // to preserve its ordering and terminal-event semantics.
+    if (!this.inner) {
+      return {
+        next: () => Promise.resolve({ value: undefined, done: true }),
+      };
+    }
+    return this.inner[Symbol.asyncIterator]();
+  }
+}
+
+/**
+ * Construct a new engine instance for the given engine id. The returned
+ * engine is uninitialized — the caller must call `startSession` before
+ * any other method.
+ *
+ * Feature-flag gate: when `engineSwap` is disabled, this returns
+ * `ClaudeCodeEngine` for every id. That guarantees the pre-OpenCode
+ * behavior — in particular, `LazyOpenCodeEngine` is never constructed, so
+ * the shared `OpenCodeServerManager` is never touched and no `opencode
+ * serve` subprocess is spawned. The flag is checked on every call (rather
+ * than cached) so runtime toggles take effect on the next session start.
+ */
+export function createEngine(engineId: EngineId): CodingAgentEngine {
+  if (!isEngineSwapEnabled()) {
+    return new ClaudeCodeEngine();
+  }
+  switch (engineId) {
+    case 'claude-code':
+      return new ClaudeCodeEngine();
+    case 'opencode':
+      return new LazyOpenCodeEngine(getSharedOpenCodeServerManager());
+    default: {
+      const exhaustive: never = engineId;
+      throw new Error(`Unknown engine id: ${String(exhaustive)}`);
+    }
+  }
+}