mstro-app 0.5.1 → 0.5.6

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,33 @@ export class ImprovisationSessionManager extends EventEmitter {
     return this._isExecuting;
   }
 
+  /**
+   * Bind this session to a web tab. Used so the headless runner can route
+   * AskUserQuestion calls back to that tab's web clients via the bridge.
+   * Idempotent and safe to call repeatedly across reconnects.
+   */
+  setTabId(tabId: string): void {
+    this.options.tabId = tabId;
+  }
+
+  /**
+   * 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

@@ -22,6 +22,13 @@ export interface ImprovisationOptions {
    * Unsupported levels gracefully fall back to the highest supported level per model.
    */
   effortLevel?: string;
+  /**
+   * Web tab id this session is bound to. Used for AskUserQuestion routing —
+   * the MCP bouncer pauses Claude on AskUserQuestion and the bridge fans the
+   * questions out to this tab's web clients. Optional: when unset the
+   * bouncer falls back to legacy behavior (allow with no answers).
+   */
+  tabId?: string;
 }
 
 // File attachment for multimodal prompts (images)
@@ -66,6 +73,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-runner-factory.ts

@@ -31,6 +31,7 @@ export function createExecutionRunner(
     noColor: session.options.noColor,
     model: session.options.model,
     effortLevel: session.options.effortLevel,
+    tabId: session.options.tabId,
     improvisationMode: true,
     movementNumber: sequenceNumber,
     continueSession: useResume,

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