mstro-app 0.5.5 → 0.5.6

package/server/routes/internal.ts

@@ -0,0 +1,112 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+
+/**
+ * Internal Routes
+ *
+ * HTTP endpoints used by sibling subprocesses (like the MCP bouncer) to talk
+ * back to the running CLI server. NOT mounted under `/api/*` — these are gated
+ * by the per-process bouncer secret instead of the user's session token.
+ *
+ * Currently a single endpoint:
+ *   POST /internal/ask-user-question
+ *     Bouncer pauses Claude on AskUserQuestion; this blocks until the web
+ *     user answers, then returns the answers Claude needs to continue.
+ */
+
+import { Hono } from 'hono'
+import {
+  isValidBouncerSecret,
+  registerPendingQuestion,
+} from '../services/websocket/ask-user-question-bridge.js'
+import type { HandlerContext } from '../services/websocket/handler-context.js'
+import { broadcastTabEvent } from '../services/websocket/tab-broadcast.js'
+import type {
+  AskUserQuestionItem,
+  AskUserQuestionPayload,
+} from '../services/websocket/types.js'
+
+interface AskUserQuestionRequestBody {
+  toolUseId?: unknown
+  tabId?: unknown
+  questions?: unknown
+  /** Override default 15min timeout (ms). Optional. */
+  timeoutMs?: unknown
+}
+
+/** Narrow an unknown into AskUserQuestionItem[] without throwing. */
+function parseQuestions(value: unknown): AskUserQuestionItem[] | null {
+  if (!Array.isArray(value)) return null
+  const out: AskUserQuestionItem[] = []
+  for (const raw of value) {
+    if (!raw || typeof raw !== 'object') return null
+    const r = raw as Record<string, unknown>
+    if (typeof r.question !== 'string' || typeof r.header !== 'string') return null
+    if (!Array.isArray(r.options)) return null
+    const options = r.options.map((o) => {
+      if (!o || typeof o !== 'object') return null
+      const oo = o as Record<string, unknown>
+      if (typeof oo.label !== 'string') return null
+      return {
+        label: oo.label,
+        description: typeof oo.description === 'string' ? oo.description : '',
+        preview: typeof oo.preview === 'string' ? oo.preview : undefined,
+      }
+    })
+    if (options.some((o) => o === null)) return null
+    out.push({
+      question: r.question,
+      header: r.header,
+      options: options as AskUserQuestionItem['options'],
+      multiSelect: r.multiSelect === true,
+    })
+  }
+  return out
+}
+
+export function createInternalRoutes(ctx: HandlerContext): Hono {
+  const app = new Hono()
+
+  app.post('/ask-user-question', async (c) => {
+    const secret = c.req.header('x-mstro-bouncer-secret')
+    if (!isValidBouncerSecret(secret)) {
+      return c.json({ error: 'Forbidden' }, 403)
+    }
+
+    let body: AskUserQuestionRequestBody
+    try {
+      body = (await c.req.json()) as AskUserQuestionRequestBody
+    } catch {
+      return c.json({ error: 'Invalid JSON' }, 400)
+    }
+
+    const toolUseId = typeof body.toolUseId === 'string' ? body.toolUseId : ''
+    const tabId = typeof body.tabId === 'string' ? body.tabId : ''
+    const questions = parseQuestions(body.questions)
+    if (!toolUseId || !tabId || !questions || questions.length === 0) {
+      return c.json({ error: 'toolUseId, tabId, and non-empty questions[] are required' }, 400)
+    }
+
+    const timeoutMs =
+      typeof body.timeoutMs === 'number' && body.timeoutMs > 0 ? body.timeoutMs : undefined
+
+    const payload: AskUserQuestionPayload = { toolUseId, questions }
+    broadcastTabEvent(ctx, tabId, 'askUserQuestion', payload)
+
+    try {
+      const answers = await registerPendingQuestion({ toolUseId, tabId, timeoutMs })
+      return c.json({ answers })
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : 'cancelled'
+      // Tell every web client to dismiss the card so users don't keep poking
+      // an already-dead question.
+      broadcastTabEvent(ctx, tabId, 'askUserQuestionDismissed', {
+        toolUseId,
+        reason: reason === 'timeout' ? 'timeout' : 'cancelled',
+      })
+      const status = reason === 'timeout' ? 504 : 410
+      return c.json({ error: reason }, status)
+    }
+  })
+
+  return app
+}

