mstro-app 0.5.1 → 0.5.5

package/server/cli/headless/stall-assessor.ts

@@ -10,6 +10,7 @@
  * best result, error classification) live in haiku-assessments.ts.
  */
 
+import type { EngineEvent } from '../../engines/EngineEvent.js';
 import { loadSkillPrompt } from '../../services/plan/agent-loader.js';
 import { spawnHaikuRaw } from './haiku-assessments.js';
 import { hlog } from './headless-logger.js';
@@ -36,6 +37,98 @@ export interface StallVerdict {
   reason: string;
 }
 
+/**
+ * Mutable tool-activity accumulator fed by an engine-agnostic `EngineEvent`
+ * stream. Consumed by {@link buildStallContext} to produce the tool-related
+ * fields of a {@link StallContext} without coupling to any specific engine's
+ * internal shapes.
+ */
+export interface ToolActivityState {
+  /** Tool calls observed by `tool.start` but not yet ended. */
+  pendingToolIds: Set<string>;
+  /** Names of tools still pending (used by the stall heuristic). */
+  pendingToolNames: Set<string>;
+  /** Map of toolId -> toolName so `tool.end` can drop names when the last id goes. */
+  pendingToolNameById: Map<string, string>;
+  /** Last tool name seen via `tool.start`. */
+  lastToolName?: string;
+  /** Short summary of the last tool input (url/query/command/prompt). */
+  lastToolInputSummary?: string;
+  /** Total number of `tool.start` events observed this session. */
+  totalToolCalls: number;
+}
+
+/** Allocate a fresh, empty tool-activity state. */
+export function createToolActivityState(): ToolActivityState {
+  return {
+    pendingToolIds: new Set(),
+    pendingToolNames: new Set(),
+    pendingToolNameById: new Map(),
+    totalToolCalls: 0,
+  };
+}
+
+/**
+ * Update a {@link ToolActivityState} from a single engine event. Non-tool
+ * events are ignored. This lets the stall assessor operate on any
+ * CodingAgentEngine's event stream without knowing the engine's internals.
+ */
+export function applyEngineEventToActivity(state: ToolActivityState, event: EngineEvent): void {
+  if (event.kind === 'tool.start') {
+    state.pendingToolIds.add(event.toolCallId);
+    state.pendingToolNames.add(event.toolName);
+    state.pendingToolNameById.set(event.toolCallId, event.toolName);
+    state.lastToolName = event.toolName;
+    state.lastToolInputSummary = summarizeToolInput(event.input);
+    state.totalToolCalls++;
+    return;
+  }
+  if (event.kind === 'tool.end') {
+    state.pendingToolIds.delete(event.toolCallId);
+    state.pendingToolNameById.delete(event.toolCallId);
+    // Only drop the name from pendingToolNames if no other pending call uses it.
+    const stillPending = Array.from(state.pendingToolNameById.values()).includes(event.toolName);
+    if (!stillPending) state.pendingToolNames.delete(event.toolName);
+  }
+}
+
+/**
+ * Build a {@link StallContext} from an engine-agnostic activity state plus
+ * the caller-owned timing fields. The stall heuristics and Haiku assessment
+ * in this module already operate on {@link StallContext}, so they are now
+ * fully drivable by any CodingAgentEngine's event stream.
+ */
+export function buildStallContext(
+  activity: ToolActivityState,
+  timing: {
+    originalPrompt: string;
+    silenceMs: number;
+    elapsedTotalMs: number;
+    tokenSilenceMs?: number;
+  },
+): StallContext {
+  return {
+    originalPrompt: timing.originalPrompt,
+    silenceMs: timing.silenceMs,
+    elapsedTotalMs: timing.elapsedTotalMs,
+    tokenSilenceMs: timing.tokenSilenceMs,
+    lastToolName: activity.lastToolName,
+    lastToolInputSummary: activity.lastToolInputSummary,
+    pendingToolCount: activity.pendingToolIds.size,
+    pendingToolNames: new Set(activity.pendingToolNames),
+    totalToolCalls: activity.totalToolCalls,
+  };
+}
+
+function summarizeToolInput(input: Record<string, unknown>): string | undefined {
+  if (input.url) return `URL: ${String(input.url).slice(0, 200)}`;
+  if (input.query) return `Query: ${String(input.query).slice(0, 200)}`;
+  if (input.command) return `Command: ${String(input.command).slice(0, 200)}`;
+  if (input.prompt) return `Prompt: ${String(input.prompt).slice(0, 200)}`;
+  const serialized = JSON.stringify(input);
+  return serialized ? serialized.slice(0, 200) : undefined;
+}
+
 // ========== Fast Heuristic ==========
 
 function hasSubagentPending(pendingNames: Set<string>, lastToolName: string | undefined, hasPendingTools: boolean): boolean {

package/server/cli/headless/tool-watchdog.ts

@@ -13,6 +13,7 @@
  * 3. Haiku tiebreaker: optional AI assessment before killing ambiguous cases
  */
 
+import type { EngineEvent } from '../../engines/EngineEvent.js';
 import { hlog } from './headless-logger.js';
 import type {
   ExecutionCheckpoint,
@@ -349,6 +350,26 @@ export class ToolWatchdog {
     }, extensionMs);
   }
 
