mstro-app 0.4.52 → 0.5.0

package/server/services/websocket/session-registry.ts

@@ -21,6 +21,13 @@ export interface RegisteredTab {
   lastActivityAt: string
   order: number
   hasUnviewedCompletion: boolean
+  /**
+   * True once the session's history file has existed on disk (first prompt
+   * ran, or the tab was resumed from an existing file). Guards `sweepGhostTabs`
+   * so brand-new tabs that haven't had a first prompt are not confused with
+   * tabs whose history file was deleted.
+   */
+  hasPersistedHistory?: boolean
   worktreePath?: string
   worktreeBranch?: string
 }
@@ -31,6 +38,7 @@ interface RegistryData {
 
 export class SessionRegistry {
   private registryPath: string
+  private historyDir: string
   private data: RegistryData
 
   constructor(workingDir: string) {
@@ -39,7 +47,9 @@ export class SessionRegistry {
       mkdirSync(mstroDir, { recursive: true })
     }
     this.registryPath = join(mstroDir, 'session-registry.json')
+    this.historyDir = join(mstroDir, 'history')
     this.data = this.load()
+    this.sweepGhostTabs()
   }
 
   private load(): RegistryData {
@@ -68,6 +78,36 @@ export class SessionRegistry {
     return { tabs: {} }
   }
 
+  /**
+   * Drop registry entries whose backing history file no longer exists.
+   *
+   * The history file may have been deleted via `clearHistory`, pruned by the
+   * user, or lost on disk. Without a sweep, `getActiveTabs` returns the tab
+   * to the web, the web tries to `initTab` it, `resumeFromHistory` throws,
+   * and the tab re-creates as an empty new session — confusing the user with
+   * a "restored" tab that lost its content.
+   *
+   * Only sweeps tabs that were previously persisted (`hasPersistedHistory`).
+   * Tabs that have never had a first prompt have no file on disk by design;
+   * removing them here would wipe a freshly opened tab after a CLI restart.
+   */
+  private sweepGhostTabs(): void {
+    const removed: string[] = []
+    for (const [tabId, tab] of Object.entries(this.data.tabs)) {
+      if (tab.hasPersistedHistory !== true) continue
+      const timestamp = tab.sessionId.replace('improv-', '')
+      const historyPath = join(this.historyDir, `${timestamp}.json`)
+      if (!existsSync(historyPath)) {
+        removed.push(tabId)
+        delete this.data.tabs[tabId]
+      }
+    }
+    if (removed.length > 0) {
+      console.log(`[SessionRegistry] Swept ${removed.length} ghost tab(s) whose history file was missing`)
+      this.save()
+    }
+  }
+
   private save(): void {
     try {
       writeFileSync(this.registryPath, JSON.stringify(this.data, null, 2))
@@ -86,13 +126,16 @@ export class SessionRegistry {
 
   registerTab(tabId: string, sessionId: string, tabName?: string): void {
     const now = new Date().toISOString()
+    const existing = this.data.tabs[tabId]
+    const sessionChanged = existing?.sessionId !== sessionId
     this.data.tabs[tabId] = {
       sessionId,
       tabName: tabName || `Chat ${this.getNextChatNumber()}`,
-      createdAt: this.data.tabs[tabId]?.createdAt || now,
+      createdAt: existing?.createdAt || now,
       lastActivityAt: now,
-      order: this.data.tabs[tabId]?.order ?? this.getNextOrder(),
-      hasUnviewedCompletion: this.data.tabs[tabId]?.hasUnviewedCompletion ?? false,
+      order: existing?.order ?? this.getNextOrder(),
+      hasUnviewedCompletion: existing?.hasUnviewedCompletion ?? false,
+      hasPersistedHistory: sessionChanged ? false : existing?.hasPersistedHistory,
     }
     this.save()
   }
@@ -145,12 +188,26 @@ export class SessionRegistry {
   }
 
   /**
-   * Update session ID for a tab (e.g., when "new session" is started)
+   * Update session ID for a tab (e.g., when "new session" is started).
+   * Resets `hasPersistedHistory` since the new session has no file on disk yet.
    */
   updateTabSession(tabId: string, sessionId: string): void {
     if (this.data.tabs[tabId]) {
       this.data.tabs[tabId].sessionId = sessionId
       this.data.tabs[tabId].lastActivityAt = new Date().toISOString()
+      this.data.tabs[tabId].hasPersistedHistory = false
+      this.save()
+    }
+  }
+
+  /**
+   * Mark a tab as having persisted its history to disk. Called after the
+   * first `persistHistory` or when an existing file is resumed.
+   */
+  markTabPersisted(tabId: string): void {
+    const tab = this.data.tabs[tabId]
+    if (tab && !tab.hasPersistedHistory) {
+      tab.hasPersistedHistory = true
       this.save()
     }
   }

package/server/services/websocket/tab-broadcast.ts

@@ -0,0 +1,38 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * Tab-scoped broadcast helper.
+ *
+ * Session and plan handlers emit streaming events that (a) fan out to all
+ * paired web clients and (b) need to survive transport reconnects. Instead of
+ * every call site knowing about both concerns, route through
+ * `broadcastTabEvent`: it assigns the next monotonic `seq` via the tab's
+ * event buffer and broadcasts the wire message with that seq attached.
+ *
+ * Receiving webs record the seq and ask for replay starting from their
+ * highest-seen seq the next time they `initTab` / `resumeSession`. See
+ * `tab-event-buffer.ts` for the buffer itself and
+ * `session-initialization.ts` for the replay path.
+ */
+
+import type { HandlerContext } from './handler-context.js'
+import type { WebSocketResponse } from './types.js'
+
+type TabScopedEventType = WebSocketResponse['type']
+
+/**
+ * Record + broadcast a tab-scoped event in one call. Returns the assigned
+ * sequence number purely for logging/tests — callers rarely need it.
+ */
+export function broadcastTabEvent(
+  ctx: HandlerContext,
+  tabId: string,
+  type: TabScopedEventType,
+  data: unknown,
+): number {
+  const buffer = ctx.tabEventBuffers.getOrCreate(tabId)
+  const seq = buffer.record(type, data)
+  ctx.broadcastToAll({ type, tabId, data, seq })
+  return seq
+}

package/server/services/websocket/tab-event-buffer.ts

@@ -0,0 +1,159 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * Tab event buffer — monotonic, bounded replay log for tab-scoped broadcasts.
+ *
+ * ## Why it exists
+ *
+ * The platform relay only fans out broadcasts to webs currently paired to the
+ * CLI's connection key. During a CLI-side platform reconnect the CLI's key
+ * rotates (new `connectionId`) and any web whose transport was pointing at
+ * the old key sees no events until it completes its own reconnect handshake.
+ * The `executionEventLog` on the session manager covers in-flight execution,
+ * but smaller lifecycle events — `movementStart`, `movementComplete`,
+ * `tabStateChanged`, `sessionUpdate`, approve/reject acknowledgements — can
+ * land in that dark window and be lost.
+ *
+ * This buffer records every tab-scoped broadcast with a monotonic per-tab
+ * `seq`. When the web sends `initTab` / `resumeSession` with its
+ * `lastSeenSeq`, we replay anything newer before emitting `tabInitialized`.
+ *
+ * ## Design choices
+ *
+ * - **Bounded by both count and age** so a long-idle tab doesn't keep ancient
+ *   events forever, and a chatty session doesn't balloon memory. The limits
+ *   are intentionally generous: 1000 events + 15 minutes covers a typical
+ *   reconnect window by orders of magnitude, and events are small objects.
+ * - **Per-tab registry, not per-session** because the web identifies replay
+ *   targets by `tabId`, which is stable across `new` (sessionId rotates, tab
+ *   doesn't).
+ * - **No sequencing gaps**: `nextSeq` strictly increments, even when the
+ *   buffer drops old events. The web compares `seq > lastSeenSeq`, so stale
+ *   numbering below the window is fine — everything the web hasn't seen yet
+ *   has a larger seq.
+ */
+
+export interface BufferedEvent {
+  /** Monotonic per-tab sequence (1-based). */
+  seq: number
+  /** Wire message type, e.g. `output`, `thinking`, `movementComplete`. */
+  type: string
+  /** Opaque payload for the wire message. */
+  data: unknown
+  /** `Date.now()` at record time. Used for age-based eviction. */
+  timestamp: number
+}
+
+/**
+ * Bounded replay log for a single tab.
+ *
+ * Size/age limits are parameterised for testability but defaulted to values
+ * that comfortably cover real-world reconnect windows.
+ */
+export class TabEventBuffer {
+  private readonly events: BufferedEvent[] = []
+  private nextSeq = 1
+
+  constructor(
+    private readonly maxEvents: number = DEFAULT_MAX_EVENTS,
+    private readonly maxAgeMs: number = DEFAULT_MAX_AGE_MS,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  /**
+   * Append an event and return its assigned sequence number.
+   *
+   * Callers include the returned `seq` on the outgoing wire message so the
+   * web can record it and ask for replay starting after that seq on a
+   * subsequent reconnect.
+   */
+  record(type: string, data: unknown): number {
+    const seq = this.nextSeq++
+    this.events.push({ seq, type, data, timestamp: this.now() })
+    this.evict()
+    return seq
+  }
+
+  /**
+   * Return all still-buffered events with `seq > afterSeq`, in original
+   * order. Returns an empty array if nothing newer is buffered (either the
+   * web is caught up or the window has rolled past).
+   */
+  getSince(afterSeq: number): BufferedEvent[] {
+    this.evict()
+    const out: BufferedEvent[] = []
+    for (const event of this.events) {
+      if (event.seq > afterSeq) out.push(event)
+    }
+    return out
+  }
+
+  /** Current highest assigned seq (monotonic; not reset by eviction). */
+  currentSeq(): number {
+    return this.nextSeq - 1
+  }
+
+  /** Events currently held in memory. For tests. */
+  size(): number {
+    return this.events.length
+  }
+
+  /**
+   * Drop events older than `maxAgeMs` from the front, then enforce
+   * `maxEvents` by trimming the front further if needed. Eviction keeps the
+   * newest events — they're the ones the web is most likely to still need.
+   */
+  private evict(): void {
+    const cutoff = this.now() - this.maxAgeMs
+    while (this.events.length > 0 && this.events[0].timestamp < cutoff) {
+      this.events.shift()
+    }
+    while (this.events.length > this.maxEvents) {
+      this.events.shift()
+    }
+  }
+}
+
+/**
+ * Registry of per-tab buffers. Kept as a thin collection so `HandlerContext`
+ * can expose one instance and every broadcast site looks up (or lazily
+ * creates) the tab's buffer with a single call.
+ */
+export class TabEventBufferRegistry {
+  private readonly buffers = new Map<string, TabEventBuffer>()
+
+  constructor(
+    private readonly bufferFactory: () => TabEventBuffer = () => new TabEventBuffer(),
+  ) {}
+
+  /** Get the buffer for `tabId`, creating it on first touch. */
+  getOrCreate(tabId: string): TabEventBuffer {
+    let buffer = this.buffers.get(tabId)
+    if (!buffer) {
+      buffer = this.bufferFactory()
+      this.buffers.set(tabId, buffer)
+    }
+    return buffer
+  }
+
+  /** Get the buffer for `tabId` without creating it. */
+  get(tabId: string): TabEventBuffer | undefined {
+    return this.buffers.get(tabId)
+  }
+
+  /** Forget `tabId` entirely — called on `tabRemoved`. */
+  delete(tabId: string): void {
+    this.buffers.delete(tabId)
+  }
+
+  /** Drop all bookkeeping. Used for tests; no production caller expected. */
+  clear(): void {
+    this.buffers.clear()
+  }
+}
+
+/** 1000 events per tab covers typical reconnect windows comfortably. */
+export const DEFAULT_MAX_EVENTS = 1000
+/** 15 minutes of history is more than enough for the longest plausible web reconnect. */
+export const DEFAULT_MAX_AGE_MS = 15 * 60 * 1000

package/server/services/websocket/tab-event-replay.ts

@@ -0,0 +1,42 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * Replay tab-scoped events missed during a transport gap.
+ *
+ * `session-initialization.ts` calls this right before sending `tabInitialized`
+ * so the web sees any events with `seq > lastSeenSeq` in-order before the
+ * usual initialization payload. Ordering matters: e.g. a `movementComplete`
+ * before `outputHistory` would render duplicate content.
+ *
+ * Delivery is targeted (`ctx.send`) rather than broadcast because only the
+ * rejoining web needs the replay; other connected webs already saw these
+ * events live.
+ */
+
+import type { HandlerContext } from './handler-context.js'
+import type { WebSocketResponse, WSContext } from './types.js'
+
+/**
+ * Replay tab events with `seq > lastSeenSeq` to `ws`. Silently no-ops when
+ * the buffer is empty or `lastSeenSeq` is unset (full init, not a resume).
+ */
+export function replayTabEventsSince(
+  ctx: HandlerContext,
+  ws: WSContext,
+  tabId: string,
+  lastSeenSeq: number | undefined,
+): void {
+  if (lastSeenSeq === undefined) return
+
+  const buffer = ctx.tabEventBuffers.get(tabId)
+  if (!buffer) return
+
+  const events = buffer.getSince(lastSeenSeq)
+  for (const event of events) {
+    // Types are checked at record time via `broadcastTabEvent`; the buffer
+    // stores them as strings but by construction they're always
+    // `WebSocketResponse['type']`. Narrow here without an extra runtime check.
+    ctx.send(ws, { type: event.type as WebSocketResponse['type'], tabId, data: event.data, seq: event.seq })
+  }
+}

package/server/services/websocket/tab-handlers.ts

@@ -78,20 +78,13 @@ export function handleSyncTabMeta(ctx: HandlerContext, _ws: WSContext, msg: WebS
   }
 }
 
-export function handleSyncPromptText(ctx: HandlerContext, _ws: WSContext, msg: WebSocketMessage, tabId: string): void {
-  if (typeof msg.data?.text !== 'string') return;
-  ctx.broadcastToAll({
-    type: 'promptTextSync',
-    tabId,
-    data: { tabId, text: msg.data.text }
-  });
-}
-
 export function handleRemoveTab(ctx: HandlerContext, _ws: WSContext, tabId: string, workingDir: string): void {
   const registry = ctx.getRegistry(workingDir);
   registry.unregisterTab(tabId);
   ctx.gitDirectories.delete(tabId);
   ctx.gitBranches.delete(tabId);
+  ctx.tabEventBuffers.delete(tabId);
+  ctx.msgIdTracker.forget(tabId);
 
   ctx.broadcastToAll({
     type: 'tabRemoved',

package/server/services/websocket/types.ts

@@ -38,7 +38,7 @@ const GitWorktreeMessages = ['gitWorktreeList', 'gitWorktreeCreate', 'gitWorktre
 
 const GitMergeMessages = ['gitMergePreview', 'gitWorktreeMerge', 'gitMergeAbort', 'gitMergeComplete'] as const;
 
-const SessionSyncMessages = ['getActiveTabs', 'createTab', 'reorderTabs', 'syncTabMeta', 'syncPromptText', 'removeTab', 'markTabViewed'] as const;
+const SessionSyncMessages = ['getActiveTabs', 'createTab', 'reorderTabs', 'syncTabMeta', 'removeTab', 'markTabViewed'] as const;
 
 const SettingsMessages = ['getSettings', 'updateSettings'] as const;
 
@@ -46,6 +46,8 @@ const QualityMessages = ['qualityDetectTools', 'qualityScan', 'qualityInstallToo
 
 const FileUploadMessages = ['fileUploadStart', 'fileUploadChunk', 'fileUploadComplete', 'fileUploadCancel'] as const;
 
+const FileDownloadMessages = ['fileDownloadStart', 'fileDownloadCancel'] as const;
+
 const PlanMessages = ['planInit', 'planGetState', 'planListIssues', 'planGetIssue', 'planGetSprint', 'planGetMilestone', 'planCreateIssue', 'planUpdateIssue', 'planDeleteIssue', 'planScaffold', 'planPrompt', 'planExecute', 'planExecuteEpic', 'planPause', 'planStop', 'planResume'] as const;
 
 const PlanBoardMessages = ['planCreateBoard', 'planUpdateBoard', 'planArchiveBoard', 'planRestoreBoard', 'planGetBoard', 'planGetBoardState', 'planReorderBoards', 'planSetActiveBoard', 'planGetBoardArtifacts'] as const;
@@ -68,6 +70,7 @@ type WebSocketMessageType =
   | typeof SettingsMessages[number]
   | typeof QualityMessages[number]
   | typeof FileUploadMessages[number]
+  | typeof FileDownloadMessages[number]
   | typeof PlanMessages[number]
   | typeof PlanBoardMessages[number]
   | typeof PlanSprintMessages[number]
@@ -83,7 +86,7 @@ export interface WebSocketMessage {
   _permission?: 'view';
 }
 
-const CoreResponseMessages = ['output', 'thinking', 'movementStart', 'movementComplete', 'movementError', 'sessionUpdate', 'history', 'sessions', 'sessionsCount', 'sessionDeleted', 'sessionData', 'historyCleared', 'searchResults', 'newSession', 'autocomplete', 'fileContent', 'error', 'pong', 'tabInitialized', 'approvalRequired', 'toolUse', 'streamingTokens', 'notificationSummary'] as const;
+const CoreResponseMessages = ['output', 'thinking', 'movementStart', 'movementComplete', 'movementError', 'sessionUpdate', 'history', 'sessions', 'sessionsCount', 'sessionDeleted', 'sessionData', 'historyCleared', 'searchResults', 'newSession', 'autocomplete', 'fileContent', 'error', 'pong', 'tabInitialized', 'approvalRequired', 'toolUse', 'streamingTokens', 'notificationSummary', 'executeAck', 'clientOffline', 'clientAuthExpired'] as const;
 
 const TerminalResponseMessages = ['terminalOutput', 'terminalReady', 'terminalExit', 'terminalError', 'terminalList', 'terminalScrollback', 'terminalCreated', 'terminalClosed'] as const;
 
@@ -101,14 +104,16 @@ const GitWorktreeResponseMessages = ['gitWorktreeListResult', 'gitWorktreeCreate
 
 const GitMergeResponseMessages = ['gitMergePreviewResult', 'gitWorktreeMergeResult', 'gitMergeAborted', 'gitMergeCompleted'] as const;
 
-const SessionSyncResponseMessages = ['activeTabs', 'tabCreated', 'tabRemoved', 'tabRenamed', 'tabsReordered', 'promptTextSync', 'tabViewed', 'tabStateChanged'] as const;
+const SessionSyncResponseMessages = ['activeTabs', 'tabCreated', 'tabRemoved', 'tabRenamed', 'tabsReordered', 'tabViewed', 'tabStateChanged'] as const;
 
 const SettingsResponseMessages = ['settings', 'settingsUpdated'] as const;
 
-const QualityResponseMessages = ['qualityToolsDetected', 'qualityScanProgress', 'qualityScanResults', 'qualityInstallProgress', 'qualityInstallComplete', 'qualityCodeReview', 'qualityCodeReviewProgress', 'qualityPostSession', 'qualityError', 'qualityStateLoaded'] as const;
+const QualityResponseMessages = ['qualityToolsDetected', 'qualityScanProgress', 'qualityScanResults', 'qualityInstallProgress', 'qualityInstallComplete', 'qualityCodeReview', 'qualityCodeReviewProgress', 'qualityPostSession', 'qualityError', 'qualityStateLoaded', 'qualityDirectoriesUpdated'] as const;
 
 const FileUploadResponseMessages = ['fileUploadAck', 'fileUploadReady', 'fileUploadError'] as const;
 
+const FileDownloadResponseMessages = ['fileDownloadReady', 'fileDownloadChunk', 'fileDownloadComplete', 'fileDownloadError'] as const;
+
 const PlanResponseMessages = ['planState', 'planIssueList', 'planIssue', 'planSprint', 'planMilestone', 'planNotFound', 'planStateUpdated', 'planIssueUpdated', 'planIssueCreated', 'planIssueDeleted', 'planScaffolded', 'planPromptStreaming', 'planPromptProgress', 'planPromptResponse', 'planExecutionStarted', 'planExecutionProgress', 'planExecutionOutput', 'planExecutionMetrics', 'planExecutionComplete', 'planExecutionError', 'planError'] as const;
 
 const PlanBoardResponseMessages = ['planBoardCreated', 'planBoardUpdated', 'planBoardArchived', 'planBoardState', 'planBoardArtifacts', 'planWorkspaceUpdated'] as const;
@@ -131,6 +136,7 @@ type WebSocketResponseType =
   | typeof SettingsResponseMessages[number]
   | typeof QualityResponseMessages[number]
   | typeof FileUploadResponseMessages[number]
+  | typeof FileDownloadResponseMessages[number]
   | typeof PlanResponseMessages[number]
   | typeof PlanBoardResponseMessages[number]
   | typeof PlanSprintResponseMessages[number]
@@ -142,6 +148,13 @@ export interface WebSocketResponse {
   terminalId?: string;
   // biome-ignore lint/suspicious/noExplicitAny: message envelope carries heterogeneous payloads — typed per-handler via destructuring
   data?: any;
+  /**
+   * Monotonic per-tab sequence number assigned by `tab-event-buffer.ts`.
+   * Stamped on tab-scoped streaming broadcasts so webs can ask for replay
+   * starting after their highest-seen seq on a reconnect (`initTab` /
+   * `resumeSession` with `lastSeenSeq` in the payload).
+   */
+  seq?: number;
 }
 
 export interface ConnectionData {