@brainpilot/web 0.0.4 → 0.0.5

package/src/contexts/messageFilters.ts

@@ -0,0 +1,29 @@
+import { ChatMessage, MessageFilterRule } from "../contracts/backend";
+
+export const defaultFilterRules: MessageFilterRule[] = [
+  {
+    id: "spurious-dot",
+    name: "Hide spurious single-dot messages",
+    description:
+      "Hides assistant text messages that contain only a single '.' character. " +
+      "These often appear when the model enters defensive thinking mode and emits minimal text before a tool call.",
+    enabled: true,
+    test: (msg: ChatMessage, _all: ChatMessage[]) => {
+      if (msg.role !== "assistant") return false;
+      if (msg.kind !== "text") return false;
+      if (msg.streaming) return false;
+      return msg.content.trim() === ".";
+    },
+  },
+];
+
+export function applyMessageFilters(
+  messages: ChatMessage[],
+  rules: MessageFilterRule[]
+): ChatMessage[] {
+  const activeRules = rules.filter((r) => r.enabled);
+  if (activeRules.length === 0) return messages;
+  return messages.filter((msg) => {
+    return !activeRules.some((rule) => rule.test(msg, messages));
+  });
+}

package/src/contexts/messageGroups.ts

@@ -0,0 +1,77 @@
+import { ChatMessage } from "../contracts/backend";
+
+/**
+ * A unit of rendering in the chat stream. Either a single standalone message
+ * (user prompt, assistant text, error, hook note) or an "activity" group that
+ * folds adjacent reasoning and tool calls/results into one collapsible block.
+ */
+export type RenderItem =
+  | { type: "single"; message: ChatMessage }
+  | { type: "activity"; id: string; steps: ChatMessage[]; streaming: boolean };
+
+/**
+ * Standalone kinds render as their own visible card. All assistant text
+ * messages — whether they come from the Principal or an Expert agent, and
+ * whether they are an intermediate utterance or the turn's final answer —
+ * stay standalone so the formal conversation is never hidden behind the
+ * "思考过程" fold. Only reasoning (`thinking`) and tool calls/results fold
+ * into activity blocks.
+ */
+function isStandalone(message: ChatMessage): boolean {
+  if (message.role === "user") return true;
+  if (message.kind === "error" || message.kind === "status" || message.kind === "hook") return true;
+  // 修正6 — new-UI kinds each render as their own standalone card.
+  if (message.kind === "system_message" || message.kind === "ask_user" || message.kind === "auto_retry") return true;
+  if (message.role === "assistant" && (message.kind === "text" || message.kind === undefined)) return true;
+  if (message.role === "system" && (message.kind === "text" || message.kind === undefined)) return true;
+  return false;
+}
+
+/**
+ * Transform the flat message list into render items. Adjacent reasoning and
+ * tool steps fold into a single activity group; everything else renders
+ * standalone. The activity group id is its first step's id so the native
+ * <details> DOM node is reused across re-renders, preserving the user's
+ * expand/collapse toggle without explicit React state.
+ *
+ * `runningAgents` is the authoritative set of agent names whose run is still
+ * active (RUN_STARTED..RUN_FINISHED, sourced from `session_state`). An activity
+ * block is "in progress" if any of its steps is still streaming OR its owning
+ * agent's run is still active. Without this, the per-message `streaming` flags
+ * all go false between ReAct rounds (each message's END clears it), so the
+ * block would flash "思考过程 · N 步" (done) in the gap before the next round —
+ * AG-UI explicitly warns against treating a message/tool END as run completion.
+ * Omitting `runningAgents` (e.g. demo replay, where messages are already
+ * terminal) preserves the original streaming-flag-only behavior.
+ */
+export function buildRenderItems(
+  messages: ChatMessage[],
+  runningAgents?: ReadonlySet<string>,
+): RenderItem[] {
+  const items: RenderItem[] = [];
+  let buffer: ChatMessage[] = [];
+  // A step keeps its block "in progress" while its owning agent's run is active.
+  // Steps default to the principal agent when unattributed, matching how the
+  // reducer/UI fall back elsewhere.
+  const agentActive = (s: ChatMessage) => runningAgents?.has(s.agent ?? "principal") ?? false;
+  const flush = () => {
+    if (buffer.length === 0) return;
+    items.push({
+      type: "activity",
+      id: buffer[0].id,
+      steps: buffer,
+      streaming: buffer.some((s) => s.streaming || agentActive(s)),
+    });
+    buffer = [];
+  };
+  for (const m of messages) {
+    if (isStandalone(m)) {
+      flush();
+      items.push({ type: "single", message: m });
+    } else {
+      buffer.push(m);
+    }
+  }
+  flush();
+  return items;
+}

