Add files using upload-large-folder tool

src/components/browser/index.ts

@@ -0,0 +1,3 @@
+export { BrowserPanel } from "../features/browser/browser";
+export { BrowserSnapshot } from "../features/browser/browser-snapshot";
+export { EmptyBrowserMessage } from "../features/browser/empty-browser-message";

src/components/conversation-events/chat/event-content-helpers/create-skill-ready-event.ts

@@ -0,0 +1,60 @@
+import { MessageEvent } from "#/types/agent-server/core";
+import { BaseEvent } from "#/types/agent-server/core/base/event";
+import {
+  getSkillReadyContent,
+  getSkillReadyItems,
+  SkillReadyItem,
+} from "./get-skill-ready-content";
+
+export type { SkillReadyItem };
+
+/**
+ * Synthetic event type for Skill Ready events.
+ * This extends BaseEvent and includes a marker to identify it as a skill ready event.
+ */
+export interface SkillReadyEvent extends BaseEvent {
+  _isSkillReadyEvent: true;
+  _skillReadyContent: string;
+  _skillReadyItems: SkillReadyItem[];
+}
+
+/**
+ * Type guard for Skill Ready events.
+ */
+export const isSkillReadyEvent = (event: unknown): event is SkillReadyEvent =>
+  typeof event === "object" &&
+  event !== null &&
+  "_isSkillReadyEvent" in event &&
+  event._isSkillReadyEvent === true;
+
+/**
+ * Creates a synthetic "Skill Ready" event from a user MessageEvent.
+ * This event appears as originating from the agent and contains formatted
+ * information about activated skills and extended content.
+ */
+export const createSkillReadyEvent = (
+  userEvent: MessageEvent,
+): SkillReadyEvent => {
+  const activatedSkills = userEvent.activated_skills || [];
+
+  const extendedContent = userEvent.extended_content || [];
+
+  // Only create event if we have skills or extended content
+  if (activatedSkills.length === 0 && extendedContent.length === 0) {
+    throw new Error(
+      "Cannot create skill ready event without activated skills or extended content",
+    );
+  }
+
+  const content = getSkillReadyContent(activatedSkills, extendedContent);
+  const items = getSkillReadyItems(activatedSkills, extendedContent);
+
+  return {
+    id: `${userEvent.id}-skill-ready`,
+    timestamp: userEvent.timestamp,
+    source: "agent",
+    _isSkillReadyEvent: true,
+    _skillReadyContent: content,
+    _skillReadyItems: items,
+  };
+};

src/components/conversation-events/chat/event-content-helpers/get-acp-tool-call-content.ts

@@ -0,0 +1,132 @@
+import { ACPToolCallEvent } from "#/types/agent-server/core/events/acp-tool-call-event";
+import i18n from "#/i18n";
+import { MAX_CONTENT_LENGTH } from "./shared";
+import { I18nKey } from "#/i18n/declaration";
+
+/**
+ * Pick the translation key used for the ACP tool call title row. Mirrors
+ * ACTION_MESSAGE$RUN / $EDIT / $READ etc.
+ */
+export const getACPToolCallTitleKey = (event: ACPToolCallEvent): string => {
+  switch (event.tool_kind) {
+    case "execute":
+      return "ACTION_MESSAGE$ACP_RUN";
+    case "edit":
+      return "ACTION_MESSAGE$ACP_EDIT";
+    case "read":
+      return "ACTION_MESSAGE$ACP_READ";
+    case "fetch":
+      return "ACTION_MESSAGE$ACP_FETCH";
+    default:
+      return "ACTION_MESSAGE$ACP_TOOL";
+  }
+};
+
+// English verb prefixes ACP servers sometimes inline into the title.
+// Claude Code emits ``"Read /Users/foo/bar"`` for a read tool — combined
+// with the i18n template ``"Reading <cmd>{{title}}</cmd>"`` that lands as
+// ``"Reading Read /Users/foo/bar"``. The redundant leading verb is the
+// part we strip; the template's own verb (which is i18n'd) stays.
+//
+// Keyed by ``tool_kind`` so the strip is scoped to where double-verbing
+// actually shows up. The english-only check is intentional — ACP servers
+// are anglophone tools and emit english titles regardless of the user's
+// canvas locale; matching translated verbs would mean every locale's
+// strip list goes stale the moment a new server is added.
+const REDUNDANT_TITLE_PREFIXES: Partial<Record<string, readonly string[]>> = {
+  read: ["Read"],
+  edit: ["Edit", "Write"],
+  execute: ["Bash", "Run"],
+  fetch: ["Fetch", "WebFetch"],
+};
+
+/**
+ * Strip a leading verb from ``event.title`` that would duplicate the
+ * verb baked into the i18n template (see ``REDUNDANT_TITLE_PREFIXES``).
+ *
+ * The match is anchored, case-sensitive, and requires the prefix to be
+ * followed by whitespace so a token like ``"Reads"`` (an actual verb
+ * elsewhere in the title) is left alone. If no prefix matches, the title
+ * is returned verbatim.
+ */
+export const stripRedundantTitlePrefix = (event: ACPToolCallEvent): string => {
+  const title = event.title;
+  const tool_kind = event.tool_kind;
+  if (!title || !tool_kind) return title;
+  const prefixes = REDUNDANT_TITLE_PREFIXES[tool_kind];
+  if (!prefixes) return title;
+  for (const prefix of prefixes) {
+    if (
+      title.length > prefix.length &&
+      title.startsWith(prefix) &&
+      /\s/.test(title.charAt(prefix.length))
+    ) {
+      return title.slice(prefix.length).trimStart();
+    }
+  }
+  return title;
+};
+
+/**
+ * Stringify an arbitrary raw_input / raw_output payload for markdown
+ * rendering. Strings pass through; objects are pretty-printed JSON.
+ */
+const stringifyPayload = (value: unknown): string => {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+};
+
+const truncate = (content: string): string =>
+  content.length > MAX_CONTENT_LENGTH
+    ? `${content.slice(0, MAX_CONTENT_LENGTH)}...`
+    : content;
+
+/**
+ * Build the markdown-flavored body for an ACP tool call card. Mirrors the
+ * shape of ``getTerminalObservationContent`` (``Command:`` + ``Output:``
+ * fenced blocks) so the rendered card lines up with regular OpenHands
+ * observations.
+ *
+ * For ``tool_kind === "execute"`` we surface ``raw_input.command`` as the
+ * command line; for others we fall back to a pretty-printed JSON dump of
+ * the input. Output is always dumped as a fenced block, with the same
+ * "(no output)" fallback copy used by the bash observation renderer.
+ */
+export const getACPToolCallContent = (event: ACPToolCallEvent): string => {
+  const toolKind = event.tool_kind;
+  const rawInput = event.raw_input;
+  const rawOutput = event.raw_output;
+  const isError = event.is_error;
+
+  let output = "";
+
+  // Input block — command for execute, JSON dump otherwise.
+  if (
+    toolKind === "execute" &&
+    rawInput &&
+    typeof rawInput === "object" &&
+    "command" in rawInput &&
+    typeof (rawInput as { command: unknown }).command === "string"
+  ) {
+    const { command } = rawInput as { command: string };
+    output += `Command: \`${command}\`\n\n`;
+  } else if (rawInput !== null && rawInput !== undefined && rawInput !== "") {
+    const inputStr = stringifyPayload(rawInput);
+    if (inputStr.trim()) {
+      output += `Input:\n\`\`\`json\n${inputStr}\n\`\`\`\n\n`;
+    }
+  }
+
+  // Output block — matches the bash observation layout exactly.
+  const outputStr = truncate(stringifyPayload(rawOutput).trim());
+  const outputLabel = isError ? "**Error:**" : "Output:";
+  const outputBody = outputStr || i18n.t(I18nKey.OBSERVATION$COMMAND_NO_OUTPUT);
+  output += `${outputLabel}\n\`\`\`\n${outputBody}\n\`\`\``;
+
+  return output;
+};

src/components/conversation-events/chat/event-content-helpers/get-action-content.ts

@@ -0,0 +1,269 @@
+import { ActionEvent } from "#/types/agent-server/core";
+import { getDefaultEventContent, MAX_CONTENT_LENGTH } from "./shared";
+import i18n from "#/i18n";
+import { SecurityRisk } from "#/types/agent-server/core/base/common";
+import { I18nKey } from "#/i18n/declaration";
+import {
+  ExecuteBashAction,
+  TerminalAction,
+  FileEditorAction,
+  StrReplaceEditorAction,
+  MCPToolAction,
+  ThinkAction,
+  FinishAction,
+  TaskTrackerAction,
+  BrowserNavigateAction,
+  BrowserClickAction,
+  BrowserTypeAction,
+  BrowserGetStateAction,
+  BrowserGetContentAction,
+  BrowserScrollAction,
+  BrowserGoBackAction,
+  BrowserListTabsAction,
+  BrowserSwitchTabAction,
+  BrowserCloseTabAction,
+  GlobAction,
+  GrepAction,
+  InvokeSkillAction,
+} from "#/types/agent-server/core/base/action";
+
+const getRiskText = (risk: SecurityRisk) => {
+  switch (risk) {
+    case SecurityRisk.LOW:
+      return i18n.t(I18nKey.SECURITY$LOW_RISK);
+    case SecurityRisk.MEDIUM:
+      return i18n.t(I18nKey.SECURITY$MEDIUM_RISK);
+    case SecurityRisk.HIGH:
+      return i18n.t(I18nKey.SECURITY$HIGH_RISK);
+    case SecurityRisk.UNKNOWN:
+    default:
+      return i18n.t(I18nKey.SECURITY$UNKNOWN_RISK);
+  }
+};
+
+const getNoContentActionContent = (): string => "";
+
+// Invoke-skill actions
+const getInvokeSkillActionContent = (action: InvokeSkillAction): string =>
+  action.name ? `**Skill:** \`${action.name}\`` : getNoContentActionContent();
+
+// Grep/Glob search actions
+const getSearchActionContent = (
+  event: ActionEvent<GlobAction | GrepAction>,
+): string => {
+  const { action } = event;
+  const parts: string[] = [];
+  if (action.pattern) {
+    parts.push(`**Pattern:** \`${action.pattern}\``);
+  }
+  if (action.path) {
+    parts.push(`**Path:** \`${action.path}\``);
+  }
+  if ("include" in action && action.include) {
+    parts.push(`**Include:** \`${action.include}\``);
+  }
+  return parts.length > 0 ? parts.join("\n") : getNoContentActionContent();
+};
+
+// File Editor Actions
+const getFileEditorActionContent = (
+  action: FileEditorAction | StrReplaceEditorAction,
+): string => {
+  // Early return if not a create command or no file text
+  if (action.command !== "create" || !action.file_text) {
+    return getNoContentActionContent();
+  }
+
+  // Process file text with length truncation
+  let fileText = action.file_text;
+  if (fileText.length > MAX_CONTENT_LENGTH) {
+    fileText = `${fileText.slice(0, MAX_CONTENT_LENGTH)}...`;
+  }
+
+  return `${action.path}\n${fileText}`;
+};
+
+// Command Actions
+const getExecuteBashActionContent = (
+  event: ActionEvent<ExecuteBashAction | TerminalAction>,
+): string => {
+  let content = `Command:\n\`${event.action.command}\``;
+
+  // Add security risk information if it's HIGH or MEDIUM
+  if (
+    event.security_risk === SecurityRisk.HIGH ||
+    event.security_risk === SecurityRisk.MEDIUM
+  ) {
+    content += `\n\n${getRiskText(event.security_risk)}`;
+  }
+
+  return content;
+};
+
+// Tool Actions
+const getMCPToolActionContent = (action: MCPToolAction): string => {
+  // For V1, the tool name is in the event's tool_name property, not in the action
+  let details = `**MCP Tool Call**\n\n`;
+  details += `**Arguments:**\n\`\`\`json\n${JSON.stringify(action.data, null, 2)}\n\`\`\``;
+  return details;
+};
+
+// Simple Actions
+const getThinkActionContent = (action: ThinkAction): string => action.thought;
+
+const getFinishActionContent = (action: FinishAction): string =>
+  action.message.trim();
+
+// Complex Actions
+const getTaskTrackerActionContent = (action: TaskTrackerAction): string => {
+  let content = `**Command:** \`${action.command}\``;
+
+  // Handle plan command with task list
+  if (action.command === "plan") {
+    if (action.task_list && action.task_list.length > 0) {
+      content += `\n\n**Task List (${action.task_list.length} ${action.task_list.length === 1 ? "item" : "items"}):**\n`;
+      action.task_list.forEach((task, index: number) => {
+        const statusMap = {
+          todo: "⏳",
+          in_progress: "🔄",
+          done: "✅",
+        };
+        const statusIcon =
+          statusMap[task.status as keyof typeof statusMap] || "❓";
+        content += `\n${index + 1}. ${statusIcon} **[${task.status.toUpperCase().replace("_", " ")}]** ${task.title}`;
+        if (task.notes) {
+          content += `\n   *Notes: ${task.notes}*`;
+        }
+      });
+    } else {
+      content += "\n\n**Task List:** Empty";
+    }
+  }
+
+  return content;
+};
+
+// Browser Actions
+type BrowserAction =
+  | BrowserNavigateAction
+  | BrowserClickAction
+  | BrowserTypeAction
+  | BrowserGetStateAction
+  | BrowserGetContentAction
+  | BrowserScrollAction
+  | BrowserGoBackAction
+  | BrowserListTabsAction
+  | BrowserSwitchTabAction
+  | BrowserCloseTabAction;
+
+const getBrowserActionContent = (action: BrowserAction): string => {
+  switch (action.kind) {
+    case "BrowserNavigateAction": {
+      let content = `Browsing ${action.url}`;
+      if (action.new_tab) {
+        content += `\n**New Tab:** Yes`;
+      }
+      return content;
+    }
+    case "BrowserClickAction": {
+      let content = `**Element Index:** ${action.index}`;
+      if (action.new_tab) {
+        content += `\n**New Tab:** Yes`;
+      }
+      return content;
+    }
+    case "BrowserTypeAction": {
+      const textPreview =
+        action.text.length > 50
+          ? `${action.text.slice(0, 50)}...`
+          : action.text;
+      return `**Element Index:** ${action.index}\n**Text:** ${textPreview}`;
+    }
+    case "BrowserGetStateAction": {
+      if (action.include_screenshot) {
+        return `**Include Screenshot:** Yes`;
+      }
+      return getNoContentActionContent();
+    }
+    case "BrowserGetContentAction": {
+      const parts: string[] = [];
+      if (action.extract_links) {
+        parts.push(`**Extract Links:** Yes`);
+      }
+      if (action.start_from_char > 0) {
+        parts.push(`**Start From Character:** ${action.start_from_char}`);
+      }
+      return parts.length > 0 ? parts.join("\n") : getNoContentActionContent();
+    }
+    case "BrowserScrollAction": {
+      return `**Direction:** ${action.direction}`;
+    }
+    case "BrowserGoBackAction": {
+      return getNoContentActionContent();
+    }
+    case "BrowserListTabsAction": {
+      return getNoContentActionContent();
+    }
+    case "BrowserSwitchTabAction": {
+      return `**Tab ID:** ${action.tab_id}`;
+    }
+    case "BrowserCloseTabAction": {
+      return `**Tab ID:** ${action.tab_id}`;
+    }
+    default:
+      return getNoContentActionContent();
+  }
+};
+
+export const getActionContent = (event: ActionEvent): string => {
+  const { action } = event;
+  const actionType = action.kind;
+
+  switch (actionType) {
+    case "FileEditorAction":
+    case "StrReplaceEditorAction":
+      return getFileEditorActionContent(action);
+
+    case "ExecuteBashAction":
+    case "TerminalAction":
+      return getExecuteBashActionContent(
+        event as ActionEvent<ExecuteBashAction | TerminalAction>,
+      );
+
+    case "MCPToolAction":
+      return getMCPToolActionContent(action);
+
+    case "ThinkAction":
+      return getThinkActionContent(action);
+
+    case "FinishAction":
+      return getFinishActionContent(action);
+
+    case "TaskTrackerAction":
+      return getTaskTrackerActionContent(action);
+
+    case "BrowserNavigateAction":
+    case "BrowserClickAction":
+    case "BrowserTypeAction":
+    case "BrowserGetStateAction":
+    case "BrowserGetContentAction":
+    case "BrowserScrollAction":
+    case "BrowserGoBackAction":
+    case "BrowserListTabsAction":
+    case "BrowserSwitchTabAction":
+    case "BrowserCloseTabAction":
+      return getBrowserActionContent(action);
+
+    case "GrepAction":
+    case "GlobAction":
+      return getSearchActionContent(
+        event as ActionEvent<GlobAction | GrepAction>,
+      );
+
+    case "InvokeSkillAction":
+      return getInvokeSkillActionContent(action as InvokeSkillAction);
+
+    default:
+      return getDefaultEventContent(event);
+  }
+};

src/components/conversation-events/chat/event-content-helpers/get-action-event-title.ts