package/server/services/runtime-info.ts

@@ -0,0 +1,24 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+
+/**
+ * Runtime Info
+ *
+ * Holds process-wide singletons that are known after server startup but
+ * needed by code paths (e.g. the headless runner / MCP config generator)
+ * that don't have a natural reference to the Hono app or instance registry.
+ *
+ * Specifically: the port the CLI server is bound to. We need it so the MCP
+ * bouncer subprocess can call back into us via HTTP for AskUserQuestion.
+ *
+ * Set once at server startup (see `server/index.ts`).
+ */
+
+let currentPort: number | undefined;
+
+export function setCurrentMstroPort(port: number): void {
+  currentPort = port;
+}
+
+export function getCurrentMstroPort(): number | undefined {
+  return currentPort;
+}

package/server/services/websocket/ask-user-question-bridge.ts

@@ -0,0 +1,148 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+
+/**
+ * AskUserQuestion Bridge
+ *
+ * Bridges the MCP bouncer subprocess (which receives Claude's AskUserQuestion
+ * tool calls) and the web client (which collects the user's answers).
+ *
+ * Flow:
+ *   Claude → MCP bouncer (subprocess)
+ *          → POST /internal/ask-user-question (this CLI server)
+ *          → registerPendingQuestion() stores a resolver
+ *          → broadcastTabEvent('askUserQuestion', …) pushes the question to web
+ *          → web user answers → WS `askUserQuestionResponse`
+ *          → resolvePendingQuestion() resolves the awaited promise
+ *          → HTTP response to bouncer with answers
+ *          → bouncer returns { behavior: "allow", updatedInput: { questions, answers } }
+ *
+ * Ownership of state: pending questions live only here, in-process. The
+ * registry is keyed by `toolUseId` (Claude's per-call id) which guarantees
+ * uniqueness across tabs and sessions.
+ *
+ * Timeouts: questions auto-reject after `DEFAULT_TIMEOUT_MS`. The bouncer's
+ * HTTP call gets a 504 and returns a deny to Claude rather than blocking the
+ * Claude turn forever.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+/** Default per-question timeout (15 minutes). */
+const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
+
+interface PendingQuestion {
+  toolUseId: string;
+  tabId: string;
+  resolve: (answers: Record<string, string>) => void;
+  reject: (reason: 'timeout' | 'cancelled' | 'session-ended') => void;
+  timer: ReturnType<typeof setTimeout>;
+  createdAt: number;
+}
+
+const pending = new Map<string, PendingQuestion>();
+
+/** Per-process secret the MCP bouncer must echo to authenticate.
+ *  Generated once at server start, passed to bouncers via env var. */
+const bouncerSharedSecret = randomUUID();
+
+/** Get the per-process bouncer secret (passed via env var to bouncer subprocesses). */
+export function getBouncerSecret(): string {
+  return bouncerSharedSecret;
+}
+
+/** Validate a secret claimed by an inbound /internal request. */
+export function isValidBouncerSecret(secret: string | undefined | null): boolean {
+  if (!secret) return false;
+  return secret === bouncerSharedSecret;
+}
+
+export interface RegisterPendingQuestionOptions {
+  toolUseId: string;
+  tabId: string;
+  timeoutMs?: number;
+}
+
+/**
+ * Register a pending question. The returned promise resolves when
+ * `resolvePendingQuestion` is called for the same toolUseId, or rejects on
+ * timeout / cancellation.
+ */
+export function registerPendingQuestion(
+  opts: RegisterPendingQuestionOptions,
+): Promise<Record<string, string>> {
+  const { toolUseId, tabId, timeoutMs = DEFAULT_TIMEOUT_MS } = opts;
+
+  // Defensive: reject any prior pending entry for this id (shouldn't happen
+  // but a process restart or duplicate POST shouldn't leak handlers).
+  const existing = pending.get(toolUseId);
+  if (existing) {
+    clearTimeout(existing.timer);
+    existing.reject('cancelled');
+    pending.delete(toolUseId);
+  }
+
+  return new Promise<Record<string, string>>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      const entry = pending.get(toolUseId);
+      if (!entry) return;
+      pending.delete(toolUseId);
+      entry.reject('timeout');
+    }, timeoutMs);
+
+    pending.set(toolUseId, {
+      toolUseId,
+      tabId,
+      resolve,
+      reject: (reason) => reject(new Error(reason)),
+      timer,
+      createdAt: Date.now(),
+    });
+  });
+}
+
+/**
+ * Resolve a pending question with the user's answers. Returns true if a
+ * pending entry was found and resolved; false if there was no matching
+ * pending question (already answered, timed out, or unknown id).
+ */
+export function resolvePendingQuestion(
+  toolUseId: string,
+  answers: Record<string, string>,
+): boolean {
+  const entry = pending.get(toolUseId);
+  if (!entry) return false;
+  pending.delete(toolUseId);
+  clearTimeout(entry.timer);
+  entry.resolve(answers);
+  return true;
+}
+
+/**
+ * Cancel all pending questions for a given tab. Used when a tab is removed,
+ * a session is reset, or an orchestra disconnects. Returns the toolUseIds
+ * that were cancelled so callers can broadcast `askUserQuestionDismissed`.
+ */
+export function cancelPendingQuestionsForTab(
+  tabId: string,
+  reason: 'cancelled' | 'session-ended' = 'cancelled',
+): string[] {
+  const cancelled: string[] = [];
+  for (const [id, entry] of pending) {
+    if (entry.tabId !== tabId) continue;
+    pending.delete(id);
+    clearTimeout(entry.timer);
+    entry.reject(reason);
+    cancelled.push(id);
+  }
+  return cancelled;
+}
+
+/** Look up the tab that owns a pending question, or undefined. */
+export function getPendingQuestionTab(toolUseId: string): string | undefined {
+  return pending.get(toolUseId)?.tabId;
+}
+
+/** Diagnostic: how many questions are currently waiting on user input. */
+export function pendingQuestionCount(): number {
+  return pending.size;
+}