+  /**
+   * Drive the watchdog from an engine-agnostic `EngineEvent` stream.
+   * Routes `tool.start` to `startWatch`, and `tool.end` to `clearWatch` +
+   * `recordCompletion` — so any CodingAgentEngine (Claude Code, OpenCode)
+   * can feed this watchdog without leaking engine-specific shapes.
+   * Non-tool events are ignored.
+   */
+  onEngineEvent(event: EngineEvent, onTimeout: (toolId: string) => void): void {
+    if (event.kind === 'tool.start') {
+      this.startWatch(event.toolCallId, event.toolName, event.input, () => onTimeout(event.toolCallId));
+      return;
+    }
+    if (event.kind === 'tool.end') {
+      this.clearWatch(event.toolCallId);
+      if (typeof event.durationMs === 'number' && event.durationMs >= 0) {
+        this.recordCompletion(event.toolName, event.durationMs);
+      }
+    }
+  }
+
   /** Stop watching a tool (it completed normally) */
   clearWatch(toolId: string): void {
     const watch = this.activeWatches.get(toolId);

package/server/cli/improvisation-history-store.ts

@@ -39,7 +39,9 @@ export function loadHistory(historyPath: string, sessionId: string): SessionHist
   if (existsSync(historyPath)) {
     try {
       const data = readFileSync(historyPath, 'utf-8');
-      return JSON.parse(data) as SessionHistory;
+      const parsed = JSON.parse(data) as SessionHistory;
+      if (!parsed.engine) parsed.engine = 'claude-code';
+      return parsed;
     } catch (error) {
       herror('Failed to load history:', error);
     }
@@ -51,6 +53,7 @@ export function loadHistory(historyPath: string, sessionId: string): SessionHist
     lastActivityAt: now,
     totalTokens: 0,
     movements: [],
+    engine: 'claude-code',
   };
 }
 

package/server/cli/improvisation-output-queue.ts

@@ -4,12 +4,29 @@
  * Small FIFO output buffer with a fixed-interval flush timer, used by the
  * improvisation session manager to coalesce rapid stdout writes into
  * steady `onOutput` emissions.
