mstro-app 0.5.0 → 0.5.5

package/server/cli/headless/types.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Headless Runner Types

package/server/cli/improvisation-attachments.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Attachment handling for improvisation sessions.

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

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Persistence helpers for improvisation session history.
@@ -40,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);
     }
@@ -52,6 +53,7 @@ export function loadHistory(historyPath: string, sessionId: string): SessionHist
     lastActivityAt: now,
     totalTokens: 0,
     movements: [],
+    engine: 'claude-code',
   };
 }
 

package/server/cli/improvisation-movements.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Pure builders for the MovementRecord snapshots that session-manager

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

@@ -1,16 +1,32 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * 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) {}
@@ -21,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-retry.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Retry and recovery logic for improvisation sessions — barrel re-export.

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

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Improvisation Session Manager v2
@@ -17,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 {
@@ -56,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;
@@ -74,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');
@@ -85,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,
@@ -127,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
@@ -166,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),
@@ -500,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 {
@@ -589,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

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Types and interfaces for the Improvisation Session Manager.
@@ -67,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/cli/retry/retry-best-result.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Picks the best result across retry attempts. Prefers Haiku's judgment

package/server/cli/retry/retry-context-loss.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Context-loss detection: figures out when a run's output indicates the

package/server/cli/retry/retry-premature-completion.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Detects when a claimed-complete run is actually unfinished (hit
@@ -80,7 +79,7 @@ function applyPrematureCompletionRetry(
   });
 
   callbacks.queueOutput(
-    `\n${reason} — resuming session (retry ${state.retryNumber}/${maxRetries}).\n`
+    `\n\n${reason} — resuming session (retry ${state.retryNumber}/${maxRetries}).\n\n`
   );
   callbacks.flushOutputQueue();
 

package/server/cli/retry/retry-recovery-strategies.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Recovery strategies: context-loss (inter-movement / native-timeout),

package/server/cli/retry/retry-resume-strategy.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Picks how the next retry iteration should resume execution:

package/server/cli/retry/retry-runner-factory.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Factory for the HeadlessRunner used in a single retry iteration.

package/server/cli/retry/retry-tool-results.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Running buffer of tool results preserved across retries so recovery

package/server/cli/retry/retry-types.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Shared types used across the retry modules. Defined separately so each

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';
+}