package/src/contexts/messageReducer.ts

@@ -0,0 +1,401 @@
+import { AgUiMessage, ChatMessage, WebSocketEvent } from "../contracts/backend";
+import {
+  askUserToChatMessage,
+  autoRetryToChatMessage,
+  isAutoRetryStatus,
+  systemMessageToChatMessage,
+} from "./newUiEvents";
+
+/**
+ * AG-UI event → message-list reducer, extracted from SessionContext so both the
+ * live session and the demo replay player fold the same way. Keeping a single
+ * implementation guarantees the replayed conversation is byte-identical to live.
+ */
+
+export function generateUUID(): string {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === "x" ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
+export function createAssistantMessage(agent?: string): ChatMessage {
+  return {
+    id: generateUUID(),
+    role: "assistant",
+    content: "",
+    createdAt: new Date().toISOString(),
+    agent: agent || "principal",
+    streaming: true,
+    kind: "text",
+  };
+}
+
+export function appendAssistantChunk(messages: ChatMessage[], text: string, agent?: string): ChatMessage[] {
+  const last = messages[messages.length - 1];
+  if (last?.role === "assistant" && last.streaming && last.kind === "text") {
+    return [...messages.slice(0, -1), { ...last, content: last.content + text, agent: agent || last.agent }];
+  }
+  return [...messages, { ...createAssistantMessage(agent), content: text }];
+}
+
+export function finalizeAssistant(messages: ChatMessage[]): ChatMessage[] {
+  const last = messages[messages.length - 1];
+  if (last?.role === "assistant" && last.streaming) {
+    return [...messages.slice(0, -1), { ...last, streaming: false }];
+  }
+  return messages;
+}
+
+export function eventSessionId(event: WebSocketEvent): string | undefined {
+  // AG-UI events carry sessionId / threadId at the top level (flat shape).
+  return event.sessionId || event.threadId;
+}
+
+/**
+ * Clear `streaming` on any message still marked in-progress for a finished run.
+ * A START with no matching END (interrupt, mid-run error, dropped END) would
+ * otherwise leave a message stuck at streaming:true, and the activity group
+ * shows "智能体思考中" forever. RUN_FINISHED / RUN_ERROR are the authoritative
+ * terminators: once a run ends, nothing under that agent can still be streaming.
+ * Scoped to `agentName` so a finishing sub-agent never clears another agent's
+ * still-live spinner in a multi-agent run (undefined sweeps all, as a fallback).
+ */
+function sweepStreaming(messages: ChatMessage[], agentName?: string): ChatMessage[] {
+  let changed = false;
+  const next = messages.map((m) => {
+    if (m.streaming && (!agentName || m.agent === agentName)) {
+      changed = true;
+      return { ...m, streaming: false };
+    }
+    return m;
+  });
+  return changed ? next : messages;
+}
+
+/**
+ * Convert an AG-UI message (from MESSAGES_SNAPSHOT) into a UI ChatMessage.
+ */
+export function agUiMessageToChatMessage(msg: AgUiMessage): ChatMessage {
+  const role = msg.role === "user" || msg.role === "system" || msg.role === "tool" ? msg.role : "assistant";
+  let kind: ChatMessage["kind"] = "text";
+  if (msg.role === "reasoning") kind = "thinking";
+  if (msg.role === "tool") kind = "tool";
+  if (msg.error && msg.role === "system") kind = "error";
+  if (msg.kind === "hook" || (msg.hookFamily && msg.role === "system")) kind = "hook";
+  return {
+    id: msg.id,
+    role: role === "tool" ? "assistant" : role,
+    content: msg.content ?? "",
+    createdAt: new Date().toISOString(),
+    agent: role === "user" ? "user" : msg.agentName,
+    streaming: !!msg.unfinished,
+    kind,
+    toolResult: msg.role === "tool" ? msg.content : undefined,
+    toolCallId: msg.toolCallId,
+    reasoning: msg.role === "reasoning" ? msg.content : undefined,
+    hookFamily: msg.hookFamily,
+    hookPhase: msg.hookPhase,
+    hookLevel: msg.hookLevel,
+    hookData: msg.hookData,
+  };
+}
+
+/**
+ * Apply an AG-UI canonical event to the running messages array. Events are
+ * keyed by `messageId` / `toolCallId`; START emits a placeholder, CONTENT
+ * appends delta, END marks completion. MESSAGES_SNAPSHOT replaces state
+ * wholesale.
+ */
+export function reduceMessagesForEvent(existing: ChatMessage[], event: WebSocketEvent): ChatMessage[] {
+  const agent = event.agentName;
+  switch (event.type) {
+    case "MESSAGES_SNAPSHOT": {
+      const messages = Array.isArray(event.messages) ? event.messages : [];
+      // Each AG-UI message may carry `tool_calls[]` nested on an assistant
+      // message (fold.py groups them so `last_assistant_message`'s tool_calls
+      // list grows). Flatten them out as standalone `kind: "tool"` ChatMessages
+      // so views that scan tool calls (Agent network, filters) see them on
+      // refresh, mirroring how live TOOL_CALL_START events would have created
+      // standalone entries.
+      const out: ChatMessage[] = [];
+      for (const m of messages) {
+        out.push(agUiMessageToChatMessage(m));
+        if (Array.isArray(m.toolCalls)) {
+          for (const tc of m.toolCalls) {
+            out.push({
+              id: tc.id,
+              role: "assistant",
+              content: `Tool: ${tc.name ?? "unknown"}`,
+              createdAt: new Date().toISOString(),
+              agent: m.agentName,
+              streaming: false,
+              kind: "tool",
+              toolName: tc.name,
+              toolInput: tc.arguments ?? "",
+            });
+          }
+        }
+      }
+      return out;
+    }
+
+    case "TEXT_MESSAGE_START": {
+      const id = event.messageId;
+      if (!id || existing.some((m) => m.id === id)) {
+        return existing;
+      }
+      const role = event.role === "user" || event.role === "system" ? event.role : "assistant";
+      return [
+        ...existing,
+        {
+          id,
+          role,
+          content: "",
+          createdAt: new Date().toISOString(),
+          agent,
+          streaming: true,
+          kind: "text",
+        },
+      ];
+    }
+
+    case "TEXT_MESSAGE_CONTENT": {
+      const id = event.messageId;
+      let delta = typeof event.delta === "string" ? event.delta : "";
+      if (!id || !delta) return existing;
+      // Strip NO-RENDER wrapper used by record_trace "Message Complete" hint
+      delta = delta.replace(/<!--NO-RENDER-->[\s\S]*?<!--\/NO-RENDER-->/g, "");
+      if (!delta) return existing;
+      return existing.map((m) =>
+        m.id === id ? { ...m, content: (m.content ?? "") + delta } : m,
+      );
+    }
+
+    case "TEXT_MESSAGE_END": {
+      const id = event.messageId;
+      if (!id) return existing;
+      // Drop messages whose entire content was a NO-RENDER wrapper
+      return existing
+        .filter((m) => !(m.id === id && (m.content ?? "").trim() === ""))
+        .map((m) => (m.id === id ? { ...m, streaming: false } : m));
+    }
+
+    case "TEXT_MESSAGE_CHUNK": {
+      // Atomic message — created and completed in one step.
+      const id = event.messageId;
+      if (!id || existing.some((m) => m.id === id)) {
+        return existing;
+      }
+      const role = event.role === "assistant" || event.role === "system" ? event.role : "user";
+      return [
+        ...existing,
+        {
+          id,
+          role,
+          content: typeof event.delta === "string" ? event.delta : "",
+          createdAt: new Date().toISOString(),
+          agent: role === "user" ? "user" : agent,
+          streaming: false,
+          kind: "text",
+        },
+      ];
+    }
+
+    case "TOOL_CALL_START": {
+      const id = event.toolCallId;
+      if (!id || existing.some((m) => m.id === id)) {
+        return existing;
+      }
+      return [
+        ...existing,
+        {
+          id,
+          role: "assistant",
+          content: `Tool: ${event.toolCallName ?? "unknown"}`,
+          createdAt: new Date().toISOString(),
+          agent,
+          streaming: true,
+          kind: "tool",
+          toolName: event.toolCallName,
+          toolInput: "",
+        },
+      ];
+    }
+
+    case "TOOL_CALL_ARGS": {
+      const id = event.toolCallId;
+      const delta = typeof event.delta === "string" ? event.delta : "";
+      if (!id || !delta) return existing;
+      return existing.map((m) =>
+        m.id === id ? { ...m, toolInput: ((m.toolInput as string) ?? "") + delta } : m,
+      );
+    }
+
+    case "TOOL_CALL_END": {
+      const id = event.toolCallId;
+      if (!id) return existing;
+      return existing.map((m) => (m.id === id ? { ...m, streaming: false } : m));
+    }
+
+    case "TOOL_CALL_RESULT": {
+      const id = event.messageId;
+      const content = typeof event.content === "string" ? event.content : "";
+      if (!id || existing.some((m) => m.id === id)) {
+        return existing;
+      }
+      return [
+        ...existing,
+        {
+          id,
+          role: "assistant",
+          content: "Tool result",
+          createdAt: new Date().toISOString(),
+          agent,
+          kind: "tool",
+          toolResult: content,
+        },
+      ];
+    }
+
+    case "REASONING_MESSAGE_START": {
+      const id = event.messageId;
+      if (!id || existing.some((m) => m.id === id)) return existing;
+      return [
+        ...existing,
+        {
+          id,
+          role: "assistant",
+          content: "",
+          createdAt: new Date().toISOString(),
+          agent,
+          streaming: true,
+          kind: "thinking",
+          reasoning: "",
+        },
+      ];
+    }
+
+    case "REASONING_MESSAGE_CONTENT": {
+      const id = event.messageId;
+      const delta = typeof event.delta === "string" ? event.delta : "";
+      if (!id || !delta) return existing;
+      return existing.map((m) =>
+        m.id === id
+          ? { ...m, content: (m.content ?? "") + delta, reasoning: (m.reasoning ?? "") + delta }
+          : m,
+      );
+    }
+
+    case "REASONING_MESSAGE_END": {
+      const id = event.messageId;
+      if (!id) return existing;
+      return existing.map((m) => (m.id === id ? { ...m, streaming: false } : m));
+    }
+
+    case "RUN_ERROR": {
+      const message = event.message ?? "Run error";
+      // Run is over → sweep any dangling streaming flag before appending error.
+      const swept = sweepStreaming(existing, event.agentName);
+      return [
+        ...swept,
+        {
+          id: generateUUID(),
+          role: "system",
+          content: String(message),
+          createdAt: new Date().toISOString(),
+          kind: "error",
+        },
+      ];
+    }
+
+    // 修正6 — system_message: 4-level styled bubble in the conversation stream.
+    case "system_message": {
+      return [...existing, systemMessageToChatMessage(event)];
+    }
+
+    // 修正6 — user_input_request (ask_user): interactive card. Keyed by
+    // requestId so a duplicate re-emit doesn't stack a second card.
+    case "user_input_request": {
+      const msg = askUserToChatMessage(event);
+      if (existing.some((m) => m.id === msg.id)) return existing;
+      return [...existing, msg];
+    }
+
+    // 修正6 — user_input_response: echo of the submitted answer. Resolve the
+    // matching ask_user card (renders as answered) rather than adding a row.
+    case "user_input_response": {
+      const e = event as Record<string, unknown>;
+      const requestId = String(e.requestId ?? e.request_id ?? "");
+      const answer = String(e.answer ?? "");
+      if (!requestId) return existing;
+      return existing.map((m) =>
+        m.kind === "ask_user" && m.askUser?.requestId === requestId
+          ? { ...m, askUser: { ...m.askUser, answer } }
+          : m,
+      );
+    }
+
+    // 修正6 — auto-retry: Pi auto_retry_start surfaces as an
+    // agent_status_update (status retrying) carrying attempt/maxAttempts/delayMs.
+    case "agent_status_update": {
+      if (isAutoRetryStatus(event)) {
+        return [...existing, autoRetryToChatMessage(event)];
+      }
+      return existing;
+    }
+
+    // RUN_FINISHED is the authoritative end of a run: sweep any message left
+    // streaming because its END never arrived (interrupt / dropped END), so the
+    // "thinking" spinner reliably clears.
+    case "RUN_FINISHED":
+      return sweepStreaming(existing, event.agentName);
+
+    // Lifecycle / brackets / extensions — no message-list change
+    case "RUN_STARTED":
+    case "REASONING_START":
+    case "REASONING_END":
+      return existing;
+    case "CUSTOM": {
+      const name = (event as any).name;
+      // Hook diagnostic — surface as a small system entry in the message
+      // stream so users can see tracker resets, flag flips, reminders, and
+      // fallback fires alongside conversation events.
+      if (name === "hook_event") {
+        const value = ((event as any).value ?? {}) as {
+          hook?: string;
+          phase?: string;
+          level?: string;
+          message?: string;
+          agent_name?: string;
+          data?: Record<string, unknown>;
+        };
+        const id = `hook-${(event as any).timestamp ?? Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        return [
+          ...existing,
+          {
+            id,
+            role: "system",
+            content: value.message ?? "(hook event)",
+            createdAt: new Date().toISOString(),
+            agent: value.agent_name,
+            streaming: false,
+            kind: "hook",
+            hookFamily: value.hook,
+            hookPhase: value.phase,
+            hookLevel: value.level,
+            hookData: value.data,
+          },
+        ];
+      }
+      return existing;
+    }
+    case "PING":
+    default:
+      return existing;
+  }
+}

package/src/contexts/newUiEvents.ts

@@ -0,0 +1,190 @@
+import type {
+  AskUserView,
+  AutoRetryView,
+  ChatMessage,
+  SystemMessageView,
+  WebSocketEvent,
+} from "../contracts/backend";
+import { generateUUID } from "./messageReducer";
+
+/**
+ * 修正6 — event → view-model mapping for the three new UI features
+ * (system_message bubble, ask_user card, auto-retry countdown).
+ *
+ * Kept as pure functions (no React, no DOM) so the mapping is unit-testable in
+ * isolation. The reducer in messageReducer.ts calls these to fold the new
+ * AG-UI events into the ChatMessage stream, consistently with the existing
+ * event handling.
+ *
+ * Events arrive post-`normalizeAgUiEvent`, which camelizes every wire key. So a
+ * wire `request_id` is read here as `requestId`, `allow_free_text` as
+ * `allowFreeText`, etc. We still tolerate the snake_case originals as a
+ * fallback in case an event bypassed normalization.
+ */
+
+function str(value: unknown, fallback = ""): string {
+  return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+
+function optStr(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function num(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+/** Map a `system_message` event to its view-model. */
+export function toSystemMessageView(event: WebSocketEvent): SystemMessageView {
+  const e = event as Record<string, unknown>;
+  const rawLevel = str(e.level, "info");
+  const level: SystemMessageView["level"] =
+    rawLevel === "warning" || rawLevel === "error" || rawLevel === "fatal" ? rawLevel : "info";
+  // `recoverable` defaults to false for fatal, true otherwise, when the wire
+  // omits it.
+  const recoverable =
+    typeof e.recoverable === "boolean" ? e.recoverable : level !== "fatal";
+  return {
+    level,
+    message: str(e.message),
+    details: optStr(e.details),
+    agent: optStr(e.agent) ?? optStr(e.agentName),
+    recoverable,
+    timestamp: optStr(e.timestamp),
+  };
+}
+
+/** Map a `user_input_request` event to the ask_user card view-model. */
+export function toAskUserView(event: WebSocketEvent): AskUserView {
+  const e = event as Record<string, unknown>;
+  const options = Array.isArray(e.options)
+    ? (e.options as unknown[]).filter((o): o is string => typeof o === "string")
+    : undefined;
+  return {
+    requestId: str(e.requestId ?? e.request_id),
+    agent: str(e.agent ?? e.agentName, "principal"),
+    question: str(e.question),
+    options: options && options.length > 0 ? options : undefined,
+    allowFreeText:
+      typeof (e.allowFreeText ?? e.allow_free_text) === "boolean"
+        ? (e.allowFreeText ?? e.allow_free_text) as boolean
+        : undefined,
+    timeoutSec: typeof (e.timeoutSec ?? e.timeout_sec) === "number"
+      ? (e.timeoutSec ?? e.timeout_sec) as number
+      : undefined,
+  };
+}
+
+/**
+ * Map an auto-retry indicator to its view-model. Pi's `auto_retry_start`
+ * surfaces as an `agent_status_update` (status `retrying`) carrying
+ * attempt/maxAttempts/delayMs, mirrored by a `system_message`. We read whichever
+ * fields are present, tolerating camel/snake casing.
+ */
+export function toAutoRetryView(event: WebSocketEvent): AutoRetryView {
+  const e = event as Record<string, unknown>;
+  // The retry detail may be nested under `data` / `value` / `autoRetry`.
+  const nested =
+    (e.autoRetry as Record<string, unknown> | undefined) ??
+    (e.data as Record<string, unknown> | undefined) ??
+    (e.value as Record<string, unknown> | undefined) ??
+    e;
+  return {
+    attempt: num(nested.attempt, 1),
+    maxAttempts: num(nested.maxAttempts ?? nested.max_attempts, 1),
+    delayMs: num(nested.delayMs ?? nested.delay_ms, 0),
+    reason: optStr(nested.reason) ?? optStr(e.message),
+  };
+}
+
+/** True iff this `agent_status_update` represents an auto-retry start. */
+export function isAutoRetryStatus(event: WebSocketEvent): boolean {
+  const e = event as Record<string, unknown>;
+  if (e.type !== "agent_status_update") return false;
+  const status = str(e.status ?? (e as { runStatus?: string }).runStatus).toLowerCase();
+  // Pi auto_retry_start surfaces with a retrying/auto_retry status marker, or an
+  // explicit autoRetry payload.
+  if (status === "retrying" || status === "auto_retry" || status === "auto_retry_start") {
+    return true;
+  }
+  return Boolean(e.autoRetry ?? e.auto_retry);
+}
+
+/** Build the `system_message` ChatMessage. */
+export function systemMessageToChatMessage(event: WebSocketEvent): ChatMessage {
+  const view = toSystemMessageView(event);
+  const e = event as Record<string, unknown>;
+  return {
+    id: str(e.id ?? e.messageId) || `sysmsg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    role: "system",
+    content: view.message,
+    createdAt: view.timestamp ?? new Date().toISOString(),
+    agent: view.agent,
+    streaming: false,
+    kind: "system_message",
+    systemMessage: view,
+  };
+}
+
+/** Build the `ask_user` ChatMessage. Keyed by requestId so it can be resolved. */
+export function askUserToChatMessage(event: WebSocketEvent): ChatMessage {
+  const view = toAskUserView(event);
+  return {
+    id: view.requestId ? `ask-${view.requestId}` : generateUUID(),
+    role: "system",
+    content: view.question,
+    createdAt: new Date().toISOString(),
+    agent: view.agent,
+    streaming: false,
+    kind: "ask_user",
+    askUser: view,
+  };
+}
+
+/** Build the `auto_retry` ChatMessage from an auto-retry status update. */
+export function autoRetryToChatMessage(event: WebSocketEvent): ChatMessage {
+  const view = toAutoRetryView(event);
+  const e = event as Record<string, unknown>;
+  return {
+    id: `retry-${str(e.agentName, "agent")}-${view.attempt}-${Date.now()}`,
+    role: "system",
+    content: view.reason ?? `Retrying (attempt ${view.attempt}/${view.maxAttempts})`,
+    createdAt: new Date().toISOString(),
+    agent: optStr(e.agentName),
+    streaming: false,
+    kind: "auto_retry",
+    autoRetry: view,
+  };
+}
+
+// ── Pure interaction helpers (shared by the components; testable w/o a DOM) ──
+
+/**
+ * Resolve an ask_user submission. Returns the `{ requestId, answer }` to send,
+ * or `null` when the input is empty or the card is no longer accepting input
+ * (already answered / timed out). The trimmed answer is what gets sent.
+ */
+export function resolveAskUserSubmission(
+  view: AskUserView,
+  rawAnswer: string,
+  opts: { answered?: boolean; timedOut?: boolean } = {},
+): { requestId: string; answer: string } | null {
+  if (opts.answered || opts.timedOut) return null;
+  const answer = rawAnswer.trim();
+  if (!answer || !view.requestId) return null;
+  return { requestId: view.requestId, answer };
+}
+
+/** Whether an ask_user card should still show interactive inputs. */
+export function isAskUserOpen(
+  view: AskUserView,
+  opts: { timedOut?: boolean } = {},
+): boolean {
+  return view.answer === undefined && !opts.timedOut;
+}
+
+/** Initial countdown (whole seconds) for an auto-retry from its delayMs. */
+export function autoRetryCountdownSeconds(view: AutoRetryView): number {
+  return view.delayMs > 0 ? Math.ceil(view.delayMs / 1000) : 0;
+}
+