@@ -0,0 +1,147 @@
+import { CANVAS_UI_CLIENT_ACTION_KIND } from "#/constants/canvas-ui";
+import { LAUNCH_CHILD_CONVERSATION_ACTION_KIND } from "#/constants/child-conversation";
+import type { ActionEvent } from "#/types/agent-server/core";
+
+export type EventTitleDescriptor =
+  | {
+      readonly kind: "translation";
+      readonly key: string;
+      readonly values: Readonly<Record<string, unknown>>;
+    }
+  | {
+      readonly kind: "text";
+      readonly text: string;
+    };
+
+export const trimEventTitleText = (text: string, maxLength: number): string => {
+  if (!text) return "";
+  return text.length > maxLength ? `${text.substring(0, maxLength)}...` : text;
+};
+
+const isServerFallbackSummary = (summary: string): boolean =>
+  /^[a-z][a-z0-9_]*\s*:\s*[[{]/i.test(summary);
+
+export const getActionSummaryTitle = (event: ActionEvent): string | null => {
+  const summary = event.summary?.trim().replace(/\s+/g, " ") || "";
+  return !summary || isServerFallbackSummary(summary) ? null : summary;
+};
+
+export const getActionEventTitleDescriptor = (
+  event: ActionEvent,
+): EventTitleDescriptor => {
+  const summary = getActionSummaryTitle(event);
+  if (summary) {
+    return { kind: "text", text: summary };
+  }
+
+  const actionType = event.action.kind;
+
+  switch (actionType) {
+    case "ExecuteBashAction":
+    case "TerminalAction":
+      return {
+        kind: "translation",
+        key: "ACTION_MESSAGE$RUN",
+        values: { command: trimEventTitleText(event.action.command, 80) },
+      };
+    case "FileEditorAction":
+    case "StrReplaceEditorAction": {
+      const key =
+        event.action.command === "view"
+          ? "ACTION_MESSAGE$READ"
+          : event.action.command === "create"
+            ? "ACTION_MESSAGE$WRITE"
+            : "ACTION_MESSAGE$EDIT";
+      return {
+        kind: "translation",
+        key,
+        values: { path: event.action.path },
+      };
+    }
+    case "MCPToolAction":
+      return {
+        kind: "translation",
+        key: "ACTION_MESSAGE$CALL_TOOL_MCP",
+        values: { mcp_tool_name: event.tool_name },
+      };
+    case "InvokeSkillAction":
+      return {
+        kind: "translation",
+        key: "ACTION_MESSAGE$INVOKE_SKILL",
+        values: { name: event.action.name },
+      };
+    case "TaskAction":
+      return {
+        kind: "translation",
+        key: "ACTION_MESSAGE$TASK",
+        values: { name: event.action.subagent_type },
+      };
+    case "ThinkAction":
+      return {
+        kind: "translation",
+        key: "ACTION_MESSAGE$THINK",
+        values: {},
+      };
+    case "FinishAction":
+      return {
+        kind: "translation",
+        key: "ACTION_MESSAGE$FINISH",
+        values: {},
+      };
+    case "TaskTrackerAction":
+      return {
+        kind: "translation",
+        key: "ACTION_MESSAGE$TASK_TRACKING",
+        values: {},
+      };
+    case "GrepAction":
+      return {
+        kind: "translation",
+        key: "ACTION_MESSAGE$GREP",
+        values: {
+          pattern: event.action.pattern
+            ? trimEventTitleText(event.action.pattern, 50)
+            : "",
+        },
+      };
+    case "GlobAction":
+      return {
+        kind: "translation",
+        key: "ACTION_MESSAGE$GLOB",
+        values: {
+          pattern: event.action.pattern
+            ? trimEventTitleText(event.action.pattern, 50)
+            : "",
+        },
+      };
+    case "BrowserNavigateAction":
+    case "BrowserClickAction":
+    case "BrowserTypeAction":
+    case "BrowserGetStateAction":
+    case "BrowserGetContentAction":
+    case "BrowserScrollAction":
+    case "BrowserGoBackAction":
+    case "BrowserListTabsAction":
+    case "BrowserSwitchTabAction":
+    case "BrowserCloseTabAction":
+      return {
+        kind: "translation",
+        key: "ACTION_MESSAGE$BROWSE",
+        values: {},
+      };
+    case "CanvasUIAction":
+    case CANVAS_UI_CLIENT_ACTION_KIND:
+      return { kind: "text", text: "CANVASUI" };
+    case LAUNCH_CHILD_CONVERSATION_ACTION_KIND:
+      return {
+        kind: "translation",
+        key: "ACTION_MESSAGE$LAUNCH_CHILD_CONVERSATION",
+        values: {},
+      };
+    default:
+      return {
+        kind: "text",
+        text: String(actionType).replace("Action", "").toUpperCase(),
+      };
+  }
+};

src/components/conversation-events/chat/event-content-helpers/get-event-content.tsx

@@ -0,0 +1,370 @@
+import { Trans } from "react-i18next";
+import React from "react";
+import { CANVAS_UI_CLIENT_TOOL_NAME } from "#/constants/canvas-ui";
+import { LAUNCH_CHILD_CONVERSATION_TOOL_NAME } from "#/constants/child-conversation";
+import {
+  OpenHandsEvent,
+  ObservationEvent,
+  ActionEvent,
+} from "#/types/agent-server/core";
+import {
+  isActionEvent,
+  isObservationEvent,
+  isACPToolCallEvent,
+  isCanvasUIActionEvent,
+} from "#/types/agent-server/type-guards";
+import { MonoComponent } from "../../../features/chat/mono-component";
+import { PathComponent } from "../../../features/chat/path-component";
+import { getActionContent } from "./get-action-content";
+import { getObservationContent } from "./get-observation-content";
+import {
+  getACPToolCallContent,
+  getACPToolCallTitleKey,
+  stripRedundantTitlePrefix,
+} from "./get-acp-tool-call-content";
+import { TaskTrackingObservationContent } from "../task-tracking/task-tracking-observation-content";
+import { TaskTrackerObservation } from "#/types/agent-server/core/base/observation";
+import { SkillReadyEvent, isSkillReadyEvent } from "./create-skill-ready-event";
+import { resolveVisualizerBody } from "../../../features/chat/tool-visualizers/dispatcher";
+import i18n from "#/i18n";
+import { I18nKey } from "#/i18n/declaration";
+import {
+  getActionEventTitleDescriptor,
+  getActionSummaryTitle,
+  trimEventTitleText,
+  type EventTitleDescriptor,
+} from "./get-action-event-title";
+
+// Helper function to create title from translation key
+const createTitleFromKey = (
+  key: string,
+  values: Readonly<Record<string, unknown>>,
+): React.ReactNode => {
+  if (!i18n.exists(key)) {
+    return key;
+  }
+
+  return (
+    <Trans
+      ns="openhands"
+      i18nKey={key}
+      values={values}
+      components={{
+        path: <PathComponent />,
+        cmd: <MonoComponent />,
+      }}
+    />
+  );
+};
+
+const renderTitleDescriptor = (
+  descriptor: EventTitleDescriptor,
+): React.ReactNode =>
+  descriptor.kind === "text"
+    ? descriptor.text
+    : createTitleFromKey(descriptor.key, descriptor.values);
+
+const getNonEmptyString = (
+  value: unknown,
+  maxLength?: number,
+): string | null => {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  return maxLength ? trimEventTitleText(trimmed, maxLength) : trimmed;
+};
+
+const getVisionInspectActionTitle = (
+  event: ActionEvent,
+): React.ReactNode | null => {
+  if (event.tool_name !== "inspect_image_with_vision") {
+    return null;
+  }
+
+  const action = event.action as unknown as Record<string, unknown>;
+  const profileName = getNonEmptyString(action.profile_name);
+
+  return profileName
+    ? `Describing image with ${profileName}`
+    : "Describing image with auxiliary vision LLM";
+};
+
+const getVisionInspectObservationTitle = (
+  event: ObservationEvent,
+  correspondingAction?: ActionEvent,
+): React.ReactNode | null => {
+  const actionToolName = correspondingAction?.tool_name;
+  const observation = event.observation as unknown as Record<string, unknown>;
+  const observationToolName = getNonEmptyString(observation.tool_name);
+
+  if (
+    actionToolName !== "inspect_image_with_vision" &&
+    observationToolName !== "inspect_image_with_vision" &&
+    String(event.observation.kind) !== "VisionInspectObservation"
+  ) {
+    return null;
+  }
+
+  const action = (correspondingAction?.action ?? {}) as unknown as Record<
+    string,
+    unknown
+  >;
+  const label =
+    getNonEmptyString(action.profile_name) ??
+    getNonEmptyString(observation.profile_name) ??
+    getNonEmptyString(observation.base_url, 80) ??
+    getNonEmptyString(observation.endpoint, 80) ??
+    getNonEmptyString(observation.model, 80);
+
+  return label
+    ? `Describing image with ${label}`
+    : "Describing image with auxiliary vision LLM";
+};
+
+// Action Event Processing
+const getActionEventTitle = (event: OpenHandsEvent): React.ReactNode => {
+  // Early return if not an action event
+  if (!isActionEvent(event)) {
+    return "";
+  }
+
+  const visionInspectTitle = getVisionInspectActionTitle(event);
+  if (visionInspectTitle) {
+    return visionInspectTitle;
+  }
+
+  return renderTitleDescriptor(getActionEventTitleDescriptor(event));
+};
+
+// Observation Event Processing
+const getObservationEventTitle = (
+  event: OpenHandsEvent,
+  correspondingAction?: ActionEvent,
+): React.ReactNode => {
+  // Early return if not an observation event
+  if (!isObservationEvent(event)) {
+    return "";
+  }
+
+  const visionInspectObservationTitle = getVisionInspectObservationTitle(
+    event,
+    correspondingAction,
+  );
+  if (visionInspectObservationTitle) {
+    return visionInspectObservationTitle;
+  }
+
+  if (correspondingAction) {
+    const visionInspectTitle = getVisionInspectActionTitle(correspondingAction);
+    if (visionInspectTitle) {
+      return visionInspectTitle;
+    }
+
+    const summaryTitle = getActionSummaryTitle(correspondingAction);
+    if (summaryTitle) {
+      return summaryTitle;
+    }
+  }
+
+  const observationType = event.observation.kind;
+  let observationKey = "";
+  let observationValues: Record<string, unknown> = {};
+
+  switch (observationType) {
+    case "ExecuteBashObservation":
+    case "TerminalObservation":
+      observationKey = "OBSERVATION_MESSAGE$RUN";
+      observationValues = {
+        command: event.observation.command
+          ? trimEventTitleText(event.observation.command, 80)
+          : "",
+      };
+      break;
+    case "FileEditorObservation":
+    case "StrReplaceEditorObservation":
+      if (event.observation.command === "view") {
+        observationKey = "OBSERVATION_MESSAGE$READ";
+      } else if (event.observation.command === "create") {
+        observationKey = "OBSERVATION_MESSAGE$WRITE";
+      } else {
+        observationKey = "OBSERVATION_MESSAGE$EDIT";
+      }
+      observationValues = {
+        path: event.observation.path || "",
+      };
+      break;
+    case "MCPToolObservation":
+      observationKey = "OBSERVATION_MESSAGE$MCP";
+      observationValues = {
+        mcp_tool_name: event.observation.tool_name,
+      };
+      break;
+    case "InvokeSkillObservation":
+      observationKey = "OBSERVATION_MESSAGE$INVOKE_SKILL";
+      observationValues = {
+        name: event.observation.skill_name,
+      };
+      break;
+    case "TaskObservation":
+      observationKey = "OBSERVATION_MESSAGE$TASK";
+      observationValues = {
+        name: event.observation.subagent,
+      };
+      break;
+    case "CanvasUIObservation":
+      observationKey = "OBSERVATION_MESSAGE$CANVAS_UI";
+      break;
+    case "ClientToolObservation":
+      if (event.tool_name === CANVAS_UI_CLIENT_TOOL_NAME) {
+        observationKey = "OBSERVATION_MESSAGE$CANVAS_UI";
+        break;
+      }
+      if (event.tool_name === LAUNCH_CHILD_CONVERSATION_TOOL_NAME) {
+        observationKey = "OBSERVATION_MESSAGE$LAUNCH_CHILD_CONVERSATION";
+        break;
+      }
+      return observationType.replace("Observation", "").toUpperCase();
+    case "SwitchLLMObservation":
+      observationKey = event.observation.is_error
+        ? "MODEL$SWITCH_FAILED"
+        : "MODEL$SWITCHED_TO_PROFILE";
+      observationValues = {
+        name: event.observation.profile_name,
+      };
+      break;
+    case "BrowserObservation":
+      observationKey = "OBSERVATION_MESSAGE$BROWSE";
+      break;
+    case "TaskTrackerObservation": {
+      const { command } = event.observation;
+      if (command === "plan") {
+        observationKey = "OBSERVATION_MESSAGE$TASK_TRACKING_PLAN";
+      } else {
+        // command === "view"
+        observationKey = "OBSERVATION_MESSAGE$TASK_TRACKING_VIEW";
+      }
+      break;
+    }
+    case "ThinkObservation":
+      observationKey = "OBSERVATION_MESSAGE$THINK";
+      break;
+    case "GlobObservation":
+      observationKey = "OBSERVATION_MESSAGE$GLOB";
+      observationValues = {
+        pattern: event.observation.pattern
+          ? trimEventTitleText(event.observation.pattern, 50)
+          : "",
+      };
+      break;
+    case "GrepObservation":
+      observationKey = "OBSERVATION_MESSAGE$GREP";
+      observationValues = {
+        pattern: event.observation.pattern
+          ? trimEventTitleText(event.observation.pattern, 50)
+          : "",
+      };
+      break;
+    default:
+      // For unknown observations, use the type name
+      return observationType.replace("Observation", "").toUpperCase();
+  }
+
+  if (observationKey) {
+    return createTitleFromKey(observationKey, observationValues);
+  }
+
+  return observationType;
+};
+
+const getCanvasUIClientObservationContent = (
+  event: ObservationEvent,
+  correspondingAction?: ActionEvent,
+): string | null => {
+  if (
+    event.observation.kind !== "ClientToolObservation" ||
+    event.tool_name !== CANVAS_UI_CLIENT_TOOL_NAME ||
+    !correspondingAction ||
+    !isCanvasUIActionEvent(correspondingAction)
+  ) {
+    return null;
+  }
+
+  return `UI command '${correspondingAction.action.command}' dispatched to the Agent Canvas frontend.`;
+};
+
+export const getEventContent = (
+  event: OpenHandsEvent | SkillReadyEvent,
+  correspondingAction?: ActionEvent,
+) => {
+  let title: React.ReactNode = "";
+  let details: string | React.ReactNode = "";
+
+  // Handle Skill Ready events first
+  if (isSkillReadyEvent(event)) {
+    // Use translation key if available, otherwise use "SKILL READY"
+    const skillReadyKey = "OBSERVATION_MESSAGE$SKILL_READY";
+    if (i18n.exists(skillReadyKey)) {
+      title = createTitleFromKey(skillReadyKey, {});
+    } else {
+      title = "Skill Ready";
+    }
+    details = event._skillReadyContent;
+  } else if (isActionEvent(event)) {
+    title = getActionEventTitle(event);
+    // Per-tool React visualizer when one is registered; markdown otherwise.
+    details = resolveVisualizerBody(event) ?? getActionContent(event);
+  } else if (isObservationEvent(event)) {
+    title = getObservationEventTitle(event, correspondingAction);
+
+    // For TaskTrackerObservation, use React component instead of markdown
+    if (event.observation.kind === "TaskTrackerObservation") {
+      details = (
+        <TaskTrackingObservationContent
+          event={event as ObservationEvent<TaskTrackerObservation>}
+        />
+      );
+    } else {
+      details =
+        getCanvasUIClientObservationContent(event, correspondingAction) ??
+        resolveVisualizerBody(event, correspondingAction) ??
+        getObservationContent(event);
+    }
+  } else if (isACPToolCallEvent(event)) {
+    // ACP sub-agent tool calls reuse the same card shape as observations:
+    // title is "Running/Editing/Reading …" via a translation key that
+    // mirrors ACTION_MESSAGE$RUN etc.; details are markdown built from
+    // raw_input + raw_output the same way getTerminalObservationContent
+    // builds "Command: / Output:" blocks.
+    title = createTitleFromKey(getACPToolCallTitleKey(event), {
+      // Strip a redundant verb prefix the ACP server may have inlined
+      // (Claude Code emits ``"Read /path"`` for a read tool; combined
+      // with the ``"Reading <cmd>{{title}}</cmd>"`` template that lands
+      // as ``"Reading Read /path"``). See ``stripRedundantTitlePrefix``.
+      title: stripRedundantTitlePrefix(event),
+    });
+    details = getACPToolCallContent(event);
+  } else if (
+    // Lenient fallback for action-like events that fail the strict isActionEvent() guard
+    // (e.g., missing tool_name or tool_call_id). Extract a title from the action kind
+    // so the UI shows something meaningful instead of "Unknown event".
+    event.source === "agent" &&
+    "action" in event &&
+    event.action !== null &&
+    typeof event.action === "object" &&
+    "kind" in event.action &&
+    typeof event.action.kind === "string"
+  ) {
+    title = String(event.action.kind).replace("Action", "").toUpperCase();
+  }
+
+  return {
+    title: title || i18n.t(I18nKey.EVENT$UNKNOWN_EVENT),
+    details,
+  };
+};

src/components/conversation-events/chat/event-content-helpers/get-invoke-skill-items.ts

@@ -0,0 +1,28 @@
+import { ObservationEvent } from "#/types/agent-server/core";
+import { InvokeSkillObservation } from "#/types/agent-server/core/base/observation";
+import { SkillReadyItem } from "./get-skill-ready-content";
+
+/**
+ * Maps an InvokeSkillObservation to the SkillReadyItem shape so invoke-skill
+ * tool calls can reuse the Skill Ready expandable list. A single skill is
+ * invoked per observation, so this yields at most one item. Returns an empty
+ * array when there is neither a skill name nor any text content to show, which
+ * tells the caller to fall back to the default markdown body.
+ */
+export const getInvokeSkillItems = (
+  event: ObservationEvent<InvokeSkillObservation>,
+): SkillReadyItem[] => {
+  const { observation } = event;
+
+  const content = observation.content
+    .filter((c) => c.type === "text")
+    .map((c) => c.text)
+    .join("\n")
+    .trim();
+
+  if (!observation.skill_name && !content) {
+    return [];
+  }
+
+  return [{ name: observation.skill_name, content }];
+};

src/components/conversation-events/chat/event-content-helpers/get-observation-content.ts

@@ -0,0 +1,436 @@
+import { CANVAS_UI_CLIENT_TOOL_NAME } from "#/constants/canvas-ui";
+import { ObservationEvent } from "#/types/agent-server/core";
+import { getObservationResult } from "./get-observation-result";
+import { getDefaultEventContent, MAX_CONTENT_LENGTH } from "./shared";
+import i18n from "#/i18n";
+import { I18nKey } from "#/i18n/declaration";
+import {
+  MCPToolObservation,
+  FinishObservation,
+  ThinkObservation,
+  BrowserObservation,
+  ExecuteBashObservation,
+  TerminalObservation,
+  FileEditorObservation,
+  StrReplaceEditorObservation,
+  TaskTrackerObservation,
+  GlobObservation,
+  GrepObservation,
+  InvokeSkillObservation,
+  CanvasUIObservation,
+  SwitchLLMObservation,
+} from "#/types/agent-server/core/base/observation";
+
+// File Editor Observations
+const getFileEditorObservationContent = (
+  event: ObservationEvent<FileEditorObservation | StrReplaceEditorObservation>,
+): string => {
+  const { observation } = event;
+
+  if (observation.error) {
+    return `**Error:**\n${observation.error}`;
+  }
+
+  // Extract text content from the observation if it exists
+  const textContent =
+    "content" in observation && Array.isArray(observation.content)
+      ? observation.content
+          .filter((c) => c.type === "text")
+          .map((c) => c.text)
+          .join("\n")
+      : null;
+
+  const successMessage = getObservationResult(event) === "success";
+
+  // For view commands or successful edits with content changes, format as code block
+  if (
+    (successMessage &&
+      "old_content" in observation &&
+      "new_content" in observation &&
+      observation.old_content &&
+      observation.new_content) ||
+    observation.command === "view"
+  ) {
+    // Prefer content over output for view commands, fallback to output if content is not available
+    const displayContent = textContent || observation.output;
+    return `\`\`\`\n${displayContent}\n\`\`\``;
+  }
+
+  // For other commands, prefer content if available, otherwise use output
+  return textContent || observation.output;
+};
+
+// Command Observations
+const getTerminalObservationContent = (
+  event: ObservationEvent<ExecuteBashObservation | TerminalObservation>,
+): string => {
+  const { observation } = event;
+
+  // Extract text content from the observation
+  const textContent = observation.content
+    .filter((c) => c.type === "text")
+    .map((c) => c.text)
+    .join("\n");
+
+  let content = textContent || "";
+
+  if (content.length > MAX_CONTENT_LENGTH) {
+    content = `${content.slice(0, MAX_CONTENT_LENGTH)}...`;
+  }
+
+  // Build the output string
+  let output = "";
+
+  // Display the command if available
+  if (observation.command) {
+    output += `Command: \`${observation.command}\`\n\n`;
+  }
+
+  // Display the output
+  output += `Output:\n\`\`\`sh\n${content.trim() || i18n.t(I18nKey.OBSERVATION$COMMAND_NO_OUTPUT)}\n\`\`\``;
+
+  return output;
+};
+
+// Tool Observations
+const getBrowserObservationContent = (
+  event: ObservationEvent<BrowserObservation>,
+): string => {
+  const { observation } = event;
+
+  // Extract text content from the observation
+  const textContent =
+    "content" in observation && Array.isArray(observation.content)
+      ? observation.content
+          .filter((c) => c.type === "text")
+          .map((c) => c.text)
+          .join("\n")
+      : observation.output || "";
+
+  let contentDetails = "";
+
+  if (observation.error) {
+    contentDetails += `**Error:**\n${observation.error}`;
+  } else if (textContent) {
+    contentDetails += `**Output:**\n${textContent}`;
+  } else {
+    contentDetails += "Browser action completed successfully.";
+  }
+
+  if (contentDetails.length > MAX_CONTENT_LENGTH) {
+    contentDetails = `${contentDetails.slice(0, MAX_CONTENT_LENGTH)}...(truncated)`;
+  }
+
+  return contentDetails;
+};
+
+const getMCPToolObservationContent = (
+  event: ObservationEvent<MCPToolObservation>,
+): string => {
+  const { observation } = event;
+
+  // Extract text content from the observation
+  const textContent = observation.content
+    .filter((c) => c.type === "text")
+    .map((c) => c.text)
+    .join("\n");
+
+  let content = `**Tool:** ${observation.tool_name}\n\n`;
+
+  if (observation.is_error) {
+    content += `**Error:**\n${textContent}`;
+  } else {
+    content += `**Result:**\n${textContent}`;
+  }
+
+  if (content.length > MAX_CONTENT_LENGTH) {
+    content = `${content.slice(0, MAX_CONTENT_LENGTH)}...`;
+  }
+
+  return content;
+};
+
+// Invoke-skill observations
+const getInvokeSkillObservationContent = (
+  event: ObservationEvent<InvokeSkillObservation>,
+): string => {
+  const { observation } = event;
+
+  const textContent = observation.content
+    .filter((c) => c.type === "text")
+    .map((c) => c.text)
+    .join("\n");
+
+  const header = observation.skill_name
+    ? `**Skill:** \`${observation.skill_name}\`\n\n`
+    : "";
+  const body = observation.is_error
+    ? `**Error:**\n${textContent}`
+    : textContent;
+
+  let content = `${header}${body}`;
+  if (content.length > MAX_CONTENT_LENGTH) {
+    content = `${content.slice(0, MAX_CONTENT_LENGTH)}...(truncated)`;
+  }
+  return content;
+};
+
+// Canvas UI observations — just surface the acknowledgement text.
+const getCanvasUIObservationContent = (
+  event: ObservationEvent<CanvasUIObservation>,
+): string =>
+  event.observation.content
+    .filter((c) => c.type === "text")
+    .map((c) => c.text)
+    .join("\n");
+
+const getSwitchLLMObservationContent = (
+  event: ObservationEvent<SwitchLLMObservation>,
+): string => {
+  const { observation } = event;
+
+  const textContent = observation.content
+    .filter((c) => c.type === "text")
+    .map((c) => c.text)
+    .join("\n");
+
+  if (observation.is_error) {
+    return textContent
+      ? `**Error:**\n${textContent}`
+      : `**Error:**\nFailed to switch LLM profile \`${observation.profile_name}\`.`;
+  }
+
+  const parts = [`**Profile:** \`${observation.profile_name}\``];
+  if (observation.active_model) {
+    parts.push(`**Active model:** \`${observation.active_model}\``);
+  }
+  if (observation.reason) {
+    parts.push(`**Reason:** ${observation.reason}`);
+  }
+
+  return parts.join("\n");
+};
+
+// Complex Observations
+const getTaskTrackerObservationContent = (
+  event: ObservationEvent<TaskTrackerObservation>,
+): string => {
+  const { observation } = event;
+
+  const { command, task_list: taskList } = observation;
+  let content = `**Command:** \`${command}\``;
+
+  if (command === "plan" && taskList.length > 0) {
+    content += `\n\n**Task List (${taskList.length} ${taskList.length === 1 ? "item" : "items"}):**\n`;
+
+    taskList.forEach((task, index: number) => {
+      const statusMap = {
+        todo: "⏳",
+        in_progress: "🔄",
+        done: "✅",
+      };
+      const statusIcon =
+        statusMap[task.status as keyof typeof statusMap] || "❓";
+
+      content += `\n${index + 1}. ${statusIcon} **[${task.status.toUpperCase().replace("_", " ")}]** ${task.title}`;
+      if (task.notes) {
+        content += `\n   *Notes: ${task.notes}*`;
+      }
+    });
+  } else if (command === "plan") {
+    content += "\n\n**Task List:** Empty";
+  }
+
+  if (
+    "content" in observation &&
+    observation.content &&
+    typeof observation.content === "string" &&
+    observation.content.trim()
+  ) {
+    content += `\n\n**Result:** ${observation.content.trim()}`;
+  }
+
+  return content;
+};
+
+// Simple Observations
+const getThinkObservationContent = (
+  event: ObservationEvent<ThinkObservation>,
+): string => {
+  const { observation } = event;
+
+  const textContent = observation.content
+    .filter((c) => c.type === "text")
+    .map((c) => c.text)
+    .join("\n");
+
+  return textContent || "";
+};
+
+const getFinishObservationContent = (
+  event: ObservationEvent<FinishObservation>,
+): string => {
+  const { observation } = event;
+
+  // Extract text content from the observation
+  const textContent = observation.content
+    .filter((c) => c.type === "text")
+    .map((c) => c.text)
+    .join("\n");
+
+  let content = "";
+
+  if (observation.is_error) {
+    content += `**Error:**\n${textContent}`;
+  } else {
+    content += textContent;
+  }
+
+  return content;
+};
+
+// Glob Observations
+const getGlobObservationContent = (
+  event: ObservationEvent<GlobObservation>,
+): string => {
+  const { observation } = event;
+
+  // Extract text content from the observation
+  const textContent = observation.content
+    .filter((c) => c.type === "text")
+    .map((c) => c.text)
+    .join("\n");
+
+  let content = `**Pattern:** \`${observation.pattern}\`\n`;
+  content += `**Search Path:** \`${observation.search_path}\`\n\n`;
+
+  if (observation.is_error) {
+    content += `**Error:**\n${textContent}`;
+  } else if (observation.files.length === 0) {
+    content += "**Result:** No files found.";
+  } else {
+    content += `**Files Found (${observation.files.length}${observation.truncated ? "+, truncated" : ""}):**\n`;
+    content += observation.files.map((f) => `- \`${f}\``).join("\n");
+  }
+
+  if (content.length > MAX_CONTENT_LENGTH) {
+    content = `${content.slice(0, MAX_CONTENT_LENGTH)}...(truncated)`;
+  }
+
+  return content;
+};
+
+// Grep Observations
+const getGrepObservationContent = (
+  event: ObservationEvent<GrepObservation>,
+): string => {
+  const { observation } = event;
+
+  // Extract text content from the observation
+  const textContent = observation.content
+    .filter((c) => c.type === "text")
+    .map((c) => c.text)
+    .join("\n");
+
+  let content = `**Pattern:** \`${observation.pattern}\`\n`;
+  content += `**Search Path:** \`${observation.search_path}\`\n`;
+  if (observation.include_pattern) {
+    content += `**Include:** \`${observation.include_pattern}\`\n`;
+  }
+  content += "\n";
+
+  if (observation.is_error) {
+    content += `**Error:**\n${textContent}`;
+  } else if (observation.matches.length === 0) {
+    content += "**Result:** No matches found.";
+  } else {
+    content += `**Matches (${observation.matches.length}${observation.truncated ? "+, truncated" : ""}):**\n`;
+    content += observation.matches.map((f) => `- \`${f}\``).join("\n");
+  }
+
+  if (content.length > MAX_CONTENT_LENGTH) {
+    content = `${content.slice(0, MAX_CONTENT_LENGTH)}...(truncated)`;
+  }
+
+  return content;
+};
+
+export const getObservationContent = (event: ObservationEvent): string => {
+  const observationType = event.observation.kind;
+
+  switch (observationType) {
+    case "FileEditorObservation":
+    case "StrReplaceEditorObservation":
+      return getFileEditorObservationContent(
+        event as ObservationEvent<
+          FileEditorObservation | StrReplaceEditorObservation
+        >,
+      );
+
+    case "ExecuteBashObservation":
+    case "TerminalObservation":
+      return getTerminalObservationContent(
+        event as ObservationEvent<ExecuteBashObservation | TerminalObservation>,
+      );
+
+    case "BrowserObservation":
+      return getBrowserObservationContent(
+        event as ObservationEvent<BrowserObservation>,
+      );
+
+    case "MCPToolObservation":
+      return getMCPToolObservationContent(
+        event as ObservationEvent<MCPToolObservation>,
+      );
+
+    case "TaskTrackerObservation":
+      return getTaskTrackerObservationContent(
+        event as ObservationEvent<TaskTrackerObservation>,
+      );
+
+    case "ThinkObservation":
+      return getThinkObservationContent(
+        event as ObservationEvent<ThinkObservation>,
+      );
+
+    case "FinishObservation":
+      return getFinishObservationContent(
+        event as ObservationEvent<FinishObservation>,
+      );
+
+    case "GlobObservation":
+      return getGlobObservationContent(
+        event as ObservationEvent<GlobObservation>,
+      );
+
+    case "GrepObservation":
+      return getGrepObservationContent(
+        event as ObservationEvent<GrepObservation>,
+      );
+
+    case "InvokeSkillObservation":
+      return getInvokeSkillObservationContent(
+        event as ObservationEvent<InvokeSkillObservation>,
+      );
+
+    case "CanvasUIObservation":
+      return getCanvasUIObservationContent(
+        event as ObservationEvent<CanvasUIObservation>,
+      );
+
+    case "ClientToolObservation":
+      return event.tool_name === CANVAS_UI_CLIENT_TOOL_NAME
+        ? getCanvasUIObservationContent(
+            event as ObservationEvent<CanvasUIObservation>,
+          )
+        : getDefaultEventContent(event);
+
+    case "SwitchLLMObservation":
+      return getSwitchLLMObservationContent(
+        event as ObservationEvent<SwitchLLMObservation>,
+      );
+
+    default:
+      return getDefaultEventContent(event);
+  }
+};

src/components/conversation-events/chat/event-content-helpers/get-observation-result.ts

@@ -0,0 +1,70 @@
+import { ObservationEvent } from "#/types/agent-server/core";
+import { ACPToolCallEvent } from "#/types/agent-server/core/events/acp-tool-call-event";
+
+export type ObservationResultStatus = "success" | "error" | "timeout";
+
+/**
+ * Map an ACPToolCallEvent's lifecycle + error flags to the same
+ * success/error status the rest of the UI uses. A non-terminal call
+ * (``pending`` / ``in_progress``) falls through to ``undefined`` so the
+ * SuccessIndicator renders nothing — the card shows as "running" via the
+ * absence of a check mark, matching how regular ActionEvents are displayed
+ * before their ObservationEvent arrives.
+ */
+export const getACPToolCallResult = (
+  event: ACPToolCallEvent,
+): ObservationResultStatus | undefined => {
+  if (event.is_error || event.status === "failed") return "error";
+  if (event.status === "completed") return "success";
+  return undefined;
+};
+
+export const getObservationResult = (
+  event: ObservationEvent,
+): ObservationResultStatus => {
+  const { observation } = event;
+  const observationType = observation.kind;
+
+  switch (observationType) {
+    case "ExecuteBashObservation": {
+      const exitCode = observation.exit_code;
+      const { metadata } = observation;
+
+      if (exitCode === -1 || metadata.exit_code === -1) return "timeout"; // Command timed out
+      if (exitCode === 0 || metadata.exit_code === 0) return "success"; // Command executed successfully
+      return "error"; // Command failed
+    }
+    case "TerminalObservation": {
+      const exitCode =
+        observation.exit_code ?? observation.metadata.exit_code ?? null;
+
+      if (observation.timeout || exitCode === -1) return "timeout";
+      if (exitCode === 0) return "success";
+      if (observation.is_error) return "error";
+      return "success";
+    }
+    case "FileEditorObservation":
+    case "StrReplaceEditorObservation":
+      // Check if there's an error
+      if (observation.error) return "error";
+      return "success";
+    case "MCPToolObservation":
+      if (observation.is_error) return "error";
+      return "success";
+    case "SwitchLLMObservation":
+      if (observation.is_error) return "error";
+      return "success";
+    case "InvokeSkillObservation":
+      if (observation.is_error) return "error";
+      return "success";
+    case "TaskObservation":
+      if (observation.is_error || observation.status === "failed")
+        return "error";
+      return "success";
+    case "CanvasUIObservation":
+      if (observation.is_error) return "error";
+      return "success";
+    default:
+      return "success";
+  }
+};

src/components/conversation-events/chat/event-content-helpers/get-skill-ready-content.ts

@@ -0,0 +1,128 @@
+import { TextContent } from "#/types/agent-server/core/base/common";
+
+/**
+ * Represents a single activated skill with its name and associated content.
+ */
+export interface SkillReadyItem {
+  name: string;
+  content: string;
+}
+
+/**
+ * Extracts all text content from an array of TextContent items.
+ */
+function extractAllText(extendedContent: TextContent[]): string {
+  return extendedContent
+    .filter((c) => c.type === "text")
+    .map((c) => c.text)
+    .join("");
+}
+
+/**
+ * Extracts all <EXTRA_INFO> blocks from the given text.
+ * Returns an array of content strings (without the wrapper tags).
+ */
+const extractExtraInfoBlocks = (text: string): string[] => {
+  const blockRegex = /<EXTRA_INFO>([\s\S]*?)<\/EXTRA_INFO>/gi;
+  return Array.from(text.matchAll(blockRegex), (match) =>
+    match[1].trim(),
+  ).filter(Boolean);
+};
+
+/**
+ * Formats a single skill with its corresponding content block.
+ */
+const formatSkillWithContent = (
+  skill: string,
+  contentBlock: string | undefined,
+): string => {
+  let formatted = `\n\n- **${skill}**`;
+
+  if (contentBlock) {
+    formatted += `\n\n${contentBlock}`;
+  }
+
+  return formatted;
+};
+
+/**
+ * Formats skills paired with their corresponding extended content blocks.
+ */
+const formatSkillKnowledge = (
+  activatedSkills: string[],
+  extraInfoBlocks: string[],
+): string => {
+  let content = `\n\n**Triggered Skill Knowledge:**`;
+
+  activatedSkills.forEach((skill, index) => {
+    const contentBlock = extraInfoBlocks[index];
+    content += formatSkillWithContent(skill, contentBlock);
+  });
+
+  return content;
+};
+
+/**
+ * Formats extended content blocks when no skills are present.
+ */
+const formatExtendedContentOnly = (extraInfoBlocks: string[]): string => {
+  let content = `\n\n**Extended Content:**`;
+
+  extraInfoBlocks.forEach((block) => {
+    content += `\n\n${block}`;
+  });
+
+  return content;
+};
+
+/**
+ * Extracts EXTRA_INFO blocks from extended content.
+ */
+const getExtraInfoBlocks = (extendedContent?: TextContent[]): string[] => {
+  if (!extendedContent) return [];
+  return extractExtraInfoBlocks(extractAllText(extendedContent));
+};
+
+/**
+ * Formats activated skills and extended content into markdown for display.
+ * Each skill is paired with its corresponding <EXTRA_INFO> block by index.
+ */
+export const getSkillReadyContent = (
+  activatedSkills: string[],
+  extendedContent: TextContent[],
+): string => {
+  const extraInfoBlocks = getExtraInfoBlocks(extendedContent);
+
+  if (activatedSkills && activatedSkills.length > 0) {
+    return formatSkillKnowledge(activatedSkills, extraInfoBlocks);
+  }
+
+  if (extraInfoBlocks.length > 0) {
+    return formatExtendedContentOnly(extraInfoBlocks);
+  }
+
+  return "";
+};
+
+/**
+ * Returns structured skill items with their names and associated content.
+ * Each skill is paired with its corresponding <EXTRA_INFO> block by index.
+ */
+export const getSkillReadyItems = (
+  activatedSkills: string[],
+  extendedContent: TextContent[],
+): SkillReadyItem[] => {
+  const extraInfoBlocks = getExtraInfoBlocks(extendedContent);
+
+  if (activatedSkills && activatedSkills.length > 0) {
+    return activatedSkills.map((skill, index) => ({
+      name: skill,
+      content: extraInfoBlocks[index] ?? "",
+    }));
+  }
+
+  return extraInfoBlocks.map((block, index) => ({
+    name: `Extended Content ${index + 1}`,
+    content: block,
+  }));
+};

src/components/conversation-events/chat/event-content-helpers/parse-message-from-event.ts

@@ -0,0 +1,42 @@
+import { MessageEvent } from "#/types/agent-server/core";
+import i18n from "#/i18n";
+import { I18nKey } from "#/i18n/declaration";
+
+export const parseMessageFromEvent = (event: MessageEvent): string => {
+  const message = event.llm_message;
+
+  // Safety check: ensure llm_message exists and has content
+  if (!message?.content) {
+    return "";
+  }
+
+  // Get the text content from the message
+  let textContent = "";
+  if (message.content) {
+    if (Array.isArray(message.content)) {
+      // Handle array of content blocks
+      textContent = message.content
+        .filter((content) => content.type === "text")
+        .map((content) => content.text)
+        .join("\n");
+    } else if (typeof message.content === "string") {
+      // Handle string content
+      textContent = message.content;
+    }
+  }
+
+  // Check if there are image_urls in the message content
+  const hasImages =
+    Array.isArray(message.content) &&
+    message.content.some((content) => content.type === "image");
+
+  if (!hasImages) {
+    return textContent;
+  }
+
+  // If there are images, try to split by the augmented prompt delimiter
+  const delimiter = i18n.t(I18nKey.CHAT_INTERFACE$AUGMENTED_PROMPT_FILES_TITLE);
+  const parts = textContent.split(delimiter);
+
+  return parts[0];
+};

src/components/conversation-events/chat/event-content-helpers/shared.ts

@@ -0,0 +1,6 @@
+import { OpenHandsEvent } from "#/types/agent-server/core";
+
+export const MAX_CONTENT_LENGTH = 1000;
+
+export const getDefaultEventContent = (event: OpenHandsEvent): string =>
+  `\`\`\`json\n${JSON.stringify(event, null, 2)}\n\`\`\``;

src/components/conversation-events/chat/event-content-helpers/should-render-event.ts

@@ -0,0 +1,148 @@
+import { CHILD_CONVERSATION_RESULT_PREFIX } from "#/constants/child-conversation";
+import { MessageEvent, OpenHandsEvent } from "#/types/agent-server/core";
+import {
+  isActionEvent,
+  isObservationEvent,
+  isMessageEvent,
+  isAgentErrorEvent,
+  isConversationStateUpdateEvent,
+  isGoalConversationStateUpdateEvent,
+  isHookExecutionEvent,
+  isACPToolCallEvent,
+  isStreamingDeltaEvent,
+} from "#/types/agent-server/type-guards";
+
+// Prefixes of the SDK goal-loop re-prompts (FOLLOWUP_PROMPT / RESUME_PROMPT in
+// openhands.sdk .../conversation/goal/prompts.py). The goal loop injects these
+// as `user` messages each round to steer the agent, and FOLLOWUP_PROMPT embeds
+// the judge's verdict — which the goal banner already surfaces. The persisted
+// event carries no marker distinguishing them from real user input, so we match
+// the prompt text to keep this machinery out of the chat. Brittle by design;
+// keep in sync with the SDK prompts (the durable fix is a persisted goal-loop
+// flag on the event).
+const GOAL_REPROMPT_PREFIXES = [
+  "The goal is NOT yet complete (audit iteration",
+  "Resuming a goal that was paused or interrupted.",
+];
+
+const userMessageText = (event: MessageEvent): string | null => {
+  if (event.llm_message?.role !== "user") return null;
+  const content = event.llm_message.content;
+  return Array.isArray(content)
+    ? content
+        .filter((c) => c.type === "text")
+        .map((c) => c.text)
+        .join("\n")
+    : "";
+};
+
+const isGoalLoopReprompt = (event: MessageEvent): boolean => {
+  const text = userMessageText(event);
+  if (text === null) return false;
+  return GOAL_REPROMPT_PREFIXES.some((prefix) => text.startsWith(prefix));
+};
+
+// The frontend posts the outcome of a `launch_child_conversation` call back as
+// a `user` message because client tools have no result channel (see
+// `services/child-conversation-launch.ts`). It is a JSON payload addressed to
+// the agent, which reports the child's id and link in its own reply, so the
+// raw message does not belong in the chat.
+const isChildConversationResult = (event: MessageEvent): boolean =>
+  userMessageText(event)?.startsWith(CHILD_CONVERSATION_RESULT_PREFIX) ?? false;
+
+export const shouldRenderEvent = (event: OpenHandsEvent) => {
+  if (isConversationStateUpdateEvent(event)) {
+    // A finished `/goal` loop renders inline so it settles into the
+    // conversation; the live (active) banner is shown separately by
+    // GoalStatusBanner, and all other state updates (and the in-progress goal
+    // events) stay hidden.
+    return isGoalConversationStateUpdateEvent(event) && !event.value.active;
+  }
+
+  // Render action events (with filtering)
+  if (isActionEvent(event)) {
+    // For V1, action is an object with kind property
+    const actionType = event.action.kind;
+
+    if (!actionType) {
+      return false;
+    }
+
+    // Hide user commands from the chat interface
+    if (actionType === "ExecuteBashAction" && event.source === "user") {
+      return false;
+    }
+
+    // Hide PlanningFileEditorAction - handled separately with PlanPreview component
+    if (actionType === "PlanningFileEditorAction") {
+      return false;
+    }
+
+    // The model switch tool reuses the same inline model message UI as
+    // `/model <profile>` once the observation arrives.
+    if (actionType === "SwitchLLMAction") {
+      return false;
+    }
+
+    return true;
+  }
+
+  // Render observation events
+  if (isObservationEvent(event)) {
+    // Successful model switches are rendered through ModelMessages so they
+    // look identical to `/model <profile>` confirmations. Failed switches
+    // still render as observations so the error remains visible in chat.
+    if (
+      event.observation.kind === "SwitchLLMObservation" &&
+      !event.observation.is_error
+    ) {
+      return false;
+    }
+
+    return true;
+  }
+
+  // Render message events (user and assistant messages), except the goal loop's
+  // injected re-prompts — the judge feedback they carry is shown in the goal
+  // banner, so otherwise they leak into the chat as fake user turns — and the
+  // child-conversation launch results, which are machine payloads the agent
+  // relays in its own reply.
+  if (isMessageEvent(event)) {
+    return !isGoalLoopReprompt(event) && !isChildConversationResult(event);
+  }
+
+  // Render agent error events
+  if (isAgentErrorEvent(event)) {
+    return true;
+  }
+
+  // Render hook execution events
+  if (isHookExecutionEvent(event)) {
+    return true;
+  }
+
+  // Render ACP sub-agent tool call events at every lifecycle stage. The SDK
+  // now persists exactly two events per ``tool_call_id`` — one early
+  // ``started`` event (``pending`` / ``in_progress``) and one terminal
+  // (``completed`` / ``failed``) event — the action->observation pair for a
+  // tool call. The ``started`` event renders the card as "running" (no check
+  // mark; see ``getACPToolCallResult``) and ``handleEventForUI`` replaces it
+  // in place by ``tool_call_id`` once the terminal event arrives, mirroring
+  // how an ObservationEvent supersedes its ActionEvent. The old terminal-only
+  // gate existed because the source fanned out one cumulative-output frame per
+  // ``ToolCallProgress``, which flashed half-formed cards mid-stream; that
+  // fan-out is gone, so the running card is now a single clean event.
+  if (isACPToolCallEvent(event)) {
+    return true;
+  }
+
+  if (isStreamingDeltaEvent(event)) {
+    return event.content !== null || event.reasoning_content !== null;
+  }
+
+  // Don't render any other event types (system events, etc.)
+  return false;
+};
+
+export const hasUserEvent = (events: OpenHandsEvent[]) =>
+  events.some((event) => event.source === "user");

src/components/conversation-events/chat/event-message-components/collapsible-thinking.tsx

@@ -0,0 +1,58 @@
+import React from "react";
+import { useTranslation } from "react-i18next";
+import ArrowDown from "#/icons/angle-down-solid.svg?react";
+import ArrowUp from "#/icons/angle-up-solid.svg?react";
+import LightbulbIcon from "#/icons/lightbulb.svg?react";
+import { I18nKey } from "#/i18n/declaration";
+import { MarkdownRenderer } from "../../../features/markdown/markdown-renderer";
+
+interface CollapsibleThinkingProps {
+  /** The thinking / reasoning content to display when expanded. */
+  content: string;
+}
+
+/**
+ * Renders agent thinking or extended reasoning content inside a collapsible
+ * section.  Collapsed by default so the chat stays compact — especially
+ * useful when the thinking language differs from the conversation language.
+ */
+export function CollapsibleThinking({ content }: CollapsibleThinkingProps) {
+  const { t } = useTranslation("openhands");
+  const [expanded, setExpanded] = React.useState(false);
+
+  if (!content.trim()) {
+    return null;
+  }
+
+  const Chevron = expanded ? ArrowUp : ArrowDown;
+
+  return (
+    <div
+      className="my-1 w-full py-1 text-sm"
+      data-testid="collapsible-thinking"
+    >
+      <button
+        type="button"
+        onClick={() => setExpanded((prev) => !prev)}
+        aria-expanded={expanded}
+        aria-label={
+          expanded ? t(I18nKey.THINKING$COLLAPSE) : t(I18nKey.THINKING$EXPAND)
+        }
+        data-testid="collapsible-thinking-toggle"
+        className="w-full flex items-center gap-2 text-left cursor-pointer"
+      >
+        <Chevron className="h-4 w-4 fill-[var(--oh-muted)] flex-shrink-0" />
+        <LightbulbIcon className="h-4 w-4 fill-[var(--oh-muted)] flex-shrink-0" />
+        <span className="font-normal text-[var(--oh-muted)]">
+          {t(I18nKey.THINKING$TITLE)}
+        </span>
+      </button>
+
+      {expanded && (
+        <div className="mt-1.5 pl-6" data-testid="collapsible-thinking-content">
+          <MarkdownRenderer>{content}</MarkdownRenderer>
+        </div>
+      )}
+    </div>
+  );
+}

src/components/conversation-events/chat/event-message-components/critic-result-display.tsx

@@ -0,0 +1,247 @@
+import React from "react";
+import { useTranslation } from "react-i18next";
+import ArrowDown from "#/icons/angle-down-solid.svg?react";
+import ArrowUp from "#/icons/angle-up-solid.svg?react";
+import { useSettings } from "#/hooks/query/use-settings";
+import { I18nKey } from "#/i18n/declaration";
+import type {
+  CriticResult,
+  CriticFeature,
+  CriticCategorizedFeatures,
+} from "#/types/agent-server/core/base/critic";
+
+/**
+ * Normalize potentially malformed runtime scores before rendering.
+ */
+function normalizeScore(score: number): number {
+  if (!Number.isFinite(score)) return 0;
+  return Math.min(1, Math.max(0, score));
+}
+
+/**
+ * Convert a normalized score (0-1) to a 5-star rating string.
+ */
+function getStarRating(normalizedScore: number): {
+  filled: number;
+  empty: number;
+} {
+  const filled = Math.round(normalizedScore * 5);
+  return { filled, empty: 5 - filled };
+}
+
+/**
+ * Get the color class for the star rating based on score.
+ */
+function getScoreColorClass(score: number): string {
+  if (score >= 0.6) return "text-green-400";
+  if (score >= 0.4) return "text-yellow-400";
+  return "text-red-400";
+}
+
+/**
+ * Get the color class for an issue probability.
+ */
+function getIssueColorClass(probability: number): string {
+  if (probability >= 0.7) return "text-red-400 font-semibold";
+  if (probability >= 0.5) return "text-yellow-400";
+  return "text-neutral-400";
+}
+
+function isSettingsRecord(value: unknown): value is Record<string, unknown> {
+  return (
+    value !== null &&
+    value !== undefined &&
+    typeof value === "object" &&
+    !Array.isArray(value)
+  );
+}
+
+function getIterativeRefinementEnabled(
+  agentSettings: Record<string, unknown> | null | undefined,
+): boolean | null {
+  const verification = agentSettings?.verification;
+  if (!isSettingsRecord(verification)) {
+    return null;
+  }
+
+  const value = verification.enable_iterative_refinement;
+  return typeof value === "boolean" ? value : null;
+}
+
+/**
+ * Renders a single issue feature with its probability.
+ */
+function FeatureItem({ feature }: { feature: CriticFeature }) {
+  const percentage = Math.round(feature.probability * 100);
+  const colorClass = getIssueColorClass(feature.probability);
+
+  return (
+    <span className="inline-flex items-center gap-1">
+      <span className="text-neutral-200">{feature.display_name}</span>
+      <span className={colorClass}>({percentage}%)</span>
+    </span>
+  );
+}
+
+/**
+ * Renders a category of features (e.g., "Potential Issues", "Infrastructure").
+ */
+function FeatureCategory({
+  label,
+  features,
+}: {
+  label: string;
+  features: CriticFeature[];
+}) {
+  if (!features || features.length === 0) return null;
+
+  return (
+    <div className="flex flex-wrap items-center gap-x-1 text-xs">
+      <span className="font-semibold text-neutral-300">{label}</span>
+      {features.map((feature, i) => (
+        <React.Fragment key={feature.name}>
+          {i > 0 && <span className="text-neutral-500">·</span>}
+          <FeatureItem feature={feature} />
+        </React.Fragment>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * Renders the categorized features breakdown.
+ */
+function FeaturesBreakdown({
+  categorized,
+}: {
+  categorized: CriticCategorizedFeatures;
+}) {
+  const { t } = useTranslation();
+
+  const hasAgentIssues =
+    categorized.agent_behavioral_issues &&
+    categorized.agent_behavioral_issues.length > 0;
+  const hasUserPatterns =
+    categorized.user_followup_patterns &&
+    categorized.user_followup_patterns.length > 0;
+  const hasInfra =
+    categorized.infrastructure_issues &&
+    categorized.infrastructure_issues.length > 0;
+  const hasOther = categorized.other && categorized.other.length > 0;
+
+  if (!hasAgentIssues && !hasUserPatterns && !hasInfra && !hasOther) {
+    return null;
+  }
+
+  return (
+    <div className="flex flex-col gap-1 mt-1.5">
+      {hasAgentIssues && (
+        <FeatureCategory
+          label={t(I18nKey.CRITIC$POTENTIAL_ISSUES)}
+          features={categorized.agent_behavioral_issues!}
+        />
+      )}
+      {hasInfra && (
+        <FeatureCategory
+          label={t(I18nKey.CRITIC$INFRASTRUCTURE)}
+          features={categorized.infrastructure_issues!}
+        />
+      )}
+      {hasUserPatterns && (
+        <FeatureCategory
+          label={t(I18nKey.CRITIC$LIKELY_FOLLOWUP)}
+          features={categorized.user_followup_patterns!}
+        />
+      )}
+      {hasOther && (
+        <FeatureCategory
+          label={t(I18nKey.CRITIC$OTHER)}
+          features={categorized.other!}
+        />
+      )}
+    </div>
+  );
+}
+
+interface CriticResultDisplayProps {
+  criticResult: CriticResult;
+}
+
+/**
+ * Displays a critic evaluation result with star rating, score percentage,
+ * and expandable categorized feature breakdown.
+ */
+export function CriticResultDisplay({
+  criticResult,
+}: CriticResultDisplayProps) {
+  const { t } = useTranslation();
+  const { data: settings } = useSettings();
+  const [expanded, setExpanded] = React.useState(false);
+
+  const normalizedScore = normalizeScore(criticResult.score);
+  const { filled, empty } = getStarRating(normalizedScore);
+  const colorClass = getScoreColorClass(normalizedScore);
+  const percentage = (normalizedScore * 100).toFixed(1);
+  const iterativeRefinementEnabled = getIterativeRefinementEnabled(
+    settings?.agent_settings as Record<string, unknown> | null | undefined,
+  );
+  const showIterativeRefinementHint = iterativeRefinementEnabled === false;
+
+  const categorized = criticResult.metadata?.categorized_features;
+  const hasDetails =
+    categorized != null &&
+    ((categorized.agent_behavioral_issues ?? []).length > 0 ||
+      (categorized.user_followup_patterns ?? []).length > 0 ||
+      (categorized.infrastructure_issues ?? []).length > 0 ||
+      (categorized.other ?? []).length > 0);
+
+  return (
+    <div className="border-l-2 border-neutral-600 pl-2 my-2 py-1.5 text-sm">
+      <div className="flex items-center gap-1">
+        <span className="font-semibold text-neutral-300 text-xs">
+          {t(I18nKey.CRITIC$SUCCESS_LIKELIHOOD_LABEL)}
+        </span>
+        <span
+          className={`${colorClass} text-xs tracking-wide`}
+          aria-label={`Score: ${percentage}%`}
+        >
+          {"★".repeat(filled)}
+          {"☆".repeat(empty)}
+        </span>
+        <span className="text-neutral-500 text-xs">({percentage}%)</span>
+
+        {hasDetails && (
+          <button
+            type="button"
+            onClick={() => setExpanded((prev) => !prev)}
+            className="cursor-pointer ml-1"
+            aria-label={
+              expanded
+                ? t(I18nKey.BUTTON$COLLAPSE_DETAILS)
+                : t(I18nKey.BUTTON$EXPAND_DETAILS)
+            }
+          >
+            {expanded ? (
+              <ArrowUp className="h-3 w-3 inline fill-neutral-400" />
+            ) : (
+              <ArrowDown className="h-3 w-3 inline fill-neutral-400" />
+            )}
+          </button>
+        )}
+      </div>
+
+      {expanded && hasDetails && (
+        <FeaturesBreakdown categorized={categorized!} />
+      )}
+
+      {showIterativeRefinementHint && (
+        <p
+          className="mt-1.5 text-xs leading-5 text-neutral-500"
+          data-testid="critic-iterative-refinement-hint"
+        >
+          {t(I18nKey.CRITIC$ITERATIVE_REFINEMENT_HINT)}
+        </p>
+      )}
+    </div>
+  );
+}

src/components/conversation-events/chat/event-message-components/error-event-message.tsx

@@ -0,0 +1,16 @@
+import React from "react";
+import { AgentErrorEvent } from "#/types/agent-server/core";
+import { isAgentErrorEvent } from "#/types/agent-server/type-guards";
+import { ErrorMessage } from "../../../features/chat/error-message";
+
+interface ErrorEventMessageProps {
+  event: AgentErrorEvent;
+}
+
+export function ErrorEventMessage({ event }: ErrorEventMessageProps) {
+  if (!isAgentErrorEvent(event)) {
+    return null;
+  }
+
+  return <ErrorMessage errorId={event.id} defaultMessage={event.error} />;
+}

src/components/conversation-events/chat/event-message-components/event-group.tsx

@@ -0,0 +1,169 @@
+import React from "react";
+import { useTranslation } from "react-i18next";
+import { LoaderCircle } from "lucide-react";
+import ArrowDown from "#/icons/angle-down-solid.svg?react";
+import ArrowUp from "#/icons/angle-up-solid.svg?react";
+import { OpenHandsEvent, ActionEvent } from "#/types/agent-server/core";
+import {
+  isActionEvent,
+  isObservationEvent,
+} from "#/types/agent-server/type-guards";
+import { I18nKey } from "#/i18n/declaration";
+import { getEventContent } from "../event-content-helpers/get-event-content";
+import { IsInEventGroupContext } from "../../../features/chat/is-in-event-group-context";
+import { PathInteractiveContext } from "../../../features/chat/path-component";
+
+interface EventGroupProps {
+  /** The events represented by this group. Used to compute the summary. */
+  events: OpenHandsEvent[];
+  /**
+   * Full event history. Used to resolve the action that produced the latest
+   * observation in the group so the summary title matches what the individual
+   * card would show (e.g. "Editing path/to/file"). Falls back to `events` when
+   * omitted.
+   */
+  allEvents?: OpenHandsEvent[];
+  /**
+   * `true` once an event outside this group has been emitted after it, so the
+   * group is no longer the "live" tail of the chat. While `false` (the
+   * default), the group keeps showing the most recent action's title as its
+   * prominent summary, with the count of completed actions shown subtly on
+   * the right.
+   */
+  isFinalized?: boolean;
+  /** The fully-rendered event messages to show when the group is expanded. */
+  children: React.ReactNode;
+}
+
+/**
+ * Collapsible container that wraps a run of consecutive agent action/observation
+ * events into a single summary card.
+ *
+ * Collapsed, while the group is still the live tail of the chat
+ * (`isFinalized=false`):
+ *   - Left (prominent): the title of the most recent action/observation in
+ *     the group — i.e. either the action currently in flight, or the latest
+ *     completed step.
+ *   - Right (subdued):  "{completed}/{total} actions completed" while at
+ *     least one action is still pending (with a spinner), otherwise
+ *     "{count} actions completed" followed by a success check.
+ *
+ * Collapsed, after the group has been "moved past" (`isFinalized=true`):
+ *   - "{count} actions completed" is promoted to the prominent foreground
+ *     style and the count is the only thing shown next to the chevron.
+ *
+ * Expanded:
+ *   - Renders the children verbatim, so each individual action/observation can
+ *     still be expanded the way it was before grouping.
+ */
+export function EventGroup({
+  events,
+  allEvents,
+  isFinalized = false,
+  children,
+}: EventGroupProps) {
+  const { t } = useTranslation("openhands");
+  const [expanded, setExpanded] = React.useState(false);
+  const contentId = React.useId();
+  const buttonId = `${contentId}-toggle`;
+
+  if (events.length === 0) {
+    return null;
+  }
+
+  // Each ObservationEvent in the group is a completed action. An ActionEvent
+  // that's still here (i.e. not yet replaced by its observation in the UI
+  // events array) is an action currently in flight.
+  const pendingAction = events.find((e): e is ActionEvent => isActionEvent(e));
+  const completedCount = events.filter(isObservationEvent).length;
+  const totalCount = events.length;
+  const isRunning = !!pendingAction;
+
+  // Title of the most recent groupable event. While running this is the
+  // pending action; otherwise it's the latest observation, with its
+  // originating action looked up so the title can be the action-style summary
+  // ("Editing path/to/file") instead of the observation default.
+  const latestEvent = events[events.length - 1];
+  let latestTitle: React.ReactNode = null;
+  if (latestEvent) {
+    if (isActionEvent(latestEvent)) {
+      latestTitle = getEventContent(latestEvent).title;
+    } else if (isObservationEvent(latestEvent)) {
+      const lookupSource = allEvents ?? events;
+      const correspondingAction = lookupSource.find(
+        (e): e is ActionEvent =>
+          isActionEvent(e) && e.id === latestEvent.action_id,
+      );
+      latestTitle = getEventContent(latestEvent, correspondingAction).title;
+    }
+  }
+
+  const countSummary = isRunning
+    ? t(I18nKey.EVENT_GROUP$ACTIONS_PROGRESS, {
+        completed: completedCount,
+        total: totalCount,
+      })
+    : t(I18nKey.EVENT_GROUP$ACTIONS_COMPLETED, { count: totalCount });
+
+  const Chevron = expanded ? ArrowUp : ArrowDown;
+
+  return (
+    <div className="my-1 w-full py-1 text-sm" data-testid="event-group">
+      <button
+        id={buttonId}
+        type="button"
+        onClick={() => setExpanded((prev) => !prev)}
+        aria-controls={contentId}
+        aria-expanded={expanded}
+        aria-label={
+          expanded
+            ? t(I18nKey.EVENT_GROUP$COLLAPSE)
+            : t(I18nKey.EVENT_GROUP$EXPAND)
+        }
+        data-testid="event-group-toggle"
+        className="w-full flex items-center justify-between gap-2 text-left cursor-pointer"
+      >
+        {isFinalized ? (
+          <span className="flex items-center gap-2 min-w-0 font-normal text-[var(--oh-muted)]">
+            <Chevron className="h-4 w-4 fill-[var(--oh-muted)] flex-shrink-0" />
+            <span className="truncate">{countSummary}</span>
+          </span>
+        ) : (
+          <>
+            <span className="flex items-center gap-2 min-w-0 font-normal text-[var(--oh-muted)]">
+              <Chevron className="h-4 w-4 fill-[var(--oh-muted)] flex-shrink-0" />
+              <span className="truncate">
+                <PathInteractiveContext.Provider value={false}>
+                  {latestTitle ?? countSummary}
+                </PathInteractiveContext.Provider>
+              </span>
+            </span>
+            <span className="flex items-center flex-shrink-0 font-normal text-[var(--oh-muted)]">
+              <span className="truncate">{countSummary}</span>
+              {isRunning ? (
+                <LoaderCircle
+                  data-testid="spinner-icon"
+                  className="h-4 w-4 ml-2 inline animate-spin text-[var(--oh-muted)]"
+                />
+              ) : null}
+            </span>
+          </>
+        )}
+      </button>
+
+      {expanded && (
+        <div
+          id={contentId}
+          role="region"
+          aria-labelledby={buttonId}
+          className="mt-1.5 flex flex-col"
+          data-testid="event-group-content"
+        >
+          <IsInEventGroupContext.Provider value>
+            {children}
+          </IsInEventGroupContext.Provider>
+        </div>
+      )}
+    </div>
+  );
+}

src/components/conversation-events/chat/event-message-components/finish-event-message.tsx

@@ -0,0 +1,35 @@
+import { ActionEvent } from "#/types/agent-server/core";
+import { FinishAction } from "#/types/agent-server/core/base/action";
+import { ChatMessage } from "../../../features/chat/chat-message";
+import { getEventContent } from "../event-content-helpers/get-event-content";
+import { CriticResultDisplay } from "./critic-result-display";
+
+interface FinishEventMessageProps {
+  event: ActionEvent<FinishAction>;
+  isFromPlanningAgent?: boolean;
+}
+
+export function FinishEventMessage({
+  event,
+  isFromPlanningAgent = false,
+}: FinishEventMessageProps) {
+  const eventContent = getEventContent(event);
+  const message =
+    typeof eventContent.details === "string"
+      ? eventContent.details
+      : String(eventContent.details);
+
+  return (
+    <>
+      <ChatMessage
+        type="agent"
+        message={message}
+        isFromPlanningAgent={isFromPlanningAgent}
+        timestamp={event.timestamp}
+      />
+      {event.critic_result != null && (
+        <CriticResultDisplay criticResult={event.critic_result} />
+      )}
+    </>
+  );
+}

src/components/conversation-events/chat/event-message-components/generic-event-message-wrapper.tsx

@@ -0,0 +1,127 @@
+import {
+  OpenHandsEvent,
+  ActionEvent,
+  ObservationEvent,
+} from "#/types/agent-server/core";
+import { InvokeSkillObservation } from "#/types/agent-server/core/base/observation";
+import { I18nKey } from "#/i18n/declaration";
+import { GenericEventMessage } from "../../../features/chat/generic-event-message";
+import { getEventContent } from "../event-content-helpers/get-event-content";
+import {
+  getACPToolCallResult,
+  getObservationResult,
+  ObservationResultStatus,
+} from "../event-content-helpers/get-observation-result";
+import {
+  isACPToolCallEvent,
+  isObservationEvent,
+} from "#/types/agent-server/type-guards";
+import {
+  SkillReadyEvent,
+  SkillReadyItem,
+  isSkillReadyEvent,
+} from "../event-content-helpers/create-skill-ready-event";
+import { getInvokeSkillItems } from "../event-content-helpers/get-invoke-skill-items";
+import { SkillReadyContentList } from "./skill-ready-content-list";
+import SkillsIcon from "#/icons/skills.svg?react";
+import { isMarkdownFileEditorEvent } from "#/components/features/chat/tool-visualizers/primitives/markdown-file-preview";
+
+interface GenericEventMessageWrapperProps {
+  event: OpenHandsEvent | SkillReadyEvent;
+  isLastMessage: boolean;
+  correspondingAction?: ActionEvent;
+}
+
+/**
+ * Resolves the expandable skill-knowledge list shared by Skill Ready events and
+ * invoke-skill tool observations. Returns the list items and their header
+ * label, or null when the event carries no skill knowledge (so the caller keeps
+ * the default details body). Additional skill-knowledge sources slot in as one
+ * more branch here.
+ */
+function getSkillKnowledge(
+  event: OpenHandsEvent | SkillReadyEvent,
+): { items: SkillReadyItem[]; titleKey: I18nKey } | null {
+  if (isSkillReadyEvent(event)) {
+    return event._skillReadyItems.length > 0
+      ? {
+          items: event._skillReadyItems,
+          titleKey: I18nKey.SKILLS$TRIGGERED_SKILL_KNOWLEDGE,
+        }
+      : null;
+  }
+  if (
+    isObservationEvent(event) &&
+    event.observation.kind === "InvokeSkillObservation"
+  ) {
+    const items = getInvokeSkillItems(
+      event as ObservationEvent<InvokeSkillObservation>,
+    );
+    return items.length > 0
+      ? { items, titleKey: I18nKey.SKILLS$INVOKED_SKILL_KNOWLEDGE }
+      : null;
+  }
+  return null;
+}
+
+export function GenericEventMessageWrapper({
+  event,
+  correspondingAction,
+}: GenericEventMessageWrapperProps) {
+  const { title, details } = getEventContent(event, correspondingAction);
+
+  // TaskTrackerObservation has its own rendering
+  if (
+    !isSkillReadyEvent(event) &&
+    isObservationEvent(event) &&
+    event.observation.kind === "TaskTrackerObservation"
+  ) {
+    return <div>{details}</div>;
+  }
+
+  // Determine success status
+  let success: ObservationResultStatus | undefined;
+  if (isSkillReadyEvent(event)) {
+    success = "success";
+  } else if (isObservationEvent(event)) {
+    success = getObservationResult(event);
+  } else if (isACPToolCallEvent(event)) {
+    success = getACPToolCallResult(event);
+  }
+
+  // Skill Ready events and invoke-skill tool observations both render the
+  // expandable skill-knowledge list (with the skills icon); they differ only in
+  // the header label.
+  const skillKnowledge = getSkillKnowledge(event);
+  const bodyDetails = skillKnowledge ? (
+    <SkillReadyContentList
+      items={skillKnowledge.items}
+      titleKey={skillKnowledge.titleKey}
+    />
+  ) : (
+    details
+  );
+
+  // Markdown file-editor cards carry a clipped preview; expand them by
+  // default so the artifact is visible without an extra chevron click.
+  const initiallyExpanded =
+    !isSkillReadyEvent(event) &&
+    isMarkdownFileEditorEvent(event, correspondingAction);
+
+  return (
+    <div>
+      <GenericEventMessage
+        title={title}
+        details={bodyDetails}
+        success={success}
+        initiallyExpanded={initiallyExpanded}
+        timestamp={event.timestamp}
+        titleIcon={
+          skillKnowledge ? (
+            <SkillsIcon className="h-4 w-4 stroke-[var(--oh-muted)] flex-shrink-0 mr-2" />
+          ) : undefined
+        }
+      />
+    </div>
+  );
+}

src/components/conversation-events/chat/event-message-components/hook-execution-event-message.tsx

@@ -0,0 +1 @@
+export { HookExecutionEventMessage } from "#/components/shared/hook-execution-event-message";

src/components/conversation-events/chat/event-message-components/index.ts

@@ -0,0 +1,8 @@
+export { UserAssistantEventMessage } from "./user-assistant-event-message";
+export { ErrorEventMessage } from "./error-event-message";
+export { FinishEventMessage } from "./finish-event-message";
+export { GenericEventMessageWrapper } from "./generic-event-message-wrapper";
+export { ThoughtEventMessage } from "./thought-event-message";
+export { HookExecutionEventMessage } from "./hook-execution-event-message";
+export { EventGroup } from "./event-group";
+export { CriticResultDisplay } from "./critic-result-display";

src/components/conversation-events/chat/event-message-components/skill-item-expanded.tsx

@@ -0,0 +1,96 @@
+import { useTranslation } from "react-i18next";
+import { I18nKey } from "#/i18n/declaration";
+import { METADATA_PREFIXES } from "#/utils/constants";
+import { Typography } from "#/ui/typography";
+import { MarkdownRenderer } from "../../../features/markdown/markdown-renderer";
+
+interface ParsedSkillContent {
+  matchInfo: string | null;
+  filePath: string | null;
+  body: string;
+}
+
+/**
+ * Parses skill content into metadata (keyword match info, file path)
+ * and the actual skill body.
+ */
+export function parseSkillContent(content: string): ParsedSkillContent {
+  const lines = content.split("\n");
+  let matchInfo: string | null = null;
+  let filePath: string | null = null;
+  let bodyStartIndex = 0;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+
+    if (line.startsWith(METADATA_PREFIXES[0])) {
+      matchInfo = line.trim();
+      bodyStartIndex = i + 1;
+    } else if (line.startsWith(METADATA_PREFIXES[2])) {
+      filePath = line.replace(METADATA_PREFIXES[2], "").trim();
+      bodyStartIndex = i + 1;
+    } else if (
+      line.startsWith(METADATA_PREFIXES[1]) ||
+      line.startsWith(METADATA_PREFIXES[3])
+    ) {
+      bodyStartIndex = i + 1;
+    } else if (line.trim() === "" && i <= bodyStartIndex) {
+      bodyStartIndex = i + 1;
+    } else {
+      break;
+    }
+  }
+
+  return {
+    matchInfo,
+    filePath,
+    body: lines.slice(bodyStartIndex).join("\n").trim(),
+  };
+}
+
+/**
+ * Wraps `<important>...</important>` tags in the content with bold markers
+ * so the markdown renderer displays them as bold text.
+ */
+export function styleImportantTags(text: string): string {
+  return text.replace(
+    /<important>([\s\S]*?)<\/important>/gi,
+    (_match, inner) => `**${inner.trim()}**`,
+  );
+}
+
+interface SkillItemExpandedProps {
+  content: string;
+}
+
+export function SkillItemExpanded({ content }: SkillItemExpandedProps) {
+  const { t } = useTranslation("openhands");
+  const { matchInfo, filePath, body } = parseSkillContent(content);
+  const hasMetadata = matchInfo || filePath;
+
+  return (
+    <div className="pl-6 pr-2 pt-2 pb-2">
+      {hasMetadata && (
+        <div className="mb-3 text-sm text-[var(--oh-muted)] space-y-1">
+          {matchInfo && <p>{matchInfo}</p>}
+          {filePath && (
+            <p>
+              <Typography.Text className="text-[var(--oh-text-subtle)]">
+                {t(I18nKey.COMMON$PATH)}{" "}
+              </Typography.Text>
+              <code className="bg-[var(--oh-surface)] px-1.5 py-0.5 rounded text-[var(--oh-text-tertiary)]">
+                {filePath}
+              </code>
+            </p>
+          )}
+        </div>
+      )}
+
+      {hasMetadata && body && (
+        <hr className="border-[var(--oh-border-subtle)] mb-3" />
+      )}
+
+      {body && <MarkdownRenderer>{styleImportantTags(body)}</MarkdownRenderer>}
+    </div>
+  );
+}

src/components/conversation-events/chat/event-message-components/skill-ready-content-list.tsx

@@ -0,0 +1,73 @@
+import React from "react";
+import { useTranslation } from "react-i18next";
+import { ChevronDown, ChevronRight } from "lucide-react";
+import { I18nKey } from "#/i18n/declaration";
+import { Typography } from "#/ui/typography";
+import { SkillReadyItem } from "../event-content-helpers/create-skill-ready-event";
+import { SkillItemExpanded } from "./skill-item-expanded";
+
+interface SkillReadyContentListProps {
+  items: SkillReadyItem[];
+  /**
+   * Translation key for the list header. Defaults to the "Triggered Skill
+   * Knowledge:" label used by Skill Ready events; invoke-skill observations
+   * pass "Invoked Skill Knowledge:" instead.
+   */
+  titleKey?: I18nKey;
+}
+
+export function SkillReadyContentList({
+  items,
+  titleKey = I18nKey.SKILLS$TRIGGERED_SKILL_KNOWLEDGE,
+}: SkillReadyContentListProps) {
+  const { t } = useTranslation("openhands");
+  const [expandedSkills, setExpandedSkills] = React.useState<
+    Record<string, boolean>
+  >({});
+
+  const toggleSkill = (name: string) => {
+    setExpandedSkills((prev) => ({ ...prev, [name]: !prev[name] }));
+  };
+
+  return (
+    <div className="flex flex-col gap-1 mt-1">
+      <Typography.Text className="font-bold text-[var(--oh-foreground)] text-sm px-2 py-1">
+        {t(titleKey)}
+      </Typography.Text>
+      {items.map((item) => {
+        const isExpanded = expandedSkills[item.name] || false;
+
+        return (
+          <div
+            key={item.name}
+            className="border border-[var(--oh-border-subtle)] rounded-md overflow-hidden"
+          >
+            <button
+              type="button"
+              onClick={() => toggleSkill(item.name)}
+              className="w-full py-1.5 px-2 text-left flex items-center gap-2 hover:bg-tertiary transition-colors cursor-pointer"
+            >
+              <Typography.Text className="text-[var(--oh-text-tertiary)]">
+                {isExpanded ? (
+                  <ChevronDown size={14} />
+                ) : (
+                  <ChevronRight size={14} />
+                )}
+              </Typography.Text>
+              <Typography.Text className="font-normal text-[var(--oh-foreground)] text-sm">
+                {item.name}
+              </Typography.Text>
+            </button>
+
+            {isExpanded && item.content && (
+              <>
+                <hr className="border-[var(--oh-border-subtle)]" />
+                <SkillItemExpanded content={item.content} />
+              </>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}

src/components/conversation-events/chat/event-message-components/thought-event-message.tsx

@@ -0,0 +1,40 @@
+import React from "react";
+import { ActionEvent } from "#/types/agent-server/core";
+import { ChatMessage } from "../../../features/chat/chat-message";
+
+interface ThoughtEventMessageProps {
+  event: ActionEvent;
+  actions?: Array<{
+    icon: React.ReactNode;
+    onClick: () => void;
+    tooltip?: string;
+  }>;
+  isFromPlanningAgent?: boolean;
+}
+
+export function ThoughtEventMessage({
+  event,
+  actions,
+  isFromPlanningAgent = false,
+}: ThoughtEventMessageProps) {
+  // Extract thought content from the action event
+  const thoughtContent = event.thought
+    .filter((t) => t.type === "text")
+    .map((t) => t.text)
+    .join("\n");
+
+  // If there's no thought content, don't render anything
+  if (!thoughtContent) {
+    return null;
+  }
+
+  return (
+    <ChatMessage
+      type="agent"
+      message={thoughtContent}
+      actions={actions}
+      isFromPlanningAgent={isFromPlanningAgent}
+      timestamp={event.timestamp}
+    />
+  );
+}

src/components/conversation-events/chat/event-message-components/user-assistant-event-message.tsx

@@ -0,0 +1,132 @@
+import React from "react";
+import { useTranslation } from "react-i18next";
+import { useNavigation } from "#/context/navigation-context";
+import { MessageEvent } from "#/types/agent-server/core";
+import { ChatMessage } from "../../../features/chat/chat-message";
+import { ImageCarousel } from "../../../features/images/image-carousel";
+import { parseMessageFromEvent } from "../event-content-helpers/parse-message-from-event";
+import { CriticResultDisplay } from "./critic-result-display";
+import { CollapsibleThinking } from "./collapsible-thinking";
+import { splitInlineThink } from "../event-thought-helpers";
+import RepoForkedIcon from "#/icons/repo-forked.svg?react";
+import { I18nKey } from "#/i18n/declaration";
+import { useOptionalConversationId } from "#/hooks/use-conversation-id";
+import { useActiveBackend } from "#/contexts/active-backend-context";
+import { useForkConversation } from "#/hooks/mutation/use-fork-conversation";
+import { useConversationStore } from "#/stores/conversation-store";
+import ConversationService from "#/api/conversation-service/conversation-service.api";
+import { displayErrorToast } from "#/utils/custom-toast-handlers";
+
+interface UserAssistantEventMessageProps {
+  event: MessageEvent;
+  isLastMessage: boolean;
+  isFromPlanningAgent: boolean;
+}
+
+export function UserAssistantEventMessage({
+  event,
+  isFromPlanningAgent,
+}: UserAssistantEventMessageProps) {
+  const { t } = useTranslation("openhands");
+  const { navigate } = useNavigation();
+  const { conversationId } = useOptionalConversationId();
+  const isCloud = useActiveBackend().backend.kind === "cloud";
+  const { mutate: forkConversation, isPending: isForking } =
+    useForkConversation();
+  const setMessageToSend = useConversationStore(
+    (state) => state.setMessageToSend,
+  );
+  // Blocks a same-tick double-click, before `isForking` flips.
+  const forkInFlightRef = React.useRef(false);
+
+  const parsed = parseMessageFromEvent(event);
+  // Route an inline <think> block (e.g. from a streamed reply) to the thinking
+  // section so reloaded conversations match the live rendering.
+  const { reasoning, message } =
+    event.source === "agent"
+      ? splitInlineThink(parsed)
+      : { reasoning: "", message: parsed };
+
+  const imageUrls: string[] = [];
+  if (Array.isArray(event.llm_message.content)) {
+    event.llm_message.content.forEach((content) => {
+      if (content.type === "image") {
+        imageUrls.push(...content.image_urls);
+      }
+    });
+  }
+
+  // "Branch from here": a user message is "edit message" (excludes the message,
+  // restores its text to the composer); an assistant message branches
+  // inclusively. Local agent-server only, inside a conversation.
+  const canBranch = !isCloud && !!conversationId;
+  const handleBranch = () => {
+    if (!conversationId || isForking || forkInFlightRef.current) return;
+    forkInFlightRef.current = true;
+
+    // Distinct title so the fork doesn't read identically to its source.
+    // getCurrentConversation() is a shared singleton — match the id in case it
+    // still holds the previously-viewed conversation.
+    const source = ConversationService.getCurrentConversation();
+    const sourceTitle =
+      source?.id === conversationId ? source.title : undefined;
+    const branchTitle = sourceTitle ? `${sourceTitle} (branch)` : undefined;
+
+    // Only edit when there's text: an image-only message parses to "", so
+    // branch it inclusively rather than dropping the image.
+    const isEdit = event.source === "user" && message.length > 0;
+
+    forkConversation(
+      {
+        sourceConversationId: conversationId,
+        eventId: event.id,
+        ...(isEdit ? { editText: message } : {}),
+        ...(branchTitle ? { title: branchTitle } : {}),
+      },
+      {
+        onSuccess: ({ info, excluded }) => {
+          navigate(`/conversations/${info.id}`);
+          // Prefill only when excluded (else the send duplicates it). Deferred
+          // so the new conversation's composer receives it (as useLaunchSkillInChat).
+          if (excluded) {
+            window.setTimeout(() => setMessageToSend(message), 0);
+          }
+        },
+        onError: (error) =>
+          displayErrorToast(error instanceof Error ? error.message : null),
+        onSettled: () => {
+          forkInFlightRef.current = false;
+        },
+      },
+    );
+  };
+  const actions = canBranch
+    ? [
+        {
+          icon: <RepoForkedIcon width={15} height={15} aria-hidden />,
+          onClick: handleBranch,
+          tooltip: t(I18nKey.CHAT_INTERFACE$BRANCH_FROM_HERE),
+        },
+      ]
+    : undefined;
+
+  return (
+    <>
+      {reasoning && <CollapsibleThinking content={reasoning} />}
+      <ChatMessage
+        type={event.source}
+        message={message}
+        isFromPlanningAgent={isFromPlanningAgent}
+        actions={actions}
+        timestamp={event.timestamp}
+      >
+        {imageUrls.length > 0 && (
+          <ImageCarousel size="small" images={imageUrls} />
+        )}
+      </ChatMessage>
+      {event.source === "agent" && event.critic_result != null && (
+        <CriticResultDisplay criticResult={event.critic_result} />
+      )}
+    </>
+  );
+}

src/components/conversation-events/chat/event-message.tsx

@@ -0,0 +1,375 @@
+import React from "react";
+import {
+  OpenHandsEvent,
+  MessageEvent,
+  ActionEvent,
+} from "#/types/agent-server/core";
+import {
+  FinishAction,
+  ThinkAction,
+} from "#/types/agent-server/core/base/action";
+import {
+  isActionEvent,
+  isObservationEvent,
+  isAgentErrorEvent,
+  isUserMessageEvent,
+  isPlanningFileEditorObservationEvent,
+  isHookExecutionEvent,
+  isACPToolCallEvent,
+  isStreamingDeltaEvent,
+  isConversationStateUpdateEvent,
+  isGoalConversationStateUpdateEvent,
+} from "#/types/agent-server/type-guards";
+import { useConfig } from "#/hooks/query/use-config";
+import { useConversationStore } from "#/stores/conversation-store";
+import { useAgentState, usePlanningAgentState } from "#/hooks/use-agent-state";
+import { AgentState } from "#/types/agent-state";
+import { ChatMessage } from "#/components/features/chat/chat-message";
+import { GoalStatusContent } from "#/components/features/chat/goal-status-content";
+import { PlanPreview } from "../../features/chat/plan-preview";
+import { ErrorEventMessage } from "./event-message-components/error-event-message";
+import { UserAssistantEventMessage } from "./event-message-components/user-assistant-event-message";
+import { FinishEventMessage } from "./event-message-components/finish-event-message";
+import { GenericEventMessageWrapper } from "./event-message-components/generic-event-message-wrapper";
+import { ThoughtEventMessage } from "./event-message-components/thought-event-message";
+import { CollapsibleThinking } from "./event-message-components/collapsible-thinking";
+import { HookExecutionEventMessage } from "./event-message-components/hook-execution-event-message";
+import { createSkillReadyEvent } from "./event-content-helpers/create-skill-ready-event";
+import { shouldShowPlanPreview } from "./hooks/use-plan-preview-events";
+import { getReasoningContent, splitInlineThink } from "./event-thought-helpers";
+
+interface EventMessageProps {
+  event: OpenHandsEvent & { isFromPlanningAgent?: boolean };
+  messages: OpenHandsEvent[];
+  isLastMessage: boolean;
+  isInLast10Actions: boolean;
+  /** Set of event IDs that should render PlanPreview (one per user message phase) */
+  planPreviewEventIds?: Set<string>;
+  /**
+   * When true, do not render the inline `ThoughtEventMessage` for action /
+   * observation events. The caller is expected to render the thought
+   * separately (e.g. via a hoisted "thought" rendered item) so the message
+   * pane and the in-group rendering don't double up on the same content.
+   * Has no effect on `ThinkAction`, whose thought IS its action body.
+   */
+  suppressThought?: boolean;
+}
+
+const getActivatedSkills = (event: MessageEvent): string[] =>
+  event.activated_skills || [];
+
+/**
+ * Checks if extended content contains valid text content.
+ */
+const hasValidExtendedContent = (
+  extendedContent: MessageEvent["extended_content"],
+): boolean => {
+  if (!extendedContent || extendedContent.length === 0) {
+    return false;
+  }
+
+  return extendedContent.some(
+    (content) => content.type === "text" && content.text.trim().length > 0,
+  );
+};
+
+/**
+ * Determines if a Skill Ready event should be displayed for the given message event.
+ */
+const shouldShowSkillReadyEvent = (messageEvent: MessageEvent): boolean => {
+  const activatedSkills = getActivatedSkills(messageEvent);
+  const hasActivatedSkills = activatedSkills.length > 0;
+  const hasExtendedContent = hasValidExtendedContent(
+    messageEvent.extended_content,
+  );
+
+  return hasActivatedSkills && hasExtendedContent;
+};
+
+interface CommonProps {
+  isLastMessage: boolean;
+  isInLast10Actions: boolean;
+  config: unknown;
+  isFromPlanningAgent: boolean;
+}
+
+/**
+ * Renders a user message with its corresponding Skill Ready event.
+ */
+const renderUserMessageWithSkillReady = (
+  messageEvent: MessageEvent,
+  commonProps: CommonProps,
+  isLastMessage: boolean,
+): React.ReactElement => {
+  try {
+    const skillReadyEvent = createSkillReadyEvent(messageEvent);
+    return (
+      <>
+        <UserAssistantEventMessage
+          event={messageEvent}
+          isLastMessage={false}
+          isFromPlanningAgent={commonProps.isFromPlanningAgent}
+        />
+        <GenericEventMessageWrapper
+          event={skillReadyEvent}
+          isLastMessage={isLastMessage}
+        />
+      </>
+    );
+  } catch (error) {
+    // If skill ready event creation fails, just render the user message
+    return (
+      <UserAssistantEventMessage
+        event={messageEvent}
+        isLastMessage={isLastMessage}
+        isFromPlanningAgent={commonProps.isFromPlanningAgent}
+      />
+    );
+  }
+};
+
+/**
+ * Renders the plan preview. Its own component so `usePlanningAgentState()`
+ * only subscribes on this rare row, not every message in the conversation.
+ */
+function PlanningObservationPreview({
+  planContent,
+  isLastMessage,
+  isMainAgentRunning,
+}: {
+  planContent: string | null;
+  isLastMessage: boolean;
+  isMainAgentRunning: boolean;
+}) {
+  const {
+    localPlanningConversationId,
+    curPlanningAgentState,
+    isPlanningAgentRunning,
+  } = usePlanningAgentState();
+
+  // Guard on the id explicitly — useAgentState(undefined) falls back to the
+  // route conversation, which could be mistaken for the planner's activity.
+  const isStreaming =
+    isLastMessage &&
+    !!localPlanningConversationId &&
+    curPlanningAgentState === AgentState.RUNNING;
+
+  return (
+    <PlanPreview
+      planContent={planContent}
+      isStreaming={isStreaming}
+      isBuildDisabled={isMainAgentRunning || isPlanningAgentRunning}
+    />
+  );
+}
+
+export function EventMessage({
+  event,
+  messages,
+  isLastMessage,
+  isInLast10Actions,
+  planPreviewEventIds,
+  suppressThought = false,
+}: EventMessageProps) {
+  const { data: config } = useConfig();
+  const { planContent } = useConversationStore();
+  const { curAgentState } = useAgentState();
+
+  // Planner-running state is folded in by PlanningObservationPreview below,
+  // not read here, to avoid a second useAgentState() subscription per row.
+  const isAgentRunning =
+    curAgentState === AgentState.RUNNING ||
+    curAgentState === AgentState.LOADING;
+
+  // Read isFromPlanningAgent directly from the event object
+  const isFromPlanningAgent = event.isFromPlanningAgent || false;
+
+  // Common props for components that need them
+  const commonProps = {
+    isLastMessage,
+    isInLast10Actions,
+    config,
+    isFromPlanningAgent,
+  };
+
+  // Finished `/goal` loop: render the terminal status inline so it settles into
+  // the conversation. should-render-event.ts only lets the terminal goal event
+  // through; the active loop is shown by the separate bottom GoalStatusBanner.
+  if (
+    isConversationStateUpdateEvent(event) &&
+    isGoalConversationStateUpdateEvent(event)
+  ) {
+    return <GoalStatusContent status={event.value} />;
+  }
+
+  // Agent error events
+  if (isAgentErrorEvent(event)) {
+    return <ErrorEventMessage event={event} {...commonProps} />;
+  }
+
+  // Hook execution events
+  if (isHookExecutionEvent(event)) {
+    return <HookExecutionEventMessage event={event} />;
+  }
+
+  // ACP sub-agent tool call events (Claude Code, Codex, Gemini CLI, …)
+  // render through the same generic wrapper used for observation events so
+  // the card shape, success indicator and markdown rendering all match.
+  if (isACPToolCallEvent(event)) {
+    return (
+      <GenericEventMessageWrapper event={event} isLastMessage={isLastMessage} />
+    );
+  }
+
+  if (isStreamingDeltaEvent(event)) {
+    // Route an inline <think> block to the thinking section, not the bubble.
+    const { reasoning: inlineThink, message } = splitInlineThink(
+      event.content ?? "",
+      { streaming: true },
+    );
+    const reasoningContent = [event.reasoning_content ?? "", inlineThink]
+      .filter(Boolean)
+      .join("\n\n");
+    return (
+      <>
+        {reasoningContent && <CollapsibleThinking content={reasoningContent} />}
+        {message && (
+          <ChatMessage
+            type="agent"
+            message={message}
+            isFromPlanningAgent={isFromPlanningAgent}
+            timestamp={event.timestamp}
+          />
+        )}
+      </>
+    );
+  }
+
+  // Finish actions
+  if (isActionEvent(event) && event.action.kind === "FinishAction") {
+    return (
+      <FinishEventMessage
+        event={event as ActionEvent<FinishAction>}
+        {...commonProps}
+      />
+    );
+  }
+
+  // ThinkAction - render the thought inside a collapsible section so it
+  // doesn't dominate the chat, especially when the thinking language
+  // (usually English) differs from the conversation language.
+  if (isActionEvent(event) && event.action.kind === "ThinkAction") {
+    const thinkAction = event as ActionEvent<ThinkAction>;
+    return <CollapsibleThinking content={thinkAction.action.thought} />;
+  }
+
+  // Action events - render thought + action (will be replaced by thought + observation)
+  if (isActionEvent(event)) {
+    const reasoningContent = getReasoningContent(event);
+    return (
+      <>
+        {reasoningContent && <CollapsibleThinking content={reasoningContent} />}
+        {!suppressThought && (
+          <ThoughtEventMessage
+            event={event}
+            isFromPlanningAgent={isFromPlanningAgent}
+          />
+        )}
+        <GenericEventMessageWrapper
+          event={event}
+          isLastMessage={isLastMessage}
+        />
+      </>
+    );
+  }
+
+  // Observation events - find the corresponding action and render thought + observation
+  if (isObservationEvent(event)) {
+    // Handle PlanningFileEditorObservation specially
+    if (isPlanningFileEditorObservationEvent(event)) {
+      // Only show PlanPreview if this event is marked as the one to display
+      // (last PlanningFileEditorObservation in its phase)
+      if (
+        planPreviewEventIds &&
+        shouldShowPlanPreview(event.id, planPreviewEventIds)
+      ) {
+        return (
+          <PlanningObservationPreview
+            planContent={planContent}
+            isLastMessage={isLastMessage}
+            isMainAgentRunning={isAgentRunning}
+          />
+        );
+      }
+      // Not the designated preview event for this phase - render nothing
+      // This prevents duplicate previews within the same phase
+      return null;
+    }
+
+    // Find the action that this observation is responding to
+    const correspondingAction = messages.find(
+      (msg) => isActionEvent(msg) && msg.id === event.action_id,
+    );
+
+    // Skip ThoughtEventMessage for ThinkAction (thought IS the action)
+    const shouldShowThought =
+      !suppressThought &&
+      correspondingAction &&
+      isActionEvent(correspondingAction) &&
+      correspondingAction.action.kind !== "ThinkAction";
+
+    const reasoningContent =
+      correspondingAction && isActionEvent(correspondingAction)
+        ? getReasoningContent(correspondingAction)
+        : "";
+
+    return (
+      <>
+        {reasoningContent && <CollapsibleThinking content={reasoningContent} />}
+        {shouldShowThought && (
+          <ThoughtEventMessage
+            event={correspondingAction}
+            isFromPlanningAgent={isFromPlanningAgent}
+          />
+        )}
+        <GenericEventMessageWrapper
+          event={event}
+          isLastMessage={isLastMessage}
+          correspondingAction={
+            correspondingAction && isActionEvent(correspondingAction)
+              ? correspondingAction
+              : undefined
+          }
+        />
+      </>
+    );
+  }
+
+  // Message events (user and assistant messages)
+  if (!isActionEvent(event) && !isObservationEvent(event)) {
+    const messageEvent = event as MessageEvent;
+
+    // Check if this is a user message that should display a Skill Ready event
+    if (isUserMessageEvent(event) && shouldShowSkillReadyEvent(messageEvent)) {
+      return renderUserMessageWithSkillReady(
+        messageEvent,
+        commonProps,
+        isLastMessage,
+      );
+    }
+
+    // Render normal message event (user or assistant)
+    return (
+      <UserAssistantEventMessage
+        event={messageEvent}
+        {...commonProps}
+        isLastMessage={isLastMessage}
+      />
+    );
+  }
+
+  // Generic fallback for all other events
+  return (
+    <GenericEventMessageWrapper event={event} isLastMessage={isLastMessage} />
+  );
+}

src/components/conversation-events/chat/event-thought-helpers.ts

@@ -0,0 +1,112 @@
+import { ActionEvent, OpenHandsEvent } from "#/types/agent-server/core";
+import { ThinkingBlock } from "#/types/agent-server/core/base/event";
+import {
+  isActionEvent,
+  isObservationEvent,
+} from "#/types/agent-server/type-guards";
+
+/**
+ * Returns the displayable thought text of an `ActionEvent`, or an empty
+ * string if the event has no usable thought content.
+ *
+ * Mirrors the logic used by `ThoughtEventMessage` so callers stay in sync
+ * with what gets rendered.
+ */
+export const getActionThoughtText = (action: ActionEvent): string =>
+  action.thought
+    .filter((t) => t.type === "text")
+    .map((t) => t.text)
+    .join("\n");
+
+/**
+ * Extracts extended thinking / reasoning content from an `ActionEvent`.
+ *
+ * Prefers `reasoning_content` (a plain string produced by many reasoning
+ * models). Falls back to the text from `thinking_blocks` (Anthropic
+ * extended thinking). Returns an empty string when neither is available.
+ */
+export const getReasoningContent = (action: ActionEvent): string => {
+  if (action.reasoning_content) {
+    return action.reasoning_content;
+  }
+
+  if (action.thinking_blocks?.length) {
+    return action.thinking_blocks
+      .filter((b): b is ThinkingBlock => b.type === "thinking")
+      .map((b) => b.thinking)
+      .join("\n\n");
+  }
+
+  return "";
+};
+
+export const hasNonEmptyThought = (action: ActionEvent): boolean =>
+  getActionThoughtText(action).trim().length > 0;
+
+/**
+ * Splits a leading `<think>…</think>` reasoning block out of assistant content
+ * so it renders in the collapsible thinking section, not the message bubble.
+ * Some models stream reasoning inline instead of via `reasoning_content`.
+ *
+ * Conservative to avoid mangling normal messages: only a `<think>` at the very
+ * start is touched (later occurrences, e.g. quoted in docs, stay verbatim),
+ * only the first block is peeled, and an unclosed leading `<think>` is reasoning
+ * only while `streaming` — in a finalized message it's literal output.
+ */
+export const splitInlineThink = (
+  content: string,
+  options?: { streaming?: boolean },
+): { reasoning: string; message: string } => {
+  const OPEN = "<think>";
+  const CLOSE = "</think>";
+
+  // Only a <think> at the very start is reasoning.
+  const leading = content.replace(/^\s+/, "");
+  if (!leading.startsWith(OPEN)) {
+    return { reasoning: "", message: content };
+  }
+
+  const afterOpen = leading.slice(OPEN.length);
+  const close = afterOpen.indexOf(CLOSE);
+
+  if (close === -1) {
+    // Unclosed: reasoning-in-progress while streaming, else literal output.
+    return options?.streaming
+      ? { reasoning: afterOpen.trim(), message: "" }
+      : { reasoning: "", message: content };
+  }
+
+  return {
+    reasoning: afterOpen.slice(0, close).trim(),
+    message: afterOpen.slice(close + CLOSE.length).trim(),
+  };
+};
+
+/**
+ * Find the `ActionEvent` whose thought should be rendered alongside the
+ * given UI event. For an `ActionEvent` the thought belongs to itself; for
+ * an `ObservationEvent` we look up the matching action in `allEvents`.
+ *
+ * `ThinkAction` is intentionally excluded because its thought IS the
+ * action body and is rendered through a separate codepath.
+ */
+export const getThoughtSourceAction = (
+  event: OpenHandsEvent,
+  allEvents: OpenHandsEvent[],
+): ActionEvent | null => {
+  if (isActionEvent(event)) {
+    if (event.action.kind === "ThinkAction") return null;
+    return hasNonEmptyThought(event) ? event : null;
+  }
+
+  if (isObservationEvent(event)) {
+    const action = allEvents.find(
+      (e): e is ActionEvent => isActionEvent(e) && e.id === event.action_id,
+    );
+    if (!action) return null;
+    if (action.action.kind === "ThinkAction") return null;
+    return hasNonEmptyThought(action) ? action : null;
+  }
+
+  return null;
+};

src/components/conversation-events/chat/group-events.ts

@@ -0,0 +1,130 @@
+import { ActionEvent, OpenHandsEvent } from "#/types/agent-server/core";
+import {
+  isActionEvent,
+  isObservationEvent,
+  isPlanningFileEditorObservationEvent,
+} from "#/types/agent-server/type-guards";
+import { isMarkdownFileEditorEvent } from "#/components/features/chat/tool-visualizers/primitives/markdown-file-preview";
+import { getThoughtSourceAction } from "./event-thought-helpers";
+
+/** Minimum run-length before consecutive actions get folded into a single
+ *  collapsible group. Even pairs are folded so the chat scroll stays compact
+ *  when the agent fires off back-to-back tool calls. */
+export const EVENT_GROUP_MIN_SIZE = 2;
+
+/**
+ * Returns true if the given event is one of the action / observation cards
+ * that we want to fold into an `EventGroup` when several appear in a row.
+ *
+ * Events that have their own dedicated rendering (FinishAction, ThinkAction,
+ * HookExecution, AgentError, MessageEvent, PlanPreview, markdown file
+ * artifacts, TaskTracker) are treated as group breakers.
+ */
+export const isGroupableEvent = (
+  event: OpenHandsEvent,
+  correspondingAction?: ActionEvent,
+): boolean => {
+  if (isActionEvent(event)) {
+    const { kind } = event.action;
+    if (kind === "FinishAction" || kind === "ThinkAction") {
+      return false;
+    }
+    // Keep markdown *create* artifact cards outside collapsed groups so their
+    // clipped preview is visible without expanding a parent summary.
+    if (isMarkdownFileEditorEvent(event, correspondingAction)) {
+      return false;
+    }
+    return true;
+  }
+
+  if (isObservationEvent(event)) {
+    if (isPlanningFileEditorObservationEvent(event)) {
+      return false;
+    }
+    if (isMarkdownFileEditorEvent(event, correspondingAction)) {
+      return false;
+    }
+    if (event.observation.kind === "TaskTrackerObservation") {
+      return false;
+    }
+    return true;
+  }
+
+  return false;
+};
+
+export type RenderedItem =
+  | { kind: "single"; event: OpenHandsEvent; index: number }
+  | { kind: "thought"; action: ActionEvent; index: number }
+  | { kind: "group"; events: OpenHandsEvent[]; startIndex: number };
+
+/**
+ * Walk a list of UI events and bucket consecutive groupable events into
+ * `group` items. Anything that breaks the run, or runs shorter than
+ * `EVENT_GROUP_MIN_SIZE`, is emitted as `single` items so they keep rendering
+ * the way they always have.
+ *
+ * Whenever a groupable event carries an agent thought (either an
+ * `ActionEvent.thought` or the corresponding action of an
+ * `ObservationEvent`), the thought is hoisted out as its own `thought`
+ * `RenderedItem`, the current run is flushed, and a new run is started with
+ * the event itself. This keeps reasoning text in the main message stream
+ * instead of buried inside a collapsed action group.
+ *
+ * `allEvents` should be the full event history so observations can find
+ * their matching action; if omitted, it defaults to `events`.
+ */
+export const groupEvents = (
+  events: OpenHandsEvent[],
+  minSize: number = EVENT_GROUP_MIN_SIZE,
+  allEvents: OpenHandsEvent[] = events,
+): RenderedItem[] => {
+  if (minSize < 1) {
+    throw new Error("minSize must be at least 1");
+  }
+
+  const items: RenderedItem[] = [];
+  const emittedThoughtActionIds = new Set<string>();
+  let run: { events: OpenHandsEvent[]; startIndex: number } | null = null;
+
+  const flushRun = () => {
+    if (!run) return;
+    if (run.events.length >= minSize) {
+      items.push({
+        kind: "group",
+        events: run.events,
+        startIndex: run.startIndex,
+      });
+    } else {
+      run.events.forEach((event, offset) => {
+        items.push({ kind: "single", event, index: run!.startIndex + offset });
+      });
+    }
+    run = null;
+  };
+
+  events.forEach((event, index) => {
+    const correspondingAction = isObservationEvent(event)
+      ? allEvents.find(
+          (candidate): candidate is ActionEvent =>
+            isActionEvent(candidate) && candidate.id === event.action_id,
+        )
+      : undefined;
+    if (isGroupableEvent(event, correspondingAction)) {
+      const thoughtAction = getThoughtSourceAction(event, allEvents);
+      if (thoughtAction && !emittedThoughtActionIds.has(thoughtAction.id)) {
+        flushRun();
+        emittedThoughtActionIds.add(thoughtAction.id);
+        items.push({ kind: "thought", action: thoughtAction, index });
+      }
+      if (!run) run = { events: [], startIndex: index };
+      run.events.push(event);
+    } else {
+      flushRun();
+      items.push({ kind: "single", event, index });
+    }
+  });
+
+  flushRun();
+  return items;
+};

src/components/conversation-events/chat/hooks/use-plan-preview-events.ts

@@ -0,0 +1,119 @@
+import { useMemo } from "react";
+import { OpenHandsEvent } from "#/types/agent-server/core";
+import {
+  isUserMessageEvent,
+  isPlanningFileEditorObservationEvent,
+} from "#/types/agent-server/type-guards";
+
+/**
+ * Groups events into phases based on user messages.
+ * A phase starts with a user message and includes all subsequent events
+ * until the next user message.
+ *
+ * @param events - The full list of events
+ * @returns Array of phases, where each phase is an array of events
+ */
+function groupEventsByPhase(events: OpenHandsEvent[]): OpenHandsEvent[][] {
+  const phases: OpenHandsEvent[][] = [];
+  let currentPhase: OpenHandsEvent[] = [];
+
+  for (const event of events) {
+    if (isUserMessageEvent(event)) {
+      // Start a new phase with the user message
+      if (currentPhase.length > 0) {
+        phases.push(currentPhase);
+      }
+      currentPhase = [event];
+    } else {
+      // Add event to current phase
+      currentPhase.push(event);
+    }
+  }
+
+  // Don't forget the last phase
+  if (currentPhase.length > 0) {
+    phases.push(currentPhase);
+  }
+
+  return phases;
+}
+
+const isPlanFilePath = (path: string | null): boolean =>
+  path?.toUpperCase().endsWith("PLAN.MD") ?? false;
+
+/**
+ * Finds the last PlanningFileEditorObservation for Plan.md in a phase.
+ *
+ * @param phase - Array of events in a phase
+ * @returns The event ID of the last Plan.md observation, or null
+ */
+function findLastPlanningObservationInPhase(
+  phase: OpenHandsEvent[],
+): string | null {
+  for (let i = phase.length - 1; i >= 0; i -= 1) {
+    const event = phase[i];
+    if (
+      isPlanningFileEditorObservationEvent(event) &&
+      isPlanFilePath(event.observation.path)
+    ) {
+      return event.id;
+    }
+  }
+  return null;
+}
+
+export interface PlanPreviewEventInfo {
+  eventId: string;
+  /** Index of this plan preview in the conversation (1st, 2nd, etc.) */
+  phaseIndex: number;
+}
+
+/**
+ * Hook to determine which PlanningFileEditorObservation events should render PlanPreview.
+ *
+ * This hook implements phase-based grouping where:
+ * - A phase starts with a user message and ends at the next user message
+ * - Only the LAST PlanningFileEditorObservation in each phase shows PlanPreview
+ * - This ensures only one preview per user request, even with multiple observations
+ *
+ * Scenario handling:
+ * - Scenario 1 (Create plan): Multiple observations in one phase → 1 preview
+ * - Scenario 2 (Create then update): Two user messages → two phases → 2 previews
+ * - Scenario 3 (Create + update while processing): Two user messages → 2 previews
+ *
+ * @param allEvents - Full list of v1 events (for phase detection)
+ * @returns Set of event IDs that should render PlanPreview
+ */
+export function usePlanPreviewEvents(allEvents: OpenHandsEvent[]): Set<string> {
+  return useMemo(() => {
+    const planPreviewEventIds = new Set<string>();
+
+    // Group events by phases (user message boundaries)
+    const phases = groupEventsByPhase(allEvents);
+
+    // For each phase, find the last PlanningFileEditorObservation
+    phases.forEach((phase) => {
+      const lastPlanningObservationId =
+        findLastPlanningObservationInPhase(phase);
+      if (lastPlanningObservationId) {
+        planPreviewEventIds.add(lastPlanningObservationId);
+      }
+    });
+
+    return planPreviewEventIds;
+  }, [allEvents]);
+}
+
+/**
+ * Check if a specific event should render PlanPreview.
+ *
+ * @param eventId - The event ID to check
+ * @param planPreviewEventIds - Set of event IDs that should render PlanPreview
+ * @returns true if this event should render PlanPreview
+ */
+export function shouldShowPlanPreview(
+  eventId: string,
+  planPreviewEventIds: Set<string>,
+): boolean {
+  return planPreviewEventIds.has(eventId);
+}

src/components/conversation-events/chat/index.ts

@@ -0,0 +1,8 @@
+export { Messages } from "./messages";
+export { EventMessage } from "./event-message";
+export * from "./event-message-components";
+export { getEventContent } from "./event-content-helpers/get-event-content";
+export {
+  shouldRenderEvent,
+  hasUserEvent,
+} from "./event-content-helpers/should-render-event";

src/components/conversation-events/chat/messages.tsx

@@ -0,0 +1,142 @@
+import React from "react";
+import { OpenHandsEvent } from "#/types/agent-server/core";
+import { EventMessage } from "./event-message";
+import { usePlanPreviewEvents } from "./hooks/use-plan-preview-events";
+import { groupEvents } from "./group-events";
+import { EventGroup } from "./event-message-components/event-group";
+import { ThoughtEventMessage } from "./event-message-components/thought-event-message";
+import { useModelStore } from "#/stores/model-store";
+import { ModelMessages } from "#/components/features/chat/model-messages";
+import { useOptionalConversationId } from "#/hooks/use-conversation-id";
+import { ConversationConfirmationButtons } from "#/components/shared/buttons/conversation-confirmation-buttons";
+
+interface MessagesProps {
+  messages: OpenHandsEvent[]; // UI events (actions replaced by observations)
+  allEvents: OpenHandsEvent[]; // Full event history (for action lookup)
+}
+
+const getLastEventId = (events: OpenHandsEvent[]) => events.at(-1)?.id;
+const getLastEvent = (events: OpenHandsEvent[]) => events.at(-1);
+
+export const Messages: React.FC<MessagesProps> = React.memo(
+  ({ messages, allEvents }) => {
+    const { conversationId } = useOptionalConversationId();
+    // Get the set of event IDs that should render PlanPreview
+    // This ensures only one preview per user message "phase"
+    const planPreviewEventIds = usePlanPreviewEvents(allEvents);
+
+    // Set of event ids that have a /model entry anchored to them — used to
+    // avoid mounting <ModelMessages> for every event (the component would
+    // otherwise early-return null).
+    const modelEntries = useModelStore((s) =>
+      conversationId ? s.entriesByConversation[conversationId] : undefined,
+    );
+    const modelAnchorIds = React.useMemo(() => {
+      if (!modelEntries || modelEntries.length === 0) return null;
+      const ids = new Set<string>();
+      for (const entry of modelEntries) {
+        if (entry.anchorEventId !== null) ids.add(entry.anchorEventId);
+      }
+      return ids.size > 0 ? ids : null;
+    }, [modelEntries]);
+
+    const maybeRenderModelMessages = (eventId: string | number | undefined) => {
+      if (!modelAnchorIds || eventId === undefined) return null;
+      const key = String(eventId);
+      if (!modelAnchorIds.has(key)) return null;
+      return (
+        <ModelMessages conversationId={conversationId} anchorEventId={key} />
+      );
+    };
+
+    // Fold consecutive action/observation events into collapsible groups so a
+    // long sequence of tool calls doesn't dominate the chat scroll. Items that
+    // can't be grouped (or that fall in a short run) are still rendered one by
+    // one, identically to before. Agent thoughts attached to an action are
+    // hoisted out as their own rendered item so they always show up in the
+    // message pane and a thought between actions starts a fresh group.
+    const renderedItems = React.useMemo(
+      () => groupEvents(messages, undefined, allEvents),
+      [messages, allEvents],
+    );
+
+    const renderEventMessage = (
+      event: OpenHandsEvent,
+      index: number,
+      suppressThought: boolean,
+    ) => (
+      <EventMessage
+        key={event.id}
+        event={event}
+        messages={allEvents}
+        isLastMessage={messages.length - 1 === index}
+        isInLast10Actions={messages.length - 1 - index < 10}
+        planPreviewEventIds={planPreviewEventIds}
+        suppressThought={suppressThought}
+      />
+    );
+
+    return (
+      <>
+        {renderedItems.map((item, itemIndex) => {
+          if (item.kind === "single") {
+            return (
+              <React.Fragment key={`single-${item.event.id}`}>
+                {/* Thoughts for singles are also hoisted as their own
+                    "thought" item, so suppress the inline render to avoid
+                    duplication. */}
+                {renderEventMessage(item.event, item.index, true)}
+                {maybeRenderModelMessages(item.event.id)}
+              </React.Fragment>
+            );
+          }
+
+          if (item.kind === "thought") {
+            return (
+              <React.Fragment key={`thought-${item.action.id}`}>
+                <ThoughtEventMessage event={item.action} />
+                {maybeRenderModelMessages(item.action.id)}
+              </React.Fragment>
+            );
+          }
+
+          // A group is "finalized" once another rendered item appears after
+          // it, signalling the agent has moved on. While the group is still
+          // the live tail, it keeps showing the latest action title as its
+          // prominent summary.
+          const isFinalized = itemIndex < renderedItems.length - 1;
+          const groupKey = item.events[0]?.id ?? `group-${item.startIndex}`;
+          return (
+            <React.Fragment key={`group-${groupKey}`}>
+              <EventGroup
+                events={item.events}
+                allEvents={allEvents}
+                isFinalized={isFinalized}
+              >
+                {item.events.map((event, offset) =>
+                  renderEventMessage(event, item.startIndex + offset, true),
+                )}
+              </EventGroup>
+              {item.events.map((event) => (
+                <React.Fragment key={`model-${event.id}`}>
+                  {maybeRenderModelMessages(event.id)}
+                </React.Fragment>
+              ))}
+            </React.Fragment>
+          );
+        })}
+        <ConversationConfirmationButtons />
+      </>
+    );
+  },
+  (prevProps, nextProps) =>
+    prevProps.messages.length === nextProps.messages.length &&
+    prevProps.allEvents.length === nextProps.allEvents.length &&
+    getLastEventId(prevProps.messages) === getLastEventId(nextProps.messages) &&
+    getLastEventId(prevProps.allEvents) ===
+      getLastEventId(nextProps.allEvents) &&
+    getLastEvent(prevProps.messages) === getLastEvent(nextProps.messages) &&
+    getLastEvent(prevProps.allEvents) === getLastEvent(nextProps.allEvents),
+);
+
+Messages.displayName = "Messages";

src/components/conversation-events/chat/task-tracking/task-item.tsx

@@ -0,0 +1,56 @@
+import { useMemo } from "react";
+import { useTranslation } from "react-i18next";
+import { TaskItem as TaskItemType } from "#/types/agent-server/core/base/common";
+import CircleIcon from "#/icons/u-circle.svg?react";
+import CheckCircleIcon from "#/icons/u-check-circle.svg?react";
+import CheckCircleHalfIcon from "#/icons/u-check-circle-half.svg?react";
+import { cn } from "#/utils/utils";
+import { Typography } from "#/ui/typography";
+import { I18nKey } from "#/i18n/declaration";
+
+interface TaskItemProps {
+  task: TaskItemType;
+}
+
+export function TaskItem({ task }: TaskItemProps) {
+  const { t } = useTranslation("openhands");
+
+  const icon = useMemo(() => {
+    switch (task.status) {
+      case "todo":
+        return <CircleIcon className="w-4 h-4 text-[#ffffff]" />;
+      case "in_progress":
+        return <CheckCircleHalfIcon className="w-4 h-4 text-[#ffffff]" />;
+      case "done":
+        return <CheckCircleIcon className="w-4 h-4 text-[var(--oh-muted)]" />;
+      default:
+        return <CircleIcon className="w-4 h-4 text-[#ffffff]" />;
+    }
+  }, [task.status]);
+
+  const isDoneStatus = task.status === "done";
+
+  return (
+    <div
+      className="flex gap-[14px] items-center px-4 py-2 w-full"
+      data-name="item"
+    >
+      <div className="shrink-0">{icon}</div>
+      <div className="flex flex-col items-start justify-center leading-[20px] text-nowrap whitespace-pre font-normal">
+        <Typography.Text
+          className={cn(
+            "text-[12px] text-white",
+            isDoneStatus && "text-[var(--oh-muted)]",
+          )}
+        >
+          {task.title}
+        </Typography.Text>
+        {task.notes && (
+          <Typography.Text className="text-[10px] text-[var(--oh-muted)]">
+            {t(I18nKey.TASK_TRACKING_OBSERVATION$TASK_NOTES)}: {task.notes}
+          </Typography.Text>
+        )}
+      </div>
+    </div>
+  );
+}

src/components/conversation-events/chat/task-tracking/task-list-section.test.tsx

@@ -0,0 +1,69 @@
+import { render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { I18nKey } from "#/i18n/declaration";
+import type { TaskItem as TaskItemType } from "#/types/agent-server/core/base/common";
+import { TaskListSection } from "./task-list-section";
+
+const useTranslationMock = vi.hoisted(() =>
+  vi.fn((namespace: string) => ({
+    t: (key: string) =>
+      namespace === "openhands" ? `translated:${key}` : `missing:${key}`,
+  })),
+);
+
+vi.mock("react-i18next", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("react-i18next")>()),
+  useTranslation: useTranslationMock,
+}));
+
+const createTask = (overrides: Partial<TaskItemType> = {}): TaskItemType => ({
+  title: "Inspect the behavior",
+  notes: "",
+  status: "todo",
+  ...overrides,
+});
+
+describe("task tracking list", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("shows every planned task in its supplied order", () => {
+    const consoleErrorSpy = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => undefined);
+    const taskList = [
+      createTask({ title: "Inspect the behavior" }),
+      createTask({ title: "Add focused coverage", status: "in_progress" }),
+      createTask({ title: "Verify the result", status: "done" }),
+    ];
+
+    const { container } = render(<TaskListSection taskList={taskList} />);
+
+    expect(
+      screen.getByText(`translated:${I18nKey.COMMON$TASKS}`),
+    ).toBeInTheDocument();
+    const renderedTasks = container.querySelectorAll('[data-name="item"]');
+    expect(renderedTasks).toHaveLength(3);
+    expect(Array.from(renderedTasks, (task) => task.textContent)).toEqual([
+      "Inspect the behavior",
+      "Add focused coverage",
+      "Verify the result",
+    ]);
+    expect(
+      consoleErrorSpy.mock.calls.some(
+        ([message]) =>
+          typeof message === "string" && message.includes("same key"),
+      ),
+    ).toBe(false);
+  });
+
+  it("keeps the task section visible when the plan is empty", () => {
+    const { container } = render(<TaskListSection taskList={[]} />);
+
+    expect(
+      screen.getByText(`translated:${I18nKey.COMMON$TASKS}`),
+    ).toBeInTheDocument();
+    expect(container.querySelectorAll('[data-name="item"]')).toHaveLength(0);
+  });
+});

src/components/conversation-events/chat/task-tracking/task-list-section.tsx

@@ -0,0 +1,33 @@
+import { useTranslation } from "react-i18next";
+import { TaskItem } from "./task-item";
+import LessonPlanIcon from "#/icons/lesson-plan.svg?react";
+import { TaskItem as TaskItemType } from "#/types/agent-server/core/base/common";
+import { I18nKey } from "#/i18n/declaration";
+import { Typography } from "#/ui/typography";
+
+interface TaskListSectionProps {
+  taskList: TaskItemType[];
+}
+
+export function TaskListSection({ taskList }: TaskListSectionProps) {
+  const { t } = useTranslation("openhands");
+
+  return (
+    <div className="flex flex-col overflow-clip bg-[var(--oh-surface)] border border-[var(--oh-border)] rounded-[12px] w-full">
+      {/* Header Tabs */}
+      <div className="flex gap-1 items-center border-b border-[var(--oh-border)] h-[41px] px-2 shrink-0">
+        <LessonPlanIcon className="shrink-0 w-4.5 h-4.5 text-[var(--oh-muted)]" />
+        <Typography.Text className="text-[11px] text-nowrap text-white tracking-[0.11px] font-medium leading-[16px] whitespace-pre">
+          {t(I18nKey.COMMON$TASKS)}
+        </Typography.Text>
+      </div>
+
+      {/* Task Items */}
+      <div>
+        {taskList.map((task, index) => (
+          <TaskItem key={`task-${index}`} task={task} />
+        ))}
+      </div>
+    </div>
+  );
+}

src/components/conversation-events/chat/task-tracking/task-tracking-observation-content.test.tsx

@@ -0,0 +1,66 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { I18nKey } from "#/i18n/declaration";
+import type { ObservationEvent } from "#/types/agent-server/core";
+import type { TaskItem as TaskItemType } from "#/types/agent-server/core/base/common";
+import type { TaskTrackerObservation } from "#/types/agent-server/core/base/observation";
+import { TaskTrackingObservationContent } from "./task-tracking-observation-content";
+
+const createTask = (overrides: Partial<TaskItemType> = {}): TaskItemType => ({
+  title: "Inspect the behavior",
+  notes: "",
+  status: "todo",
+  ...overrides,
+});
+
+const createTaskTrackingEvent = (
+  observationOverrides: Partial<TaskTrackerObservation> = {},
+): ObservationEvent<TaskTrackerObservation> => ({
+  id: "observation-1",
+  timestamp: "2026-07-13T12:00:00.000Z",
+  source: "environment",
+  tool_name: "task_tracker",
+  tool_call_id: "tool-call-1",
+  action_id: "action-1",
+  observation: {
+    kind: "TaskTrackerObservation",
+    content: "Current plan",
+    command: "plan",
+    task_list: [createTask()],
+    ...observationOverrides,
+  },
+});
+
+describe("task tracking observations", () => {
+  it("shows a non-empty plan", () => {
+    const event = createTaskTrackingEvent({
+      task_list: [
+        createTask({ title: "Inspect the behavior" }),
+        createTask({ title: "Verify the result", status: "done" }),
+      ],
+    });
+
+    render(<TaskTrackingObservationContent event={event} />);
+
+    expect(screen.getByText(I18nKey.COMMON$TASKS)).toBeInTheDocument();
+    expect(screen.getByText("Inspect the behavior")).toBeInTheDocument();
+    expect(screen.getByText("Verify the result")).toBeInTheDocument();
+  });
+
+  it("hides task data emitted by commands other than plan", () => {
+    const event = createTaskTrackingEvent({ command: "update" });
+
+    render(<TaskTrackingObservationContent event={event} />);
+
+    expect(screen.queryByText(I18nKey.COMMON$TASKS)).not.toBeInTheDocument();
+    expect(screen.queryByText("Inspect the behavior")).not.toBeInTheDocument();
+  });
+
+  it("hides an empty plan", () => {
+    const event = createTaskTrackingEvent({ task_list: [] });
+
+    render(<TaskTrackingObservationContent event={event} />);
+
+    expect(screen.queryByText(I18nKey.COMMON$TASKS)).not.toBeInTheDocument();
+  });
+});

src/components/conversation-events/chat/task-tracking/task-tracking-observation-content.tsx

@@ -0,0 +1,23 @@
+import React from "react";
+import { ObservationEvent } from "#/types/agent-server/core";
+import { TaskTrackerObservation } from "#/types/agent-server/core/base/observation";
+import { TaskListSection } from "./task-list-section";
+
+interface TaskTrackingObservationContentProps {
+  event: ObservationEvent<TaskTrackerObservation>;
+}
+
+export function TaskTrackingObservationContent({
+  event,
+}: TaskTrackingObservationContentProps): React.ReactNode {
+  const { observation } = event;
+  const { command, task_list: taskList } = observation;
+  const shouldShowTaskList = command === "plan" && taskList.length > 0;
+
+  return (
+    <div className="flex flex-col gap-4">
+      {/* Task List section - only show for 'plan' command */}
+      {shouldShowTaskList && <TaskListSection taskList={taskList} />}
+    </div>
+  );
+}

src/components/conversation/index.ts

@@ -0,0 +1,8 @@
+export { ConversationView } from "../../routes/conversation";
+export { ChatInterface as ChatPanel } from "../features/chat/chat-interface";
+export { ConversationLoading } from "../features/conversation/conversation-loading";
+export { ConversationMain } from "../features/conversation/conversation-main/conversation-main";
+export { ChatInterfaceWrapper } from "../features/conversation/conversation-main/chat-interface-wrapper";
+export { ConversationName } from "../features/conversation/conversation-name";
+export { ConversationNameWithStatus } from "../features/conversation/conversation-name-with-status";
+export { ConversationTabs } from "../features/conversation/conversation-tabs/conversation-tabs";

src/components/features/alerts/alert-banner.tsx

@@ -0,0 +1,143 @@
+import { useTranslation } from "react-i18next";
+import { useMemo } from "react";
+import { useLocalStorage } from "@uidotdev/usehooks";
+import { FaTriangleExclamation } from "react-icons/fa6";
+import CloseIcon from "#/icons/close.svg?react";
+import { useNavigation } from "#/context/navigation-context";
+import { cn } from "#/utils/utils";
+import { I18nKey } from "#/i18n/declaration";
+import { Typography } from "#/ui/typography";
+
+interface AlertBannerProps {
+  maintenanceStartTime?: string | null;
+  faultyModels?: string[];
+  errorMessage?: string | null;
+  updatedAt: string;
+}
+
+export function AlertBanner({
+  maintenanceStartTime,
+  faultyModels,
+  errorMessage,
+  updatedAt,
+}: AlertBannerProps) {
+  const { t } = useTranslation("openhands");
+  const [dismissedAt, setDismissedAt] = useLocalStorage<string | null>(
+    "alert_banner_dismissed_at",
+    null,
+  );
+
+  const { currentPath } = useNavigation();
+
+  // Format ISO timestamp to user's local timezone
+  const formatMaintenanceTime = (isoTimeString: string): string => {
+    const date = new Date(isoTimeString);
+    return date.toLocaleString(undefined, {
+      year: "numeric",
+      month: "short",
+      day: "numeric",
+      hour: "2-digit",
+      minute: "2-digit",
+      timeZoneName: "short",
+    });
+  };
+
+  const localTime = maintenanceStartTime
+    ? formatMaintenanceTime(maintenanceStartTime)
+    : null;
+
+  const hasMaintenanceAlert = !!maintenanceStartTime;
+  const hasFaultyModels = faultyModels && faultyModels.length > 0;
+  const hasErrorMessage = errorMessage && errorMessage.trim().length > 0;
+
+  const hasAnyAlert = hasMaintenanceAlert || hasFaultyModels || hasErrorMessage;
+
+  const isBannerVisible = useMemo(() => {
+    if (!hasAnyAlert) {
+      return false;
+    }
+    return dismissedAt !== updatedAt;
+  }, [dismissedAt, updatedAt, hasAnyAlert]);
+
+  // Try to translate error message, fallback to raw message
+  const translatedErrorMessage = useMemo(() => {
+    if (!errorMessage) return null;
+
+    // Check if the error message is a translation key (e.g., "ERROR$SOME_KEY")
+    const translated = t(errorMessage as I18nKey);
+    // If translation returns the same key, it means no translation exists
+    if (translated === errorMessage) {
+      return errorMessage;
+    }
+    return translated;
+  }, [errorMessage, t]);
+
+  if (!isBannerVisible) {
+    return null;
+  }
+
+  const renderMessages = () => {
+    const messages: React.ReactNode[] = [];
+
+    if (hasMaintenanceAlert && localTime) {
+      messages.push(
+        <Typography.Paragraph key="maintenance" className="text-sm font-medium">
+          {t(I18nKey.MAINTENANCE$SCHEDULED_MESSAGE, { time: localTime })}
+        </Typography.Paragraph>,
+      );
+    }
+
+    if (hasFaultyModels) {
+      messages.push(
+        <Typography.Paragraph
+          key="faulty-models"
+          className="text-sm font-medium"
+        >
+          {t(I18nKey.ALERT$FAULTY_MODELS_MESSAGE)} {faultyModels!.join(", ")}
+        </Typography.Paragraph>,
+      );
+    }
+
+    if (hasErrorMessage && translatedErrorMessage) {
+      messages.push(
+        <Typography.Paragraph
+          key="error-message"
+          className="text-sm font-medium"
+        >
+          {translatedErrorMessage}
+        </Typography.Paragraph>,
+      );
+    }
+
+    return messages;
+  };
+
+  return (
+    <div
+      data-testid="alert-banner"
+      className={cn(
+        "bg-base border border-primary text-white p-4 rounded",
+        "flex flex-row items-center justify-between m-1",
+        currentPath === "/" && "mt-3 mr-3",
+      )}
+    >
+      <div className="flex items-center">
+        <div className="flex-shrink-0">
+          <FaTriangleExclamation className="text-primary align-middle" />
+        </div>
+        <div className="ml-3 flex flex-col gap-1">{renderMessages()}</div>
+      </div>
+
+      <button
+        type="button"
+        data-testid="dismiss-button"
+        onClick={() => setDismissedAt(updatedAt)}
+        className={cn(
+          "bg-base rounded-full w-5 h-5 flex items-center justify-center cursor-pointer",
+        )}
+      >
+        <CloseIcon />
+      </button>
+    </div>
+  );
+}

src/components/features/backends/add-backend-modal.tsx

@@ -0,0 +1,9 @@
+import { BackendFormModal } from "./backend-form-modal";
+
+interface AddBackendModalProps {
+  onClose: () => void;
+}
+
+export function AddBackendModal({ onClose }: AddBackendModalProps) {
+  return <BackendFormModal mode="add" onClose={onClose} />;
+}

src/components/features/backends/api-key-entry-screen.tsx

@@ -0,0 +1,150 @@
+import React from "react";
+import { useTranslation } from "react-i18next";
+import { SettingsClient } from "@openhands/typescript-client/clients";
+import { I18nKey } from "#/i18n/declaration";
+import { isSdkHttpStatusError } from "#/api/agent-server-compatibility";
+import { getAgentServerClientOptions } from "#/api/agent-server-client-options";
+import { isNoBackend } from "#/api/backend-registry/active-store";
+import { useActiveBackendContext } from "#/contexts/active-backend-context";
+import { BrandButton } from "#/components/features/settings/brand-button";
+import {
+  MODAL_MAX_WIDTH_VIEWPORT,
+  modalWidthClassName,
+} from "#/components/shared/modals/modal-body";
+import { cn } from "#/utils/utils";
+import { BackendStatusDot } from "./backend-status-dot";
+import {
+  BackendForm,
+  type BackendFormSubmitPayload,
+} from "./backend-form-modal";
+
+/**
+ * Full-screen prompt shown when the server is in public mode
+ * (`VITE_AUTH_REQUIRED=true`) and no valid API key has been configured.
+ *
+ * Reuses {@link BackendForm} with `hostReadOnly` + `onSubmitOverride`
+ * to render the standard name / host / API-key inputs while adding
+ * server-side validation (calls `GET /api/settings` before persisting)
+ * and a connection status indicator.
+ */
+export default function ApiKeyEntryScreen() {
+  const { t } = useTranslation("openhands");
+  const { active, addBackend, updateBackend } = useActiveBackendContext();
+
+  const host = window.location.origin;
+
+  const [isValidating, setIsValidating] = React.useState(false);
+  const [connectionStatus, setConnectionStatus] = React.useState<
+    "idle" | "success" | "error"
+  >("idle");
+  const [errorMessage, setErrorMessage] = React.useState<string | null>(null);
+
+  const handleSubmitOverride = React.useCallback(
+    async (payload: BackendFormSubmitPayload) => {
+      setIsValidating(true);
+      setConnectionStatus("idle");
+      setErrorMessage(null);
+
+      try {
+        await new SettingsClient(
+          getAgentServerClientOptions({
+            host: payload.host,
+            sessionApiKey: payload.apiKey,
+            timeout: 5000,
+          }),
+        ).getSettings();
+
+        setConnectionStatus("success");
+
+        if (isNoBackend(active.backend)) {
+          addBackend(payload);
+        } else {
+          updateBackend(active.backend.id, payload);
+        }
+
+        window.location.reload();
+      } catch (err: unknown) {
+        setConnectionStatus("error");
+
+        if (isSdkHttpStatusError(err, 401)) {
+          setErrorMessage(t(I18nKey.AUTH$INVALID_KEY));
+        } else {
+          const detail = err instanceof Error ? err.message : String(err);
+          setErrorMessage(
+            `${t(I18nKey.AUTH$CONNECTION_FAILED)}${detail ? `: ${detail}` : ""}`,
+          );
+        }
+        setIsValidating(false);
+      }
+    },
+    [active.backend, addBackend, updateBackend, t],
+  );
+
+  return (
+    <div
+      data-testid="api-key-entry-screen"
+      className="flex min-h-screen items-center justify-center bg-base px-6"
+    >
+      <div
+        className={cn(
+          "relative rounded-xl border border-[var(--oh-border)] bg-base-secondary",
+          modalWidthClassName("md"),
+          MODAL_MAX_WIDTH_VIEWPORT,
+        )}
+      >
+        <div className="px-6 pt-6 pb-2 pr-12">
+          <h2 className="text-lg font-semibold">
+            {t(I18nKey.BACKEND$ADD_TITLE)}
+          </h2>
+        </div>
+
+        <div className="px-6 pb-6 pt-2">
+          <BackendForm
+            mode="add"
+            backend={{ ...active.backend, host, apiKey: "", name: "" }}
+            onSubmitted={() => {}}
+            testIdRoot="api-key-entry"
+            hostReadOnly
+            requireApiKey
+            onSubmitOverride={handleSubmitOverride}
+            renderActions={({ canSubmit, testIdRoot }) => (
+              <>
+                {connectionStatus !== "idle" && (
+                  <div className="flex items-center gap-3 text-sm">
+                    <BackendStatusDot
+                      isConnected={connectionStatus === "success"}
+                    />
+                    <span
+                      data-testid={`${testIdRoot}-status`}
+                      className={
+                        connectionStatus === "error"
+                          ? "text-red-400"
+                          : "text-green-400"
+                      }
+                    >
+                      {connectionStatus === "error"
+                        ? errorMessage
+                        : t(I18nKey.ONBOARDING$BACKEND_STATUS_CONNECTED)}
+                    </span>
+                  </div>
+                )}
+
+                <BrandButton
+                  type="submit"
+                  variant="secondary"
+                  isDisabled={!canSubmit || isValidating}
+                  testId={`${testIdRoot}-submit`}
+                  className="w-full text-center"
+                >
+                  {isValidating
+                    ? t(I18nKey.ONBOARDING$BACKEND_STATUS_CHECKING)
+                    : t(I18nKey.BACKEND$CONNECT)}
+                </BrandButton>
+              </>
+            )}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}

src/components/features/backends/backend-form-modal.test.tsx

@@ -0,0 +1,80 @@
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { BackendConnectionOptions } from "./backend-form-modal";
+
+// Isolate the manual "add backend" column: the sibling Cloud-login column
+// drives an OAuth device flow that is irrelevant to backend-kind selection.
+vi.mock("./device-flow-auth", () => ({
+  DeviceFlowAuth: () => null,
+}));
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("BackendConnectionOptions — manual backend type", () => {
+  it("defaults the Type selector to Cloud for an OpenHands Cloud host", () => {
+    render(
+      <BackendConnectionOptions
+        onConnected={vi.fn()}
+        initialManualBackend={{ host: "https://app.all-hands.dev" }}
+      />,
+    );
+
+    expect(screen.getByTestId("add-backend-kind-option-cloud")).toHaveAttribute(
+      "aria-checked",
+      "true",
+    );
+    expect(screen.getByTestId("add-backend-kind-option-local")).toHaveAttribute(
+      "aria-checked",
+      "false",
+    );
+  });
+
+  it("defaults the Type selector to Local for a self-hosted host on a custom domain", () => {
+    // A self-hosted OHE on a custom domain is indistinguishable from a local
+    // agent-server by host alone, so it must not be auto-classified as Cloud.
+    render(
+      <BackendConnectionOptions
+        onConnected={vi.fn()}
+        initialManualBackend={{ host: "https://app.adorable.build.one" }}
+      />,
+    );
+
+    expect(screen.getByTestId("add-backend-kind-option-local")).toHaveAttribute(
+      "aria-checked",
+      "true",
+    );
+  });
+
+  it("persists the user-selected Cloud kind when adding a self-hosted OHE on a custom domain", async () => {
+    const onConnected = vi.fn();
+    render(
+      <BackendConnectionOptions
+        onConnected={onConnected}
+        initialManualBackend={{
+          name: "Adorable Enterprise",
+          host: "app.adorable.build.one",
+          apiKey: "oh-cloud-key",
+        }}
+      />,
+    );
+
+    // The user overrides the (Local) default to declare this custom domain a
+    // Cloud app-server, then connects.
+    fireEvent.click(screen.getByTestId("add-backend-kind-option-cloud"));
+    fireEvent.click(screen.getByTestId("add-backend-submit"));
+
+    await waitFor(() => expect(onConnected).toHaveBeenCalledTimes(1));
+    expect(onConnected).toHaveBeenCalledWith(
+      expect.objectContaining({
+        kind: "cloud",
+        name: "Adorable Enterprise",
+        host: "https://app.adorable.build.one",
+        apiKey: "oh-cloud-key",
+      }),
+      "manual",
+      { agentServerVersion: null },
+    );
+  });
+});

src/components/features/backends/backend-form-modal.tsx

@@ -0,0 +1,1629 @@
+import React from "react";
+import { useQuery } from "@tanstack/react-query";
+import { useTranslation } from "react-i18next";
+import { ChevronDown, Globe, Info, Monitor } from "lucide-react";
+import { ServerClient } from "@openhands/typescript-client/clients";
+import OpenHandsLogoWhite from "#/assets/branding/openhands-logo-white.svg?react";
+import { ModalBackdrop } from "#/components/shared/modals/modal-backdrop";
+import {
+  MODAL_MAX_WIDTH_VIEWPORT,
+  modalWidthClassName,
+} from "#/components/shared/modals/modal-body";
+import { ModalCloseButton } from "#/components/shared/modals/modal-close-button";
+import { BrandButton } from "#/components/features/settings/brand-button";
+import { SettingsInput } from "#/components/features/settings/settings-input";
+import { SegmentedToggle } from "#/components/features/files-tab/segmented-toggle";
+import { useActiveBackendContext } from "#/contexts/active-backend-context";
+import { useNavigation } from "#/context/navigation-context";
+import { useBackendsHealth } from "#/hooks/query/use-backends-health";
+import { useTracking } from "#/hooks/use-tracking";
+import type { CloudConnectionSource } from "#/services/cloud-funnel-analytics";
+import { getAgentServerClientOptions } from "#/api/agent-server-client-options";
+import { getLockedCloudHost } from "#/api/agent-server-config";
+import { isOpenHandsCloudHost } from "#/api/device-flow-client";
+import {
+  getDisplayAgentServerVersion,
+  validateLocalBackend,
+} from "#/api/agent-server-compatibility";
+import ChevronDownSmallIcon from "#/icons/chevron-down-small.svg?react";
+import { I18nKey } from "#/i18n/declaration";
+import type { Backend, BackendKind } from "#/api/backend-registry/types";
+import { getUserFacingConnectionErrorMessage } from "#/utils/user-facing-error";
+import { cn } from "#/utils/utils";
+import {
+  modalTitleLgClassName,
+  modalTitleLgMediumClassName,
+} from "#/utils/modal-classes";
+import ExternalLinkIcon from "#/icons/external-link.svg?react";
+import ServerIcon from "#/icons/server.svg?react";
+import { getBackendStatusLabel } from "./backend-status-label";
+import { BackendStatusDot } from "./backend-status-dot";
+import { DeviceFlowAuth } from "./device-flow-auth";
+
+export type BackendFormMode = "add" | "edit";
+
+interface BackendConnectionTestMetadata {
+  agentServerVersion: string | null;
+}
+
+interface BackendFormModalProps {
+  mode: BackendFormMode;
+  /** Required when `mode === "edit"`. */
+  backend?: Backend;
+  onClose: () => void;
+  /** Analytics surface for the `backend_added` event (add mode only). */
+  source?: BackendAddedSource;
+  /** Hide the close button and disable backdrop/escape dismissal. Used for locked Cloud first-run. */
+  hideCloseButton?: boolean;
+}
+
+/**
+ * Seed the default backend kind from the host. Uses proper hostname-suffix
+ * matching (via {@link isOpenHandsCloudHost}) rather than a substring test, so
+ * a look-alike host such as `all-hands-testing.dev` isn't misread as cloud.
+ *
+ * This is only a *default*: a self-hosted OpenHands Cloud/Enterprise instance
+ * on a truly custom domain is indistinguishable from a local agent-server by
+ * host alone, so the manual add form lets the user override the kind
+ * explicitly (see the Type selector in ManualConnectionColumn).
+ */
+function inferKindFromHost(host: string): BackendKind {
+  return isOpenHandsCloudHost(host) ? "cloud" : "local";
+}
+
+/**
+ * Returns true for hostnames that represent a local / private-network address.
+ * Used by normalizeHost to choose http:// instead of https://.
+ */
+function isLocalAddress(hostname: string): boolean {
+  // Strip IPv6 bracket notation: [::1] → ::1
+  const h = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  // IPv6 loopback, any-address, and named loopback
+  if (h === "localhost" || h === "::1" || h === "::" || h === "0.0.0.0")
+    return true;
+  // 127.x.x.x loopback range + IPv4-mapped loopback (::ffff:127.x.x.x)
+  if (/^127\./.test(h) || /^::ffff:127\./i.test(h)) return true;
+  // RFC 1918 private ranges
+  if (/^10\./.test(h)) return true;
+  if (/^192\.168\./.test(h)) return true;
+  if (/^172\.(1[6-9]|2\d|3[01])\./.test(h)) return true;
+  // IPv6 link-local (fe80::/10) and unique local (fc00::/7)
+  if (/^fe[89ab][0-9a-f]:/i.test(h)) return true;
+  if (/^f[cd][0-9a-f]{2}:/i.test(h)) return true;
+  // mDNS / Bonjour (.local)
+  if (h.endsWith(".local")) return true;
+  // Single-label hostnames (no dots, no colons) are local network names.
+  // Colons are excluded so bare IPv6 addresses don't accidentally match.
+  if (!h.includes(".") && !h.includes(":")) return true;
+  return false;
+}
+
+function normalizeHost(host: string): string {
+  const trimmed = host.trim().replace(/\/+$/, "");
+  if (!trimmed) return "";
+  // Already has an explicit scheme — respect it.
+  if (/^https?:\/\//i.test(trimmed)) return trimmed;
+  // Extract the pure hostname for scheme selection, handling three cases:
+  //   [::1]:8080  → bracket IPv6 notation → extract ::1
+  //   ::1         → bare IPv6 (multiple colons, no bracket) → whole string
+  //   host:port   → regular host:port → part before the colon
+  const bracketMatch = trimmed.match(/^\[([^\]]+)\]/);
+  const hostname = bracketMatch
+    ? bracketMatch[1]
+    : (trimmed.match(/:/g) ?? []).length > 1
+      ? trimmed
+      : trimmed.split(":")[0];
+  const scheme = isLocalAddress(hostname) ? "http" : "https";
+  return `${scheme}://${trimmed}`;
+}
+
+/**
+ * Returns true when `host` represents a reachable backend URL.
+ *
+ * Rules (applied in order):
+ *   1. Must be non-empty after trimming.
+ *   2. Must contain no whitespace — spaces can never appear in a host/port.
+ *   3. After normalisation (bare hosts get `https://` prepended), must parse
+ *      as a valid http or https URL with a non-empty hostname.
+ */
+function isValidHostUrl(host: string): boolean {
+  const trimmed = host.trim();
+  if (!trimmed) return false;
+  // Spaces anywhere in the input are an immediate rejection.
+  if (/\s/.test(trimmed)) return false;
+  const normalized = normalizeHost(trimmed);
+  if (!normalized) return false;
+  try {
+    const url = new URL(normalized);
+    return (
+      (url.protocol === "http:" || url.protocol === "https:") &&
+      url.hostname.length > 0
+    );
+  } catch {
+    return false;
+  }
+}
+
+const DEFAULT_OPENHANDS_CLOUD_HOST = "https://app.all-hands.dev";
+const LOCAL_BACKEND_COMMAND = "agent-canvas --backend-only --port 8001";
+const LOCAL_AGENT_SERVER_DOCS_URL =
+  "https://github.com/OpenHands/OpenHands/blob/main/docs/DEVELOPMENT.md#alternative-development-workflows";
+const REMOTE_AGENT_SERVER_DOCS_URL =
+  "https://github.com/OpenHands/OpenHands/blob/main/docs/SELF_HOSTING.md";
+const DEPLOYMENT_OPTIONS_URL =
+  "https://docs.openhands.dev/overview/introduction";
+export type BackendConnectionMethod = "manual" | "cloud_login";
+
+export type BackendAddedSource = CloudConnectionSource;
+type AddBackendOption = "cloud" | "agent-server";
+type AgentServerLocation = "local" | "remote";
+
+function getConnectionTestFailedTitle(
+  t: ReturnType<typeof useTranslation>["t"],
+  host: string,
+): string {
+  return t(I18nKey.BACKEND$CONNECTION_TEST_FAILED, {
+    host,
+    interpolation: { escapeValue: false },
+  });
+}
+
+function getConnectionErrorDetail(error: unknown): string | null {
+  return getUserFacingConnectionErrorMessage(error);
+}
+
+function getConnectionTestFailedMessage(title: string, error: unknown): string {
+  const detail = getConnectionErrorDetail(error);
+  return detail ? `${title}\n${detail}` : title;
+}
+
+async function testBackendConnection(
+  backend: Pick<Backend, "host" | "apiKey" | "kind">,
+): Promise<BackendConnectionTestMetadata> {
+  // Cloud backends authenticate via OAuth; preflight GET is not applicable.
+  if (backend.kind !== "local") return { agentServerVersion: null };
+  const agentServerVersion = await validateLocalBackend(backend, 5000);
+  return { agentServerVersion };
+}
+
+/**
+ * Live status row for the edit form: shows a connection dot, a
+ * "Local"/"Cloud" label, and the agent server's reported version when
+ * available. Replaces the legacy local/cloud radio fieldset (kind is
+ * now inferred from the host).
+ */
+function BackendStatusBadge({
+  backend,
+  testIdRoot,
+}: {
+  backend: Backend;
+  testIdRoot: string;
+}) {
+  const { t } = useTranslation("openhands");
+  const healthByBackendId = useBackendsHealth([backend]);
+  const health = healthByBackendId[backend.id];
+  const isConnected = health?.isConnected ?? null;
+  const disabled = health?.disabled === true;
+  const consecutiveFailures = health?.consecutiveFailures ?? 0;
+  const lastError = health?.lastError ?? null;
+
+  const { data: version } = useQuery({
+    queryKey: ["backend-version", backend.host, backend.apiKey],
+    queryFn: async () => {
+      const info = await new ServerClient(
+        getAgentServerClientOptions({
+          host: backend.host,
+          sessionApiKey: backend.apiKey || null,
+          timeout: 5000,
+        }),
+      ).getServerInfo();
+      return getDisplayAgentServerVersion(info);
+    },
+    retry: false,
+    staleTime: 60_000,
+    enabled: backend.kind === "local" && !disabled,
+  });
+
+  const statusLabel = getBackendStatusLabel(t, backend, health);
+
+  const kindLabel =
+    backend.kind === "cloud"
+      ? t(I18nKey.BACKEND$KIND_CLOUD)
+      : t(I18nKey.BACKEND$KIND_LOCAL);
+
+  return (
+    <div className="flex flex-col gap-2">
+      <div
+        data-testid={`${testIdRoot}-status`}
+        className="flex items-center gap-3 text-sm"
+      >
+        <BackendStatusDot isConnected={isConnected} />
+        <span className="text-white" data-testid={`${testIdRoot}-status-label`}>
+          {statusLabel}
+        </span>
+        <span className="text-tertiary-alt">·</span>
+        <span className="text-[var(--oh-text-tertiary)]">{kindLabel}</span>
+        {version ? (
+          <span
+            className="text-xs text-[var(--oh-muted)]"
+            data-testid={`${testIdRoot}-version`}
+          >
+            {t(I18nKey.BACKEND$VERSION_LABEL, { version })}
+          </span>
+        ) : null}
+      </div>
+
+      {disabled ? (
+        <div
+          data-testid={`${testIdRoot}-status-error`}
+          className="flex flex-col gap-1 rounded-md border border-red-500/40 bg-red-500/10 p-3 text-sm"
+        >
+          <span className="font-semibold text-red-300">
+            {t(I18nKey.BACKEND$HEALTH_FAILED_TITLE)}
+          </span>
+          <span className="text-xs text-[var(--oh-text-tertiary)]">
+            {t(I18nKey.BACKEND$HEALTH_FAILED_DETAIL, {
+              count: consecutiveFailures,
+            })}
+          </span>
+          {lastError ? (
+            <span
+              data-testid={`${testIdRoot}-status-error-message`}
+              className="text-xs text-red-300 whitespace-pre-wrap break-words"
+            >
+              {lastError}
+            </span>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export interface BackendFormSubmitPayload {
+  name: string;
+  host: string;
+  apiKey: string;
+  kind: BackendKind;
+}
+
+interface UseBackendFormOptions {
+  initialName?: string;
+  initialHost?: string;
+  initialApiKey?: string;
+  /**
+   * Called to test the connection. The hook does NOT call
+   * `testBackendConnection` directly so callers can inject a
+   * wrapped version (e.g. with extra logging or different timeout).
+   * Should throw on failure.
+   */
+  onTestConnection: (
+    payload: BackendFormSubmitPayload,
+  ) => Promise<BackendConnectionTestMetadata>;
+  /** Called after a successful connection test and persistence. */
+  onSuccess: (metadata: BackendConnectionTestMetadata) => void;
+  /** Require a non-empty API key even when the host looks local. */
+  requireApiKey?: boolean;
+  /**
+   * When provided, completely replaces the default submit flow
+   * (onTestConnection + onSuccess). The hook still manages form state
+   * and canSubmit validation, but the caller owns error handling and
+   * success side effects. Should throw on failure.
+   */
+  onSubmitOverride?: (payload: BackendFormSubmitPayload) => Promise<void>;
+  /** Fix the persisted backend kind instead of inferring it from the host. */
+  fixedKind?: BackendKind;
+}
+
+/**
+ * Shared hook for the backend-form state used by both `BackendForm`
+ * (edit/add mode) and `ManualConnectionColumn` (add-mode-only column).
+ * Encapsulates name / host / apiKey fields, `connectionError`,
+ * `isSubmitting`, and the shared `handleSubmit` flow.
+ */
+function useBackendForm({
+  initialName = "",
+  initialHost = "",
+  initialApiKey = "",
+  onTestConnection,
+  onSuccess,
+  requireApiKey = false,
+  onSubmitOverride,
+  fixedKind,
+}: UseBackendFormOptions) {
+  const { t } = useTranslation("openhands");
+
+  const [name, setName] = React.useState(initialName);
+  const [host, setHost] = React.useState(initialHost);
+  const [apiKey, setApiKey] = React.useState(initialApiKey);
+  const [connectionError, setConnectionError] = React.useState<string | null>(
+    null,
+  );
+  const [isSubmitting, setIsSubmitting] = React.useState(false);
+  const [kindOverride, setKindOverride] = React.useState<BackendKind | null>(
+    null,
+  );
+
+  // Kind follows host inference until the user explicitly picks a type, then
+  // respects that choice. A custom-domain OHE can't be distinguished from a
+  // custom-domain local agent-server by host alone, so ManualConnectionColumn
+  // exposes `setKind` (a Type selector) to let the user declare it.
+  const kind = fixedKind ?? kindOverride ?? inferKindFromHost(host);
+  const needsApiKey = requireApiKey || kind !== "local";
+  const canSubmit =
+    name.trim().length > 0 &&
+    isValidHostUrl(host) &&
+    (!needsApiKey || apiKey.trim().length > 0);
+
+  const handleSubmit = React.useCallback(
+    async (e: React.FormEvent<HTMLFormElement>) => {
+      e.preventDefault();
+      if (!canSubmit || isSubmitting) return;
+
+      const payload: BackendFormSubmitPayload = {
+        name: name.trim(),
+        host: normalizeHost(host),
+        apiKey: apiKey.trim(),
+        kind,
+      };
+
+      setConnectionError(null);
+      setIsSubmitting(true);
+
+      try {
+        // When onSubmitOverride is provided, it completely replaces the
+        // default flow (onTestConnection + onSuccess).
+        if (onSubmitOverride) {
+          await onSubmitOverride(payload);
+        } else {
+          const metadata = await onTestConnection(payload);
+          onSuccess(metadata);
+        }
+      } catch (error) {
+        setConnectionError(
+          getConnectionTestFailedMessage(
+            getConnectionTestFailedTitle(t, payload.host),
+            error,
+          ),
+        );
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [
+      canSubmit,
+      isSubmitting,
+      name,
+      host,
+      apiKey,
+      kind,
+      onTestConnection,
+      onSuccess,
+      requireApiKey,
+      onSubmitOverride,
+      fixedKind,
+      t,
+    ],
+  );
+
+  return {
+    name,
+    setName,
+    host,
+    setHost,
+    apiKey,
+    setApiKey,
+    connectionError,
+    setConnectionError,
+    isSubmitting,
+    kind,
+    setKind: setKindOverride,
+    canSubmit,
+    handleSubmit,
+  };
+}
+
+export interface BackendFormProps {
+  mode: BackendFormMode;
+  /** Required when `mode === "edit"`. */
+  backend?: Backend;
+  /**
+   * Called after the form is submitted and the backend has been
+   * persisted. Use this to dismiss a containing modal, advance an
+   * onboarding step, etc.
+   */
+  onSubmitted: () => void;
+  /**
+   * Optional render slot rendered in place of the default
+   * Save / Cancel button row, so callers (e.g. the onboarding flow)
+   * can re-skin the action area while still owning submission via the
+   * standard `<form onSubmit>` flow. Receives the form's submit-ready
+   * state.
+   */
+  renderActions?: (state: {
+    canSubmit: boolean;
+    isSubmitting: boolean;
+    testIdRoot: string;
+  }) => React.ReactNode;
+  /** Used to disambiguate test ids across the same screen. */
+  testIdRoot?: string;
+  /** When true, the host field is pre-filled and disabled. */
+  hostReadOnly?: boolean;
+  /**
+   * When true, a non-empty API key is required for submission regardless
+   * of the inferred backend kind.  The standard add form allows empty
+   * keys for local backends; the auth-gate screen needs to enforce one.
+   */
+  requireApiKey?: boolean;
+  /**
+   * When true, hides the name/host/API-key inputs (and related inline
+   * errors) while keeping the action row visible — used by onboarding
+   * after a successful connection probe.
+   */
+  hideConfigurationFields?: boolean;
+  /**
+   * Replace the default synchronous add/update-and-close submit with a
+   * custom async handler.  The form builds the payload, validates
+   * client-side, then hands it to this callback. If the callback throws,
+   * the form remains open so the caller can surface errors.
+   */
+  onSubmitOverride?: (payload: BackendFormSubmitPayload) => Promise<void>;
+}
+
+/**
+ * Reusable form body for adding / editing a backend. Renders the
+ * common name / host / API-key inputs plus the kind selector
+ * (radio buttons in `add` mode, status badge in `edit` mode).
+ *
+ * Rendered as a `<form>`, so consumers should put any extra controls
+ * either inside `renderActions` or as siblings inside a wrapping
+ * element — but submission flows through the standard form submit so
+ * Enter-to-submit still works.
+ */
+export function BackendForm({
+  mode,
+  backend,
+  onSubmitted,
+  renderActions,
+  testIdRoot: explicitTestIdRoot,
+  hostReadOnly,
+  requireApiKey,
+  hideConfigurationFields = false,
+  onSubmitOverride,
+}: BackendFormProps) {
+  const { t } = useTranslation("openhands");
+  const { addBackend, updateBackend } = useActiveBackendContext();
+
+  // In edit mode preserve the existing backend's kind so that renaming or
+  // rotating the API key on a cloud backend (e.g. an OHE/enterprise instance
+  // on a custom domain) does not silently downgrade it to "local" and switch
+  // the auth header from `Authorization: Bearer` to `X-Session-API-Key`.
+  // Only infer from the host when adding a new backend.
+  const fixedKind: BackendKind | null =
+    mode === "edit" && backend ? backend.kind : null;
+
+  const {
+    name,
+    setName,
+    host,
+    setHost,
+    apiKey,
+    setApiKey,
+    connectionError,
+    setConnectionError,
+    isSubmitting,
+    kind: inferredKind,
+    handleSubmit: runSubmit,
+  } = useBackendForm({
+    initialName: backend?.name ?? "",
+    initialHost: backend?.host ?? "",
+    initialApiKey: backend?.apiKey ?? "",
+    onTestConnection: testBackendConnection,
+    onSuccess: async () => {
+      const payload: BackendFormSubmitPayload = {
+        name: name.trim(),
+        host: normalizeHost(host),
+        apiKey: apiKey.trim(),
+        kind: fixedKind ?? inferredKind,
+      };
+      if (mode === "edit" && backend) {
+        updateBackend(backend.id, payload);
+      } else {
+        addBackend(payload);
+      }
+      onSubmitted();
+    },
+    requireApiKey,
+    onSubmitOverride,
+  });
+
+  // Inline validation: only show errors after the user has left a field.
+  const [nameTouched, setNameTouched] = React.useState(false);
+  const [hostTouched, setHostTouched] = React.useState(false);
+
+  const kind = fixedKind ?? inferredKind;
+  const testIdRoot =
+    explicitTestIdRoot ?? (mode === "edit" ? "edit-backend" : "add-backend");
+
+  const needsApiKey = requireApiKey || kind !== "local";
+  const canSubmit =
+    name.trim().length > 0 &&
+    isValidHostUrl(host) &&
+    (!needsApiKey || apiKey.trim().length > 0);
+
+  // Error messages — only surfaced after the user has blurred the field.
+  const nameError =
+    nameTouched && !name.trim() ? t(I18nKey.BACKEND$NAME_REQUIRED) : undefined;
+  const hostError = hostTouched
+    ? !host.trim()
+      ? t(I18nKey.BACKEND$HOST_REQUIRED)
+      : !isValidHostUrl(host)
+        ? t(I18nKey.BACKEND$HOST_INVALID)
+        : undefined
+    : undefined;
+
+  const handleSubmit = async (event: React.FormEvent<HTMLFormElement>) => {
+    if (!canSubmit) {
+      // Mark all validated fields as touched so inline errors become visible
+      // (e.g. user pressed Enter before filling required fields).
+      setNameTouched(true);
+      setHostTouched(true);
+      return;
+    }
+    await runSubmit(event);
+  };
+
+  return (
+    <form
+      data-testid={`${testIdRoot}-form`}
+      onSubmit={handleSubmit}
+      className="flex flex-col gap-4"
+    >
+      <div
+        data-testid={`${testIdRoot}-configuration-fields`}
+        className={cn(
+          "flex flex-col gap-4",
+          hideConfigurationFields && "hidden",
+        )}
+      >
+        <SettingsInput
+          testId={`${testIdRoot}-name`}
+          name={`${testIdRoot}-name`}
+          type="text"
+          label={t(I18nKey.BACKEND$NAME_LABEL)}
+          value={name}
+          onChange={(value) => {
+            setName(value);
+            setConnectionError(null);
+          }}
+          onBlur={() => setNameTouched(true)}
+          // eslint-disable-next-line i18next/no-literal-string -- example placeholder, not user-facing copy
+          placeholder="Production"
+          className="w-full"
+          showRequiredTag
+          error={nameError}
+        />
+
+        <SettingsInput
+          testId={`${testIdRoot}-host`}
+          name={`${testIdRoot}-host`}
+          type="text"
+          label={t(I18nKey.BACKEND$HOST_LABEL)}
+          value={host}
+          onChange={
+            hostReadOnly
+              ? undefined
+              : (value) => {
+                  setHost(value);
+                  setConnectionError(null);
+                }
+          }
+          onBlur={() => setHostTouched(true)}
+          placeholder={DEFAULT_OPENHANDS_CLOUD_HOST}
+          className="w-full"
+          showRequiredTag
+          error={hostError}
+          isDisabled={hostReadOnly}
+        />
+
+        <SettingsInput
+          testId={`${testIdRoot}-api-key`}
+          name={`${testIdRoot}-api-key`}
+          type="password"
+          label={t(I18nKey.BACKEND$KEY_LABEL)}
+          value={apiKey}
+          onChange={(value) => {
+            setApiKey(value);
+            setConnectionError(null);
+          }}
+          placeholder=""
+          className="w-full"
+        />
+
+        {connectionError ? (
+          <div
+            role="alert"
+            data-testid={`${testIdRoot}-error`}
+            className="rounded-md border border-red-500/40 bg-red-500/10 p-3 text-sm text-red-300 whitespace-pre-wrap break-words"
+          >
+            {connectionError}
+          </div>
+        ) : null}
+
+        {mode === "edit" && backend && (
+          <BackendStatusBadge backend={backend} testIdRoot={testIdRoot} />
+        )}
+      </div>
+
+      {renderActions ? (
+        renderActions({
+          canSubmit: canSubmit && !isSubmitting,
+          isSubmitting,
+          testIdRoot,
+        })
+      ) : (
+        <div className="flex justify-end gap-2 mt-2 w-full">
+          <BrandButton
+            type="button"
+            variant="secondary"
+            onClick={onSubmitted}
+            testId={`${testIdRoot}-cancel`}
+          >
+            {t(I18nKey.BUTTON$CANCEL)}
+          </BrandButton>
+          <BrandButton
+            type="submit"
+            variant="primary"
+            isDisabled={!canSubmit || isSubmitting}
+            testId={`${testIdRoot}-submit`}
+          >
+            {t(I18nKey.BACKEND$SAVE)}
+          </BrandButton>
+        </div>
+      )}
+    </form>
+  );
+}
+
+// ── Add-mode two-column layout ──────────────────────────────────────
+
+/**
+ * @spec BM-002 — Adding a backend auto-switches the active selection to it
+ * (BM-001), so a backend-scoped detail page the user is viewing now belongs
+ * to the previous backend. Redirect to that section's list so they never see
+ * stale data, mirroring the switch-backend redirect in BackendSelector.
+ */
+function useRedirectAfterAddBackend() {
+  const { currentPath, navigate } = useNavigation();
+  return React.useCallback(() => {
+    if (/^\/automations\/[^/]+/.test(currentPath)) navigate("/automations");
+    else if (/^\/conversations\/[^/]+/.test(currentPath))
+      navigate("/conversations");
+  }, [currentPath, navigate]);
+}
+
+interface BackendConnectionOptionsProps {
+  onConnected: (
+    payload: BackendFormSubmitPayload,
+    connectionMethod: BackendConnectionMethod,
+    metadata?: BackendConnectionTestMetadata,
+  ) => void;
+  testIdRoot?: string;
+  initialManualBackend?: Partial<
+    Pick<BackendFormSubmitPayload, "name" | "host" | "apiKey">
+  >;
+  requireManualApiKey?: boolean;
+  manualSubmitLabel?: React.ReactNode;
+  manualSubmittingLabel?: React.ReactNode;
+  manualSubmitTestId?: string;
+  analyticsSource?: CloudConnectionSource;
+}
+
+/**
+ * Manual agent-server connection plus OpenHands Cloud OAuth login.
+ * Used by both the Add Backend modal and the onboarding backend step so
+ * supported backend choices stay consistent across first-run and settings UI.
+ */
+export function BackendConnectionOptions({
+  onConnected,
+  testIdRoot = "add-backend",
+  initialManualBackend,
+  requireManualApiKey = false,
+  manualSubmitLabel,
+  manualSubmittingLabel,
+  manualSubmitTestId,
+  analyticsSource,
+}: BackendConnectionOptionsProps) {
+  const { t } = useTranslation("openhands");
+  const lockedCloudHost = getLockedCloudHost();
+
+  if (lockedCloudHost) {
+    return (
+      <div
+        data-testid={`${testIdRoot}-connection-options`}
+        className="flex justify-center"
+      >
+        <div className="w-full">
+          <CloudLoginColumn
+            onConnected={onConnected}
+            testIdRoot={testIdRoot}
+            lockedHost={lockedCloudHost}
+            analyticsSource={analyticsSource}
+          />
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      data-testid={`${testIdRoot}-connection-options`}
+      className="flex flex-col gap-6 md:flex-row"
+    >
+      <div className="flex-1 min-w-0">
+        <ManualConnectionColumn
+          onConnected={onConnected}
+          testIdRoot={testIdRoot}
+          initialBackend={initialManualBackend}
+          requireApiKey={requireManualApiKey}
+          submitLabel={manualSubmitLabel ?? t(I18nKey.BACKEND$CONNECT)}
+          submittingLabel={
+            manualSubmittingLabel ??
+            t(I18nKey.ONBOARDING$BACKEND_STATUS_CHECKING)
+          }
+          submitTestId={manualSubmitTestId}
+        />
+      </div>
+
+      <div className="flex-1 min-w-0">
+        <CloudLoginColumn
+          onConnected={onConnected}
+          testIdRoot={testIdRoot}
+          analyticsSource={analyticsSource}
+        />
+      </div>
+    </div>
+  );
+}
+
+interface ManualConnectionColumnProps {
+  onConnected: (
+    payload: BackendFormSubmitPayload,
+    connectionMethod: BackendConnectionMethod,
+    metadata?: BackendConnectionTestMetadata,
+  ) => void;
+  testIdRoot: string;
+  initialBackend?: Partial<
+    Pick<BackendFormSubmitPayload, "name" | "host" | "apiKey">
+  >;
+  requireApiKey: boolean;
+  submitLabel: React.ReactNode;
+  submittingLabel: React.ReactNode;
+  submitTestId?: string;
+  fixedKind?: BackendKind;
+  showKindSelector?: boolean;
+}
+
+/**
+ * Manual connection via Host + API Key. Designed for self-hosted agent servers
+ * and self-hosted OpenHands Cloud with API key auth.
+ */
+function ManualConnectionColumn({
+  onConnected,
+  testIdRoot,
+  initialBackend,
+  requireApiKey,
+  submitLabel,
+  submittingLabel,
+  submitTestId,
+  fixedKind,
+  showKindSelector = true,
+}: ManualConnectionColumnProps) {
+  const { t } = useTranslation("openhands");
+
+  const {
+    name,
+    setName,
+    host,
+    setHost,
+    apiKey,
+    setApiKey,
+    connectionError,
+    setConnectionError,
+    isSubmitting,
+    kind,
+    setKind,
+    canSubmit,
+    handleSubmit,
+  } = useBackendForm({
+    initialName: initialBackend?.name ?? "",
+    initialHost: initialBackend?.host ?? "",
+    initialApiKey: initialBackend?.apiKey ?? "",
+    onTestConnection: testBackendConnection,
+    onSuccess: (metadata) => {
+      onConnected(
+        {
+          name: name.trim(),
+          host: normalizeHost(host),
+          apiKey: apiKey.trim(),
+          kind,
+        },
+        "manual",
+        metadata,
+      );
+    },
+    requireApiKey,
+    fixedKind,
+  });
+
+  return (
+    <form
+      data-testid={`${testIdRoot}-form`}
+      onSubmit={handleSubmit}
+      className="flex flex-col gap-4 flex-1 min-w-0"
+    >
+      <SettingsInput
+        testId={`${testIdRoot}-name`}
+        name={`${testIdRoot}-name`}
+        type="text"
+        label={t(I18nKey.BACKEND$NAME_LABEL)}
+        hint={t(I18nKey.BACKEND$NAME_HELPER)}
+        value={name}
+        onChange={(value) => {
+          setName(value);
+          setConnectionError(null);
+        }}
+        // eslint-disable-next-line i18next/no-literal-string -- example placeholder, not user-facing copy
+        placeholder="e.g. My Server"
+        className="w-full"
+      />
+
+      <SettingsInput
+        testId={`${testIdRoot}-host`}
+        name={`${testIdRoot}-host`}
+        type="text"
+        label={t(I18nKey.BACKEND$HOST_LABEL)}
+        hint={t(I18nKey.BACKEND$HOST_HELPER)}
+        value={host}
+        onChange={(value) => {
+          setHost(value);
+          setConnectionError(null);
+        }}
+        // eslint-disable-next-line i18next/no-literal-string -- example value, not translatable
+        placeholder="http://localhost:8000"
+        className="w-full"
+      />
+
+      {showKindSelector ? (
+        <div className="flex flex-col items-start gap-2.5">
+          <span className="text-sm">{t(I18nKey.BACKEND$KIND_LABEL)}</span>
+          <SegmentedToggle<BackendKind>
+            value={kind}
+            options={[
+              { value: "local", label: t(I18nKey.BACKEND$KIND_LOCAL) },
+              { value: "cloud", label: t(I18nKey.BACKEND$KIND_CLOUD) },
+            ]}
+            onChange={(value) => setKind(value)}
+            ariaLabel={t(I18nKey.BACKEND$KIND_LABEL)}
+            testId={`${testIdRoot}-kind`}
+          />
+        </div>
+      ) : null}
+
+      <SettingsInput
+        testId={`${testIdRoot}-api-key`}
+        name={`${testIdRoot}-api-key`}
+        type="password"
+        label={t(I18nKey.BACKEND$KEY_LABEL)}
+        value={apiKey}
+        onChange={(value) => {
+          setApiKey(value);
+          setConnectionError(null);
+        }}
+        // eslint-disable-next-line i18next/no-literal-string -- example value, not translatable
+        placeholder="sk-••••••••••"
+        className="w-full"
+      />
+
+      {connectionError ? (
+        <div
+          role="alert"
+          data-testid={`${testIdRoot}-error`}
+          className="rounded-md border border-red-500/40 bg-red-500/10 p-3 text-sm text-red-300 whitespace-pre-wrap break-words"
+        >
+          {connectionError}
+        </div>
+      ) : null}
+
+      <BrandButton
+        type="submit"
+        variant="secondary"
+        isDisabled={!canSubmit || isSubmitting}
+        testId={submitTestId ?? `${testIdRoot}-submit`}
+        className="w-full text-center"
+      >
+        {isSubmitting ? submittingLabel : submitLabel}
+      </BrandButton>
+    </form>
+  );
+}
+
+interface CloudLoginColumnProps {
+  onConnected: (
+    payload: BackendFormSubmitPayload,
+    connectionMethod: BackendConnectionMethod,
+    metadata?: BackendConnectionTestMetadata,
+  ) => void;
+  testIdRoot: string;
+  lockedHost?: string;
+  analyticsSource?: CloudConnectionSource;
+  /** Omit repeated branding when a surrounding chooser already names Cloud. */
+  showBranding?: boolean;
+}
+
+/**
+ * One-click OAuth login with OpenHands Cloud. Includes an "Advanced"
+ * disclosure for users who self-host OpenHands Cloud and need to override the
+ * host.
+ */
+function CloudLoginColumn({
+  onConnected,
+  testIdRoot,
+  lockedHost,
+  analyticsSource,
+  showBranding = true,
+}: CloudLoginColumnProps) {
+  const { t } = useTranslation("openhands");
+
+  const [advancedOpen, setAdvancedOpen] = React.useState(false);
+  const [customHost, setCustomHost] = React.useState("");
+  const advancedPanelId = `${testIdRoot}-advanced-panel`;
+
+  const effectiveHost =
+    lockedHost ?? (customHost.trim() || DEFAULT_OPENHANDS_CLOUD_HOST);
+
+  const handleLoginSuccess = (apiKey: string) => {
+    onConnected(
+      {
+        name: "OpenHands Cloud",
+        host: normalizeHost(effectiveHost),
+        apiKey,
+        kind: "cloud",
+      },
+      "cloud_login",
+    );
+  };
+
+  return (
+    <div className="flex w-full min-w-0 flex-col items-center gap-3">
+      {showBranding ? (
+        <div className="flex flex-col items-center gap-1">
+          <OpenHandsLogoWhite width={56} height={56} aria-hidden />
+
+          <h4
+            className={modalTitleLgMediumClassName}
+            data-testid={`${testIdRoot}-cloud-title`}
+          >
+            {t(I18nKey.BACKEND$CLOUD_TITLE)}
+          </h4>
+        </div>
+      ) : null}
+
+      <DeviceFlowAuth
+        host={effectiveHost}
+        onSuccess={handleLoginSuccess}
+        testIdRoot={testIdRoot}
+        analyticsSource={analyticsSource}
+        className="w-full items-center"
+        idleDescription={
+          <p
+            className="text-center text-sm leading-relaxed text-[var(--oh-muted)]"
+            data-testid={`${testIdRoot}-cloud-description`}
+          >
+            {t(I18nKey.BACKEND$CLOUD_DESCRIPTION)}
+          </p>
+        }
+        // Host overriding only matters before the flow starts, so it rides the
+        // same idle-only slot as the description instead of sitting under the
+        // authorization status.
+        idleFooter={
+          lockedHost ? null : (
+            // Keep the Advanced disclosure at the original compact width even
+            // though the surrounding cloud panel spans the full chooser.
+            <div className="mx-auto w-full max-w-md">
+              <button
+                type="button"
+                onClick={() => setAdvancedOpen((open) => !open)}
+                aria-expanded={advancedOpen}
+                aria-controls={advancedPanelId}
+                data-testid={`${testIdRoot}-advanced-toggle`}
+                className="flex w-full cursor-pointer items-center justify-center gap-1 text-center text-xs text-[var(--oh-muted)] transition-colors hover:text-content-2"
+              >
+                <span>{t(I18nKey.BACKEND$ADVANCED)}</span>
+                <ChevronDownSmallIcon
+                  className={cn(
+                    "h-4 w-4 shrink-0 text-muted transition-transform duration-200 ease-out",
+                    advancedOpen && "rotate-180",
+                  )}
+                  aria-hidden
+                />
+              </button>
+              {/* Height animates through `grid-template-rows` (0fr ↔ 1fr) so no
+                  max-height guess is needed; the inner clip is what makes `0fr`
+                  collapse. Content stays mounted so a typed host survives, and
+                  `inert` keeps the collapsed field out of the tab order. */}
+              <div
+                className={cn(
+                  "grid transition-[grid-template-rows] duration-200 ease-out motion-reduce:transition-none",
+                  advancedOpen ? "grid-rows-[1fr]" : "grid-rows-[0fr]",
+                )}
+              >
+                <div className="overflow-hidden">
+                  <div
+                    id={advancedPanelId}
+                    data-testid={`${testIdRoot}-advanced-panel`}
+                    aria-hidden={!advancedOpen}
+                    inert={!advancedOpen ? true : undefined}
+                    className={cn(
+                      "pt-3 transition-opacity duration-200 ease-out motion-reduce:transition-none",
+                      advancedOpen ? "opacity-100" : "opacity-0",
+                    )}
+                  >
+                    <SettingsInput
+                      testId={`${testIdRoot}-cloud-host`}
+                      name={`${testIdRoot}-cloud-host`}
+                      type="text"
+                      label={t(I18nKey.BACKEND$HOST_LABEL)}
+                      value={customHost}
+                      onChange={setCustomHost}
+                      placeholder={DEFAULT_OPENHANDS_CLOUD_HOST}
+                      className="w-full"
+                    />
+                    <p className="mt-1 text-xs text-[var(--oh-muted)]">
+                      {t(I18nKey.BACKEND$LOGIN_CLOUD_HINT)}
+                    </p>
+                  </div>
+                </div>
+              </div>
+            </div>
+          )
+        }
+      />
+    </div>
+  );
+}
+
+interface BackendOptionTabProps {
+  value: AddBackendOption;
+  selectedValue: AddBackendOption;
+  title: string;
+  description: string;
+  icon: React.ReactNode;
+  onSelect: (value: AddBackendOption) => void;
+  panelId: string;
+  testId: string;
+}
+
+/**
+ * Presents a connection-method tab: icon, title, and a one-line subtitle.
+ *
+ * The shared tablist owns the outer border, so these buttons meet cleanly at
+ * the center. Selection uses a bottom bar instead of recoloring the full
+ * outline, preserving the group as one visual control.
+ */
+function BackendOptionTab({
+  value,
+  selectedValue,
+  title,
+  description,
+  icon,
+  onSelect,
+  panelId,
+  testId,
+}: BackendOptionTabProps) {
+  const isSelected = value === selectedValue;
+  const tabId = `${testId}-tab`;
+
+  return (
+    <button
+      id={tabId}
+      type="button"
+      role="tab"
+      aria-selected={isSelected}
+      aria-controls={panelId}
+      data-testid={testId}
+      onClick={() => onSelect(value)}
+      className={cn(
+        "relative flex min-h-16 w-full cursor-pointer items-center gap-3 px-3 py-3 text-left transition-colors",
+        "first:border-r first:border-r-[var(--oh-border)]",
+        "focus-visible:z-10 focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-blue-300",
+        isSelected
+          ? "bg-[var(--oh-surface-raised)] text-white after:absolute after:inset-x-0 after:bottom-0 after:h-0.5 after:bg-primary"
+          : "text-[var(--oh-muted)] hover:bg-[var(--oh-surface-raised)] hover:text-white",
+      )}
+    >
+      <span
+        className="flex size-8 shrink-0 items-center justify-center"
+        aria-hidden
+      >
+        {icon}
+      </span>
+      <span className="min-w-0 flex-1">
+        <span className="block truncate text-sm font-medium">{title}</span>
+        <span className="mt-0.5 block text-xs leading-tight text-[var(--oh-muted)]">
+          {description}
+        </span>
+      </span>
+    </button>
+  );
+}
+
+interface AnimatedPanelHeightProps {
+  children: React.ReactNode;
+}
+
+/**
+ * Animates a panel between content-driven heights.
+ *
+ * A ResizeObserver keeps the wrapper synchronized as tabs or nested
+ * disclosures change. The transition class remains mounted before the
+ * observer publishes a new height; adding it in the same render as the height
+ * would give the browser no previous painted value to interpolate from.
+ */
+function AnimatedPanelHeight({ children }: AnimatedPanelHeightProps) {
+  const contentRef = React.useRef<HTMLDivElement>(null);
+  const [height, setHeight] = React.useState<number>();
+
+  React.useLayoutEffect(() => {
+    const content = contentRef.current;
+    if (!content) return undefined;
+
+    const measure = () => {
+      const nextHeight = content.getBoundingClientRect().height;
+      // jsdom reports zero-sized layout boxes; leaving height automatic there
+      // keeps component tests representative without changing browser behavior.
+      setHeight(nextHeight > 0 ? nextHeight : undefined);
+    };
+
+    measure();
+    if (typeof ResizeObserver === "undefined") return undefined;
+
+    const observer = new ResizeObserver(measure);
+    observer.observe(content);
+    return () => observer.disconnect();
+  }, []);
+
+  return (
+    <div
+      data-testid="add-backend-panel-height"
+      style={height === undefined ? undefined : { height }}
+      className="overflow-hidden transition-[height] duration-300 ease-in-out motion-reduce:transition-none"
+    >
+      <div ref={contentRef}>{children}</div>
+    </div>
+  );
+}
+
+/**
+ * Collects every setup instruction for the selected location into one
+ * collapsible note.
+ *
+ * All of the guidance lives here — the intro, the example command (local) or
+ * the host formats to use with a tunnel (remote), and the docs link — so users
+ * never have to leave the modal to find out what belongs in the host field.
+ * It starts collapsed so the connection form remains compact; users can
+ * reveal the complete instructions without leaving the modal.
+ *
+ * Open/close uses a `grid-template-rows` transition (`0fr` ↔ `1fr`) so the
+ * height animates without a fixed `max-height` guess. Content stays mounted
+ * so the toggle does not remount the docs link on every expand.
+ */
+function AgentServerGuidance({ location }: { location: AgentServerLocation }) {
+  const { t } = useTranslation("openhands");
+  const [isExpanded, setIsExpanded] = React.useState(false);
+  const isRemote = location === "remote";
+  const title = isRemote
+    ? t(I18nKey.BACKEND$REMOTE_SETUP_TITLE)
+    : t(I18nKey.BACKEND$BEFORE_CONNECT_TITLE);
+  const description = isRemote
+    ? t(I18nKey.BACKEND$REMOTE_SETUP_DESCRIPTION)
+    : t(I18nKey.BACKEND$LOCAL_SETUP_DESCRIPTION);
+  const docsHref = isRemote
+    ? REMOTE_AGENT_SERVER_DOCS_URL
+    : LOCAL_AGENT_SERVER_DOCS_URL;
+  const docsLabel = isRemote
+    ? t(I18nKey.BACKEND$REMOTE_SETUP_DOCS)
+    : t(I18nKey.BACKEND$LOCAL_SETUP_DOCS);
+  const testIdRoot = isRemote ? "add-backend-remote" : "add-backend-local";
+  const toggleId = `${testIdRoot}-guidance-toggle`;
+  const bodyId = `${testIdRoot}-guidance-body`;
+
+  return (
+    <aside
+      data-testid={`${testIdRoot}-guidance`}
+      className="rounded-lg bg-[var(--oh-surface-raised)] text-sm text-[var(--oh-muted)]"
+    >
+      {/* Heading wraps the button so the accordion keeps a real heading in the
+          document outline while the whole row stays clickable. */}
+      <h4 className="text-white">
+        <button
+          id={toggleId}
+          type="button"
+          onClick={() => setIsExpanded((expanded) => !expanded)}
+          aria-expanded={isExpanded}
+          aria-controls={bodyId}
+          data-testid={toggleId}
+          className={cn(
+            // Padding lives on the button rather than the card so the hover
+            // fill spans the full row.
+            "flex w-full cursor-pointer items-center justify-between gap-2 rounded-lg px-3 py-2 text-left font-medium",
+            "transition-colors hover:bg-[var(--oh-interactive-hover)]",
+            "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-300",
+          )}
+        >
+          <span className="flex min-w-0 items-center gap-2">
+            <Info
+              className="size-4 shrink-0 text-[var(--oh-muted)]"
+              aria-hidden
+            />
+            <span className="truncate">{title}</span>
+          </span>
+          <ChevronDown
+            className={cn(
+              "size-5 shrink-0 text-[var(--oh-muted)] transition-transform duration-200 ease-out",
+              isExpanded && "rotate-180",
+            )}
+            aria-hidden
+          />
+        </button>
+      </h4>
+
+      {/* Outer grid owns the height animation; the inner overflow clip is
+          required so `1fr` measures the content while `0fr` fully collapses. */}
+      <div
+        className={cn(
+          "grid transition-[grid-template-rows] duration-200 ease-out motion-reduce:transition-none",
+          isExpanded ? "grid-rows-[1fr]" : "grid-rows-[0fr]",
+        )}
+      >
+        <div className="overflow-hidden">
+          <div
+            id={bodyId}
+            data-testid={bodyId}
+            role="region"
+            aria-labelledby={toggleId}
+            aria-hidden={!isExpanded}
+            inert={!isExpanded ? true : undefined}
+            className={cn(
+              "flex flex-col gap-2 px-3 pb-3 transition-opacity duration-200 ease-out motion-reduce:transition-none",
+              isExpanded ? "opacity-100" : "opacity-0",
+            )}
+          >
+            <p className="leading-5">{description}</p>
+
+            {isRemote ? (
+              <div>
+                <h5 className="font-medium text-white">
+                  {t(I18nKey.BACKEND$REMOTE_CONNECTION_TITLE)}
+                </h5>
+                <p className="mt-1 leading-5">
+                  {t(I18nKey.BACKEND$REMOTE_CONNECTION_DESCRIPTION)}
+                </p>
+              </div>
+            ) : (
+              <code className="block break-words font-mono text-xs text-white">
+                {LOCAL_BACKEND_COMMAND}
+              </code>
+            )}
+
+            <a
+              href={docsHref}
+              target="_blank"
+              rel="noopener noreferrer"
+              data-testid={`${testIdRoot}-docs-link`}
+              tabIndex={isExpanded ? undefined : -1}
+              className="inline-flex w-fit items-center gap-1.5 text-primary hover:underline"
+            >
+              <span>{docsLabel}</span>
+              <ExternalLinkIcon className="size-4 shrink-0" aria-hidden />
+            </a>
+          </div>
+        </div>
+      </div>
+    </aside>
+  );
+}
+
+function AddBackendChooser({
+  onConnected,
+  source,
+}: {
+  onConnected: (
+    payload: BackendFormSubmitPayload,
+    connectionMethod: BackendConnectionMethod,
+    metadata?: BackendConnectionTestMetadata,
+  ) => void;
+  source: BackendAddedSource;
+}) {
+  const { t } = useTranslation("openhands");
+  const [selectedOption, setSelectedOption] =
+    React.useState<AddBackendOption>("cloud");
+  const [agentServerLocation, setAgentServerLocation] =
+    React.useState<AgentServerLocation>("local");
+  const panelId = "add-backend-selected-panel";
+  const selectedTabId = `add-backend-option-${selectedOption}-tab`;
+  const isCloudSelected = selectedOption === "cloud";
+
+  return (
+    <div data-testid="add-backend-chooser" className="flex flex-col">
+      <div
+        role="tablist"
+        aria-label={t(I18nKey.BACKEND$CHOOSER_TITLE)}
+        className="grid grid-cols-2 overflow-hidden rounded-lg border border-[var(--oh-border)]"
+      >
+        <BackendOptionTab
+          value="cloud"
+          selectedValue={selectedOption}
+          title={t(I18nKey.BACKEND$CLOUD_TITLE)}
+          description={t(I18nKey.BACKEND$CLOUD_OPTION_DESCRIPTION)}
+          icon={
+            <OpenHandsLogoWhite
+              width={32}
+              height={32}
+              data-testid="add-backend-option-cloud-logo"
+            />
+          }
+          onSelect={setSelectedOption}
+          panelId={panelId}
+          testId="add-backend-option-cloud"
+        />
+        <BackendOptionTab
+          value="agent-server"
+          selectedValue={selectedOption}
+          title={t(I18nKey.BACKEND$AGENT_SERVER_TITLE)}
+          description={t(I18nKey.BACKEND$AGENT_SERVER_OPTION_DESCRIPTION)}
+          icon={<ServerIcon className="size-6" />}
+          onSelect={setSelectedOption}
+          panelId={panelId}
+          testId="add-backend-option-agent-server"
+        />
+      </div>
+
+      <div className="mt-6">
+        <AnimatedPanelHeight>
+          <section
+            id={panelId}
+            role="tabpanel"
+            aria-labelledby={selectedTabId}
+            className="min-w-0"
+          >
+            {isCloudSelected ? (
+              /* Padding keeps the CTA and Advanced host field from hugging the
+                 border; when Advanced expands the panel grows with the content
+                 instead of squeezing it into the reserved min-height. */
+              <div
+                data-testid="add-backend-cloud-panel"
+                className={cn(
+                  "relative isolate flex min-h-[13.5rem] w-full items-center justify-center rounded-xl border border-[var(--oh-border)] px-5 py-6",
+                  // A soft greyscale halo sits behind the CTA; -z-10 keeps it under the
+                  // content rather than washing over it.
+                  "before:pointer-events-none before:absolute before:inset-0 before:-z-10 before:rounded-xl",
+                  "before:bg-[radial-gradient(75%_75%_at_50%_50%,rgba(255,255,255,0.1)_0%,rgba(255,255,255,0)_70%)]",
+                )}
+              >
+                <CloudLoginColumn
+                  onConnected={onConnected}
+                  testIdRoot="add-backend"
+                  analyticsSource={source}
+                  showBranding={false}
+                />
+              </div>
+            ) : (
+              <div
+                data-testid="add-backend-agent-server-panel"
+                className="mx-auto w-full max-w-xl"
+              >
+                {/* Rules on either side center the toggle and read as a
+                    divider between the chooser and the connection form. */}
+                <div className="flex items-center gap-3">
+                  <span
+                    className="h-px flex-1 bg-[var(--oh-border)]"
+                    aria-hidden
+                  />
+                  <SegmentedToggle<AgentServerLocation>
+                    value={agentServerLocation}
+                    options={[
+                      {
+                        value: "local",
+                        label: t(I18nKey.BACKEND$KIND_LOCAL),
+                        icon: <Monitor aria-hidden />,
+                      },
+                      {
+                        value: "remote",
+                        label: t(I18nKey.BACKEND$KIND_REMOTE),
+                        icon: <Globe aria-hidden />,
+                      },
+                    ]}
+                    onChange={setAgentServerLocation}
+                    ariaLabel={t(I18nKey.BACKEND$AGENT_SERVER_LOCATION)}
+                    testId="add-backend-location"
+                  />
+                  <span
+                    className="h-px flex-1 bg-[var(--oh-border)]"
+                    aria-hidden
+                  />
+                </div>
+
+                <div className="mt-4 flex flex-col gap-4">
+                  <AgentServerGuidance
+                    key={agentServerLocation}
+                    location={agentServerLocation}
+                  />
+                  <ManualConnectionColumn
+                    onConnected={onConnected}
+                    testIdRoot="add-backend"
+                    requireApiKey={agentServerLocation === "remote"}
+                    submitLabel={t(I18nKey.BACKEND$CONNECT)}
+                    submittingLabel={t(
+                      I18nKey.ONBOARDING$BACKEND_STATUS_CHECKING,
+                    )}
+                    fixedKind="local"
+                    showKindSelector={false}
+                  />
+                </div>
+              </div>
+            )}
+          </section>
+        </AnimatedPanelHeight>
+      </div>
+    </div>
+  );
+}
+
+function AddBackendConnectionOptions({
+  onClose,
+  source,
+}: {
+  onClose: () => void;
+  source: BackendAddedSource;
+}) {
+  const { addBackend } = useActiveBackendContext();
+  const redirectAfterAdd = useRedirectAfterAddBackend();
+  const { trackBackendAdded } = useTracking();
+  const lockedCloudHost = getLockedCloudHost();
+
+  const handleConnected = React.useCallback(
+    (
+      payload: BackendFormSubmitPayload,
+      connectionMethod: BackendConnectionMethod,
+      metadata?: BackendConnectionTestMetadata,
+    ) => {
+      addBackend(payload);
+      trackBackendAdded({
+        backendKind: payload.kind,
+        connectionMethod,
+        hasApiKey: Boolean(payload.apiKey),
+        source,
+        agentServerVersion: metadata?.agentServerVersion,
+      });
+      redirectAfterAdd();
+      onClose();
+    },
+    [addBackend, redirectAfterAdd, onClose, trackBackendAdded, source],
+  );
+
+  if (lockedCloudHost) {
+    return (
+      <CloudLoginColumn
+        onConnected={handleConnected}
+        testIdRoot="add-backend"
+        lockedHost={lockedCloudHost}
+        analyticsSource={source}
+      />
+    );
+  }
+
+  return <AddBackendChooser onConnected={handleConnected} source={source} />;
+}
+
+// ── Modal wrappers ──────────────────────────────────────────────────
+
+/**
+ * Modal wrapper. In **add** mode it renders a two-column layout
+ * (manual connection | OR | Cloud login). In **edit** mode it wraps
+ * the standard `BackendForm`.
+ */
+export function BackendFormModal({
+  mode,
+  backend,
+  onClose,
+  source = "add_backend_modal",
+  hideCloseButton = false,
+}: BackendFormModalProps) {
+  const { t } = useTranslation("openhands");
+
+  if (mode === "add") {
+    return (
+      <ModalBackdrop
+        onClose={hideCloseButton ? undefined : onClose}
+        closeOnEscape={false}
+        closeOnBackdropClick={!hideCloseButton}
+        aria-label={t(I18nKey.BACKEND$ADD_TITLE)}
+      >
+        <div
+          data-testid={
+            hideCloseButton ? "onboarding-modal" : "add-backend-modal"
+          }
+          className={cn(
+            "relative max-h-[92vh] w-[720px] overflow-y-auto rounded-xl border border-[var(--oh-border)] bg-base-secondary p-6",
+            MODAL_MAX_WIDTH_VIEWPORT,
+          )}
+        >
+          {hideCloseButton ? null : (
+            <ModalCloseButton onClose={onClose} testId="add-backend-close" />
+          )}
+          {hideCloseButton ? null : (
+            <div className="pr-8">
+              <h2 className={modalTitleLgClassName}>
+                {t(I18nKey.BACKEND$CHOOSER_TITLE)}
+              </h2>
+              <p
+                className="mt-2 text-sm leading-6 text-[var(--oh-muted)]"
+                data-testid="add-backend-description"
+              >
+                {t(I18nKey.BACKEND$CHOOSER_DESCRIPTION)}{" "}
+                <a
+                  href={DEPLOYMENT_OPTIONS_URL}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  aria-label={t(I18nKey.BACKEND$DEPLOYMENT_OPTIONS)}
+                  data-testid="add-backend-deployment-options-link"
+                  className="text-primary hover:underline"
+                >
+                  {t(I18nKey.CTA$LEARN_MORE)}
+                  <ExternalLinkIcon
+                    className="ml-1 inline size-3.5 align-[-0.125em]"
+                    aria-hidden
+                  />
+                </a>
+              </p>
+            </div>
+          )}
+
+          <div className={hideCloseButton ? undefined : "mt-5"}>
+            <AddBackendConnectionOptions onClose={onClose} source={source} />
+          </div>
+        </div>
+      </ModalBackdrop>
+    );
+  }
+
+  // Edit mode — single-column form (unchanged)
+  const testIdRoot = "edit-backend";
+  return (
+    <ModalBackdrop
+      onClose={onClose}
+      closeOnEscape={false}
+      aria-label={t(I18nKey.BACKEND$EDIT_TITLE)}
+    >
+      <div
+        data-testid={`${testIdRoot}-modal`}
+        className={cn(
+          "relative bg-base-secondary p-6 rounded-xl flex flex-col gap-4 border border-[var(--oh-border)]",
+          modalWidthClassName("md"),
+        )}
+      >
+        <ModalCloseButton onClose={onClose} testId={`${testIdRoot}-close`} />
+        <h2 className={cn("pr-6", modalTitleLgClassName)}>
+          {t(I18nKey.BACKEND$EDIT_TITLE)}
+        </h2>
+        <BackendForm
+          mode="edit"
+          backend={backend}
+          onSubmitted={onClose}
+          testIdRoot={testIdRoot}
+        />
+      </div>
+    </ModalBackdrop>
+  );
+}

src/components/features/backends/backend-row.tsx

@@ -0,0 +1,162 @@
+import { useTranslation } from "react-i18next";
+import { Pencil, RefreshCw, Trash2 } from "lucide-react";
+
+import { type Backend } from "#/api/backend-registry/types";
+import {
+  isCloudBackendLoggedOutHealthError,
+  isInvalidBackendApiKeyHealthError,
+  type BackendHealth,
+} from "#/hooks/query/use-backends-health";
+import { I18nKey } from "#/i18n/declaration";
+import { cn } from "#/utils/utils";
+import { BackendStatusDot } from "./backend-status-dot";
+import { BackendVersion } from "./backend-version";
+import { DeviceFlowAuth } from "./device-flow-auth";
+import { getBackendStatusLabel } from "./backend-status-label";
+import { getLockedCloudHost } from "#/api/agent-server-config";
+
+const ROW_ACTION_BUTTON_CLASS =
+  "inline-flex cursor-pointer items-center justify-center rounded-md p-1 text-muted transition-colors hover:bg-interactive-hover hover:text-white";
+
+interface BackendRowProps {
+  backend: Backend;
+  health: BackendHealth | undefined;
+  orgLabel?: string;
+  onSelect: () => void;
+  onEdit: () => void;
+  onRemove: () => void;
+  onLogin?: (apiKey: string) => void;
+}
+
+export function BackendRow({
+  backend,
+  health,
+  orgLabel,
+  onSelect,
+  onEdit,
+  onRemove,
+  onLogin,
+}: BackendRowProps) {
+  const { t } = useTranslation("openhands");
+  const isInvalidApiKey = isInvalidBackendApiKeyHealthError(health?.lastError);
+  const isCloudLoggedOut =
+    backend.kind === "cloud" &&
+    isCloudBackendLoggedOutHealthError(health?.lastError);
+  const statusDetail =
+    !isInvalidApiKey &&
+    !isCloudLoggedOut &&
+    health?.isConnected === false &&
+    health.lastError
+      ? health.lastError
+      : null;
+  const statusLabel = isCloudLoggedOut
+    ? t(I18nKey.BACKEND$LOGGED_OUT)
+    : getBackendStatusLabel(t, backend, health);
+  const statusClassName =
+    health?.isConnected === true
+      ? "text-green-300"
+      : health?.isConnected === false
+        ? "text-red-300"
+        : "text-[var(--oh-muted)]";
+  const dotStatus = isInvalidApiKey ? false : (health?.isConnected ?? null);
+  const canSelect = health?.isConnected === true && !isInvalidApiKey;
+  const lockedCloudHost = getLockedCloudHost();
+
+  return (
+    <li
+      className="flex items-stretch"
+      data-testid={`manage-backends-row-${backend.name}`}
+    >
+      <button
+        type="button"
+        disabled={!canSelect}
+        onClick={onSelect}
+        className={cn(
+          "flex min-w-0 flex-1 items-center gap-3 px-3 py-3 text-left",
+          canSelect
+            ? "cursor-pointer transition-colors hover:bg-interactive-hover focus-visible:bg-interactive-hover focus-visible:outline-none"
+            : "cursor-default",
+        )}
+      >
+        <BackendStatusDot isConnected={dotStatus} />
+        <div className="flex min-w-0 flex-1 flex-col">
+          <div className="flex min-w-0 items-center gap-2">
+            <span className="truncate text-sm text-white">{backend.name}</span>
+            <BackendVersion backend={backend} />
+          </div>
+          {orgLabel ? (
+            <span
+              data-testid={`manage-backends-org-${backend.name}`}
+              className="truncate text-xs text-[var(--oh-text-secondary)]"
+            >
+              {orgLabel}
+            </span>
+          ) : null}
+          <span className="truncate text-xs text-[var(--oh-muted)]">
+            {backend.host}
+          </span>
+          <span
+            data-testid={`manage-backends-status-${backend.name}`}
+            className={cn("truncate text-xs", statusClassName)}
+          >
+            {statusLabel}
+          </span>
+          {statusDetail ? (
+            <span
+              data-testid={`manage-backends-status-detail-${backend.name}`}
+              title={statusDetail}
+              className="text-xs text-red-300/80 whitespace-normal break-words"
+            >
+              {statusDetail}
+            </span>
+          ) : null}
+        </div>
+        <span className="px-2 py-1 rounded-full text-[11px] uppercase tracking-wide text-[var(--oh-text-tertiary)] bg-[var(--oh-surface)] border border-[var(--oh-border)]">
+          {backend.kind === "cloud"
+            ? t(I18nKey.BACKEND$KIND_CLOUD)
+            : t(I18nKey.BACKEND$KIND_LOCAL)}
+        </span>
+      </button>
+      <div className="flex shrink-0 items-center gap-2 px-3 py-3">
+        {isCloudLoggedOut && onLogin ? (
+          <DeviceFlowAuth
+            host={backend.host}
+            onSuccess={onLogin}
+            testIdRoot={`manage-backends-login-${backend.id}`}
+            idleButtonLabel={t(I18nKey.BACKEND$LOG_BACK_IN)}
+            idleButtonContent={
+              <RefreshCw className="size-4" strokeWidth={2} aria-hidden />
+            }
+            className="w-auto"
+            buttonVariant="unstyled"
+            buttonClassName={ROW_ACTION_BUTTON_CLASS}
+            statusDisplay="modal"
+            analyticsSource="manage_backends_modal"
+          />
+        ) : null}
+        {!lockedCloudHost && (
+          <button
+            type="button"
+            onClick={onEdit}
+            aria-label={t(I18nKey.BACKEND$EDIT)}
+            data-testid={`manage-backends-edit-${backend.name}`}
+            className={ROW_ACTION_BUTTON_CLASS}
+          >
+            <Pencil aria-hidden className="size-4" strokeWidth={2} />
+          </button>
+        )}
+        {!lockedCloudHost && (
+          <button
+            type="button"
+            onClick={onRemove}
+            aria-label={t(I18nKey.BACKEND$REMOVE)}
+            data-testid={`manage-backends-remove-${backend.name}`}
+            className={ROW_ACTION_BUTTON_CLASS}
+          >
+            <Trash2 aria-hidden className="size-4" strokeWidth={2} />
+          </button>
+        )}
+      </div>
+    </li>
+  );
+}

src/components/features/backends/backend-selector.tsx

@@ -0,0 +1,474 @@
+import React from "react";
+import { useTranslation } from "react-i18next";
+import { useMatch, useNavigate } from "react-router";
+import { Plus, Settings } from "lucide-react";
+import { Dropdown } from "#/ui/dropdown/dropdown";
+import { DropdownOption } from "#/ui/dropdown/types";
+import { getLockedCloudHost } from "#/api/agent-server-config";
+import { isNoBackend } from "#/api/backend-registry/active-store";
+import { useActiveBackendContext } from "#/contexts/active-backend-context";
+import { useAllCloudOrganizations } from "#/hooks/query/use-cloud-organizations";
+import { useCloudCurrentUserId } from "#/hooks/query/use-cloud-current-user-id";
+import {
+  useBackendsHealth,
+  type BackendHealth,
+} from "#/hooks/query/use-backends-health";
+import { I18nKey } from "#/i18n/declaration";
+import type { Backend } from "#/api/backend-registry/types";
+// Import the trigger helpers from the lightweight store, not the overlay
+// component, so the eagerly-mounted sidebar/backend-selector graph does not
+// pull in the overlay's render code (the overlay is lazy-loaded from
+// `routes/root-layout.tsx`).
+import {
+  ENVIRONMENT_SWITCH_SETACTIVE_DELAY_MS,
+  triggerEnvironmentSwitch,
+} from "#/components/features/backends/environment-switch-store";
+import { NavigationLink } from "#/components/shared/navigation-link";
+import { StyledTooltip } from "#/components/shared/buttons/styled-tooltip";
+import { useConversationStore } from "#/stores/conversation-store";
+import { AddBackendModal } from "./add-backend-modal";
+import { BackendStatusDot } from "./backend-status-dot";
+import { ManageBackendsModal } from "./manage-backends-modal";
+import { cn } from "#/utils/utils";
+import { formControlTransitionClassName } from "#/utils/form-control-classes";
+import {
+  dropdownFooterActionClassName,
+  dropdownMenuListClassName,
+  dropdownMenuRowIconWrapperClassName,
+} from "#/utils/dropdown-classes";
+
+const VALUE_SEPARATOR = "::";
+
+function makeOptionValue(backendId: string, orgId: string | null): string {
+  return orgId ? `${backendId}${VALUE_SEPARATOR}${orgId}` : backendId;
+}
+
+function parseOptionValue(value: string): {
+  backendId: string;
+  orgId: string | null;
+} {
+  const [backendId, orgId] = value.split(VALUE_SEPARATOR);
+  return { backendId, orgId: orgId ?? null };
+}
+
+function buildStatusPrefix(health: BackendHealth | undefined) {
+  return <BackendStatusDot isConnected={health?.isConnected ?? null} />;
+}
+
+function buildNoBackendPrefix() {
+  return <BackendStatusDot isConnected="unavailable" />;
+}
+
+function buildOptions(
+  registered: Backend[],
+  personalWorkspaceLabel: string,
+  cloudOrgs: ReturnType<typeof useAllCloudOrganizations>,
+  currentUserIds: ReturnType<typeof useCloudCurrentUserId>,
+  healthByBackendId: Record<string, BackendHealth>,
+): DropdownOption[] {
+  const options: DropdownOption[] = [];
+
+  const locals = registered.filter((b) => b.kind === "local");
+  const clouds = registered.filter((b) => b.kind === "cloud");
+
+  for (const b of locals) {
+    options.push({
+      value: makeOptionValue(b.id, null),
+      label: b.name,
+      prefix: buildStatusPrefix(healthByBackendId[b.id]),
+    });
+  }
+
+  for (const b of clouds) {
+    const entry = cloudOrgs[b.id];
+    const prefix = buildStatusPrefix(healthByBackendId[b.id]);
+    if (!entry || entry.orgs.length === 0) {
+      options.push({
+        value: makeOptionValue(b.id, null),
+        label: b.name,
+        prefix,
+      });
+    } else {
+      // Personal-workspace rule (per the cloud contract): the org whose
+      // id matches the calling user's id is the user's personal
+      // workspace. We resolve `user_id` once per backend (via /me on any
+      // one org) and apply it across all orgs of that backend.
+      const userIdForBackend = currentUserIds[b.id]?.userId ?? null;
+
+      for (const org of entry.orgs) {
+        const isPersonal = !!userIdForBackend && userIdForBackend === org.id;
+        const orgLabel = isPersonal ? personalWorkspaceLabel : org.name;
+        options.push({
+          value: makeOptionValue(b.id, org.id),
+          label: `${b.name} – ${orgLabel}`,
+          // All org rows for the same cloud backend share that backend's
+          // single connectivity verdict — there is no per-org probe.
+          prefix,
+        });
+      }
+    }
+  }
+
+  return options;
+}
+
+interface BackendSelectorProps {
+  /** Render the menu above the trigger (e.g. when pinned to bottom of sidebar). */
+  openUpward?: boolean;
+  /** Hide the selector input trigger and only render the dropdown menu. */
+  hideTrigger?: boolean;
+  /** Whether the dropdown menu should start open on mount. */
+  defaultOpen?: boolean;
+  /** Callback fired after selecting a backend/org option. */
+  onSelectOption?: () => void;
+  /**
+   * Override the internal Add Backend modal handling. When provided,
+   * clicking "Add Backend" calls this instead of opening BackendSelector's
+   * own modal. Useful when the selector is mounted inside an ephemeral
+   * container (e.g. the collapsed-sidebar popover) and the modal must
+   * survive the parent unmounting.
+   */
+  onOpenAddBackend?: () => void;
+  /** Same as onOpenAddBackend but for the Manage Backends modal. */
+  onOpenManageBackends?: () => void;
+  /**
+   * Whether the surrounding sidebar rail is in its collapsed variant. Passed
+   * down from `SidebarRailBody` so the mobile drawer (which always renders
+   * the expanded rail) can override the persisted desktop value.
+   */
+  sidebarCollapsed?: boolean;
+}
+
+export function BackendSelector({
+  openUpward = false,
+  hideTrigger = false,
+  defaultOpen = false,
+  onSelectOption,
+  onOpenAddBackend,
+  onOpenManageBackends,
+  sidebarCollapsed = false,
+}: BackendSelectorProps = {}) {
+  const { t } = useTranslation("openhands");
+  const { backends, active, setActive } = useActiveBackendContext();
+  const cloudOrgs = useAllCloudOrganizations();
+  const currentUserIds = useCloudCurrentUserId();
+  // Probe each registered backend every 10s.
+  const healthByBackendId = useBackendsHealth(backends);
+  const navigate = useNavigate();
+  const settingsMatch = useMatch("/settings");
+  const settingsSubrouteMatch = useMatch("/settings/*");
+  const conversationMatch = useMatch("/conversations/:conversationId");
+  const automationDetailMatch = useMatch("/automations/:automationId");
+  const [addBackendModalOpen, setAddBackendModalOpen] = React.useState(false);
+  const [manageBackendsModalOpen, setManageBackendsModalOpen] =
+    React.useState(false);
+
+  const personalWorkspaceLabel = t(I18nKey.BACKEND$PERSONAL_WORKSPACE);
+
+  const options = React.useMemo(
+    () =>
+      buildOptions(
+        backends,
+        personalWorkspaceLabel,
+        cloudOrgs,
+        currentUserIds,
+        healthByBackendId,
+      ),
+    [
+      backends,
+      personalWorkspaceLabel,
+      cloudOrgs,
+      currentUserIds,
+      healthByBackendId,
+    ],
+  );
+
+  const noBackendSelected = isNoBackend(active.backend);
+  const noBackendLabel = t(I18nKey.BACKEND$NO_BACKEND_AVAILABLE);
+  const activeValue = makeOptionValue(active.backend.id, active.orgId);
+  const activeOption = noBackendSelected
+    ? undefined
+    : options.find((o) => o.value === activeValue);
+  const isSettingsActive = Boolean(settingsMatch || settingsSubrouteMatch);
+  const settingsLabel = t(I18nKey.SIDEBAR$SETTINGS);
+  // `org` is consumed by the cloud settings loader so the page opens on the
+  // org that is active here instead of the cloud's last-used org.
+  const cloudSettingsOrgQuery = active.orgId
+    ? `?org=${encodeURIComponent(active.orgId)}`
+    : "";
+  const isRightPanelShown = useConversationStore(
+    (state) => state.isRightPanelShown,
+  );
+  // When the sidebar rail is expanded, `placement="left"` hugs the main
+  // canvas and reads awkwardly; prefer above the control. When the rail is
+  // collapsed, keep left except on active conversation + open right drawer.
+  const settingsTooltipPlacement =
+    !sidebarCollapsed || (conversationMatch && isRightPanelShown)
+      ? "top"
+      : "left";
+
+  const someCloudLoading = Object.values(cloudOrgs).some((c) => c.isLoading);
+
+  // Self-heal a malformed `(cloudBackendId, null)` selection.
+  //
+  // Once a cloud backend's orgs resolve, the dropdown only renders
+  // per-org rows for it — the `(backendId, null)` row disappears, so
+  // selecting that shape would drift from what the dropdown can render
+  // (UI says "Local", APIs hit cloud). When we detect the drift, snap
+  // the selection onto Cloud's current org first, then fall back to the
+  // personal workspace (or, lacking a /me result, the first org). The
+  // selection is recorded locally only; the cloud request scope follows
+  // from the X-Org-Id header sent by `callCloudProxy`, so the cloud UI's
+  // org choice is never mutated as a side effect.
+  React.useEffect(() => {
+    if (noBackendSelected || active.backend.kind !== "cloud" || active.orgId)
+      return;
+    const { backend } = active;
+    const entry = cloudOrgs[backend.id];
+    if (!entry || entry.orgs.length === 0) return;
+
+    const currentOrg = entry.currentOrgId
+      ? entry.orgs.find((o) => o.id === entry.currentOrgId)
+      : undefined;
+    const userId = currentUserIds[backend.id]?.userId ?? null;
+    const personal = userId
+      ? entry.orgs.find((o) => o.id === userId)
+      : undefined;
+    const target = currentOrg ?? personal ?? entry.orgs[0];
+    if (target) {
+      setActive(backend.id, target.id);
+    }
+  }, [active, cloudOrgs, currentUserIds, setActive, noBackendSelected]);
+
+  const openAddBackendModal = React.useCallback(() => {
+    if (onOpenAddBackend) {
+      onOpenAddBackend();
+      onSelectOption?.();
+      return;
+    }
+    setAddBackendModalOpen(true);
+  }, [onOpenAddBackend, onSelectOption]);
+
+  const openManageBackendsModal = React.useCallback(() => {
+    if (onOpenManageBackends) {
+      onOpenManageBackends();
+      onSelectOption?.();
+      return;
+    }
+    setManageBackendsModalOpen(true);
+  }, [onOpenManageBackends, onSelectOption]);
+
+  const isLockedToCloud = getLockedCloudHost() !== null;
+  // A cookie-auth (OHE-hosted) Canvas has nothing to add, manage, or
+  // reconnect — its single locked backend is owned by the main-app session.
+  const hideBackendFooter =
+    isLockedToCloud && active.backend.authMode === "cookie";
+
+  const preventDropdownMenuClose = React.useCallback(
+    (event: React.SyntheticEvent<HTMLButtonElement>) => {
+      event.preventDefault();
+      event.stopPropagation();
+    },
+    [],
+  );
+
+  const handleAddBackendClick = React.useCallback(
+    (event: React.MouseEvent<HTMLButtonElement>) => {
+      preventDropdownMenuClose(event);
+      openAddBackendModal();
+    },
+    [openAddBackendModal, preventDropdownMenuClose],
+  );
+
+  const handleAddBackendTouchEnd = React.useCallback(
+    (event: React.TouchEvent<HTMLButtonElement>) => {
+      preventDropdownMenuClose(event);
+      openAddBackendModal();
+    },
+    [openAddBackendModal, preventDropdownMenuClose],
+  );
+
+  const handleManageBackendsClick = React.useCallback(
+    (event: React.MouseEvent<HTMLButtonElement>) => {
+      preventDropdownMenuClose(event);
+      openManageBackendsModal();
+    },
+    [openManageBackendsModal, preventDropdownMenuClose],
+  );
+
+  const handleManageBackendsTouchEnd = React.useCallback(
+    (event: React.TouchEvent<HTMLButtonElement>) => {
+      preventDropdownMenuClose(event);
+      openManageBackendsModal();
+    },
+    [openManageBackendsModal, preventDropdownMenuClose],
+  );
+
+  const addBackendFooter = hideBackendFooter ? undefined : (
+    <div className={dropdownMenuListClassName}>
+      {isLockedToCloud ? null : (
+        <button
+          type="button"
+          data-testid="add-backend-menu-item"
+          onMouseDown={preventDropdownMenuClose}
+          onTouchStart={preventDropdownMenuClose}
+          onTouchEnd={handleAddBackendTouchEnd}
+          onClick={handleAddBackendClick}
+          className={cn(
+            dropdownFooterActionClassName,
+            "cursor-pointer rounded-md",
+          )}
+        >
+          <span className={dropdownMenuRowIconWrapperClassName} aria-hidden>
+            <Plus width={16} height={16} />
+          </span>
+          {t(I18nKey.BACKEND$ADD)}
+        </button>
+      )}
+      <button
+        type="button"
+        data-testid="manage-backends-menu-item"
+        onMouseDown={preventDropdownMenuClose}
+        onTouchStart={preventDropdownMenuClose}
+        onTouchEnd={handleManageBackendsTouchEnd}
+        onClick={handleManageBackendsClick}
+        className={cn(
+          dropdownFooterActionClassName,
+          "cursor-pointer rounded-md",
+        )}
+      >
+        <span className={dropdownMenuRowIconWrapperClassName} aria-hidden>
+          <Settings width={16} height={16} />
+        </span>
+        {t(
+          isLockedToCloud
+            ? I18nKey.BACKEND$RECONNECT_CLOUD
+            : I18nKey.BACKEND$MANAGE,
+        )}
+      </button>
+    </div>
+  );
+
+  const handleSelectBackend = React.useCallback(
+    async (value: string) => {
+      if (value === activeValue) return;
+
+      const { backendId, orgId } = parseOptionValue(value);
+      const target = backends.find((b) => b.id === backendId);
+      if (!target) return;
+
+      triggerEnvironmentSwitch(
+        options.find((option) => option.value === value)?.label ?? target.name,
+      );
+      await new Promise<void>((resolve) => {
+        setTimeout(resolve, ENVIRONMENT_SWITCH_SETACTIVE_DELAY_MS);
+      });
+
+      // @spec BM-002 — Switching backends keeps the user on the same page
+      if (conversationMatch) navigate("/conversations");
+      else if (automationDetailMatch) navigate("/automations");
+
+      setActive(target.id, orgId);
+      onSelectOption?.();
+    },
+    [
+      activeValue,
+      backends,
+      conversationMatch,
+      automationDetailMatch,
+      navigate,
+      options,
+      setActive,
+      t,
+      onSelectOption,
+    ],
+  );
+
+  return (
+    <>
+      <div className="flex items-center gap-2 w-full">
+        <div className="flex-1 min-w-0">
+          <Dropdown
+            testId="backend-selector"
+            key={`${activeValue}-${activeOption?.label ?? ""}`}
+            defaultValue={
+              activeOption ?? {
+                value: activeValue,
+                label: noBackendSelected ? noBackendLabel : active.backend.name,
+                prefix: noBackendSelected
+                  ? buildNoBackendPrefix()
+                  : buildStatusPrefix(healthByBackendId[active.backend.id]),
+              }
+            }
+            footer={addBackendFooter}
+            openUpward={openUpward}
+            hideTrigger={hideTrigger}
+            defaultOpen={defaultOpen}
+            openOnHover={!hideTrigger}
+            onChange={(item) => {
+              if (!item) return;
+              void handleSelectBackend(item.value);
+            }}
+            placeholder={
+              noBackendSelected ? noBackendLabel : active.backend.name
+            }
+            loading={someCloudLoading}
+            options={options}
+            className="h-10 px-2 py-0 bg-transparent border-transparent hover:bg-[var(--oh-surface-raised)] focus-within:bg-[var(--oh-surface-raised)] focus-within:border-transparent focus-within:ring-0"
+          />
+        </div>
+        {!hideTrigger ? (
+          <StyledTooltip
+            content={settingsLabel}
+            placement={settingsTooltipPlacement}
+            offset={10}
+          >
+            {active.backend.kind === "cloud" ? (
+              <a
+                href={`${active.backend.host.replace(/\/+$/, "")}/settings${cloudSettingsOrgQuery}`}
+                target={isLockedToCloud ? undefined : "_blank"}
+                rel={isLockedToCloud ? undefined : "noopener noreferrer"}
+                data-testid="backend-selector-settings-link"
+                aria-label={settingsLabel}
+                className={cn(
+                  "inline-flex items-center justify-center shrink-0 w-9 h-9 rounded-md text-[var(--oh-muted)] hover:text-white hover:bg-[var(--oh-surface-raised)] cursor-pointer",
+                  formControlTransitionClassName,
+                )}
+              >
+                <Settings width={16} height={16} />
+              </a>
+            ) : (
+              <NavigationLink
+                to="/settings"
+                data-testid="backend-selector-settings-link"
+                data-active={isSettingsActive}
+                aria-label={settingsLabel}
+                className={
+                  isSettingsActive
+                    ? cn(
+                        "inline-flex items-center justify-center shrink-0 w-9 h-9 rounded-md bg-tertiary text-white font-normal cursor-pointer",
+                        formControlTransitionClassName,
+                      )
+                    : cn(
+                        "inline-flex items-center justify-center shrink-0 w-9 h-9 rounded-md text-[var(--oh-muted)] hover:text-white hover:bg-[var(--oh-surface-raised)] cursor-pointer",
+                        formControlTransitionClassName,
+                      )
+                }
+              >
+                <Settings width={16} height={16} />
+              </NavigationLink>
+            )}
+          </StyledTooltip>
+        ) : null}
+      </div>
+      {addBackendModalOpen ? (
+        <AddBackendModal onClose={() => setAddBackendModalOpen(false)} />
+      ) : null}
+      {manageBackendsModalOpen ? (
+        <ManageBackendsModal
+          onClose={() => setManageBackendsModalOpen(false)}
+        />
+      ) : null}
+    </>
+  );
+}

src/components/features/backends/backend-status-dot.tsx

@@ -0,0 +1,55 @@
+import React from "react";
+import { cn } from "#/utils/utils";
+
+interface BackendStatusDotProps {
+  /** `null` while the first probe is in flight. */
+  isConnected: boolean | null | "unavailable";
+  className?: string;
+}
+
+/**
+ * Small colored dot that reflects backend reachability:
+ *   - green when connected
+ *   - red when disconnected
+ *   - dim gray while the first probe is in flight
+ */
+export function BackendStatusDot({
+  isConnected,
+  className,
+}: BackendStatusDotProps) {
+  let color: string;
+  let label: string;
+  let status: string;
+  if (isConnected === "unavailable") {
+    color = "bg-[var(--oh-text-tertiary)]";
+    label = "No Backend Available";
+    status = "unavailable";
+  } else if (isConnected === true) {
+    color = "bg-[var(--oh-status-success)]";
+    label = "Connected";
+    status = "connected";
+  } else if (isConnected === false) {
+    color = "bg-red-500";
+    label = "Disconnected";
+    status = "disconnected";
+  } else {
+    color = "bg-[var(--oh-interactive-selected)]";
+    label = "Checking connection";
+    status = "checking";
+  }
+
+  return (
+    <span
+      data-testid="backend-status-dot"
+      data-status={status}
+      aria-label={label}
+      title={label}
+      role="status"
+      className={cn(
+        "inline-block w-2 h-2 rounded-full shrink-0",
+        color,
+        className,
+      )}
+    />
+  );
+}

src/components/features/backends/backend-status-label.test.ts

@@ -0,0 +1,101 @@
+import type { TFunction } from "i18next";
+import { describe, expect, it } from "vitest";
+import {
+  INVALID_BACKEND_API_KEY_ERROR,
+  MISSING_BACKEND_API_KEY_ERROR,
+} from "#/hooks/query/use-backends-health";
+import { I18nKey } from "#/i18n/declaration";
+import { CORS_OR_NETWORK_ERROR_MESSAGE } from "#/utils/user-facing-error";
+import { getBackendStatusLabel } from "./backend-status-label";
+
+const t = ((key: string) => key) as TFunction<"openhands">;
+
+describe("getBackendStatusLabel", () => {
+  it("prefers add API key for Cloud backends with a blank API key", () => {
+    expect(
+      getBackendStatusLabel(
+        t,
+        { kind: "cloud", apiKey: "" },
+        { isConnected: false, lastError: CORS_OR_NETWORK_ERROR_MESSAGE },
+      ),
+    ).toBe(I18nKey.BACKEND$STATUS_DISCONNECTED_ADD_API_KEY);
+  });
+
+  it("maps Cloud browser-network failures to API key or network guidance", () => {
+    expect(
+      getBackendStatusLabel(
+        t,
+        { kind: "cloud", apiKey: "oh-cloud-key" },
+        { isConnected: false, lastError: CORS_OR_NETWORK_ERROR_MESSAGE },
+      ),
+    ).toBe(I18nKey.BACKEND$STATUS_DISCONNECTED_CHECK_CLOUD_ACCESS);
+  });
+
+  it("keeps local browser-network failures generic", () => {
+    expect(
+      getBackendStatusLabel(
+        t,
+        { kind: "local", apiKey: "" },
+        { isConnected: false, lastError: CORS_OR_NETWORK_ERROR_MESSAGE },
+      ),
+    ).toBe(I18nKey.BACKEND$STATUS_DISCONNECTED_CHECK_URL_OR_NETWORK);
+  });
+
+  it("returns connected when the health probe is connected", () => {
+    expect(
+      getBackendStatusLabel(
+        t,
+        { kind: "local", apiKey: "" },
+        { isConnected: true, lastError: null },
+      ),
+    ).toBe(I18nKey.ONBOARDING$BACKEND_STATUS_CONNECTED);
+  });
+
+  it("returns disconnected for failed probes without a more specific reason", () => {
+    expect(
+      getBackendStatusLabel(
+        t,
+        { kind: "local", apiKey: "" },
+        { isConnected: false, lastError: "Unexpected failure" },
+      ),
+    ).toBe(I18nKey.ONBOARDING$BACKEND_STATUS_DISCONNECTED);
+  });
+
+  it("returns checking while the health probe is unresolved", () => {
+    expect(
+      getBackendStatusLabel(
+        t,
+        { kind: "local", apiKey: "" },
+        { isConnected: null, lastError: null },
+      ),
+    ).toBe(I18nKey.ONBOARDING$BACKEND_STATUS_CHECKING);
+  });
+
+  it("maps request timeouts to tunnel guidance", () => {
+    expect(
+      getBackendStatusLabel(
+        t,
+        { kind: "local", apiKey: "" },
+        { isConnected: false, lastError: "Backend request timed out" },
+      ),
+    ).toBe(I18nKey.BACKEND$STATUS_DISCONNECTED_CHECK_TUNNEL);
+  });
+
+  it("maps missing and invalid API key health errors to credential guidance", () => {
+    expect(
+      getBackendStatusLabel(
+        t,
+        { kind: "cloud", apiKey: "oh-cloud-key" },
+        { isConnected: false, lastError: MISSING_BACKEND_API_KEY_ERROR },
+      ),
+    ).toBe(I18nKey.BACKEND$STATUS_DISCONNECTED_ADD_API_KEY);
+
+    expect(
+      getBackendStatusLabel(
+        t,
+        { kind: "cloud", apiKey: "oh-cloud-key" },
+        { isConnected: false, lastError: INVALID_BACKEND_API_KEY_ERROR },
+      ),
+    ).toBe(I18nKey.BACKEND$STATUS_DISCONNECTED_CHECK_API_KEY);
+  });
+});

src/components/features/backends/backend-status-label.ts

@@ -0,0 +1,77 @@
+import type { TFunction } from "i18next";
+import {
+  isCloudBackendApiKeyOrNetworkHealthError,
+  isCloudBackendLoggedOutHealthError,
+  isInvalidBackendApiKeyHealthError,
+  isMissingBackendApiKeyHealthError,
+} from "#/hooks/query/use-backends-health";
+import { I18nKey } from "#/i18n/declaration";
+import {
+  isBackendRequestTimeoutMessage,
+  isCorsOrNetworkErrorMessage,
+} from "#/utils/user-facing-error";
+
+interface BackendStatusLabelHealth {
+  isConnected?: boolean | null;
+  lastError?: string | null;
+}
+
+export function getBackendStatusLabel(
+  t: TFunction<"openhands">,
+  backend:
+    | {
+        kind?: "local" | "cloud";
+        apiKey?: string | null;
+      }
+    | undefined,
+  health: BackendStatusLabelHealth | undefined,
+): string {
+  const lastError = health?.lastError ?? null;
+  const isCloud = backend?.kind === "cloud";
+
+  if (isCloud && !backend?.apiKey?.trim()) {
+    return t(I18nKey.BACKEND$STATUS_DISCONNECTED_ADD_API_KEY);
+  }
+
+  if (isMissingBackendApiKeyHealthError(lastError)) {
+    return t(I18nKey.BACKEND$STATUS_DISCONNECTED_ADD_API_KEY);
+  }
+
+  if (isInvalidBackendApiKeyHealthError(lastError)) {
+    return t(I18nKey.BACKEND$STATUS_DISCONNECTED_CHECK_API_KEY);
+  }
+
+  if (isCloudBackendLoggedOutHealthError(lastError)) {
+    return t(I18nKey.BACKEND$LOGGED_OUT);
+  }
+
+  if (health?.isConnected === true) {
+    return t(I18nKey.ONBOARDING$BACKEND_STATUS_CONNECTED);
+  }
+
+  if (
+    isCloud &&
+    health?.isConnected === false &&
+    (isCloudBackendApiKeyOrNetworkHealthError(lastError) ||
+      isCorsOrNetworkErrorMessage(lastError))
+  ) {
+    return t(I18nKey.BACKEND$STATUS_DISCONNECTED_CHECK_CLOUD_ACCESS);
+  }
+
+  if (
+    health?.isConnected === false &&
+    isBackendRequestTimeoutMessage(lastError)
+  ) {
+    return t(I18nKey.BACKEND$STATUS_DISCONNECTED_CHECK_TUNNEL);
+  }
+
+  if (health?.isConnected === false && isCorsOrNetworkErrorMessage(lastError)) {
+    return t(I18nKey.BACKEND$STATUS_DISCONNECTED_CHECK_URL_OR_NETWORK);
+  }
+
+  if (health?.isConnected === false) {
+    return t(I18nKey.ONBOARDING$BACKEND_STATUS_DISCONNECTED);
+  }
+
+  return t(I18nKey.ONBOARDING$BACKEND_STATUS_CHECKING);
+}

src/components/features/backends/backend-version.tsx

@@ -0,0 +1,39 @@
+import { useTranslation } from "react-i18next";
+import { useQuery } from "@tanstack/react-query";
+
+import { ServerClient } from "@openhands/typescript-client/clients";
+import { type Backend } from "#/api/backend-registry/types";
+import { getAgentServerClientOptions } from "#/api/agent-server-client-options";
+import { getDisplayAgentServerVersion } from "#/api/agent-server-compatibility";
+import { I18nKey } from "#/i18n/declaration";
+
+export function BackendVersion({ backend }: { backend: Backend }) {
+  const { t } = useTranslation("openhands");
+  const { data: version } = useQuery({
+    queryKey: ["backend-version", backend.host, backend.apiKey],
+    queryFn: async () => {
+      const info = await new ServerClient(
+        getAgentServerClientOptions({
+          host: backend.host,
+          sessionApiKey: backend.apiKey || null,
+          timeout: 5000,
+        }),
+      ).getServerInfo();
+      return getDisplayAgentServerVersion(info);
+    },
+    retry: false,
+    staleTime: 60_000,
+    enabled: backend.kind === "local",
+  });
+
+  if (!version) return null;
+
+  return (
+    <span
+      className="inline-flex shrink-0 items-center rounded-full border border-[var(--oh-border)] bg-[var(--oh-surface)] px-1.5 py-0.5 text-[10px] font-medium leading-none text-[var(--oh-text-dim)]"
+      data-testid={`manage-backends-version-${backend.name}`}
+    >
+      {t(I18nKey.BACKEND$VERSION_LABEL, { version })}
+    </span>
+  );
+}

src/components/features/backends/device-flow-auth.tsx

@@ -0,0 +1,367 @@
+import React from "react";
+import { useTranslation } from "react-i18next";
+import { BrandButton } from "#/components/features/settings/brand-button";
+import { ModalBackdrop } from "#/components/shared/modals/modal-backdrop";
+import { ModalBody } from "#/components/shared/modals/modal-body";
+import { useDeviceFlow, type DeviceFlowStatus } from "#/hooks/use-device-flow";
+import type { CloudConnectionSource } from "#/services/cloud-funnel-analytics";
+import { I18nKey } from "#/i18n/declaration";
+import { cn } from "#/utils/utils";
+
+type DeviceFlowButtonVariant =
+  | "primary"
+  | "secondary"
+  | "tertiary"
+  | "unstyled";
+type DeviceFlowStatusDisplay = "inline" | "modal";
+
+interface DeviceFlowAuthProps {
+  /** The host URL for the cloud backend */
+  host: string;
+  /** Callback when authentication succeeds with the API key */
+  onSuccess: (apiKey: string) => void;
+  /** Test ID prefix for the component */
+  testIdRoot: string;
+  /** Whether the login button should be disabled (e.g., when no host is entered) */
+  isDisabled?: boolean;
+  /** Override for the idle button label and icon-only accessible name. */
+  idleButtonLabel?: string;
+  /** Optional visible content for the idle button. Defaults to the idle label. */
+  idleButtonContent?: React.ReactNode;
+  /** Optional content shown only before authentication starts. */
+  idleDescription?: React.ReactNode;
+  /**
+   * Optional content rendered under the idle button and, like
+   * `idleDescription`, only before authentication starts — so secondary
+   * controls step aside once the flow takes over the surface.
+   */
+  idleFooter?: React.ReactNode;
+  /** Optional classes for the root wrapper. */
+  className?: string;
+  /** Optional classes for the idle button. */
+  buttonClassName?: string;
+  /** Visual variant for the idle button. */
+  buttonVariant?: DeviceFlowButtonVariant;
+  /** Whether in-progress auth content should render inline or in a modal. */
+  statusDisplay?: DeviceFlowStatusDisplay;
+  /** Product surface that initiated this authorization attempt. */
+  analyticsSource?: CloudConnectionSource;
+}
+
+/**
+ * Device Flow authentication UI component.
+ *
+ * Shows a "Connect to OpenHands" button that initiates OAuth 2.0 Device Flow
+ * authentication. Displays status during the auth process and auto-opens
+ * the browser for user authorization.
+ */
+/**
+ * Validate that a URL is safe to open in a popup.
+ * Prevents XSS via javascript: URLs or other malicious schemes.
+ */
+function isValidVerificationUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+export function DeviceFlowAuth({
+  host,
+  onSuccess,
+  testIdRoot,
+  isDisabled = false,
+  idleButtonLabel,
+  idleButtonContent,
+  idleDescription,
+  idleFooter,
+  className,
+  buttonClassName,
+  buttonVariant = "primary",
+  statusDisplay = "inline",
+  analyticsSource,
+}: DeviceFlowAuthProps) {
+  const { t } = useTranslation("openhands");
+  const deviceFlow = useDeviceFlow();
+  const popupRef = React.useRef<Window | null>(null);
+
+  // Close popup on unmount or when auth completes/errors
+  React.useEffect(() => {
+    return () => {
+      popupRef.current?.close();
+    };
+  }, []);
+
+  // Update popup URL when verification URL becomes available
+  React.useEffect(() => {
+    if (
+      deviceFlow.status === "awaiting_authorization" &&
+      deviceFlow.verificationUrl &&
+      popupRef.current &&
+      !popupRef.current.closed
+    ) {
+      // Validate URL before assigning to prevent XSS
+      if (!isValidVerificationUrl(deviceFlow.verificationUrl)) {
+        console.error("Invalid verification URL protocol");
+        return;
+      }
+      try {
+        popupRef.current.location.href = deviceFlow.verificationUrl;
+      } catch {
+        // Cross-origin error - popup was navigated away
+        // Open a new one as fallback
+        popupRef.current = window.open(
+          deviceFlow.verificationUrl,
+          "_blank",
+          "noopener,noreferrer",
+        );
+      }
+    }
+  }, [deviceFlow.status, deviceFlow.verificationUrl]);
+
+  // Call onSuccess when authentication completes
+  React.useEffect(() => {
+    if (deviceFlow.status === "success" && deviceFlow.apiKey) {
+      try {
+        onSuccess(deviceFlow.apiKey);
+      } finally {
+        deviceFlow.reset();
+        popupRef.current?.close();
+      }
+    }
+  }, [deviceFlow.status, deviceFlow.apiKey, deviceFlow.reset, onSuccess]);
+
+  const handleStartAuth = () => {
+    // Normalize and validate the host URL
+    const normalizedHost = host.trim().replace(/\/+$/, "");
+    const fullHost = /^https?:\/\//i.test(normalizedHost)
+      ? normalizedHost
+      : `https://${normalizedHost}`;
+
+    // Validate URL before proceeding
+    try {
+      const url = new URL(fullHost);
+      // Check for URL manipulation attacks
+      if (url.username || url.password) {
+        throw new Error("Invalid URL format");
+      }
+    } catch {
+      return; // Invalid URL, don't proceed
+    }
+
+    // Open popup immediately on user click to avoid popup blocker
+    // Start with about:blank and update URL once we have verification URL
+    // Note: We intentionally don't use "noopener" here because we need to
+    // maintain a reference to update the popup's location when the
+    // verification URL becomes available
+    popupRef.current = window.open("about:blank", "_blank");
+
+    if (!popupRef.current) {
+      // Popup was blocked - flow will still work, user can click manual link
+      console.warn("Popup blocked - user will need to use manual link");
+    }
+
+    deviceFlow.start(fullHost, analyticsSource);
+  };
+
+  const handleCancel = () => {
+    deviceFlow.cancel();
+    popupRef.current?.close();
+  };
+
+  const statusContent = (
+    <DeviceFlowStatusContent
+      status={deviceFlow.status}
+      error={deviceFlow.error}
+      verificationUrl={deviceFlow.verificationUrl}
+      testIdRoot={testIdRoot}
+      onCancel={handleCancel}
+      onRetry={handleStartAuth}
+    />
+  );
+  const showStatusModal =
+    statusDisplay === "modal" && deviceFlow.status !== "idle";
+  const idleLabel = idleButtonLabel ?? t(I18nKey.BACKEND$LOGIN_WITH_OPENHANDS);
+
+  return (
+    <div
+      data-testid={`${testIdRoot}-device-flow`}
+      className={cn("flex flex-col gap-3", className)}
+    >
+      {deviceFlow.status === "idle" ? idleDescription : null}
+
+      {deviceFlow.status === "idle" && buttonVariant === "unstyled" && (
+        <button
+          type="button"
+          onClick={handleStartAuth}
+          data-testid={`${testIdRoot}-login-button`}
+          className={buttonClassName}
+          disabled={isDisabled}
+          aria-label={idleButtonContent ? idleLabel : undefined}
+        >
+          {idleButtonContent ?? idleLabel}
+        </button>
+      )}
+
+      {deviceFlow.status === "idle" && buttonVariant !== "unstyled" && (
+        <BrandButton
+          type="button"
+          variant={buttonVariant}
+          onClick={handleStartAuth}
+          testId={`${testIdRoot}-login-button`}
+          className={buttonClassName}
+          isDisabled={isDisabled}
+          ariaLabel={idleButtonContent ? idleLabel : undefined}
+        >
+          {idleButtonContent ?? idleLabel}
+        </BrandButton>
+      )}
+
+      {deviceFlow.status === "idle" ? idleFooter : null}
+
+      {statusDisplay === "inline" ? statusContent : null}
+
+      {showStatusModal ? (
+        <ModalBackdrop
+          onClose={handleCancel}
+          aria-label={t(I18nKey.BACKEND$LOGIN_WITH_OPENHANDS)}
+          closeOnBackdropClick={false}
+        >
+          <ModalBody
+            testID={`${testIdRoot}-auth-modal`}
+            width="sm"
+            className="items-stretch border border-[var(--oh-border)]"
+          >
+            {statusContent}
+          </ModalBody>
+        </ModalBackdrop>
+      ) : null}
+    </div>
+  );
+}
+
+interface DeviceFlowStatusContentProps {
+  status: DeviceFlowStatus;
+  error: string | null;
+  verificationUrl: string | null;
+  testIdRoot: string;
+  onCancel: () => void;
+  onRetry: () => void;
+}
+
+function DeviceFlowStatusContent({
+  status,
+  error,
+  verificationUrl,
+  testIdRoot,
+  onCancel,
+  onRetry,
+}: DeviceFlowStatusContentProps) {
+  const { t } = useTranslation("openhands");
+
+  if (status === "idle" || status === "success") return null;
+
+  if (status === "starting") {
+    return (
+      <div
+        className="flex items-center justify-center gap-2"
+        data-testid={`${testIdRoot}-auth-starting`}
+        role="status"
+        aria-live="polite"
+      >
+        <LoadingSpinner />
+        <span className="text-sm text-[var(--oh-text-tertiary)]">
+          {t(I18nKey.BACKEND$AUTH_STARTING)}
+        </span>
+      </div>
+    );
+  }
+
+  if (status === "awaiting_authorization") {
+    const validVerificationUrl =
+      verificationUrl && isValidVerificationUrl(verificationUrl)
+        ? verificationUrl
+        : null;
+
+    return (
+      <div
+        className="flex flex-col gap-4"
+        data-testid={`${testIdRoot}-auth-awaiting`}
+        role="status"
+        aria-live="polite"
+      >
+        <div className="flex items-center justify-center gap-2">
+          <LoadingSpinner />
+          <span className="text-sm font-medium text-white">
+            {t(I18nKey.BACKEND$AUTH_AWAITING)}
+          </span>
+        </div>
+        <div className="flex flex-col gap-1">
+          <p className="text-center text-sm leading-5 text-[var(--oh-text-tertiary)]">
+            {validVerificationUrl
+              ? `${t(I18nKey.BACKEND$AUTH_BROWSER_OPENED)} ${t(I18nKey.BACKEND$AUTH_OPEN_MANUALLY)}`
+              : t(I18nKey.BACKEND$AUTH_BROWSER_OPENED)}
+          </p>
+          {validVerificationUrl ? (
+            <a
+              href={validVerificationUrl}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="max-h-16 overflow-auto break-all text-center text-xs text-blue-400 hover:underline"
+            >
+              {validVerificationUrl}
+            </a>
+          ) : null}
+        </div>
+        <BrandButton
+          type="button"
+          variant="secondary"
+          onClick={onCancel}
+          testId={`${testIdRoot}-auth-cancel`}
+          className="w-full"
+        >
+          {t(I18nKey.BACKEND$AUTH_CANCEL)}
+        </BrandButton>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className="flex flex-col gap-3 rounded-lg border border-red-700 bg-red-900/20 p-4"
+      data-testid={`${testIdRoot}-auth-error`}
+      role="alert"
+    >
+      <p className="text-sm text-red-400">{error}</p>
+      <BrandButton
+        type="button"
+        variant="secondary"
+        onClick={onRetry}
+        testId={`${testIdRoot}-auth-retry`}
+        className="w-full"
+      >
+        {t(I18nKey.BACKEND$AUTH_RETRY)}
+      </BrandButton>
+    </div>
+  );
+}
+
+function LoadingSpinner() {
+  return (
+    <svg
+      className="animate-spin h-4 w-4 text-white"
+      xmlns="http://www.w3.org/2000/svg"
+      fill="none"
+      viewBox="0 0 24 24"
+      aria-hidden="true"
+    >
+      <path
+        className="opacity-75"
+        fill="currentColor"
+        d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+      />
+    </svg>
+  );
+}

src/components/features/backends/environment-switch-overlay.tsx

@@ -0,0 +1,172 @@
+import React from "react";
+import { createPortal } from "react-dom";
+import { useTranslation } from "react-i18next";
+import { I18nKey } from "#/i18n/declaration";
+import {
+  getEnvironmentSwitchSnapshot,
+  subscribeEnvironmentSwitch,
+} from "./environment-switch-store";
+
+// Re-export the store API so existing call sites and tests that import from
+// this module keep working unchanged.
+export {
+  ENVIRONMENT_SWITCH_DURATION_MS,
+  ENVIRONMENT_SWITCH_SETACTIVE_DELAY_MS,
+  triggerEnvironmentSwitch,
+  dismissEnvironmentSwitch,
+  __resetEnvironmentSwitchOverlayForTests,
+} from "./environment-switch-store";
+
+function EnvironmentSwitchIcon({ className }: { className?: string }) {
+  return (
+    <svg
+      viewBox="0 0 74.17 22"
+      xmlns="http://www.w3.org/2000/svg"
+      className={className}
+      aria-hidden
+    >
+      <g>
+        <rect
+          x="1"
+          y="1"
+          width="20"
+          height="8"
+          rx="2"
+          ry="2"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.5"
+        />
+        <rect
+          x="1"
+          y="13"
+          width="20"
+          height="8"
+          rx="2"
+          ry="2"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.5"
+        />
+        <line
+          x1="5"
+          y1="5"
+          x2="5.01"
+          y2="5"
+          stroke="currentColor"
+          strokeWidth="1.5"
+          strokeLinecap="round"
+        />
+        <line
+          x1="5"
+          y1="17"
+          x2="5.01"
+          y2="17"
+          stroke="currentColor"
+          strokeWidth="1.5"
+          strokeLinecap="round"
+        />
+      </g>
+      <g>
+        <rect
+          x="53.17"
+          y="1"
+          width="20"
+          height="8"
+          rx="2"
+          ry="2"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.5"
+        />
+        <rect
+          x="53.17"
+          y="13"
+          width="20"
+          height="8"
+          rx="2"
+          ry="2"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.5"
+        />
+        <line
+          x1="57.17"
+          y1="5"
+          x2="57.18"
+          y2="5"
+          stroke="currentColor"
+          strokeWidth="1.5"
+          strokeLinecap="round"
+        />
+        <line
+          x1="57.17"
+          y1="17"
+          x2="57.18"
+          y2="17"
+          stroke="currentColor"
+          strokeWidth="1.5"
+          strokeLinecap="round"
+        />
+      </g>
+      <g>
+        <path
+          d="M43.09,7l4,4-4,4"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.5"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+        <path
+          d="M27.09,11h20"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.5"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+        <path
+          d="M31.09,7l-4,4,4,4"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.5"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+      </g>
+    </svg>
+  );
+}
+
+export function EnvironmentSwitchOverlay() {
+  const { t } = useTranslation("openhands");
+  const { visible, target } = React.useSyncExternalStore(
+    subscribeEnvironmentSwitch,
+    getEnvironmentSwitchSnapshot,
+    getEnvironmentSwitchSnapshot,
+  );
+
+  if (!visible || typeof document === "undefined") return null;
+
+  return createPortal(
+    <div
+      data-testid="environment-switch-overlay"
+      data-target={target}
+      className="environment-switch-overlay pointer-events-none fixed inset-0 z-[2147483646] flex items-center justify-center"
+      aria-live="polite"
+      aria-atomic="true"
+    >
+      <div className="pointer-events-none flex min-w-[280px] max-w-[420px] flex-col items-center gap-2 rounded-xl border border-[var(--oh-border)] bg-[var(--oh-surface)] px-5 py-4 text-[var(--oh-foreground)] shadow-2xl">
+        <EnvironmentSwitchIcon className="mb-2 h-6 w-20 shrink-0 text-[var(--oh-foreground)]" />
+        <p className="text-center text-sm font-medium">
+          {t(I18nKey.BACKEND$SWITCHING_TO, { environment: target })}
+        </p>
+      </div>
+    </div>,
+    document.body,
+  );
+}
+
+// React.lazy() expects a default export.
+export default EnvironmentSwitchOverlay;