+ *
+ * ## Why coalesce inside `flush()`
+ *
+ * Claude's stdout arrives as many small chunks during streaming. Each chunk
+ * lands here via `queue_`. When `flush()` ran one `onEmit` per queued chunk,
+ * a streaming-heavy run produced thousands of `onOutput` events per minute,
+ * each becoming a tab-scoped broadcast that consumes a slot in the per-tab
+ * replay buffer (`tab-event-buffer.ts`). For 14-min runs with ~120 tool
+ * calls, that easily exceeded the buffer's 1000-event cap and triggered
+ * silent replay gaps on web reconnect.
+ *
+ * The flush window (50ms) is below the human-perceptible paint threshold and
+ * below WebSocket roundtrip latency, so concatenating all queued text into a
+ * single `onEmit` per tick is invisible to the user but cuts buffer pressure
+ * by 3-10× during streaming. No call site downstream depends on chunk
+ * boundaries — `onOutput` consumers (terminal renderer, history persistence)
+ * already treat the text as an opaque append.
  */
 
 const FLUSH_INTERVAL_MS = 50;
 
 export class OutputQueue {
-  private queue: Array<{ text: string; timestamp: number }> = [];
+  private queue: string[] = [];
   private timer: NodeJS.Timeout | null = null;
 
   constructor(private readonly onEmit: (text: string) => void) {}
@@ -20,15 +37,20 @@ export class OutputQueue {
   }
 
   queue_(text: string): void {
-    this.queue.push({ text, timestamp: Date.now() });
+    if (text.length === 0) return;
+    this.queue.push(text);
   }
 
-  /** Drain all buffered entries, emitting each via `onEmit` in order. */
+  /**
+   * Drain all buffered entries, emitting them as a single concatenated
+   * string via `onEmit`. Order is preserved (FIFO). No-op when the queue is
+   * empty so the periodic timer doesn't fire spurious empty-string emits.
+   */
   flush(): void {
-    while (this.queue.length > 0) {
-      const item = this.queue.shift();
-      if (item) this.onEmit(item.text);
-    }
+    if (this.queue.length === 0) return;
+    const merged = this.queue.join('');
+    this.queue.length = 0;
+    this.onEmit(merged);
   }
 
   /** Stop the flush timer. Does NOT drain; call `flush()` first if needed. */

package/server/cli/improvisation-session-manager.ts

@@ -16,7 +16,10 @@
 import { EventEmitter } from 'node:events';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { createEngine } from '../engines/factory.js';
+import type { EngineId } from '../engines/types.js';
 import { AnalyticsEvents, trackEvent } from '../services/analytics.js';
+import { type EtaProfile, getEtaProfileCached } from './eta-estimator.js';
 import { herror } from './headless/headless-logger.js';
 import { cleanupAttachments, preparePromptAndAttachments } from './improvisation-attachments.js';
 import {
@@ -55,6 +58,12 @@ export class ImprovisationSessionManager extends EventEmitter {
   private history: SessionHistory;
   private currentRunner: import('./headless/index.js').HeadlessRunner | null = null;
   private options: ImprovisationOptions;
+  /**
+   * Coding-agent backend identifier. Routed through `createEngine` from
+   * `engines/factory.ts` so Epic 3 can swap in OpenCodeEngine by changing
+   * this value — the retry loop and headless runner remain unchanged.
+   */
+  private engineId: EngineId = 'claude-code';
   private pendingApproval?: {
     plan: unknown;
     resolve: (approved: boolean) => void;
@@ -73,6 +82,13 @@ export class ImprovisationSessionManager extends EventEmitter {
   private _currentUserPrompt: string = '';
   private _currentSequenceNumber: number = 0;
   private _hasPersistedToDisk: boolean = false;
+  /**
+   * Cached duration-quantile profile used by the web "Composing" indicator
+   * to render an ETA. Built lazily on first executePrompt and refreshed by
+   * the eta-estimator's TTL cache. Null means "not enough history yet" — the
+   * web falls back to elapsed-only display.
+   */
+  private _etaProfile: EtaProfile | null = null;
 
   static resumeFromHistory(workingDir: string, historicalSessionId: string, overrides?: Partial<ImprovisationOptions>): ImprovisationSessionManager {
     const historyDir = join(workingDir, '.mstro', 'history');
@@ -84,6 +100,7 @@ export class ImprovisationSessionManager extends EventEmitter {
     }
 
     const historyData = JSON.parse(readFileSync(historyPath, 'utf-8')) as SessionHistory;
+    if (!historyData.engine) historyData.engine = 'claude-code';
     const manager = new ImprovisationSessionManager({
       workingDir,
       sessionId: historyData.sessionId,
@@ -126,6 +143,11 @@ export class ImprovisationSessionManager extends EventEmitter {
     this.historyPath = paths.historyPath;
     ensureHistoryDir(this.improviseDir);
 
+    // Validate the engine is available via the factory. Epic 3 will extend
+    // `createEngine` to also return OpenCodeEngine; today this asserts that
+    // a known engine id was requested and surfaces config errors early.
+    createEngine(this.engineId);
+
     this.history = loadHistory(this.historyPath, this.sessionId);
     // History is persisted lazily on the first `persistHistory` call (see
     // `executePrompt`). Deferring the initial write keeps the Chat History
@@ -165,7 +187,8 @@ export class ImprovisationSessionManager extends EventEmitter {
     const sequenceNumber = this.history.movements.length + 1;
     this._currentUserPrompt = displayPrompt;
     this._currentSequenceNumber = sequenceNumber;
-    this.emit('onMovementStart', sequenceNumber, displayPrompt, isAutoContinue);
+    await this.refreshEtaProfile();
+    this.emit('onMovementStart', sequenceNumber, displayPrompt, isAutoContinue, this._etaProfile);
     trackEvent(AnalyticsEvents.IMPROVISE_PROMPT_RECEIVED, {
       prompt_length: userPrompt.length,
       has_attachments: !!(attachments && attachments.length > 0),
@@ -499,6 +522,22 @@ export class ImprovisationSessionManager extends EventEmitter {
     });
   }
 
+  // ========== ETA profile ==========
+
+  /**
+   * Resolve the duration-quantile profile before announcing the movement
+   * so the web indicator can render an ETA from t=0. The cache amortizes
+   * I/O across prompts; only the very first prompt of a project pays the
+   * ~50–100ms scan cost. Failures degrade silently to "no ETA".
+   */
+  private async refreshEtaProfile(): Promise<void> {
+    try {
+      this._etaProfile = await getEtaProfileCached(this.improviseDir);
+    } catch {
+      this._etaProfile = null;
+    }
+  }
+
   // ========== History I/O ==========
 
   private persistHistory(): void {
@@ -588,10 +627,24 @@ export class ImprovisationSessionManager extends EventEmitter {
     return this._isExecuting;
   }
 
+  /**
+   * AI engine that produced this session. Read from SessionHistory (populated
+   * on load/creation). Defaults to 'claude-code' if the history record is
+   * missing the field (older sessions).
+   */
+  get engine(): string {
+    return this.history.engine || 'claude-code';
+  }
+
   get executionStartTimestamp(): number | undefined {
     return this._executionStartTimestamp;
   }
 
+  /** Most recently resolved ETA quantile profile, or null if none yet built. */
+  get etaProfile(): EtaProfile | null {
+    return this._etaProfile;
+  }
+
   getExecutionEventLog(): Array<{ type: string; data: unknown; timestamp: number }> {
     return this.executionEventLog;
   }

package/server/cli/improvisation-types.ts

@@ -66,6 +66,8 @@ export interface SessionHistory {
   totalTokens: number;
   movements: MovementRecord[];
   claudeSessionId?: string;
+  /** AI engine that produced this session (e.g. 'claude-code', 'opencode'). Older histories default to 'claude-code' on read. */
+  engine: string;
 }
 
 /** Entry in the retry log for debugging recovery paths */

package/server/engines/EngineEvent.ts

@@ -0,0 +1,156 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * EngineEvent — the engine-agnostic event stream produced by every
+ * CodingAgentEngine (see ./types.ts).
+ *
+ * Contract:
+ * - Every event has a `kind` discriminator, a `sessionId` (the engine's own
+ *   session identifier — Claude Code session id, OpenCode session id, etc.),
+ *   and a `timestamp` in Unix ms.
+ * - Payloads must carry enough information to populate OutputLine in the web
+ *   client without the consumer knowing which engine produced them. Do not
+ *   leak engine-specific fields (e.g. Claude tool_use_ids, OpenCode part ids)
+ *   through typed event fields — keep them in `raw` when needed for debugging.
+ * - Ordering is guaranteed within a single session: for a given tool call,
+ *   `tool.start` precedes `tool.end`; `usage.update` values are monotonic.
+ * - `session.idle` marks the end of a turn (assistant finished responding),
+ *   not the end of the session. Multiple idle events per session are normal.
+ * - `engine.error` with `fatal: true` is terminal — the async iterator must
+ *   complete after emitting it.
+ */
+
+/** Identifier for which concrete engine produced an event. */
+export type EngineId = 'claude-code' | 'opencode';
+
+/** Fields shared by every engine event. */
+interface EngineEventBase {
+  /** Engine-reported session id (e.g. Claude Code session id, OpenCode session id). */
+  sessionId: string;
+  /** Unix epoch milliseconds when the engine observed this event. */
+  timestamp: number;
+  /** Optional raw payload from the engine for debugging/audit. Must not be used for business logic. */
+  raw?: unknown;
+}
+
+/** Streaming assistant text (user-visible output). */
+export interface MessageDeltaEvent extends EngineEventBase {
+  kind: 'message.delta';
+  /** Incremental chunk of assistant-visible text. Consumers concatenate. */
+  text: string;
+}
+
+/** Streaming assistant thinking/reasoning text (collapsed by default in UI). */
+export interface MessageThinkingEvent extends EngineEventBase {
+  kind: 'message.thinking';
+  /** Incremental chunk of thinking text. */
+  text: string;
+}
+
+/** A tool invocation has started. */
+export interface ToolStartEvent extends EngineEventBase {
+  kind: 'tool.start';
+  /** Engine-agnostic tool call id (unique within the session). */
+  toolCallId: string;
+  /** Name of the tool (e.g. "Read", "Bash"). */
+  toolName: string;
+  /**
+   * Arguments passed to the tool. May be partial at start — some engines
+   * stream arguments. Consumers should treat this as best-effort until
+   * `tool.end` arrives with the authoritative input.
+   */
+  input: Record<string, unknown>;
+}
+
+/** A tool invocation has completed (successfully or with an error). */
+export interface ToolEndEvent extends EngineEventBase {
+  kind: 'tool.end';
+  toolCallId: string;
+  toolName: string;
+  /** Authoritative tool input as executed. */
+  input: Record<string, unknown>;
+  /** Serialized tool result (stdout, file contents, JSON, etc.). */
+  result: string;
+  /** True if the tool returned an error. */
+  isError: boolean;
+  /** Wall-clock duration in ms between tool.start and tool.end. */
+  durationMs: number;
+}
+
+/**
+ * The engine is asking whether a tool call should proceed. Consumed by
+ * the Bouncer in Epic 4 which must resolve the request via the engine's
+ * matching permission-response channel.
+ */
+export interface PermissionRequestEvent extends EngineEventBase {
+  kind: 'permission.request';
+  /** Opaque id the engine will expect echoed back in a decision. */
+  requestId: string;
+  toolName: string;
+  /** Tool arguments to be classified. */
+  input: Record<string, unknown>;
+  /** Engine-provided reason string, if any. */
+  reason?: string;
+}
+
+/**
+ * Session returned to idle — the assistant finished its current turn.
+ * Not the end of the session; a new prompt may still be sent.
+ */
+export interface SessionIdleEvent extends EngineEventBase {
+  kind: 'session.idle';
+  /** Engine's stop reason if known (e.g. 'end_turn', 'max_tokens'). */
+  stopReason?: string;
+}
+
+/**
+ * Running token counts. Values are cumulative across the session
+ * (not per-turn) and must be monotonically non-decreasing.
+ */
+export interface UsageUpdateEvent extends EngineEventBase {
+  kind: 'usage.update';
+  inputTokens: number;
+  outputTokens: number;
+  cacheCreationTokens?: number;
+  cacheReadTokens?: number;
+}
+
+/**
+ * An engine-level error occurred. With `fatal: true`, the session is
+ * unrecoverable and the async iterator completes after this event.
+ */
+export interface EngineErrorEvent extends EngineEventBase {
+  kind: 'engine.error';
+  /** Short error code for UI mapping (see ClaudeErrorCode in web/src/types/output.ts). */
+  code: string;
+  /** Human-readable message. */
+  message: string;
+  /** True if the session is unrecoverable and should be torn down. */
+  fatal: boolean;
+}
+
+/** Discriminated union of every event a CodingAgentEngine may emit. */
+export type EngineEvent =
+  | MessageDeltaEvent
+  | MessageThinkingEvent
+  | ToolStartEvent
+  | ToolEndEvent
+  | PermissionRequestEvent
+  | SessionIdleEvent
+  | UsageUpdateEvent
+  | EngineErrorEvent;
+
+/** Narrow helper — returns true for events that carry user-visible text. */
+export function isMessageEvent(
+  event: EngineEvent,
+): event is MessageDeltaEvent | MessageThinkingEvent {
+  return event.kind === 'message.delta' || event.kind === 'message.thinking';
+}
+
+/** Narrow helper — returns true for the tool lifecycle events. */
+export function isToolEvent(
+  event: EngineEvent,
+): event is ToolStartEvent | ToolEndEvent {
+  return event.kind === 'tool.start' || event.kind === 'tool.end';
+}