package/server/services/websocket/handler.ts

@@ -15,6 +15,7 @@ import type { ImprovisationSessionManager } from '../../cli/improvisation-sessio
 import type { InstanceRegistry } from '../instances.js';
 import { captureException } from '../sentry.js';
 import { getPTYManager } from '../terminal/pty-manager.js';
+import { resolvePendingQuestion } from './ask-user-question-bridge.js';
 import { AutocompleteService } from './autocomplete.js';
 import { FileDownloadHandler } from './file-download-handler.js';
 import { handleFileExplorerMessage, handleFileMessage } from './file-explorer-handlers.js';
@@ -217,6 +218,9 @@ export class WebSocketImproviseHandler implements HandlerContext {
         return handleListSkills(this, ws, workingDir);
       case 'shutdownInstance':
         return this.handleShutdownInstance(ws, permission);
+      case 'askUserQuestionResponse':
+        if (permission === 'view') return;
+        return this.handleAskUserQuestionResponse(msg, tabId);
     }
 
     // Dispatch table lookup for domain handlers
@@ -391,6 +395,32 @@ export class WebSocketImproviseHandler implements HandlerContext {
     this.sessions.delete(sessionId);
   }
 
+  /**
+   * Resolve a pending AskUserQuestion call with the user's answers. The
+   * bouncer subprocess is awaiting on the bridge promise; calling
+   * `resolvePendingQuestion` releases it so Claude resumes with the answers.
+   * Stale toolUseIds are no-ops — likely the question already timed out or
+   * was cancelled, and a stale web client is replaying its submission.
+   */
+  private handleAskUserQuestionResponse(msg: WebSocketMessage, tabId: string): void {
+    const data = msg.data as { toolUseId?: unknown; answers?: unknown } | undefined;
+    const toolUseId = typeof data?.toolUseId === 'string' ? data.toolUseId : '';
+    const answersIn = data?.answers;
+    if (!toolUseId) return;
+
+    // Only accept a flat string-string map; coerce safely so a malformed
+    // payload doesn't crash the bridge.
+    const answers: Record<string, string> = {};
+    if (answersIn && typeof answersIn === 'object' && !Array.isArray(answersIn)) {
+      for (const [k, v] of Object.entries(answersIn as Record<string, unknown>)) {
+        if (typeof v === 'string') answers[k] = v;
+      }
+    }
+
+    void tabId; // tabId is informational; the toolUseId is the unique key
+    resolvePendingQuestion(toolUseId, answers);
+  }
+
   /**
    * Handle a `shutdownInstance` control message from a web client.
    *

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

@@ -248,6 +248,9 @@ export function buildOutputHistory(session: ImprovisationSessionManager): Array<
  */
 export function setupSessionListeners(ctx: HandlerContext, session: ImprovisationSessionManager, _ws: WSContext, tabId: string): void {
   session.removeAllListeners();
+  // Bind tabId before listeners — the headless runner reads it at executePrompt
+  // time to wire AskUserQuestion routing back to this tab's web clients.
+  session.setTabId(tabId);
   const engine = resolveEngineForSession(session);
 
   session.on('onHistoryPersisted', () => {

package/server/services/websocket/types.ts

@@ -19,7 +19,7 @@ export interface WSContext {
   _ws?: unknown
 }
 
-const CoreMessages = ['execute', 'cancel', 'getHistory', 'getSessions', 'getSessionsCount', 'deleteSession', 'getSessionById', 'clearHistory', 'searchHistory', 'new', 'autocomplete', 'readFile', 'ping', 'initTab', 'resumeSession', 'approve', 'reject', 'recordSelection', 'requestNotificationSummary'] as const;
+const CoreMessages = ['execute', 'cancel', 'getHistory', 'getSessions', 'getSessionsCount', 'deleteSession', 'getSessionById', 'clearHistory', 'searchHistory', 'new', 'autocomplete', 'readFile', 'ping', 'initTab', 'resumeSession', 'approve', 'reject', 'recordSelection', 'requestNotificationSummary', 'askUserQuestionResponse'] as const;
 
 const TerminalMessages = ['terminalInit', 'terminalReconnect', 'terminalList', 'terminalInput', 'terminalResize', 'terminalClose'] as const;
 
@@ -108,7 +108,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', 'executeAck', 'clientOffline', 'clientAuthExpired'] 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', 'askUserQuestion', 'askUserQuestionDismissed'] as const;
 
 const TerminalResponseMessages = ['terminalOutput', 'terminalReady', 'terminalExit', 'terminalError', 'terminalList', 'terminalScrollback', 'terminalCreated', 'terminalClosed'] as const;
 
@@ -193,6 +193,52 @@ export interface ConnectionData {
   workingDir: string;
 }
 
+// ============================================================================
+// AskUserQuestion Types
+// ============================================================================
+
+/**
+ * Single option Claude offers in an AskUserQuestion call. Mirrors the
+ * Claude Agent SDK shape so we can pass-through with no translation.
+ */
+export interface AskUserQuestionOption {
+  label: string;
+  description: string;
+  /** Optional HTML/Markdown preview snippet (when previewFormat is set). */
+  preview?: string;
+}
+
+/**
+ * One question in an AskUserQuestion call. Per Claude SDK: each call
+ * carries 1–4 questions, each question 2–4 options. Header is a short
+ * label (≤12 chars) used for compact display.
+ */
+export interface AskUserQuestionItem {
+  question: string;
+  header: string;
+  options: AskUserQuestionOption[];
+  multiSelect: boolean;
+}
+
+/** Outbound payload (cli → web) when Claude pauses on an AskUserQuestion. */
+export interface AskUserQuestionPayload {
+  toolUseId: string;
+  questions: AskUserQuestionItem[];
+}
+
+/** Outbound payload (cli → web) when a pending question is no longer answerable. */
+export interface AskUserQuestionDismissedPayload {
+  toolUseId: string;
+  reason: 'timeout' | 'cancelled' | 'session-ended';
+}
+
+/** Inbound payload (web → cli) carrying the user's selections. */
+export interface AskUserQuestionResponseData {
+  toolUseId: string;
+  /** Map of question text → selected label(s) (joined with ", " for multi-select). */
+  answers: Record<string, string>;
+}
+
 export interface SkillEntry {
   name: string;
   displayName: string;