Add files using upload-large-folder tool

src/constants/acp-brand-marks.ts

@@ -0,0 +1,18 @@
+// Brand-mark SVG path data for the agent harnesses we recognise on a
+// conversation chip. Kept as raw path strings (drawn with ``currentColor``
+// so callers can size & colour them via Tailwind) rather than embedded
+// ``<svg>`` files to avoid an extra asset round-trip and so the icons can
+// be reused inline at multiple sizes (onboarding tile, conversation chip,
+// settings preview).
+
+export const CLAUDE_CODE_MARK_PATH =
+  "m19.6 66.5 19.7-11 .3-1-.3-.5h-1l-3.3-.2-11.2-.3L14 53l-9.5-.5-2.4-.5L0 49l.2-1.5 2-1.3 2.9.2 6.3.5 9.5.6 6.9.4L38 49.1h1.6l.2-.7-.5-.4-.4-.4L29 41l-10.6-7-5.6-4.1-3-2-1.5-2-.6-4.2 2.7-3 3.7.3.9.2 3.7 2.9 8 6.1L37 36l1.5 1.2.6-.4.1-.3-.7-1.1L33 25l-6-10.4-2.7-4.3-.7-2.6c-.3-1-.4-2-.4-3l3-4.2L28 0l4.2.6L33.8 2l2.6 6 4.1 9.3L47 29.9l2 3.8 1 3.4.3 1h.7v-.5l.5-7.2 1-8.7 1-11.2.3-3.2 1.6-3.8 3-2L61 2.6l2 2.9-.3 1.8-1.1 7.7L59 27.1l-1.5 8.2h.9l1-1.1 4.1-5.4 6.9-8.6 3-3.5L77 13l2.3-1.8h4.3l3.1 4.7-1.4 4.9-4.4 5.6-3.7 4.7-5.3 7.1-3.2 5.7.3.4h.7l12-2.6 6.4-1.1 7.6-1.3 3.5 1.6.4 1.6-1.4 3.4-8.2 2-9.6 2-14.3 3.3-.2.1.2.3 6.4.6 2.8.2h6.8l12.6 1 3.3 2 1.9 2.7-.3 2-5.1 2.6-6.8-1.6-16-3.8-5.4-1.3h-.8v.4l4.6 4.5 8.3 7.5L89 80.1l.5 2.4-1.3 2-1.4-.2-9.2-7-3.6-3-8-6.8h-.5v.7l1.8 2.7 9.8 14.7.5 4.5-.7 1.4-2.6 1-2.7-.6-5.8-8-6-9-4.7-8.2-.5.4-2.9 30.2-1.3 1.5-3 1.2-2.5-2-1.4-3 1.4-6.2 1.6-8 1.3-6.4 1.2-7.9.7-2.6v-.2H49L43 72l-9 12.3-7.2 7.6-1.7.7-3-1.5.3-2.8L24 86l10-12.8 6-7.9 4-4.6-.1-.5h-.3L17.2 77.4l-4.7.6-2-2 .2-3 1-1 8-5.5Z";
+export const CLAUDE_CODE_VIEWBOX = "0 0 100 100";
+
+export const CODEX_MARK_PATH =
+  "M4.04286 0.228393C4.52451 0.0304495 5.0488 -0.0409817 5.56586 0.0208928C6.23236 0.0973928 6.82636 0.380893 7.34786 0.870893C7.35488 0.877545 7.36344 0.882351 7.37278 0.884881C7.38212 0.887412 7.39194 0.887588 7.40136 0.885393C8.10536 0.712393 8.78236 0.773393 9.43186 1.06839L9.46336 1.08339L9.54036 1.12139C10.2189 1.47289 10.7054 2.00639 10.9994 2.72039C11.1384 3.05989 11.2084 3.41439 11.2099 3.78339C11.2197 4.05816 11.1893 4.33288 11.1199 4.59889C11.1164 4.61245 11.1165 4.62665 11.12 4.6402C11.1235 4.65374 11.1303 4.66618 11.1399 4.67639C11.5329 5.0749 11.8063 5.57572 11.9289 6.12189C12.1214 7.07239 11.9239 7.92939 11.3374 8.69189L11.2464 8.80189C10.8579 9.24669 10.3481 9.56836 9.77936 9.72739C9.76694 9.73097 9.75556 9.73747 9.74617 9.74634C9.73677 9.75521 9.72964 9.7662 9.72536 9.77839C9.59786 10.1464 9.46986 10.4604 9.23186 10.7744C8.63236 11.5654 7.75086 12.0054 6.75786 11.9999C5.96636 11.9959 5.26486 11.7064 4.65286 11.1319C4.64358 11.1234 4.63225 11.1174 4.61998 11.1146C4.6077 11.1118 4.59491 11.1123 4.58286 11.1159C4.32386 11.1994 4.06286 11.2114 3.78086 11.2084C3.33033 11.2048 2.88658 11.0984 2.48336 10.8974C2.0613 10.688 1.6939 10.3831 1.41036 10.0069C1.30886 9.87239 1.20836 9.74589 1.13486 9.59639C1.03349 9.39033 0.95066 9.17565 0.887357 8.95489C0.754446 8.45324 0.751521 7.92599 0.878857 7.42289C0.882974 7.41102 0.884341 7.39837 0.882857 7.38589C0.88038 7.37348 0.873877 7.36223 0.864357 7.35389C0.556147 7.04213 0.320543 6.66619 0.174357 6.25289C0.0775698 5.99842 0.0213841 5.73031 0.00785682 5.45839C-0.0163229 5.10033 0.0153902 4.74069 0.101857 4.39239C0.326857 3.65039 0.756357 3.06839 1.39036 2.64589C1.53136 2.55189 1.66536 2.47889 1.79136 2.42689C1.93436 2.36689 2.07786 2.31689 2.22186 2.27489C2.23216 2.27184 2.24153 2.26626 2.24913 2.25866C2.25672 2.25107 2.2623 2.24169 2.26536 2.23139C2.37455 1.83888 2.56235 1.47264 2.81736 1.15489C3.15736 0.731893 3.56586 0.422893 4.04286 0.228393ZM3.64086 4.15339C3.58503 4.05573 3.49269 3.98424 3.38415 3.95465C3.27562 3.92507 3.15977 3.93981 3.06211 3.99564C2.96444 4.05147 2.89295 4.14381 2.86337 4.25235C2.83378 4.36088 2.84853 4.47673 2.90436 4.57439L3.75136 6.05689L2.90736 7.48089C2.85561 7.57738 2.84315 7.69014 2.87257 7.7956C2.902 7.90106 2.97104 7.99108 3.06526 8.04684C3.15949 8.1026 3.27162 8.1198 3.37823 8.09484C3.48484 8.06988 3.57768 8.00469 3.63736 7.91289L4.60736 6.27689C4.64561 6.21237 4.66609 6.13887 4.66671 6.06386C4.66732 5.98886 4.64805 5.91503 4.61086 5.84989L3.64086 4.15339ZM6.36386 7.27339C6.25583 7.27982 6.15434 7.32727 6.08012 7.40603C6.00591 7.48479 5.96458 7.58892 5.96458 7.69714C5.96458 7.80536 6.00591 7.90949 6.08012 7.98826C6.15434 8.06702 6.25583 8.11446 6.36386 8.12089H8.78786C8.89675 8.1156 8.99943 8.06862 9.07462 7.98969C9.14982 7.91075 9.19176 7.80591 9.19176 7.69689C9.19176 7.58787 9.14982 7.48303 9.07462 7.4041C8.99943 7.32516 8.89675 7.27818 8.78786 7.27289H6.36386V7.27339Z";
+export const CODEX_VIEWBOX = "0 0 12 12";
+
+export const GEMINI_MARK_PATH =
+  "M12 0C12.904 6.056 17.944 11.096 24 12C17.944 12.904 12.904 17.944 12 24C11.096 17.944 6.056 12.904 0 12C6.056 11.096 11.096 6.056 12 0Z";
+export const GEMINI_VIEWBOX = "0 0 24 24";

src/constants/acp-providers.test.ts

@@ -0,0 +1,114 @@
+import { ACP_PROVIDERS as CLIENT_ACP_PROVIDERS } from "@openhands/typescript-client";
+import { describe, expect, it } from "vitest";
+import {
+  ACP_MANAGED_SENTINEL,
+  ACP_PROVIDERS,
+  getAcpProviderSecrets,
+  SURFACED_ACP_PROVIDERS,
+  resolveEffectiveAcpModel,
+} from "./acp-providers";
+
+describe("ACP_PROVIDERS", () => {
+  it("passes every codex data field through from the pinned client registry", () => {
+    // No local override may sit between the registry and the picker: a
+    // hand-maintained model entry survives an upstream *removal*, so Canvas
+    // would keep offering an id the live ACP server has started rejecting.
+    const codex = ACP_PROVIDERS.find(({ key }) => key === "codex");
+    const client = CLIENT_ACP_PROVIDERS.codex;
+    expect(codex?.default_command).toEqual([...client.default_command]);
+    expect(codex?.available_models).toEqual(
+      client.available_models.map(({ id, label }) => ({ id, label })),
+    );
+  });
+
+  it("carries GPT-6 Astra, so the pin is new enough to launch it", () => {
+    // Canary for the pin's freshness, not a catalog Canvas maintains: Astra
+    // needs codex-acp >= 1.10.0, which only client >= 1.45.0 mirrors.
+    const codex = ACP_PROVIDERS.find(({ key }) => key === "codex");
+    expect(codex?.available_models?.map(({ id }) => id)).toContain(
+      "gpt-6-astra",
+    );
+  });
+});
+
+describe("resolveEffectiveAcpModel", () => {
+  it("surfaces the real claude-agent-acp 0.44+ 'default' model", () => {
+    // ``default`` ("Default (recommended)") is a real, selectable Claude model
+    // in the configOptions select — the server reports it as the current model.
+    // It must NOT be suppressed as a placeholder (regression: the chip would
+    // otherwise show no model for a session genuinely running on 'default').
+    expect(resolveEffectiveAcpModel({ runtimeId: "default" })).toBe("default");
+    expect(
+      resolveEffectiveAcpModel({ runtimeName: "Default (recommended)" }),
+    ).toBe("Default (recommended)");
+  });
+
+  it("follows the runtime → configured → sdkLlm precedence", () => {
+    expect(
+      resolveEffectiveAcpModel({
+        runtimeName: "Sonnet",
+        runtimeId: "sonnet",
+        configured: "haiku",
+      }),
+    ).toBe("Sonnet");
+    expect(resolveEffectiveAcpModel({ configured: "haiku" })).toBe("haiku");
+    expect(resolveEffectiveAcpModel({ sdkLlm: "gpt-5.5/medium" })).toBe(
+      "gpt-5.5/medium",
+    );
+  });
+
+  it("still suppresses the legacy acp-managed sentinel and blanks", () => {
+    expect(
+      resolveEffectiveAcpModel({ sdkLlm: ACP_MANAGED_SENTINEL }),
+    ).toBeNull();
+    expect(resolveEffectiveAcpModel({ runtimeId: "   " })).toBeNull();
+    expect(resolveEffectiveAcpModel({})).toBeNull();
+  });
+
+  it("falls back to providerDefault only when no concrete model resolves", () => {
+    expect(
+      resolveEffectiveAcpModel({
+        sdkLlm: ACP_MANAGED_SENTINEL,
+        providerDefault: "opus[1m]",
+      }),
+    ).toBe("opus[1m]");
+    // A real 'default' wins over providerDefault — it is a concrete model.
+    expect(
+      resolveEffectiveAcpModel({
+        runtimeId: "default",
+        providerDefault: "opus[1m]",
+      }),
+    ).toBe("default");
+  });
+});
+
+describe("surfaced ACP providers", () => {
+  // Everything the pinned client registry publishes that Canvas does not
+  // offer. Derived, so a harness added upstream is covered here without an
+  // edit — the point of declaring what we surface rather than what we hide.
+  const unsurfaced = Object.keys(CLIENT_ACP_PROVIDERS).filter(
+    (key) => !SURFACED_ACP_PROVIDERS.includes(key),
+  );
+
+  it("surfaces only Claude Code, Codex and Gemini CLI", () => {
+    expect([...SURFACED_ACP_PROVIDERS]).toEqual([
+      "claude-code",
+      "codex",
+      "gemini-cli",
+    ]);
+  });
+
+  it("surfaces nothing the pinned client registry has dropped", () => {
+    // A rename or removal upstream must break loudly rather than leave a tile
+    // whose command and models resolve to nothing. An addition stays a no-op.
+    expect(
+      SURFACED_ACP_PROVIDERS.filter((key) => !(key in CLIENT_ACP_PROVIDERS)),
+    ).toEqual([]);
+  });
+
+  it("offers no credential fields for a harness it does not surface", () => {
+    unsurfaced.forEach((key) => {
+      expect(getAcpProviderSecrets(key)).toEqual([]);
+    });
+  });
+});

src/constants/acp-providers.ts

@@ -0,0 +1,542 @@
+import { getAcpProvider as getClientAcpProvider } from "@openhands/typescript-client";
+import { I18nKey } from "#/i18n/declaration";
+
+export type ACPProviderIcon =
+  | "claude-code"
+  | "codex"
+  | "gemini"
+  | "cli-generic";
+
+export const ACP_PROVIDER_FALLBACK_ICON: ACPProviderIcon = "cli-generic";
+
+// Sentinel ``agent.llm.model`` returned by older SDKs for ACP conversations
+// in lieu of a real model. Suppressed at every consumer that resolves a
+// display string.
+//
+// NB: ``"default"`` is NOT a placeholder. claude-agent-acp 0.44+ exposes
+// ``default`` ("Default (recommended)") as a real, selectable model in its
+// configOptions select — the server reports it as ``currentModelId`` and lists
+// it in ``availableModels`` — so it must surface like any other model id.
+export const ACP_MANAGED_SENTINEL = "acp-managed";
+
+/**
+ * Filter for "real" ACP model strings — non-empty and not the legacy
+ * ``acp-managed`` sentinel. Returns the trimmed value on success, ``null``
+ * otherwise.
+ */
+function realAcpModel(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (trimmed === ACP_MANAGED_SENTINEL) return null;
+  return trimmed;
+}
+
+/**
+ * Single source of truth for resolving the model string to surface for an
+ * ACP conversation/settings context. Consumed by the conversation adapter
+ * (chip text), the conversation-creation path (concrete ``acp_model``
+ * payload), the Settings → Agent form (initial value), and the chat-input
+ * model label.
+ *
+ * Precedence: SDK runtime fields → user-configured ``acp_model`` →
+ * legacy ``agent.llm.model`` → provider default (when ``providerDefault``
+ * is passed). Pass ``providerDefault`` only on surfaces that should
+ * silently substitute the registry default; omit it for the conversation
+ * chip, which must distinguish "no concrete model" from "default".
+ */
+export function resolveEffectiveAcpModel(inputs: {
+  runtimeName?: string | null;
+  runtimeId?: string | null;
+  configured?: string | null;
+  sdkLlm?: string | null;
+  providerDefault?: string | null;
+}): string | null {
+  for (const candidate of [
+    inputs.runtimeName,
+    inputs.runtimeId,
+    inputs.configured,
+    inputs.sdkLlm,
+  ]) {
+    const value = realAcpModel(candidate);
+    if (value) return value;
+  }
+  return inputs.providerDefault ?? null;
+}
+
+/**
+ * Shape of a built-in ACP (Agent Client Protocol) provider as Canvas consumes
+ * it. The data fields (display name, launch command, model picker + default)
+ * are sourced at module load from ``@openhands/typescript-client``'s ACP
+ * registry — the generated mirror of the Python source of truth
+ * ``openhands.sdk.settings.acp_providers``. This config only adds the
+ * Canvas-specific UI fields ({@link ACPProviderConfig.icon} +
+ * {@link ACPProviderConfig.description_key}); see {@link ACP_PROVIDER_UI}.
+ */
+export interface ACPProviderConfig {
+  /** Stable registry key, also stored on conversations as ``tags.acpserver``. */
+  key: string;
+  /** Human-readable name shown in dropdowns and conversation chips. */
+  display_name: string;
+  /**
+   * Tokens passed to the agent-server as ``acp_command`` when this preset
+   * is picked. Each entry must be a real ACP-protocol stdio server — the
+   * SDK validates this against the {@link ACPProviderConfig.key}.
+   *
+   * NB: ``npx -y @openai/codex acp`` looks plausible but is **not** an
+   * ACP server — the codex CLI has no ``acp`` subcommand and exits with
+   * ``Error: stdin is not a terminal`` when spawned without a TTY, which
+   * silently deadlocks the agent-server's ACP handshake. Use
+   * ``@agentclientprotocol/codex-acp`` (the codex ACP wrapper) instead.
+   */
+  default_command: string[];
+  /**
+   * Suggested ACP model IDs for the provider's picker, sourced from the
+   * typescript-client registry. Not authoritative access checks; users can
+   * still enter a custom override in Settings -> Agent.
+   */
+  available_models?: ACPModelOption[];
+  /** Model ID preselected for built-in providers so Canvas never saves blank. */
+  default_model?: string;
+  /**
+   * i18n key for the one-line provider description rendered under the
+   * onboarding tile. Stored on the registry so adding a new ACP
+   * provider only requires editing this file (not the onboarding tile
+   * list separately).
+   */
+  description_key: I18nKey;
+  /**
+   * Serializable icon key used by UI surfaces that render provider
+   * choices. Kept as a string so the SDK mirror check can continue to
+   * parse this registry without importing React components.
+   */
+  icon?: ACPProviderIcon;
+}
+
+export interface ACPModelOption {
+  /** Exact model ID sent as ``acp_model``. */
+  id: string;
+  /** Human-readable label shown in Settings -> Agent. */
+  label: string;
+}
+
+// Canvas-only UI metadata per built-in provider, keyed by the ACP registry
+// key. Everything else — display name, launch command, model picker list and
+// default — comes from the typescript-client registry below. Adding a model
+// or a provider happens upstream in the SDK; Canvas only owns the brand icon
+// and the onboarding-tile description here. Its keys are the harnesses Canvas
+// offers — see {@link SURFACED_ACP_PROVIDERS}.
+const ACP_PROVIDER_UI: Record<
+  string,
+  { icon: ACPProviderIcon; description_key: I18nKey }
+> = {
+  "claude-code": {
+    icon: "claude-code",
+    description_key: I18nKey.ONBOARDING$AGENT_CLAUDE_CODE_DESCRIPTION,
+  },
+  codex: {
+    icon: "codex",
+    description_key: I18nKey.ONBOARDING$AGENT_CODEX_DESCRIPTION,
+  },
+  "gemini-cli": {
+    icon: "gemini",
+    description_key: I18nKey.ONBOARDING$AGENT_GEMINI_CLI_DESCRIPTION,
+  },
+};
+
+function getAvailableModels(key: string): ACPModelOption[] | undefined {
+  return getClientAcpProvider(key)?.available_models?.map((model) => ({
+    id: model.id,
+    label: model.label,
+  }));
+}
+
+/**
+ * The ACP harnesses Canvas surfaces — its own declaration of what it offers,
+ * independent of what the SDK registry happens to contain. Registering a
+ * harness upstream is a no-op here: nothing in Canvas enumerates the registry,
+ * so there is no list to keep in step with it.
+ */
+export const SURFACED_ACP_PROVIDERS: readonly string[] =
+  Object.keys(ACP_PROVIDER_UI);
+
+// Built-in ACP providers Canvas surfaces, built by enriching each upstream
+// registry record (``@openhands/typescript-client`` → Python SDK) with the
+// Canvas UI metadata above.
+export const ACP_PROVIDERS: ACPProviderConfig[] = Object.entries(
+  ACP_PROVIDER_UI,
+).map(([key, ui]) => {
+  const info = getClientAcpProvider(key);
+  return {
+    key,
+    display_name: info?.display_name ?? key,
+    default_command: info ? [...info.default_command] : [],
+    available_models: getAvailableModels(key),
+    default_model: info?.default_model ?? undefined,
+    description_key: ui.description_key,
+    icon: ui.icon,
+  };
+});
+
+export const ACP_CUSTOM_PRESET_KEY = "custom";
+
+/**
+ * A credential an ACP provider authenticates with, surfaced during onboarding
+ * so the user can populate it without leaving the flow. The {@link name} is
+ * both the global-secret name and the environment variable the agent-server
+ * exports into the ACP subprocess — keeping them identical is what makes a
+ * saved secret actually reach the provider CLI.
+ */
+export interface ACPProviderSecretField {
+  /** Secret name and env var (e.g. ``"ANTHROPIC_API_KEY"``). Must satisfy the
+   * secret-name pattern ``^[a-zA-Z][a-zA-Z0-9_]{0,63}$``. */
+  name: string;
+  /** Render as a masked password input (API keys, OAuth tokens, credential
+   * blobs) rather than a plain-text input (base URLs, project IDs). Doubles as
+   * "this is an actual credential": when the onboarding step is required, only
+   * a ``secret`` field satisfies it — a base URL or GCP scalar alone can't
+   * authenticate anything. */
+  secret?: boolean;
+  /** Render as a multi-line textarea rather than a single-line input. Set for
+   * file-content credentials the user pastes verbatim (Codex ``auth.json``,
+   * Gemini Vertex service-account / ADC JSON) — the ones the SDK materialises
+   * to disk, which a cloud backend can't consume yet (agent-canvas#1016). */
+  multiline?: boolean;
+  /** i18n key for the one-line helper text under the field. */
+  hint_key: I18nKey;
+  /**
+   * Interpolation values for {@link hint_key} (e.g. ``{ file: "~/.codex/auth.json" }``
+   * for the shared "paste the file contents" hint). Omitted for hints that
+   * take no parameters.
+   */
+  hint_values?: Record<string, string>;
+}
+
+/**
+ * Container credentials — beyond the registry's API key / base URL — that
+ * canvas collects per provider so a *containerized* agent-server (no host login
+ * state) can authenticate the ACP CLI: subscription tokens plus the file-content
+ * blobs and Vertex config the SDK's ``acp_file_secrets`` materialisation
+ * consumes (agent-canvas#1013/#1014). They have no registry env-var entry
+ * because they're a deployment concern, not a model registry field. The Gemini
+ * project/location/flag are plain config, not secrets — grouped here because
+ * they travel with the SA blob.
+ *
+ * The blob *names* (``CODEX_AUTH_JSON`` / ``GOOGLE_APPLICATION_CREDENTIALS_JSON``)
+ * duplicate the SDK registry's ``file_secrets`` specs; derive them from the
+ * client registry once the pinned ``@openhands/typescript-client`` mirrors that
+ * field (same bump that unblocks ``acp_isolate_data_dir``, see #1019).
+ */
+const ACP_RESERVED_CREDENTIALS: Record<string, ACPProviderSecretField[]> = {
+  codex: [
+    {
+      name: "CODEX_AUTH_JSON",
+      secret: true,
+      multiline: true,
+      hint_key: I18nKey.ONBOARDING$ACP_SECRET_FILE_BLOB_HINT,
+      hint_values: { file: "~/.codex/auth.json" },
+    },
+  ],
+  "claude-code": [
+    {
+      name: "CLAUDE_CODE_OAUTH_TOKEN",
+      secret: true,
+      hint_key: I18nKey.ONBOARDING$ACP_SECRET_OAUTH_TOKEN_HINT,
+    },
+  ],
+  "gemini-cli": [
+    {
+      name: "GOOGLE_APPLICATION_CREDENTIALS_JSON",
+      secret: true,
+      multiline: true,
+      hint_key: I18nKey.ONBOARDING$ACP_SECRET_FILE_BLOB_HINT,
+      hint_values: {
+        file: "~/.config/gcloud/application_default_credentials.json",
+      },
+    },
+    {
+      name: "GOOGLE_CLOUD_PROJECT",
+      hint_key: I18nKey.ONBOARDING$ACP_SECRET_GCP_PROJECT_HINT,
+    },
+    {
+      name: "GOOGLE_CLOUD_LOCATION",
+      hint_key: I18nKey.ONBOARDING$ACP_SECRET_GCP_LOCATION_HINT,
+    },
+    {
+      name: "GOOGLE_GENAI_USE_VERTEXAI",
+      hint_key: I18nKey.ONBOARDING$ACP_SECRET_VERTEXAI_FLAG_HINT,
+    },
+  ],
+};
+
+/**
+ * Credential pairs that break each other at runtime, keyed by provider —
+ * mirrors the SDK's ``_ENV_CONFLICT_MAP`` (software-agent-sdk#3588). Claude's
+ * OAuth token (``CLAUDE_CODE_OAUTH_TOKEN``) authenticates against Anthropic
+ * directly, so when it is set the SDK strips:
+ *   - ``ANTHROPIC_API_KEY``  — otherwise it takes precedence and silently
+ *     bypasses the subscription;
+ *   - ``ANTHROPIC_BASE_URL`` — otherwise it proxies the bearer to an endpoint
+ *     that rejects it (see docs/ACP_AGENTS.md).
+ * Either one set alongside the token is silently ignored at runtime, so warn.
+ */
+const ACP_CREDENTIAL_CONFLICTS: Record<string, Array<[string, string]>> = {
+  "claude-code": [
+    ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_API_KEY"],
+    ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_BASE_URL"],
+  ],
+};
+
+/**
+ * The ``[credential, conflicting]`` pairs the user currently has set for
+ * ``providerKey``. ``hasValue`` should cover both typed and already-saved
+ * values, since a previously saved secret conflicts just the same.
+ */
+export function getAcpCredentialConflicts(
+  key: string | null | undefined,
+  hasValue: (name: string) => boolean,
+): Array<[string, string]> {
+  if (!key) return [];
+  return (ACP_CREDENTIAL_CONFLICTS[key] ?? []).filter(
+    ([credential, conflicting]) =>
+      hasValue(credential) && hasValue(conflicting),
+  );
+}
+
+/**
+ * Vertex AI-safe ``acp_model`` for Gemini.
+ *
+ * Left unset, gemini-cli falls back to its own internal default — a preview
+ * flash model that 404s on Google Cloud projects without preview access. And a
+ * ``*-flash`` id is no safer to pin: gemini-cli re-resolves flash ids at
+ * generation time to its *current default* flash (software-agent-sdk#3532), so
+ * a pinned ``gemini-2.5-flash`` still ran ``gemini-3-flash``. Only a non-flash
+ * id sticks; ``gemini-2.5-pro`` is broadly available on Vertex and the
+ * API-key / Google-login paths, so canvas preselects it. Kept as a named
+ * constant so every model-default consumer agrees.
+ */
+export const ACP_VERTEX_SAFE_MODEL = "gemini-2.5-pro";
+
+/**
+ * The default ``acp_model`` canvas substitutes for ``providerKey`` wherever no
+ * concrete model is configured — settings seeding (onboarding, Settings →
+ * Agent), the {@link buildAcpAgentSettingsDiff} fallback, and the start-request
+ * fallback for a saved ``null``. Overrides only Gemini (→
+ * {@link ACP_VERTEX_SAFE_MODEL}, see why above); every other provider keeps its
+ * registry {@link ACPProviderConfig.default_model}. Returns ``null`` when
+ * there's no override and no registry default, letting the ACP server pick its
+ * own.
+ *
+ * Distinct from {@link ACPProviderConfig.default_model} (which mirrors the SDK
+ * registry verbatim, closing agent-canvas#740): this is the *preferred* default,
+ * deliberately diverging for Gemini where the registry value isn't safe on
+ * every backend — so every default-model surface must route through this, not
+ * read ``default_model`` directly.
+ */
+export function getAcpPreferredDefaultModel(
+  key: string | null | undefined,
+): string | null {
+  if (key === "gemini-cli") return ACP_VERTEX_SAFE_MODEL;
+  return getAcpProvider(key)?.default_model ?? null;
+}
+
+/**
+ * List the credentials Canvas should prompt for when onboarding the given ACP
+ * provider. The API-key and base-URL field *names* track the SDK registry's
+ * ``api_key_env_var`` / ``base_url_env_var`` (mirrored via
+ * ``@openhands/typescript-client``) so they can't drift as providers are added
+ * or renamed; the per-provider container credentials (subscription / Vertex
+ * blobs) come from {@link ACP_RESERVED_CREDENTIALS}, since those are a
+ * containerized-deployment concern with no model-registry entry. Each field
+ * name equals the env var the agent-server exports into the provider subprocess
+ * (which is what makes a saved secret reach the CLI). On the wire none of this
+ * is special — every saved credential travels uniformly as a ``LookupSecret``.
+ *
+ * Field order is: container subscription/Vertex credentials → API key →
+ * optional base URL. Every field is optional at the UI level — the step is
+ * skippable, and a subscription / OAuth login on the backend takes precedence
+ * over a key at runtime. (Whether the *step* is required is a
+ * backend-capability decision the onboarding modal makes; see
+ * ``backendRequiresAcpCredentials``.)
+ *
+ * NB: the base URL is rendered plain-text (not ``secret``), so it never counts
+ * toward a required credential step — setting ``ANTHROPIC_BASE_URL`` alongside
+ * a ``CLAUDE_CODE_OAUTH_TOKEN`` breaks the token's bearer auth, which the forms
+ * surface via {@link getAcpCredentialConflicts}.
+ *
+ * Returns ``[]`` for OpenHands, the ``"custom"`` preset, any unknown key, and a
+ * future OAuth-only provider whose registry entry has no ``api_key_env_var`` —
+ * callers treat an empty list as "no credentials step for this provider".
+ */
+export function getAcpProviderSecrets(
+  key: string | null | undefined,
+): ACPProviderSecretField[] {
+  if (!key) return [];
+  // Surfaced providers only. The client registry grows with every harness the
+  // SDK adds, so reading it directly would offer credential fields for one
+  // Canvas never lists.
+  if (!getAcpProvider(key)) return [];
+  const info = getClientAcpProvider(key);
+  if (!info) return [];
+  // Subscription / Vertex credentials first — they're the primary auth path for
+  // ACP providers (Claude Pro/Max OAuth token, Codex ChatGPT auth.json), with
+  // the API key as the fallback below.
+  const fields: ACPProviderSecretField[] = [
+    ...(ACP_RESERVED_CREDENTIALS[key] ?? []),
+  ];
+  if (info.api_key_env_var) {
+    fields.push({
+      name: info.api_key_env_var,
+      secret: true,
+      hint_key: I18nKey.ONBOARDING$ACP_SECRET_API_KEY_HINT,
+    });
+  }
+  if (info.base_url_env_var) {
+    fields.push({
+      name: info.base_url_env_var,
+      hint_key: I18nKey.ONBOARDING$ACP_SECRET_BASE_URL_HINT,
+    });
+  }
+  return fields;
+}
+
+/**
+ * Look up a built-in ACP provider config by its registry key.
+ *
+ * Returns ``undefined`` for an empty / null key, for the ``"custom"`` preset
+ * (which has no registry entry), and for any forward-compatible key Canvas's
+ * registry doesn't know about yet. Centralizes the ``ACP_PROVIDERS.find(...)``
+ * lookup shared by the resolvers below and by the adapter / settings surfaces
+ * so the key-comparison shape lives in one place.
+ */
+export function getAcpProvider(
+  key: string | null | undefined,
+): ACPProviderConfig | undefined {
+  if (!key) return undefined;
+  return ACP_PROVIDERS.find((provider) => provider.key === key);
+}
+
+/**
+ * Resolve an ACP provider registry key (the value stored under
+ * ``tags.acpserver`` on a conversation) to a human display name for the
+ * sidebar chip.
+ *
+ * Returns ``null`` for an empty / null key and for keys not in
+ * {@link ACP_PROVIDERS} — most notably ``"custom"`` (the user-supplied
+ * command preset has no canonical brand name) and any forward-compatible
+ * value Canvas's registry doesn't know about yet. Callers should fall
+ * back to a generic ``"ACP"`` label in that case so the chip still
+ * communicates "this is an ACP conversation".
+ *
+ * Kept separate from {@link buildAcpAgentSettingsDiff}'s lookup so the
+ * conversation-card render path can resolve display names without
+ * importing the settings-payload builder.
+ */
+export function getAcpProviderDisplayName(
+  key: string | null | undefined,
+): string | null {
+  const found = getAcpProvider(key);
+  return found ? found.display_name : null;
+}
+
+/**
+ * Resolve an ACP provider registry key to the icon discriminator the
+ * conversation chip should render alongside the model text.
+ *
+ * Falls back to {@link ACP_PROVIDER_FALLBACK_ICON} for ``"custom"``,
+ * unknown keys, or a missing key — the chip then shows a neutral
+ * terminal glyph that still communicates "this is an ACP conversation"
+ * without claiming a brand identity we don't know.
+ */
+export function resolveAcpProviderIcon(
+  key: string | null | undefined,
+): ACPProviderIcon {
+  return getAcpProvider(key)?.icon ?? ACP_PROVIDER_FALLBACK_ICON;
+}
+
+/**
+ * Resolve a raw ``acp_model`` ID to the human-readable label the provider's
+ * picker shows for it (e.g. ``"claude-opus-4-7"`` → ``"Claude Opus 4.7"``).
+ *
+ * Falls back to the raw ID when the provider is unknown or the ID isn't one
+ * of its registered {@link ACPModelOption}s — so a user's custom override
+ * still renders something meaningful rather than nothing. Returns ``null``
+ * only when there is no model to show, letting the conversation chip decide
+ * to display the provider name instead.
+ */
+export function labelForAcpModel(
+  serverKey: string | null | undefined,
+  modelId: string | null | undefined,
+): string | null {
+  if (!modelId) return null;
+  const provider = getAcpProvider(serverKey);
+  const match = provider?.available_models?.find((m) => m.id === modelId);
+  return match?.label ?? modelId;
+}
+
+/**
+ * Build the ``agent_settings_diff`` payload PATCH /api/settings expects
+ * for the agent-kind/provider choice the user just made.
+ *
+ * Used by both the Settings → Agent page and the onboarding "choose
+ * agent" step — keeping the shape in one helper means a future change
+ * (e.g. always seeding ``acp_command`` from the registry instead of
+ * sending ``[]``, or adding new ``acp_*`` reset fields) lands in both
+ * surfaces atomically.
+ *
+ * Returns ``null`` for an unknown ACP provider key by default — the
+ * caller can skip the save (the UI shouldn't surface unknown options,
+ * but the defensive path keeps a buggy preset list from corrupting
+ * settings).
+ *
+ * Pass ``allowUnknownServer: true`` to opt into pass-through for keys
+ * that aren't in {@link ACP_PROVIDERS} or ``ACP_CUSTOM_PRESET_KEY``.
+ * The Settings → Agent page uses this when the user opens settings
+ * that already carry an ``acp_server`` value canvas's registry
+ * doesn't know about (e.g. set out-of-band via the API for a provider
+ * we haven't mirrored yet) and saves without changing the command —
+ * otherwise the original key would be silently demoted to ``"custom"``.
+ */
+export function buildAcpAgentSettingsDiff(
+  providerKey: string,
+  options: {
+    command?: string[];
+    model?: string | null;
+    allowUnknownServer?: boolean;
+  } = {},
+): Record<string, unknown> | null {
+  if (providerKey === "openhands") {
+    // Switching back to OpenHands. The agent-server's ``Settings.update``
+    // applies a fresh ``{'agent_kind': ...}`` base whenever the kind
+    // flips, so any ``acp_*`` fields would be discarded before
+    // validation. Send the kind alone.
+    return { agent_kind: "openhands" };
+  }
+
+  const isCustom = providerKey === ACP_CUSTOM_PRESET_KEY;
+  const provider = isCustom ? undefined : getAcpProvider(providerKey);
+  if (!isCustom && !provider && !options.allowUnknownServer) {
+    return null;
+  }
+
+  // Undefined model → the *preferred* default (Vertex-safe for Gemini), not
+  // the raw registry default — see getAcpPreferredDefaultModel.
+  const model =
+    options.model === undefined
+      ? getAcpPreferredDefaultModel(providerKey)
+      : options.model;
+
+  // ``acp_args: []`` resets any API-set ``acp_args`` that would
+  // otherwise survive and concatenate to ``acp_command`` at spawn time
+  // (the agent-server merges the two before exec). Callers building the
+  // payload from a textarea that already shows the merged command
+  // (Settings → Agent) round-trip correctly — the merged tokens land in
+  // ``acp_command`` here, so no args are lost.
+  return {
+    agent_kind: "acp",
+    acp_server: providerKey,
+    acp_command: options.command ?? [],
+    acp_args: [],
+    acp_model: model ?? null,
+  };
+}

src/constants/canvas-ui.ts

@@ -0,0 +1,10 @@
+export const LEGACY_CANVAS_UI_TOOL_NAME = "canvas_ui";
+export const CANVAS_UI_CLIENT_TOOL_NAME = "canvas_ui_control";
+
+/**
+ * Action discriminator generated by the SDK for the client-defined Canvas UI
+ * tool (`ClientAction_<tool-name>`). Keep the SDK naming convention contained
+ * here instead of repeating its generated class name throughout the frontend.
+ */
+export const CANVAS_UI_CLIENT_ACTION_KIND =
+  `ClientAction_${CANVAS_UI_CLIENT_TOOL_NAME}` as const;

src/constants/child-conversation.ts

@@ -0,0 +1,37 @@
+export const LAUNCH_CHILD_CONVERSATION_TOOL_NAME = "launch_child_conversation";
+
+/**
+ * Action discriminator generated by the SDK for the client-defined launch tool
+ * (`ClientAction_<tool-name>`). Keep the SDK naming convention contained here
+ * instead of repeating its generated class name throughout the frontend.
+ */
+export const LAUNCH_CHILD_CONVERSATION_ACTION_KIND =
+  `ClientAction_${LAUNCH_CHILD_CONVERSATION_TOOL_NAME}` as const;
+
+/**
+ * Prefix of the machine-generated message the frontend posts back into the
+ * parent conversation after a launch. Client tools are acknowledged by the
+ * agent-server before the browser has done any work, so this message is the
+ * only way to hand the agent the child's id, URL and status — or corrective
+ * guidance when the call was malformed. The chat hides it (see
+ * `should-render-event.ts`) because the agent relays the same information in
+ * its own reply.
+ */
+export const CHILD_CONVERSATION_RESULT_PREFIX = "[child-conversation] ";
+
+export const CHILD_CONVERSATION_TARGETS = ["local", "cloud"] as const;
+export type ChildConversationTarget =
+  (typeof CHILD_CONVERSATION_TARGETS)[number];
+
+export const CHILD_CONVERSATION_ISOLATIONS = ["worktree", "shared"] as const;
+export type ChildConversationIsolation =
+  (typeof CHILD_CONVERSATION_ISOLATIONS)[number];
+
+/**
+ * `parent_conversation_id` on the local start-conversation request landed in
+ * software-agent-sdk#4188. Older agent-servers accept the request and drop the
+ * field (the pydantic model ignores extras), so the launch still succeeds — we
+ * just tell the agent the relationship was not persisted instead of letting it
+ * believe in a link that does not exist.
+ */
+export const MIN_AGENT_SERVER_VERSION_FOR_PARENT_LINK = "1.37.1";

src/constants/llm-balance.ts

@@ -0,0 +1,14 @@
+/**
+ * Agent-server endpoint reporting the LLM provider's credit balance.
+ * Servers without balance support (or providers that can't report one)
+ * answer 404 — callers must treat that as "hide the balance UI".
+ */
+export const LLM_BALANCE_PATH = "/api/llm/balance";
+
+/**
+ * Ceiling on a single balance request. A server that accepts the connection
+ * and then never answers would otherwise leave the request in flight forever:
+ * the query sets `retry: false`, which suppresses retries but does not bound a
+ * stuck request, so the balance card would stay hidden with nothing surfaced.
+ */
+export const LLM_BALANCE_TIMEOUT_MS = 10_000;

src/constants/llm-subscription.ts

@@ -0,0 +1,75 @@
+import type { SettingsChoice, SettingsFieldSchema } from "#/types/settings";
+
+export const LLM_AUTH_TYPE_KEY = "llm.auth_type";
+export const LLM_SUBSCRIPTION_VENDOR_KEY = "llm.subscription_vendor";
+export const LLM_AUTH_TYPE_API_KEY = "api_key";
+export const LLM_AUTH_TYPE_SUBSCRIPTION = "subscription";
+export const OPENAI_SUBSCRIPTION_VENDOR = "openai";
+
+export const OPENAI_SUBSCRIPTION_MODELS_PATH =
+  "/api/llm/subscription/openai/models";
+export const OPENAI_SUBSCRIPTION_STATUS_PATH =
+  "/api/llm/subscription/openai/status";
+export const OPENAI_SUBSCRIPTION_DEVICE_START_PATH =
+  "/api/llm/subscription/openai/device/start";
+export const OPENAI_SUBSCRIPTION_DEVICE_POLL_PATH =
+  "/api/llm/subscription/openai/device/poll";
+export const OPENAI_SUBSCRIPTION_LOGOUT_PATH =
+  "/api/llm/subscription/openai/logout";
+
+export type LlmAuthType =
+  | typeof LLM_AUTH_TYPE_API_KEY
+  | typeof LLM_AUTH_TYPE_SUBSCRIPTION;
+
+export const LLM_AUTH_TYPE_CHOICES: SettingsChoice[] = [
+  { label: "API key", value: LLM_AUTH_TYPE_API_KEY },
+  { label: "ChatGPT subscription", value: LLM_AUTH_TYPE_SUBSCRIPTION },
+];
+
+const LLM_AUTH_TYPE_FIELD: SettingsFieldSchema = {
+  key: LLM_AUTH_TYPE_KEY,
+  label: "Authentication",
+  description:
+    "Choose whether this profile uses API credentials or a ChatGPT subscription.",
+  section: "llm",
+  section_label: "LLM",
+  value_type: "string",
+  default: LLM_AUTH_TYPE_API_KEY,
+  choices: LLM_AUTH_TYPE_CHOICES,
+  depends_on: [],
+  prominence: "critical",
+  secret: false,
+  required: true,
+};
+
+const LLM_SUBSCRIPTION_VENDOR_FIELD: SettingsFieldSchema = {
+  key: LLM_SUBSCRIPTION_VENDOR_KEY,
+  label: "Subscription provider",
+  description: "Provider used for subscription-backed LLM access.",
+  section: "llm",
+  section_label: "LLM",
+  value_type: "string",
+  default: OPENAI_SUBSCRIPTION_VENDOR,
+  choices: [{ label: "OpenAI", value: OPENAI_SUBSCRIPTION_VENDOR }],
+  depends_on: [],
+  prominence: "critical",
+  secret: false,
+  required: true,
+};
+
+export const LLM_SUBSCRIPTION_SCHEMA_FIELDS = [
+  LLM_AUTH_TYPE_FIELD,
+  LLM_SUBSCRIPTION_VENDOR_FIELD,
+];
+
+export function resolveLlmAuthType(value: unknown): LlmAuthType {
+  return value === LLM_AUTH_TYPE_SUBSCRIPTION
+    ? LLM_AUTH_TYPE_SUBSCRIPTION
+    : LLM_AUTH_TYPE_API_KEY;
+}
+
+export function isSubscriptionLlmConfig(
+  llm: Record<string, unknown> | null | undefined,
+): boolean {
+  return resolveLlmAuthType(llm?.auth_type) === LLM_AUTH_TYPE_SUBSCRIPTION;
+}

src/constants/profile-scope.ts

@@ -0,0 +1,33 @@
+/** Picker state for a profile's scope fields: server default, or an explicit list. */
+export type ProfileScopeMode = "standard" | "custom";
+
+/**
+ * Read a stored profile's `mcp_server_refs` into picker state.
+ *
+ * Tri-state on the wire: `null`/absent = every configured server, an array =
+ * only those keys (`[]` = none).
+ */
+export function readProfileMcpRefs(value: unknown): {
+  mode: ProfileScopeMode;
+  selected: string[];
+} {
+  if (!Array.isArray(value)) return { mode: "standard", selected: [] };
+  return {
+    mode: "custom",
+    selected: value.filter((name): name is string => typeof name === "string"),
+  };
+}
+
+/**
+ * Whether two scope selections name the same servers.
+ *
+ * Compared as a set: the resolver de-duplicates refs and uses them as an
+ * allow-list, so neither order nor a repeat changes what the agent gets. The
+ * editor emits catalog order while a stored profile keeps whatever order it was
+ * written in, so an order-sensitive check reports a profile dirty on open.
+ */
+export function sameScopeSelection(a: string[], b: string[]): boolean {
+  const normalize = (names: string[]) =>
+    [...new Set(names)].sort().join("\u0000");
+  return normalize(a) === normalize(b);
+}

src/constants/server-connection-error.ts

@@ -0,0 +1 @@
+export const SERVER_CONNECTION_ERROR_MESSAGE = "Unable to connect to server";

src/constants/settings-nav.tsx

@@ -0,0 +1,77 @@
+import { AppWindow, Brain, Shield } from "lucide-react";
+import KeyIcon from "#/icons/key.svg?react";
+import MemoryIcon from "#/icons/memory_icon.svg?react";
+import CircuitIcon from "#/icons/u-circuit.svg?react";
+import RobotIcon from "#/icons/u-robot.svg?react";
+
+export interface SettingsNavItem {
+  icon: React.ReactElement;
+  to: string;
+  text: string;
+  /** Short grey subline under the page title (`settings.tsx`). */
+  subtitle: string;
+}
+
+export const OSS_NAV_ITEMS: SettingsNavItem[] = [
+  {
+    // "Agent" is the Agent Profile library: it lists the user's agent profiles
+    // and its create/edit view is the reused Agent settings form plus a name.
+    // The active profile is the current agent (#1571). Replaces the old split
+    // of a global "Agent" form + a separate "Agent profiles" library.
+    icon: <RobotIcon width={16} height={16} />,
+    to: "/settings/agents",
+    text: "SETTINGS$NAV_AGENT",
+    subtitle: "SETTINGS$PAGE_AGENT_PROFILES_SUBLINE",
+  },
+  {
+    icon: <CircuitIcon width={16} height={16} />,
+    to: "/settings/llm",
+    text: "SETTINGS$NAV_LLM",
+    subtitle: "SETTINGS$PAGE_LLM_SUBLINE",
+  },
+  {
+    icon: <MemoryIcon width={16} height={16} />,
+    to: "/settings/condenser",
+    text: "SETTINGS$NAV_CONDENSER",
+    subtitle: "SETTINGS$PAGE_CONDENSER_SUBLINE",
+  },
+  {
+    // The agent's ``agent_context`` section, whatever the schema exposes in it
+    // — today only persistent memory (``agent_context.load_memory``). Not
+    // ``disabledByAcp``: the stored flag rides the shared agent_settings
+    // record into ACP conversations too — inline launches spread it into
+    // ``agent_context``, and profile launches (the normal ACP path) have the
+    // agent-server stamp it onto the profile-resolved agent.
+    icon: <Brain className="size-4" strokeWidth={2} aria-hidden />,
+    to: "/settings/agent-context",
+    text: "SETTINGS$NAV_AGENT_CONTEXT",
+    subtitle: "SETTINGS$PAGE_AGENT_CONTEXT_SUBLINE",
+  },
+  {
+    icon: <Shield className="size-4" strokeWidth={2} aria-hidden />,
+    to: "/settings/verification",
+    text: "SETTINGS$NAV_VERIFICATION",
+    subtitle: "SETTINGS$PAGE_VERIFICATION_SUBLINE",
+  },
+  {
+    icon: <AppWindow className="size-4" strokeWidth={2} aria-hidden />,
+    to: "/settings/app",
+    text: "SETTINGS$NAV_APPLICATION",
+    subtitle: "SETTINGS$PAGE_APPLICATION_SUBLINE",
+  },
+  {
+    icon: <KeyIcon width={16} height={16} />,
+    to: "/settings/secrets",
+    text: "SETTINGS$NAV_SECRETS",
+    subtitle: "SETTINGS$PAGE_SECRETS_SUBLINE",
+  },
+];
+
+/**
+ * The only OSS nav entry listed when the canvas is locked to a Cloud host —
+ * i.e. deployed into SaaS / self-hosted OHE next to the OHE web app, whose own
+ * settings shell (reached via "All Cloud Settings") owns everything else. The
+ * other pages stay routable for in-app deep links; they are just unlisted
+ * (OHE-3168).
+ */
+export const LOCKED_CLOUD_SETTINGS_NAV_PATH = "/settings/app";

src/constants/skills-docs.ts

@@ -0,0 +1,7 @@
+export const ADD_SKILL_DOCS_URL =
+  "https://docs.openhands.dev/overview/skills/adding#adding-new-skills";
+
+export const ADD_SKILL_SKILL_NAME = "add-skill";
+
+export const ADD_SKILL_EXAMPLE_COMMAND =
+  "/add-skill https://github.com/OpenHands/extensions/tree/main/skills/codereview";

src/constants/status-colors.ts

@@ -0,0 +1,5 @@
+/** Connected / running indicators (sidebar conversation dots, server status). */
+export const OH_STATUS_SUCCESS_COLOR = "var(--oh-status-success)";
+
+/** Disconnected / error indicators aligned with sidebar status dots. */
+export const OH_STATUS_ERROR_COLOR = "var(--oh-status-error)";

src/context/navigation-context.tsx

@@ -0,0 +1,41 @@
+import React from "react";
+
+export interface NavigationOptions {
+  replace?: boolean;
+}
+
+export interface NavigationContextValue {
+  currentPath: string;
+  conversationId: string | null;
+  isNavigating: boolean;
+  navigate: (to: string, options?: NavigationOptions) => void;
+}
+
+const noop = () => {};
+
+const NavigationContext = React.createContext<NavigationContextValue>({
+  currentPath: "/",
+  conversationId: null,
+  isNavigating: false,
+  navigate: noop,
+});
+
+interface NavigationProviderProps {
+  value: NavigationContextValue;
+  children: React.ReactNode;
+}
+
+export function NavigationProvider({
+  value,
+  children,
+}: NavigationProviderProps) {
+  return (
+    <NavigationContext.Provider value={value}>
+      {children}
+    </NavigationContext.Provider>
+  );
+}
+
+export function useNavigation() {
+  return React.useContext(NavigationContext);
+}

src/context/scroll-context.tsx

@@ -0,0 +1,50 @@
+import React, { createContext, useContext, ReactNode, RefObject } from "react";
+import { useScrollToBottom } from "#/hooks/use-scroll-to-bottom";
+
+interface ScrollContextType {
+  scrollRef: RefObject<HTMLDivElement | null>;
+  autoScroll: boolean;
+  setAutoScroll: (value: boolean) => void;
+  scrollDomToBottom: () => void;
+  hitBottom: boolean;
+  setHitBottom: (value: boolean) => void;
+  onChatBodyScroll: (e: HTMLElement) => void;
+}
+
+export const ScrollContext = createContext<ScrollContextType | undefined>(
+  undefined,
+);
+
+interface ScrollProviderProps {
+  children: ReactNode;
+  value?: ScrollContextType;
+}
+
+export function ScrollProvider({ children, value }: ScrollProviderProps) {
+  const scrollHook = useScrollToBottom(React.useRef<HTMLDivElement>(null));
+
+  // Use provided value or default to the hook
+  const contextValue = value || scrollHook;
+
+  return (
+    <ScrollContext.Provider value={contextValue}>
+      {children}
+    </ScrollContext.Provider>
+  );
+}
+
+export function useScrollContext() {
+  const context = useContext(ScrollContext);
+  if (context === undefined) {
+    throw new Error("useScrollContext must be used within a ScrollProvider");
+  }
+  return context;
+}
+
+// Same as useScrollContext but returns undefined when no provider is mounted.
+// Use this in components that have valid render paths both inside and outside
+// the chat's ScrollProvider (e.g. GitControlBar in production vs. isolated
+// test mounts).
+export function useOptionalScrollContext() {
+  return useContext(ScrollContext);
+}

src/contexts/active-backend-context.tsx

@@ -0,0 +1,251 @@
+import React from "react";
+import { clearCachedAgentServerInfo } from "#/api/agent-server-compatibility";
+import {
+  getActiveSelection,
+  getRegisteredBackends,
+  getSnapshot,
+  NO_BACKEND,
+  setActiveSelection,
+  setRegisteredBackends,
+  subscribeActiveBackend,
+} from "#/api/backend-registry/active-store";
+import { makeDefaultLocalBackend } from "#/api/backend-registry/default-backend";
+import {
+  dropBackendHealth,
+  resetBackendHealth,
+} from "#/api/backend-registry/health-store";
+import {
+  type Backend,
+  type BackendSelection,
+  type ResolvedActiveBackend,
+} from "#/api/backend-registry/types";
+import { QUERY_KEYS } from "#/hooks/query/query-keys";
+import { queryClient } from "#/query-client-config";
+import {
+  setTelemetryCloudContext,
+  setTelemetryIdentity,
+} from "#/services/telemetry";
+
+type BackendInput = Omit<Backend, "id" | "connectionRevision">;
+
+interface ActiveBackendContextValue {
+  backends: Backend[];
+  active: ResolvedActiveBackend;
+  setActive: (backendId: string, orgId?: string | null) => void;
+  addBackend: (backend: BackendInput) => Backend;
+  updateBackend: (id: string, patch: Partial<BackendInput>) => void;
+  removeBackend: (id: string) => void;
+}
+
+const ActiveBackendContext =
+  React.createContext<ActiveBackendContextValue | null>(null);
+
+function generateId(): string {
+  if (
+    typeof crypto !== "undefined" &&
+    typeof crypto.randomUUID === "function"
+  ) {
+    return crypto.randomUUID();
+  }
+  return `backend-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function applyTelemetrySelectionBoundary(
+  previous: ResolvedActiveBackend,
+  next: ResolvedActiveBackend,
+): void {
+  const previousWasCloud = previous.backend.kind === "cloud";
+  const nextIsCloud = next.backend.kind === "cloud";
+  if (!previousWasCloud && !nextIsCloud) return;
+
+  setTelemetryCloudContext(null);
+
+  if (
+    nextIsCloud &&
+    (!previousWasCloud || previous.backend.id !== next.backend.id)
+  ) {
+    void setTelemetryIdentity(null);
+  }
+}
+
+export function ActiveBackendProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const snapshot = React.useSyncExternalStore(
+    subscribeActiveBackend,
+    getSnapshot,
+    getSnapshot,
+  );
+
+  const retryBootstrapProbe = React.useCallback(() => {
+    clearCachedAgentServerInfo();
+    void queryClient.invalidateQueries({
+      queryKey: QUERY_KEYS.WEB_CLIENT_CONFIG,
+    });
+  }, []);
+
+  const setActive = React.useCallback(
+    (backendId: string, orgId?: string | null) => {
+      const currentSnapshot = getSnapshot();
+      const prevBackendId = getActiveSelection()?.backendId ?? null;
+      const prevOrgId = getActiveSelection()?.orgId ?? null;
+      const nextOrgId = orgId ?? null;
+
+      if (backendId === prevBackendId && nextOrgId === prevOrgId) return;
+
+      const registeredBackends = getRegisteredBackends();
+      const selectedBackend = registeredBackends.find(
+        (b) => b.id === backendId,
+      );
+      const nextActive: ResolvedActiveBackend = {
+        backend: selectedBackend ?? registeredBackends[0] ?? NO_BACKEND,
+        orgId: selectedBackend ? nextOrgId : null,
+      };
+      applyTelemetrySelectionBoundary(currentSnapshot.active, nextActive);
+
+      const next: BackendSelection = { backendId, orgId: nextOrgId };
+      setActiveSelection(next);
+      retryBootstrapProbe();
+
+      // No blanket `invalidateQueries()` here. Long-lived queries
+      // (`useSettings`, `usePaginatedConversations`,
+      // `useGitRepositories`, `useAppInstallations`,
+      // `useCloudCurrentUserId`, `useGitUser`, …) include the active
+      // backend's `id` and `orgId` in their query keys, so React Query
+      // treats a backend/org switch as a brand-new query and fetches
+      // automatically — once, with no duplicate waves.
+    },
+    [retryBootstrapProbe],
+  );
+
+  // @spec BM-001 — Auto-switch to newly connected backend
+  const addBackend = React.useCallback(
+    (backend: BackendInput): Backend => {
+      const previousActive = getSnapshot().active;
+      const next: Backend = { ...backend, id: generateId() };
+      const list = [...getRegisteredBackends(), next];
+      applyTelemetrySelectionBoundary(previousActive, {
+        backend: next,
+        orgId: null,
+      });
+      setRegisteredBackends(list);
+      setActiveSelection({ backendId: next.id });
+      retryBootstrapProbe();
+      return next;
+    },
+    [retryBootstrapProbe],
+  );
+
+  const updateBackend = React.useCallback(
+    (id: string, patch: Partial<BackendInput>) => {
+      const prev = getRegisteredBackends().find((b) => b.id === id);
+      const activeBeforeUpdate = getSnapshot().active.backend.id;
+      // Re-arm health polling when the user edits the fields that
+      // actually drive the probe. Cosmetic edits (name) shouldn't
+      // re-enable a backend that was disabled for being unreachable.
+      const hostChanged =
+        patch.host !== undefined &&
+        prev !== undefined &&
+        patch.host !== prev.host;
+      const apiKeyChanged =
+        patch.apiKey !== undefined &&
+        prev !== undefined &&
+        patch.apiKey !== prev.apiKey;
+      const list = getRegisteredBackends().map((b) =>
+        b.id === id
+          ? {
+              ...b,
+              ...patch,
+              connectionRevision:
+                hostChanged || apiKeyChanged
+                  ? (b.connectionRevision ?? 0) + 1
+                  : b.connectionRevision,
+            }
+          : b,
+      );
+      setRegisteredBackends(list);
+
+      if (hostChanged || apiKeyChanged) {
+        resetBackendHealth(id);
+        if (activeBeforeUpdate === id) {
+          if (prev?.kind === "cloud") {
+            setTelemetryCloudContext(null);
+            void setTelemetryIdentity(null);
+          }
+          retryBootstrapProbe();
+        }
+      }
+    },
+    [retryBootstrapProbe],
+  );
+
+  const removeBackend = React.useCallback(
+    (id: string) => {
+      const removed = getRegisteredBackends().find((b) => b.id === id);
+      const wasActiveCloud =
+        removed?.kind === "cloud" &&
+        getSnapshot().active.backend.id === removed.id;
+      const list = getRegisteredBackends().filter((b) => b.id !== id);
+      setRegisteredBackends(list);
+      if (wasActiveCloud) {
+        setTelemetryCloudContext(null);
+        void setTelemetryIdentity(null);
+      }
+      dropBackendHealth(id);
+      retryBootstrapProbe();
+      // If the active selection pointed at this backend, the active
+      // store falls back to the first remaining local backend (or the
+      // env-derived default if no locals exist); consumer hooks re-key
+      // by the new active backend identity and refetch automatically.
+    },
+    [retryBootstrapProbe],
+  );
+
+  const value = React.useMemo<ActiveBackendContextValue>(
+    () => ({
+      backends: snapshot.backends,
+      active: snapshot.active,
+      setActive,
+      addBackend,
+      updateBackend,
+      removeBackend,
+    }),
+    [snapshot, setActive, addBackend, updateBackend, removeBackend],
+  );
+
+  return (
+    <ActiveBackendContext.Provider value={value}>
+      {children}
+    </ActiveBackendContext.Provider>
+  );
+}
+
+export function useActiveBackendContext(): ActiveBackendContextValue {
+  const ctx = React.useContext(ActiveBackendContext);
+  if (!ctx) {
+    throw new Error(
+      "useActiveBackendContext must be used inside <ActiveBackendProvider>",
+    );
+  }
+  return ctx;
+}
+
+/**
+ * Read the resolved active backend.
+ *
+ * Falls back to a synthesized env-derived local backend when called
+ * outside an `<ActiveBackendProvider>` (e.g. from a unit test that
+ * mounts a narrow component without the full provider stack). That
+ * synthesized backend is identical to the seed used on first install.
+ *
+ * Components that need to mutate state (`setActive`, `addBackend`,
+ * etc.) must use `useActiveBackendContext()` directly — that throws if
+ * the provider is missing, since mutation requires the live store.
+ */
+export function useActiveBackend(): ResolvedActiveBackend {
+  const ctx = React.useContext(ActiveBackendContext);
+  if (ctx) return ctx.active;
+  return { backend: makeDefaultLocalBackend() ?? NO_BACKEND, orgId: null };
+}

src/contexts/conversation-websocket-context.tsx

@@ -0,0 +1,1278 @@
+import React, {
+  createContext,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useState,
+  useCallback,
+  useMemo,
+  useRef,
+} from "react";
+import { ConversationClient } from "@openhands/typescript-client/clients";
+
+import { useQueryClient } from "@tanstack/react-query";
+import { useWebSocket, WebSocketHookOptions } from "#/hooks/use-websocket";
+import { SERVER_CONNECTION_ERROR_MESSAGE } from "#/constants/server-connection-error";
+import { useEventStore } from "#/stores/use-event-store";
+import { useErrorMessageStore } from "#/stores/error-message-store";
+import { useOptimisticUserMessageStore } from "#/stores/optimistic-user-message-store";
+import { useConversationStateStore } from "#/stores/conversation-state-store";
+import { useCommandStore } from "#/stores/command-store";
+import { useBrowserStore } from "#/stores/browser-store";
+import { useGoalStore } from "#/stores/goal-store";
+import {
+  isAgentServerEvent,
+  isAgentErrorEvent,
+  isUserMessageEvent,
+  isActionEvent,
+  isConversationStateUpdateEvent,
+  isFullStateConversationStateUpdateEvent,
+  isAgentStatusConversationStateUpdateEvent,
+  isStatsConversationStateUpdateEvent,
+  isGoalConversationStateUpdateEvent,
+  isExecuteBashActionEvent,
+  isExecuteBashObservationEvent,
+  isDisplayableErrorEvent,
+  isPlanningFileEditorObservationEvent,
+  isBrowserObservationEvent,
+  isBrowserNavigateActionEvent,
+  isSwitchLLMObservationEvent,
+  isCanvasUIActionEvent,
+  isStreamingDeltaEvent,
+  isLaunchChildConversationActionEvent,
+} from "#/types/agent-server/type-guards";
+import {
+  createStreamingDeltaBatcher,
+  StreamingDeltaBatcher,
+} from "#/utils/streaming-delta-batcher";
+import { handleCanvasUIAction } from "#/services/canvas-ui";
+import { handleLaunchChildConversationAction } from "#/services/child-conversation-launch";
+import { ConversationStateUpdateEventStats } from "#/types/agent-server/core/events/conversation-state-event";
+import type {
+  ConversationErrorEvent,
+  ServerErrorEvent,
+} from "#/types/agent-server/core/events/conversation-state-event";
+import { handleActionEventCacheInvalidation } from "#/utils/cache-utils";
+import { buildWebSocketUrl } from "#/utils/websocket-url";
+import type {
+  AppConversation,
+  SendMessageRequest,
+} from "#/api/conversation-service/agent-server-conversation-service.types";
+import EventService from "#/api/event-service/event-service.api";
+import { getAgentServerClientOptions } from "#/api/agent-server-client-options";
+import { useConversationStore } from "#/stores/conversation-store";
+import { trackError } from "#/utils/error-handler";
+import { useReadConversationFile } from "#/hooks/mutation/use-read-conversation-file";
+import useMetricsStore, { type MetricsState } from "#/stores/metrics-store";
+import { useConversationHistory } from "#/hooks/query/use-conversation-history";
+import { setConversationState } from "#/utils/conversation-local-storage";
+import {
+  recordModelSwitchMessage,
+  seedModelSwitchesFromHistory,
+  stampActiveLlmProfile,
+} from "#/hooks/chat/record-model-switch-message";
+import {
+  invalidateConversationQueries,
+  updateConversationLlmModelInCache,
+} from "#/hooks/mutation/conversation-mutation-utils";
+import { isPlanFilePath } from "#/utils/plan-file";
+
+export type WebSocketConnectionState =
+  | "CONNECTING"
+  | "OPEN"
+  | "CLOSED"
+  | "CLOSING";
+
+interface SendMessageResult {
+  queued: boolean; // true if message was queued for later delivery, false if sent immediately
+}
+
+interface ConversationWebSocketContextType {
+  connectionState: WebSocketConnectionState;
+  /**
+   * The main connection's own state, unmerged with the planning connection —
+   * see `useMainWebSocketStatus`.
+   */
+  mainConnectionState: WebSocketConnectionState;
+  sendMessage: (message: SendMessageRequest) => Promise<SendMessageResult>;
+  isLoadingHistory: boolean;
+  reconnect: () => void;
+}
+
+const ConversationWebSocketContext = createContext<
+  ConversationWebSocketContextType | undefined
+>(undefined);
+
+/**
+ * Extract the text body of an echoed user `MessageEvent` for matching against
+ * the optimistic pending-message queue. The server wraps the original
+ * `args.content` string in one or more `TextContent` entries (alongside any
+ * `ImageContent` entries for inline images), so concatenating the `text`
+ * fields gives us back the exact prompt we sent.
+ */
+function extractMessageEventText(
+  event: import("#/types/agent-server/core/events/message-event").MessageEvent,
+): string {
+  return event.llm_message.content
+    .filter(
+      (part): part is { type: "text"; text: string } => part.type === "text",
+    )
+    .map((part) => part.text)
+    .join("");
+}
+
+export function ConversationWebSocketProvider({
+  children,
+  conversationId,
+  conversationUrl,
+  sessionApiKey,
+  subConversations,
+  subConversationIds,
+}: {
+  children: React.ReactNode;
+  conversationId?: string;
+  conversationUrl?: string | null;
+  sessionApiKey?: string | null;
+  subConversations?: AppConversation[];
+  subConversationIds?: string[];
+}) {
+  // Separate connection state tracking for each WebSocket
+  const [mainConnectionState, setMainConnectionState] =
+    useState<WebSocketConnectionState>("CONNECTING");
+  const [planningConnectionState, setPlanningConnectionState] =
+    useState<WebSocketConnectionState>("CONNECTING");
+
+  // Track if we've ever successfully connected for each connection
+  // Don't show errors until after first successful connection
+  const hasConnectedRefMain = React.useRef(false);
+  const hasConnectedRefPlanning = React.useRef(false);
+
+  const queryClient = useQueryClient();
+  const addEvent = useEventStore((state) => state.addEvent);
+  const addEvents = useEventStore((state) => state.addEvents);
+  const clearEventsForConversation = useEventStore(
+    (state) => state.clearEventsForConversation,
+  );
+  const { setErrorMessage, removeErrorMessage, clearConnectionError } =
+    useErrorMessageStore();
+  const consumeMatchingPendingMessage = useOptimisticUserMessageStore(
+    (state) => state.consumeMatchingPendingMessage,
+  );
+  const { setExecutionStatus } = useConversationStateStore();
+  const { appendInput, appendOutput } = useCommandStore();
+  const resetBrowserStore = useBrowserStore((state) => state.reset);
+
+  // Coalesce streaming deltas to ≤1 store commit/render per frame.
+  // Separate batchers keep the main and planning streams from ever merging.
+  const mainDeltaBatcherRef = useRef<StreamingDeltaBatcher | null>(null);
+  if (mainDeltaBatcherRef.current === null) {
+    mainDeltaBatcherRef.current = createStreamingDeltaBatcher((delta) => {
+      useEventStore.getState().addEvent(delta);
+      // A delta means connectivity recovered — mirror handleNonErrorEvent.
+      useErrorMessageStore.getState().clearConnectionError();
+    });
+  }
+  const planningDeltaBatcherRef = useRef<StreamingDeltaBatcher | null>(null);
+  if (planningDeltaBatcherRef.current === null) {
+    planningDeltaBatcherRef.current = createStreamingDeltaBatcher((delta) => {
+      useEventStore
+        .getState()
+        .addEvent({ ...delta, isFromPlanningAgent: true });
+      useErrorMessageStore.getState().clearConnectionError();
+    });
+  }
+
+  // History loading state.
+  // - Main conversation history is now loaded via REST (`useConversationHistory`),
+  //   so its loading state mirrors the REST query state (see below).
+  // - Planning sub-conversation history still streams over the WebSocket using
+  //   `resend_mode='all'`, so we keep the count-based detection for it.
+  const [isLoadingHistoryPlanning, setIsLoadingHistoryPlanning] =
+    useState(true);
+  const [expectedEventCountPlanning, setExpectedEventCountPlanning] = useState<
+    number | null
+  >(null);
+
+  const { setPlanContent } = useConversationStore();
+
+  useEffect(() => {
+    setPlanContent(null);
+  }, [conversationId, setPlanContent]);
+
+  const { mutate: readConversationFile } = useReadConversationFile();
+
+  // Track planning-agent received events (still WS-driven).
+  const receivedEventCountRefPlanning = useRef(0);
+
+  // Track the latest PlanningFileEditorObservation for Plan.md during history replay
+  const latestPlanningFileEventRef = useRef<{
+    path: string;
+    conversationId: string;
+  } | null>(null);
+
+  const handleNonErrorEvent = useCallback(() => {
+    // A normal event means connectivity recovered: clear a transient connection
+    // error, but keep sticky conversation errors (e.g. a wrong API key).
+    clearConnectionError();
+  }, [clearConnectionError]);
+
+  // Helper function to update metrics from stats event
+  const updateMetricsFromStats = useCallback(
+    (event: ConversationStateUpdateEventStats) => {
+      const usageToMetrics = event.value.usage_to_metrics;
+      if (!usageToMetrics) {
+        return;
+      }
+
+      // usage_to_metrics is keyed by arbitrary LLM usage ids ("default",
+      // "condenser", "profile:<name>:<uuid>", …) — combine across all of
+      // them, mirroring getCombinedMetrics on the REST path.
+      const combined = Object.values(usageToMetrics).reduce<{
+        cost: number;
+        maxBudgetPerTask: number | null;
+        usage: MetricsState["usage"];
+      }>(
+        (acc, metrics) => {
+          acc.cost += metrics.accumulated_cost;
+          if (
+            acc.maxBudgetPerTask === null &&
+            metrics.max_budget_per_task !== null
+          ) {
+            acc.maxBudgetPerTask = metrics.max_budget_per_task;
+          }
+          const tokenUsage = metrics.accumulated_token_usage;
+          if (tokenUsage) {
+            acc.usage = {
+              prompt_tokens:
+                (acc.usage?.prompt_tokens ?? 0) + tokenUsage.prompt_tokens,
+              completion_tokens:
+                (acc.usage?.completion_tokens ?? 0) +
+                tokenUsage.completion_tokens,
+              cache_read_tokens:
+                (acc.usage?.cache_read_tokens ?? 0) +
+                tokenUsage.cache_read_tokens,
+              cache_write_tokens:
+                (acc.usage?.cache_write_tokens ?? 0) +
+                tokenUsage.cache_write_tokens,
+              context_window: Math.max(
+                acc.usage?.context_window ?? 0,
+                tokenUsage.context_window,
+              ),
+              per_turn_token: Math.max(
+                acc.usage?.per_turn_token ?? 0,
+                tokenUsage.per_turn_token,
+              ),
+            };
+          }
+          return acc;
+        },
+        { cost: 0, maxBudgetPerTask: null, usage: null },
+      );
+
+      useMetricsStore.getState().setMetrics({
+        cost: combined.cost,
+        max_budget_per_task: combined.maxBudgetPerTask,
+        usage: combined.usage,
+      });
+    },
+    [],
+  );
+
+  // Initial REST history load: fetch the most recent events and seed the
+  // store. Older events are paginated in via `useLoadOlderEvents` when the
+  // user scrolls to the top of the chat. The WebSocket connection waits for
+  // this query so it can subscribe with `resend_mode='since'` and avoid
+  // re-streaming everything REST already returned.
+  const { data: preloadedHistory, isPending: isPreloadingHistory } =
+    useConversationHistory(conversationId);
+
+  // Skeleton only on the genuine first load (no cached data yet). On return the
+  // cached page is present, so `isPending` is false and we render the
+  // last-known discussion immediately while the tail refetch runs in the
+  // background — the socket gate below also keys on `isPending`, so that
+  // refetch never drops a live socket.
+  const isLoadingHistoryMain = !!conversationId && isPreloadingHistory;
+
+  // Clear the (global, not conversation-scoped) event store when the active
+  // conversation changes, BEFORE the preloaded-history effect below re-seeds
+  // it. This MUST live here rather than in the route component: a parent's
+  // passive effect runs *after* this child's layout effects, so clearing from
+  // the route would wipe the freshly seeded history. On a conversation switch
+  // the history page is already cached, so `preloadedHistory` is available
+  // synchronously — without ordering the clear first, the user's already-echoed
+  // message gets seeded then immediately wiped, leaving only the `since`
+  // WebSocket resend (the agent's reply). Re-entering the same conversation is
+  // a no-op, so the store survives navigating away to Settings and back.
+  useLayoutEffect(() => {
+    const nextId = conversationId ?? null;
+    if (useEventStore.getState().loadedConversationId === nextId) {
+      return;
+    }
+    // Single atomic action: clears the previous conversation's events and
+    // records the new loaded id in one `set`, so no subscriber can observe a
+    // half-applied state (events gone but the old id still reported).
+    clearEventsForConversation(nextId);
+    resetBrowserStore();
+    // The metrics store is conversation-scoped state too: without a reset the
+    // previous conversation's usage/cost keeps rendering in the new
+    // conversation's meter until fresh WS stats arrive — and a brand-new
+    // conversation sends none, so the stale figure stuck indefinitely.
+    useMetricsStore.getState().resetMetrics();
+  }, [conversationId, clearEventsForConversation, resetBrowserStore]);
+
+  useLayoutEffect(() => {
+    if (!preloadedHistory || preloadedHistory.events.length === 0) {
+      return;
+    }
+    addEvents(preloadedHistory.events);
+
+    // The first user message of a cloud start-task conversation is persisted
+    // server-side and reaches us via this REST preload, not over the WebSocket
+    // (which subscribes with resend_mode='since' after the latest preloaded
+    // timestamp). Consume any matching optimistic "Sending…" bubble here too —
+    // mirroring the WS handler — so it doesn't linger as a duplicate of the echo.
+    if (conversationId) {
+      // Rebuild inline "Switched to" messages from the REST-preloaded history.
+      // The live store writers (WS handler / user action) never see preloaded
+      // events, so without this past model switches wouldn't render on reload.
+      // Read the post-`addEvents` `uiEvents` (actions replaced by observations,
+      // Think/Finish observations dropped) — not the raw history — so anchors
+      // match the ids the renderer actually mounts.
+      seedModelSwitchesFromHistory(
+        conversationId,
+        useEventStore.getState().uiEvents,
+      );
+
+      for (const event of preloadedHistory.events) {
+        if (isUserMessageEvent(event)) {
+          consumeMatchingPendingMessage(
+            conversationId,
+            extractMessageEventText(event),
+          );
+        }
+      }
+    }
+  }, [
+    preloadedHistory,
+    addEvents,
+    conversationId,
+    consumeMatchingPendingMessage,
+  ]);
+
+  /**
+   * Timestamp of the latest event we already have from REST. Used as
+   * `after_timestamp` when opening the WebSocket so the server only resends
+   * events strictly after this point. `null` until the first REST page lands
+   * (the WS connection is gated on that — see `wsUrl` below). During
+   * background refetches `preloadedHistory` keeps the last-known page, so the
+   * anchor holds steady instead of flipping to null; reconnects read the
+   * freshest value from the options ref at connect time.
+   */
+  const initialAfterTimestamp = useMemo<string | null>(() => {
+    const events = preloadedHistory?.events ?? [];
+    const latest = events[events.length - 1];
+    if (!latest || !("timestamp" in latest) || !latest.timestamp) return null;
+    return latest.timestamp;
+  }, [preloadedHistory]);
+
+  // Build WebSocket URL from props.
+  //
+  // We deliberately wait for the FIRST history load (`isPending`: no data for
+  // this query key yet) before opening the socket, so the WS subscription can
+  // use `resend_mode='since'` with a meaningful `after_timestamp` instead of
+  // falling back to `resend_mode='all'`. The gate is intentionally NOT on
+  // `isFetching`: background refetches (e.g. the `refetchOnMount` fired when
+  // returning to a conversation) must never tear a live socket down — on a
+  // flaky link that caused a refetch → teardown → reconnect → refetch loop
+  // that kept the conversation stuck at "Connecting" for minutes. Connecting
+  // during a background refetch anchors `since` to the cached tail; the
+  // overlap with the refetched page is deduped by the event store and the
+  // `isDuplicateEvent` guards in the message handlers. A query-key reset
+  // (backend swap / new session key) makes `isPending` true again, so a
+  // genuine reset still re-gates. If the initial load errors, `isPending`
+  // flips false and we fall through to connect with `resend_mode='all'` so
+  // the user still sees live events.
+  const wsUrl = useMemo(() => {
+    if (!conversationId || !conversationUrl) {
+      return null;
+    }
+    if (isPreloadingHistory) {
+      return null;
+    }
+    return buildWebSocketUrl(conversationId, conversationUrl);
+  }, [conversationId, conversationUrl, isPreloadingHistory]);
+
+  // Derived from `subConversationIds` (the pre-filtered, tag-verified id
+  // list) rather than the resolved `subConversations` entry, which lands a
+  // tick later — routing on it would leave a window where the first prompt
+  // sent in plan mode fell through to the parent (the code agent) instead of
+  // the planner.
+  const planningConversationId = useMemo(
+    () => subConversationIds?.[0] ?? null,
+    [subConversationIds],
+  );
+
+  const planningAgentWsUrl = useMemo(() => {
+    if (!subConversations?.length) {
+      return null;
+    }
+
+    // Currently, there is only one sub-conversation and it uses the planning agent.
+    const planningAgentConversation = subConversations[0];
+
+    if (
+      !planningAgentConversation?.id ||
+      !planningAgentConversation.conversation_url
+    ) {
+      return null;
+    }
+
+    return buildWebSocketUrl(
+      planningAgentConversation.id,
+      planningAgentConversation.conversation_url,
+    );
+  }, [subConversations]);
+
+  // Merged connection state - reflects combined status of both connections
+  const connectionState = useMemo<WebSocketConnectionState>(() => {
+    // If planning agent connection doesn't exist, use main connection state
+    if (!planningAgentWsUrl) {
+      return mainConnectionState;
+    }
+
+    // If either is connecting, merged state is connecting
+    if (
+      mainConnectionState === "CONNECTING" ||
+      planningConnectionState === "CONNECTING"
+    ) {
+      return "CONNECTING";
+    }
+
+    // If both are open, merged state is open
+    if (mainConnectionState === "OPEN" && planningConnectionState === "OPEN") {
+      return "OPEN";
+    }
+
+    // If both are closed, merged state is closed
+    if (
+      mainConnectionState === "CLOSED" &&
+      planningConnectionState === "CLOSED"
+    ) {
+      return "CLOSED";
+    }
+
+    // If either is closing, merged state is closing
+    if (
+      mainConnectionState === "CLOSING" ||
+      planningConnectionState === "CLOSING"
+    ) {
+      return "CLOSING";
+    }
+
+    // Default to closed if states don't match expected patterns
+    return "CLOSED";
+  }, [mainConnectionState, planningConnectionState, planningAgentWsUrl]);
+
+  useEffect(() => {
+    if (
+      expectedEventCountPlanning !== null &&
+      receivedEventCountRefPlanning.current >= expectedEventCountPlanning &&
+      isLoadingHistoryPlanning
+    ) {
+      setIsLoadingHistoryPlanning(false);
+    }
+  }, [
+    expectedEventCountPlanning,
+    isLoadingHistoryPlanning,
+    receivedEventCountRefPlanning,
+  ]);
+
+  // Call API once after history loading completes if we tracked any PlanningFileEditorObservation events
+  useEffect(() => {
+    if (!isLoadingHistoryPlanning && latestPlanningFileEventRef.current) {
+      const { path, conversationId: currentPlanningConversationId } =
+        latestPlanningFileEventRef.current;
+
+      readConversationFile(
+        {
+          conversationId: currentPlanningConversationId,
+          filePath: path,
+        },
+        {
+          onSuccess: (fileContent) => {
+            setPlanContent(fileContent);
+          },
+          onError: (error) => {
+            console.warn("Failed to read conversation file:", error);
+          },
+        },
+      );
+
+      // Clear the ref after calling the API
+      latestPlanningFileEventRef.current = null;
+    }
+  }, [isLoadingHistoryPlanning, readConversationFile, setPlanContent]);
+
+  useEffect(() => {
+    hasConnectedRefMain.current = false;
+    setIsLoadingHistoryPlanning(!!subConversationIds?.length);
+    setExpectedEventCountPlanning(null);
+    receivedEventCountRefPlanning.current = 0;
+    // Reset the tracked event ref when sub-conversations change
+    latestPlanningFileEventRef.current = null;
+  }, [subConversationIds]);
+
+  // Reset hasConnected flags when the conversation changes.
+  useEffect(() => {
+    hasConnectedRefMain.current = false;
+    hasConnectedRefPlanning.current = false;
+    // Reset the tracked event ref when conversation changes
+    latestPlanningFileEventRef.current = null;
+  }, [conversationId]);
+
+  // Drop buffered deltas on conversation switch/unmount: the store is cleared on
+  // switch, so flushing them would leak into the next conversation.
+  useEffect(() => {
+    const mainBatcher = mainDeltaBatcherRef.current;
+    const planningBatcher = planningDeltaBatcherRef.current;
+    return () => {
+      mainBatcher?.reset();
+      planningBatcher?.reset();
+    };
+  }, [conversationId]);
+
+  // Merged loading history state - true if either connection is still loading
+  const isLoadingHistory = useMemo(
+    () => isLoadingHistoryMain || isLoadingHistoryPlanning,
+    [isLoadingHistoryMain, isLoadingHistoryPlanning],
+  );
+
+  // Separate message handlers for each connection
+  const handleMainMessage = useCallback(
+    (messageEvent: MessageEvent) => {
+      try {
+        const event = JSON.parse(messageEvent.data);
+
+        // History loading for the main conversation is REST-driven now;
+        // every WS message is a new event we add to the store.
+
+        // Use type guard to validate v1 event structure
+        if (isAgentServerEvent(event)) {
+          // Buffer deltas; nothing else in this handler applies to them.
+          if (isStreamingDeltaEvent(event)) {
+            mainDeltaBatcherRef.current?.enqueue(event);
+            return;
+          }
+          // Flush buffered deltas before this event so it can't overtake them.
+          mainDeltaBatcherRef.current?.flush();
+
+          // A reconnect replays the backlog from a stale anchor. The store
+          // dedups by id, but the side-effects below aren't idempotent, so skip
+          // them for replayed events (#1656).
+          const isDuplicateEvent = useEventStore
+            .getState()
+            .eventIds.has(event.id ?? "");
+          const switchLLMObservation = isSwitchLLMObservationEvent(event)
+            ? event
+            : null;
+          addEvent(event);
+          if (isDuplicateEvent) {
+            return;
+          }
+
+          // Handle displayable error events - show error banner
+          // AgentErrorEvent errors are displayed inline in the chat, not as banners
+          if (isDisplayableErrorEvent(event)) {
+            const errorEvent = event as
+              | ConversationErrorEvent
+              | ServerErrorEvent;
+            const classification =
+              "classification" in errorEvent ? errorEvent.classification : null;
+            trackError({
+              source: "conversation",
+              metadata: {
+                eventId: errorEvent.id,
+                errorCode: errorEvent.code,
+              },
+              classification,
+            });
+            setErrorMessage(
+              errorEvent.detail,
+              "conversation",
+              errorEvent.code,
+              classification,
+            );
+          } else {
+            handleNonErrorEvent();
+          }
+
+          // LLM errors render inline in the chat (see ErrorEventMessage); track
+          // them for analytics but keep them out of the banner above the chat box.
+          if (isAgentErrorEvent(event)) {
+            trackError({
+              source: "agent",
+              metadata: {
+                eventId: event.id,
+                toolName: event.tool_name,
+                toolCallId: event.tool_call_id,
+              },
+              classification: event.classification,
+            });
+          }
+
+          // Clear optimistic user message when a user message is confirmed.
+          // We match by the echoed text content (with FIFO fallback inside the
+          // store), so an echo for "second" pops "second" — not whichever
+          // pending entry happens to be oldest — protecting against any
+          // out-of-order delivery between conversations or sub-agents.
+          if (isUserMessageEvent(event)) {
+            if (conversationId) {
+              consumeMatchingPendingMessage(
+                conversationId,
+                extractMessageEventText(event),
+              );
+              // Clear draft from localStorage - message was successfully delivered
+              setConversationState(conversationId, { draftMessage: null });
+            }
+          }
+
+          // Handle cache invalidation for ActionEvent
+          if (isActionEvent(event)) {
+            const currentConversationId =
+              conversationId || "test-conversation-id"; // TODO: Get from context
+            handleActionEventCacheInvalidation(
+              event,
+              currentConversationId,
+              queryClient,
+            );
+          }
+
+          // Handle conversation state updates
+          // TODO: Tests
+          if (isConversationStateUpdateEvent(event)) {
+            if (
+              isFullStateConversationStateUpdateEvent(event) &&
+              conversationId
+            ) {
+              setExecutionStatus(conversationId, event.value.execution_status);
+            }
+            if (
+              isAgentStatusConversationStateUpdateEvent(event) &&
+              conversationId
+            ) {
+              setExecutionStatus(conversationId, event.value);
+            }
+            if (isStatsConversationStateUpdateEvent(event)) {
+              updateMetricsFromStats(event);
+            }
+            // Mirror goal status into the store. Intentionally duplicated across
+            // the main and planning WebSocket handlers (like the execution_status
+            // and stats branches above), not a merge artifact.
+            if (isGoalConversationStateUpdateEvent(event) && conversationId) {
+              useGoalStore.getState().setStatus(conversationId, event.value);
+            }
+          }
+
+          // Handle ExecuteBashAction events - add command as input to terminal
+          if (isExecuteBashActionEvent(event)) {
+            appendInput(event.action.command);
+          }
+
+          // Handle ExecuteBashObservation events - add output to terminal
+          if (isExecuteBashObservationEvent(event)) {
+            // Extract text content from the observation content array
+            const textContent = event.observation.content
+              .filter((c) => c.type === "text")
+              .map((c) => c.text)
+              .join("\n");
+            appendOutput(textContent);
+          }
+
+          // Handle BrowserObservation events - update browser store with screenshot
+          if (isBrowserObservationEvent(event)) {
+            const { screenshot_data: screenshotData } = event.observation;
+            if (screenshotData) {
+              const screenshotSrc = screenshotData.startsWith("data:")
+                ? screenshotData
+                : `data:image/png;base64,${screenshotData}`;
+              useBrowserStore.getState().setScreenshotSrc(screenshotSrc);
+            }
+          }
+
+          // Handle BrowserNavigateAction events - update browser store with URL
+          if (isBrowserNavigateActionEvent(event)) {
+            useBrowserStore.getState().setUrl(event.action.url);
+          }
+
+          if (
+            conversationId &&
+            switchLLMObservation &&
+            !switchLLMObservation.observation.is_error
+          ) {
+            recordModelSwitchMessage(
+              conversationId,
+              switchLLMObservation.observation.profile_name,
+            );
+
+            // Mirror the user-driven `/model` path: persist the profile so the
+            // chat-header switcher shows the right name after a reload, even
+            // when several profiles share a model (#1082). Stamp with the
+            // observation's own timestamp so a later history seed of this same
+            // event can't roll it back (or needlessly rewrite it).
+            stampActiveLlmProfile(
+              conversationId,
+              switchLLMObservation.observation.profile_name,
+              switchLLMObservation.timestamp,
+            );
+
+            if (switchLLMObservation.observation.active_model) {
+              updateConversationLlmModelInCache(
+                queryClient,
+                conversationId,
+                switchLLMObservation.observation.active_model,
+              );
+            }
+
+            invalidateConversationQueries(queryClient, conversationId);
+          }
+
+          // Handle canvas_ui ActionEvents from both the legacy Python tool and
+          // the client-defined JSON tool. The server acknowledges immediately;
+          // the actual UI change happens here on the client.
+          if (isCanvasUIActionEvent(event)) {
+            handleCanvasUIAction(event.action, conversationId ?? null);
+          }
+
+          // Same client-tool pattern, but the work is a network call: launch
+          // the requested child conversation and post the outcome back so the
+          // agent learns the id the server-side acknowledgement can't carry.
+          if (conversationId && isLaunchChildConversationActionEvent(event)) {
+            void handleLaunchChildConversationAction(
+              event.action,
+              conversationId,
+              event.tool_call_id,
+            );
+          }
+        }
+      } catch (error) {
+        console.warn("Failed to parse WebSocket message as JSON:", error);
+      }
+    },
+    [
+      addEvent,
+      setErrorMessage,
+      consumeMatchingPendingMessage,
+      queryClient,
+      conversationId,
+      setExecutionStatus,
+      appendInput,
+      appendOutput,
+      updateMetricsFromStats,
+      handleNonErrorEvent,
+    ],
+  );
+
+  const handlePlanningMessage = useCallback(
+    (messageEvent: MessageEvent) => {
+      try {
+        const event = JSON.parse(messageEvent.data);
+
+        // Track received events for history loading (count ALL events from WebSocket)
+        // Always count when loading, even if we don't have the expected count yet
+        if (isLoadingHistoryPlanning) {
+          receivedEventCountRefPlanning.current += 1;
+
+          if (
+            expectedEventCountPlanning !== null &&
+            receivedEventCountRefPlanning.current >= expectedEventCountPlanning
+          ) {
+            setIsLoadingHistoryPlanning(false);
+          }
+        }
+
+        // Use type guard to validate v1 event structure
+        if (isAgentServerEvent(event)) {
+          // Buffer deltas (the commit re-applies the planning flag).
+          if (isStreamingDeltaEvent(event)) {
+            planningDeltaBatcherRef.current?.enqueue(event);
+            return;
+          }
+          // Flush buffered deltas before this event so it can't overtake them.
+          planningDeltaBatcherRef.current?.flush();
+
+          // Skip non-idempotent side-effects for replayed events, as in the
+          // main handler (#1656).
+          const isDuplicateEvent = useEventStore
+            .getState()
+            .eventIds.has(event.id ?? "");
+          // Mark this event as coming from the planning agent
+          const eventWithPlanningFlag = {
+            ...event,
+            isFromPlanningAgent: true,
+          };
+          addEvent(eventWithPlanningFlag);
+          if (isDuplicateEvent) {
+            return;
+          }
+
+          // Handle displayable error events - show error banner
+          // AgentErrorEvent errors are displayed inline in the chat, not as banners
+          if (isDisplayableErrorEvent(event)) {
+            const errorEvent = event as
+              | ConversationErrorEvent
+              | ServerErrorEvent;
+            const classification =
+              "classification" in errorEvent ? errorEvent.classification : null;
+            trackError({
+              source: "planning_conversation",
+              metadata: {
+                eventId: errorEvent.id,
+                errorCode: errorEvent.code,
+              },
+              classification,
+            });
+            setErrorMessage(
+              errorEvent.detail,
+              "conversation",
+              errorEvent.code,
+              classification,
+            );
+          } else {
+            handleNonErrorEvent();
+          }
+
+          // LLM errors render inline in the chat (see ErrorEventMessage); track
+          // them for analytics but keep them out of the banner above the chat box.
+          if (isAgentErrorEvent(event)) {
+            trackError({
+              source: "planning_agent",
+              metadata: {
+                eventId: event.id,
+                toolName: event.tool_name,
+                toolCallId: event.tool_call_id,
+              },
+              classification: event.classification,
+            });
+          }
+
+          // Clear optimistic user message when a user message is confirmed.
+          // Always scope to the main `conversationId` (where the user types)
+          // and match on the echoed content so the planning sub-agent's own
+          // events can never consume a main-conversation pending entry.
+          if (isUserMessageEvent(event)) {
+            if (conversationId) {
+              consumeMatchingPendingMessage(
+                conversationId,
+                extractMessageEventText(event),
+              );
+              setConversationState(conversationId, { draftMessage: null });
+            }
+          }
+
+          // Handle cache invalidation for ActionEvent
+          if (isActionEvent(event)) {
+            const planningAgentConversation = subConversations?.[0];
+            const currentConversationId =
+              planningAgentConversation?.id || "test-conversation-id"; // TODO: Get from context
+            handleActionEventCacheInvalidation(
+              event,
+              currentConversationId,
+              queryClient,
+            );
+          }
+
+          // Handle conversation state updates
+          // TODO: Tests
+          if (isConversationStateUpdateEvent(event)) {
+            // Scope to the planning agent's own conversation id, not the main
+            // `conversationId` — this socket reports the planning helper
+            // conversation's run/idle transitions, which must never overwrite
+            // the main conversation's status in the shared store.
+            if (
+              isFullStateConversationStateUpdateEvent(event) &&
+              planningConversationId
+            ) {
+              setExecutionStatus(
+                planningConversationId,
+                event.value.execution_status,
+              );
+            }
+            if (
+              isAgentStatusConversationStateUpdateEvent(event) &&
+              planningConversationId
+            ) {
+              setExecutionStatus(planningConversationId, event.value);
+            }
+            if (isStatsConversationStateUpdateEvent(event)) {
+              updateMetricsFromStats(event);
+            }
+            // Mirror goal status into the store. Intentionally duplicated across
+            // the main and planning WebSocket handlers (like the execution_status
+            // and stats branches above), not a merge artifact.
+            if (isGoalConversationStateUpdateEvent(event) && conversationId) {
+              useGoalStore.getState().setStatus(conversationId, event.value);
+            }
+          }
+
+          // Handle ExecuteBashAction events - add command as input to terminal
+          if (isExecuteBashActionEvent(event)) {
+            appendInput(event.action.command);
+          }
+
+          // Handle ExecuteBashObservation events - add output to terminal
+          if (isExecuteBashObservationEvent(event)) {
+            // Extract text content from the observation content array
+            const textContent = event.observation.content
+              .filter((c) => c.type === "text")
+              .map((c) => c.text)
+              .join("\n");
+            appendOutput(textContent);
+          }
+
+          // Handle PlanningFileEditorObservation - only update plan for Plan.md
+          if (isPlanningFileEditorObservationEvent(event)) {
+            const { path } = event.observation;
+            if (isPlanFilePath(path)) {
+              const planningAgentConversation = subConversations?.[0];
+              const planningConversationId = planningAgentConversation?.id;
+
+              if (planningConversationId && path) {
+                if (isLoadingHistoryPlanning) {
+                  latestPlanningFileEventRef.current = {
+                    path,
+                    conversationId: planningConversationId,
+                  };
+                } else {
+                  readConversationFile(
+                    {
+                      conversationId: planningConversationId,
+                      filePath: path,
+                    },
+                    {
+                      onSuccess: (fileContent) => {
+                        setPlanContent(fileContent);
+                      },
+                      onError: (error) => {
+                        console.warn(
+                          "Failed to read conversation file:",
+                          error,
+                        );
+                      },
+                    },
+                  );
+                }
+              }
+            }
+          }
+        }
+      } catch (error) {
+        console.warn("Failed to parse WebSocket message as JSON:", error);
+      }
+    },
+    [
+      addEvent,
+      isLoadingHistoryPlanning,
+      expectedEventCountPlanning,
+      setErrorMessage,
+      consumeMatchingPendingMessage,
+      queryClient,
+      subConversations,
+      planningConversationId,
+      conversationId,
+      setExecutionStatus,
+      appendInput,
+      appendOutput,
+      readConversationFile,
+      setPlanContent,
+      updateMetricsFromStats,
+      handleNonErrorEvent,
+    ],
+  );
+
+  // Separate WebSocket options for main connection
+  const mainWebsocketOptions: WebSocketHookOptions = useMemo(() => {
+    // History was already loaded over REST (`useConversationHistory`).
+    // Subscribe with `resend_mode='since'` so the server only resends events
+    // strictly after the latest one we already have. If REST returned no
+    // events at all (brand-new conversation), fall back to `'all'` so any
+    // events that may have been written between the REST call and the WS
+    // handshake still show up. Dedup in the event store handles overlap.
+    const queryParams: Record<string, string | boolean> = initialAfterTimestamp
+      ? { resend_mode: "since", after_timestamp: initialAfterTimestamp }
+      : { resend_mode: "all" };
+
+    return {
+      queryParams,
+      sessionApiKey,
+      reconnect: { enabled: true },
+      onOpen: () => {
+        setMainConnectionState("OPEN");
+        hasConnectedRefMain.current = true; // Mark that we've successfully connected
+        clearConnectionError(); // Clear a previous connection error; keep sticky conversation errors
+      },
+      onClose: () => {
+        setMainConnectionState("CLOSED");
+      },
+      onError: () => {
+        setMainConnectionState("CLOSED");
+        // Only show error message if we've previously connected successfully
+        if (hasConnectedRefMain.current) {
+          setErrorMessage(SERVER_CONNECTION_ERROR_MESSAGE, "connection");
+        }
+      },
+      onMessage: handleMainMessage,
+    };
+  }, [
+    handleMainMessage,
+    setErrorMessage,
+    clearConnectionError,
+    sessionApiKey,
+    initialAfterTimestamp,
+  ]);
+
+  // Separate WebSocket options for planning agent connection
+  const planningWebsocketOptions: WebSocketHookOptions = useMemo(() => {
+    const queryParams: Record<string, string | boolean> = {
+      resend_all: true,
+    };
+
+    const planningAgentConversation = subConversations?.[0];
+    const planningApiKey =
+      planningAgentConversation?.session_api_key ?? sessionApiKey;
+
+    return {
+      queryParams,
+      sessionApiKey: planningApiKey,
+      reconnect: { enabled: true },
+      onOpen: async () => {
+        setPlanningConnectionState("OPEN");
+        hasConnectedRefPlanning.current = true; // Mark that we've successfully connected
+        clearConnectionError(); // Clear a previous connection error; keep sticky conversation errors
+
+        // Fetch expected event count for history loading detection
+        if (
+          planningAgentConversation?.id &&
+          planningAgentConversation.conversation_url
+        ) {
+          try {
+            const count = await EventService.getEventCount(
+              planningAgentConversation.id,
+              planningAgentConversation.conversation_url,
+              planningAgentConversation.session_api_key,
+            );
+            setExpectedEventCountPlanning(count);
+
+            // If no events expected, mark as loaded immediately
+            if (count === 0) {
+              setIsLoadingHistoryPlanning(false);
+            }
+          } catch (error) {
+            // Fall back to marking as loaded to avoid infinite loading state
+            setIsLoadingHistoryPlanning(false);
+          }
+        }
+      },
+      onClose: () => {
+        setPlanningConnectionState("CLOSED");
+      },
+      onError: () => {
+        setPlanningConnectionState("CLOSED");
+        // Only show error message if we've previously connected successfully
+        if (hasConnectedRefPlanning.current) {
+          setErrorMessage(SERVER_CONNECTION_ERROR_MESSAGE, "connection");
+        }
+      },
+      onMessage: handlePlanningMessage,
+    };
+  }, [
+    handlePlanningMessage,
+    setErrorMessage,
+    clearConnectionError,
+    sessionApiKey,
+    subConversations,
+  ]);
+
+  // Only attempt WebSocket connection when we have a valid URL
+  // This prevents connection attempts during task polling phase
+  const websocketUrl = wsUrl;
+  const { socket: mainSocket, reconnect: reconnectMain } = useWebSocket(
+    websocketUrl || "",
+    mainWebsocketOptions,
+  );
+
+  const { socket: planningAgentSocket, reconnect: reconnectPlanning } =
+    useWebSocket(planningAgentWsUrl || "", planningWebsocketOptions);
+
+  const reconnect = useCallback(() => {
+    removeErrorMessage();
+    const currentMode = useConversationStore.getState().conversationMode;
+    if (currentMode === "plan" && planningAgentWsUrl) {
+      reconnectPlanning();
+      return;
+    }
+    reconnectMain();
+  }, [
+    planningAgentWsUrl,
+    reconnectMain,
+    reconnectPlanning,
+    removeErrorMessage,
+  ]);
+
+  // V1 send message function via WebSocket
+  // Falls back to REST API queue when WebSocket is not connected
+  const sendMessage = useCallback(
+    async (message: SendMessageRequest): Promise<SendMessageResult> => {
+      const currentMode = useConversationStore.getState().conversationMode;
+      const currentSocket =
+        currentMode === "plan" ? planningAgentSocket : mainSocket;
+      const targetConversationId =
+        currentMode === "plan" ? planningConversationId : conversationId;
+
+      if (currentSocket?.readyState !== WebSocket.OPEN) {
+        // WebSocket not connected - queue message via REST API
+        // Message will be delivered automatically when conversation becomes ready
+        if (!targetConversationId) {
+          // Never fall back to the parent in plan mode: without a planner
+          // target the message would run in the code agent, which is exactly
+          // the boundary plan mode exists to enforce.
+          const error = new Error(
+            currentMode === "plan"
+              ? "Planning conversation is not ready yet"
+              : "No conversation ID available",
+          );
+          setErrorMessage(error.message);
+          throw error;
+        }
+
+        try {
+          await new ConversationClient(getAgentServerClientOptions()).sendEvent(
+            targetConversationId,
+            {
+              role: "user",
+              content: message.content,
+            },
+            { run: true },
+          );
+          // Message queued successfully - it will be delivered when ready
+          // Return queued: true so caller knows not to show optimistic UI
+          return { queued: true };
+        } catch (error) {
+          const errorMessage =
+            error instanceof Error
+              ? error.message
+              : "Failed to queue message for delivery";
+          setErrorMessage(errorMessage);
+          throw error;
+        }
+      }
+
+      try {
+        // Send message through WebSocket as JSON with run: true so the
+        // agent loop starts automatically in async mode.
+        currentSocket.send(JSON.stringify({ ...message, run: true }));
+        return { queued: false };
+      } catch (error) {
+        const errorMessage =
+          error instanceof Error ? error.message : "Failed to send message";
+        setErrorMessage(errorMessage);
+        throw error;
+      }
+    },
+    [
+      mainSocket,
+      planningAgentSocket,
+      setErrorMessage,
+      conversationId,
+      planningConversationId,
+    ],
+  );
+
+  // Track main socket state changes
+  useEffect(() => {
+    // Only process socket updates if we have a valid URL and socket
+    if (mainSocket && wsUrl) {
+      // Update state based on socket readyState
+      const updateState = () => {
+        switch (mainSocket.readyState) {
+          case WebSocket.CONNECTING:
+            setMainConnectionState("CONNECTING");
+            break;
+          case WebSocket.OPEN:
+            setMainConnectionState("OPEN");
+            break;
+          case WebSocket.CLOSING:
+            setMainConnectionState("CLOSING");
+            break;
+          case WebSocket.CLOSED:
+            setMainConnectionState("CLOSED");
+            break;
+          default:
+            setMainConnectionState("CLOSED");
+            break;
+        }
+      };
+
+      updateState();
+    }
+  }, [mainSocket, wsUrl]);
+
+  // Track planning agent socket state changes
+  useEffect(() => {
+    // Only process socket updates if we have a valid URL and socket
+    if (planningAgentSocket && planningAgentWsUrl) {
+      // Update state based on socket readyState
+      const updateState = () => {
+        switch (planningAgentSocket.readyState) {
+          case WebSocket.CONNECTING:
+            setPlanningConnectionState("CONNECTING");
+            break;
+          case WebSocket.OPEN:
+            setPlanningConnectionState("OPEN");
+            break;
+          case WebSocket.CLOSING:
+            setPlanningConnectionState("CLOSING");
+            break;
+          case WebSocket.CLOSED:
+            setPlanningConnectionState("CLOSED");
+            break;
+          default:
+            setPlanningConnectionState("CLOSED");
+            break;
+        }
+      };
+
+      updateState();
+    }
+  }, [planningAgentSocket, planningAgentWsUrl]);
+
+  const contextValue = useMemo(
+    () => ({
+      connectionState,
+      mainConnectionState,
+      sendMessage,
+      isLoadingHistory,
+      reconnect,
+    }),
+    [
+      connectionState,
+      mainConnectionState,
+      sendMessage,
+      isLoadingHistory,
+      reconnect,
+    ],
+  );
+
+  return (
+    <ConversationWebSocketContext.Provider value={contextValue}>
+      {children}
+    </ConversationWebSocketContext.Provider>
+  );
+}
+
+export const useConversationWebSocket =
+  (): ConversationWebSocketContextType | null => {
+    const context = useContext(ConversationWebSocketContext);
+    // Return null instead of throwing when not in provider
+    // This allows the hook to be called conditionally based on conversation version
+    return context || null;
+  };

src/contexts/settings-section-header-context.tsx

@@ -0,0 +1,35 @@
+import React from "react";
+
+interface SettingsSectionHeaderContextValue {
+  setHideSectionHeader: (hide: boolean) => void;
+}
+
+const SettingsSectionHeaderContext =
+  React.createContext<SettingsSectionHeaderContextValue | null>(null);
+
+export function SettingsSectionHeaderProvider({
+  setHideSectionHeader,
+  children,
+}: React.PropsWithChildren<{
+  setHideSectionHeader: (hide: boolean) => void;
+}>) {
+  const value = React.useMemo(
+    () => ({ setHideSectionHeader }),
+    [setHideSectionHeader],
+  );
+
+  return (
+    <SettingsSectionHeaderContext.Provider value={value}>
+      {children}
+    </SettingsSectionHeaderContext.Provider>
+  );
+}
+
+export function useSettingsSectionHeader() {
+  const context = React.useContext(SettingsSectionHeaderContext);
+  return (
+    context ?? {
+      setHideSectionHeader: () => {},
+    }
+  );
+}

src/contexts/websocket-provider-wrapper.tsx

@@ -0,0 +1,114 @@
+import React from "react";
+import { ConversationWebSocketProvider } from "#/contexts/conversation-websocket-context";
+import { useActiveConversation } from "#/hooks/query/use-active-conversation";
+import { useSubConversations } from "#/hooks/query/use-sub-conversations";
+import type { AppConversation } from "#/api/conversation-service/agent-server-conversation-service.types";
+import { useConversationStore } from "#/stores/conversation-store";
+import { useActiveBackend } from "#/contexts/active-backend-context";
+import { findPlannerConversationId } from "#/utils/plan-file";
+
+interface WebSocketProviderWrapperProps {
+  children: React.ReactNode;
+  conversationId: string;
+}
+
+export function WebSocketProviderWrapper({
+  children,
+  conversationId,
+}: WebSocketProviderWrapperProps) {
+  const { data: conversation } = useActiveConversation();
+  const { backend } = useActiveBackend();
+  const isLocalBackend = backend.kind !== "cloud";
+  const localPlanningConversationId = useConversationStore(
+    (state) => state.localPlanningConversationId,
+  );
+
+  // `localPlanningConversationId` is a single unscoped Zustand field. Right
+  // after switching conversations it can still hold the *previous*
+  // conversation's planner id, since the reset effect in
+  // routes/conversation.tsx and `useActiveConversation()`'s refetch both lag
+  // this render — only trust it once `conversation` matches `conversationId`.
+  const isConversationDataFresh = conversation?.id === conversationId;
+  const trustedLocalPlanningConversationId = isConversationDataFresh
+    ? localPlanningConversationId
+    : null;
+
+  // Candidate ids to resolve. On local backends `sub_conversation_ids` is the
+  // generic (untyped) child list, so fetch it below to find the
+  // `plannerparent`-tagged entry; cloud has no such ambiguity. Memoized: a
+  // fresh array literal each render would re-fire ConversationWebSocketProvider's
+  // reference-keyed effects and wipe the pending PLAN.md read.
+  const candidateConversationIds = React.useMemo(() => {
+    if (!isLocalBackend) {
+      return conversation?.sub_conversation_ids ?? [];
+    }
+    if (
+      conversation?.sub_conversation_ids &&
+      conversation.sub_conversation_ids.length > 0
+    ) {
+      return conversation.sub_conversation_ids;
+    }
+    return trustedLocalPlanningConversationId
+      ? [trustedLocalPlanningConversationId]
+      : [];
+  }, [
+    isLocalBackend,
+    conversation?.sub_conversation_ids,
+    trustedLocalPlanningConversationId,
+  ]);
+  const { data: subConversations } = useSubConversations(
+    candidateConversationIds,
+  );
+
+  // Identify the planner via the `plannerparent` tag rather than list
+  // position — an unrelated child must never be adopted as the planner.
+  // Kept as its own memo (a primitive) rather than inlined below: `subConversations`
+  // gets a new array reference on every refetch even when the planner id
+  // hasn't changed, and planningConversationIds must not rebuild its own
+  // array in that case — see candidateConversationIds above.
+  const plannerConversationId = React.useMemo(() => {
+    if (!isLocalBackend) return null;
+    return findPlannerConversationId(subConversations, conversation?.id);
+  }, [isLocalBackend, subConversations, conversation?.id]);
+
+  const planningConversationIds = React.useMemo(() => {
+    if (!isLocalBackend) return candidateConversationIds;
+    if (plannerConversationId) return [plannerConversationId];
+    // Tag data hasn't resolved yet — bridge with the verified store id (see
+    // `trustedLocalPlanningConversationId` above), otherwise stay empty
+    // rather than guessing an untagged child is the planner.
+    return trustedLocalPlanningConversationId
+      ? [trustedLocalPlanningConversationId]
+      : [];
+  }, [
+    isLocalBackend,
+    candidateConversationIds,
+    plannerConversationId,
+    trustedLocalPlanningConversationId,
+  ]);
+
+  const filteredSubConversations = subConversations?.filter(
+    (subConversation): subConversation is AppConversation =>
+      subConversation !== null &&
+      planningConversationIds.includes(subConversation.id),
+  );
+
+  // Suppress the URL while the cloud sandbox is PAUSED — it still points at
+  // the old (now-rejecting) host until the sandbox resumes.
+  const conversationUrl =
+    conversation?.sandbox_status === "PAUSED"
+      ? null
+      : conversation?.conversation_url;
+
+  return (
+    <ConversationWebSocketProvider
+      conversationId={conversationId}
+      conversationUrl={conversationUrl}
+      sessionApiKey={conversation?.session_api_key}
+      subConversationIds={planningConversationIds}
+      subConversations={filteredSubConversations}
+    >
+      {children}
+    </ConversationWebSocketProvider>
+  );
+}

src/mocks/agent-profiles-handlers.ts

@@ -0,0 +1,245 @@
+import { http, HttpResponse } from "msw";
+import type {
+  AgentProfile,
+  AgentProfileSaveInput,
+  AgentProfileSummary,
+} from "@openhands/typescript-client";
+
+/**
+ * In-memory agent-profile store for the mock agent-server API. Keyed by name
+ * (agent-server uses name-based lookups, not IDs).
+ *
+ * Two consumers depend on it:
+ *
+ * - Settings → Agent *is* the agent-profile library (#1571), and the embedded
+ *   editor behind it is the only surface that renders `AgentSettingsScreen`.
+ *   Without a seeded store the page shows "Failed to load profiles" under
+ *   `npm run dev:mock`, so the whole agent-settings form is unreachable there.
+ * - `useCreateConversation` no longer downgrades silently when the profile
+ *   list fails (#16523): in non-mocked tests `listProfiles` would hit the real
+ *   network, reject, and surface as a hard failure.
+ *
+ * State is per-module-load and deliberately in-memory: create, edit, rename
+ * and delete all round-trip so the editor's save path (a whole-profile
+ * overwrite) can be exercised, but nothing persists across a refresh.
+ *
+ * Imported as a live module so consumers can seed entries and reset between
+ * tests without re-registering handlers.
+ */
+const profiles = new Map<string, AgentProfile>();
+
+let activeProfileId: string | null = null;
+
+const DEFAULT_VERIFICATION = {
+  critic_enabled: false,
+  critic_mode: "off",
+  enable_iterative_refinement: false,
+  critic_threshold: 0.5,
+  max_refinement_iterations: 3,
+  critic_server_url: null,
+  critic_model_name: null,
+};
+
+function makeOpenHandsProfile(
+  overrides: Partial<AgentProfile> & { id: string; name: string },
+): AgentProfile {
+  return {
+    schema_version: 1,
+    revision: 1,
+    mcp_server_refs: null,
+    agent_kind: "openhands",
+    llm_profile_ref: "default",
+    agent: "CodeActAgent",
+    skills: [],
+    system_message_suffix: null,
+    condenser: null,
+    verification: DEFAULT_VERIFICATION,
+    enable_sub_agents: false,
+    tool_concurrency_limit: 1,
+    ...overrides,
+  } as AgentProfile;
+}
+
+/** Stable id of the seeded `default` profile (the active one after a seed). */
+export const MOCK_DEFAULT_AGENT_PROFILE_ID =
+  "3f1c1b7e-0000-4000-8000-000000000001";
+
+const SEEDED_PROFILES: readonly AgentProfile[] = [
+  makeOpenHandsProfile({
+    id: MOCK_DEFAULT_AGENT_PROFILE_ID,
+    name: "default",
+  }),
+  makeOpenHandsProfile({
+    id: "3f1c1b7e-0000-4000-8000-000000000002",
+    name: "research",
+    enable_sub_agents: true,
+    tool_concurrency_limit: 4,
+  }),
+];
+
+// Monotonic so ids minted after a delete never collide with a live profile.
+let nextProfileSeq = SEEDED_PROFILES.length + 1;
+
+function newProfileId(): string {
+  const suffix = String(nextProfileSeq).padStart(12, "0");
+  nextProfileSeq += 1;
+  return `3f1c1b7e-0000-4000-8000-${suffix}`;
+}
+
+/** Reset the in-memory store to empty (no profiles, no active pointer). */
+export function resetMockAgentProfiles(): void {
+  profiles.clear();
+  activeProfileId = null;
+  nextProfileSeq = SEEDED_PROFILES.length + 1;
+}
+
+/**
+ * Restore the seeded store: a `default` profile (active, mirroring what the
+ * agent-server seeds on first run) plus a `research` profile so the library
+ * has something to switch between.
+ */
+export function seedMockAgentProfiles(): void {
+  resetMockAgentProfiles();
+  for (const profile of SEEDED_PROFILES) {
+    profiles.set(profile.name, { ...profile });
+  }
+  activeProfileId = MOCK_DEFAULT_AGENT_PROFILE_ID;
+}
+seedMockAgentProfiles();
+
+function toSummary(name: string, profile: AgentProfile): AgentProfileSummary {
+  return {
+    id: profile.id,
+    name,
+    agent_kind: profile.agent_kind,
+    revision: profile.revision,
+    llm_profile_ref:
+      profile.agent_kind === "openhands" ? profile.llm_profile_ref : null,
+    mcp_server_refs: profile.mcp_server_refs,
+  };
+}
+
+function notFound(name: string) {
+  return HttpResponse.json(
+    { detail: `Agent profile '${name}' not found` },
+    { status: 404 },
+  );
+}
+
+/**
+ * Mock handlers for the agent-server `/api/agent-profiles` endpoints (the same
+ * contract consumed by `AgentProfilesService` and the cloud proxy).
+ *
+ * Routes mirror `agent_profiles_router.py` in the agent-server. MSW anchors its
+ * path matcher, so the list route never claims the `:name` routes below and no
+ * extra path guarding is needed.
+ */
+export const AGENT_PROFILES_HANDLERS = [
+  // GET /api/agent-profiles - List all profiles + the active id.
+  http.get("*/api/agent-profiles", async () => {
+    const summaries = Array.from(profiles.entries()).map(([name, profile]) =>
+      toSummary(name, profile),
+    );
+    return HttpResponse.json({
+      profiles: summaries,
+      active_agent_profile_id: activeProfileId,
+    });
+  }),
+
+  // GET /api/agent-profiles/:name - Fetch a single profile.
+  http.get("*/api/agent-profiles/:name", async ({ params }) => {
+    const { name } = params;
+    if (typeof name !== "string") {
+      return HttpResponse.json({ detail: "Invalid name" }, { status: 400 });
+    }
+    const profile = profiles.get(name);
+    if (!profile) return notFound(name);
+    return HttpResponse.json({ name, profile });
+  }),
+
+  // POST /api/agent-profiles/:name/rename - Rename a profile.
+  http.post(
+    "*/api/agent-profiles/:name/rename",
+    async ({ params, request }) => {
+      const { name } = params;
+      if (typeof name !== "string") {
+        return HttpResponse.json({ detail: "Invalid name" }, { status: 400 });
+      }
+      const body = (await request.json()) as { new_name?: string } | null;
+      const newName = body?.new_name;
+      if (!newName) {
+        return HttpResponse.json(
+          { detail: "new_name is required" },
+          { status: 422 },
+        );
+      }
+      const profile = profiles.get(name);
+      if (!profile) return notFound(name);
+      if (newName !== name && profiles.has(newName)) {
+        return HttpResponse.json(
+          { detail: `Agent profile '${newName}' already exists` },
+          { status: 409 },
+        );
+      }
+      profiles.delete(name);
+      // Rename preserves the stable id, and the active pointer with it.
+      profiles.set(newName, { ...profile, name: newName });
+      return HttpResponse.json({
+        name: newName,
+        message: "Agent profile renamed.",
+      });
+    },
+  ),
+
+  // POST /api/agent-profiles/:id/activate - Activate by stable UUID (pointer-only).
+  http.post("*/api/agent-profiles/:id/activate", async ({ params }) => {
+    const { id } = params;
+    if (typeof id !== "string") {
+      return HttpResponse.json({ detail: "Invalid id" }, { status: 400 });
+    }
+    const profile = Array.from(profiles.values()).find((p) => p.id === id);
+    if (!profile) return notFound(id);
+    activeProfileId = id;
+    return HttpResponse.json({
+      id,
+      message: "Agent profile activated.",
+      agent_settings_applied: false,
+    });
+  }),
+
+  // POST /api/agent-profiles/:name - Create or overwrite a profile (upsert).
+  http.post("*/api/agent-profiles/:name", async ({ params, request }) => {
+    const { name } = params;
+    if (typeof name !== "string") {
+      return HttpResponse.json({ detail: "Invalid name" }, { status: 400 });
+    }
+    const body = (await request.json()) as AgentProfileSaveInput;
+    const existing = profiles.get(name);
+    // Upsert with server-managed identity: the id survives an overwrite and
+    // the revision counter moves, matching `save_profile_preserving_identity`.
+    // A caller-supplied id is honoured only on create, so tests can seed a
+    // profile with a known id and activate it.
+    profiles.set(name, {
+      ...(body as AgentProfile),
+      name,
+      id: existing?.id ?? body.id ?? newProfileId(),
+      revision: (existing?.revision ?? 0) + 1,
+    });
+    return HttpResponse.json({ name, message: "Agent profile saved." });
+  }),
+
+  // DELETE /api/agent-profiles/:name - Delete by name (idempotent).
+  http.delete("*/api/agent-profiles/:name", async ({ params }) => {
+    const { name } = params;
+    if (typeof name !== "string") {
+      return HttpResponse.json({ detail: "Invalid name" }, { status: 400 });
+    }
+    // Deleting the active profile clears the pointer rather than leaving it
+    // dangling; a missing name still resolves 200, as on the server.
+    if (activeProfileId === profiles.get(name)?.id) {
+      activeProfileId = null;
+    }
+    profiles.delete(name);
+    return HttpResponse.json({ name, message: "Agent profile deleted." });
+  }),
+];

src/mocks/analytics-handlers.ts

@@ -0,0 +1,13 @@
+import { http, HttpResponse } from "msw";
+
+// Block both the direct PostHog ingestion endpoint and the OpenHands reverse
+// proxy (z.openhands.dev) used by the library telemetry service so mock-mode
+// builds never send analytics events to PostHog.
+export const ANALYTICS_HANDLERS = [
+  http.post("https://us.i.posthog.com/e", async () =>
+    HttpResponse.json(null, { status: 200 }),
+  ),
+  http.post("https://z.openhands.dev/*", async () =>
+    HttpResponse.json(null, { status: 200 }),
+  ),
+];

src/mocks/auth-handlers.ts

@@ -0,0 +1,33 @@
+import { http, HttpResponse } from "msw";
+import { GitUser } from "#/types/git";
+
+export const AUTH_HANDLERS = [
+  // Cloud proxy is not available in mock mode; return a clean 503 so callers
+  // (useAllCloudOrganizations, useBackendsHealth cloud path) fail gracefully
+  // instead of falling through to the real dev server and getting a 502.
+  http.post("*/api/cloud-proxy", () =>
+    HttpResponse.json(
+      { error: "cloud proxy not available in mock mode" },
+      { status: 503 },
+    ),
+  ),
+
+  http.get("*/api/user/info", () => {
+    const user: GitUser = {
+      id: "1",
+      login: "octocat",
+      avatar_url: "https://avatars.githubusercontent.com/u/583231?v=4",
+      company: "GitHub",
+      email: "placeholder@placeholder.placeholder",
+      name: "monalisa octocat",
+    };
+
+    return HttpResponse.json(user);
+  }),
+
+  http.post("*/api/authenticate", async () =>
+    HttpResponse.json({ message: "Authenticated" }),
+  ),
+
+  http.post("*/api/logout", () => HttpResponse.json(null, { status: 200 })),
+];

src/mocks/automation-handlers.ts

@@ -0,0 +1,364 @@
+import { http, HttpResponse, delay } from "msw";
+import capabilitiesFixture from "@openhands/extensions/testing/automations/capabilities.json";
+import type {
+  DeploymentCapabilities,
+  DraftValidationError,
+  ValidateDraftResponse,
+} from "#/manifests/types";
+import type {
+  Automation,
+  AutomationsResponse,
+  AutomationRun,
+  AutomationRunsResponse,
+} from "#/types/automation";
+import { AutomationRunStatus } from "#/types/automation";
+import { MOCK_AUTOMATIONS_RESPONSE } from "./automations.mock";
+import { MOCK_AUTOMATION_RUNS } from "./automation-runs.mock";
+
+// The "supported" deployment from the published contract fixtures. Discovery
+// and preflight answer with it, so the setup flow runs against the same
+// reference data the extensions contract is verified against.
+const CAPABILITIES: DeploymentCapabilities =
+  capabilitiesFixture.responses.supported.body;
+
+interface DraftTrigger {
+  type?: string;
+  schedule?: string;
+  on?: string;
+  source?: string;
+}
+
+// The schedules the mock can read: "* * * * *" and "*/N * * * *". Anything
+// else is assumed to satisfy the deployment minimum — this stands in for the
+// service's cron parser rather than reimplementing it.
+const STEP_SCHEDULE_PATTERN = /^(?:\*|\*\/(\d+)) \* \* \* \*$/;
+
+function cronIntervalSeconds(schedule: string): number | null {
+  const match = STEP_SCHEDULE_PATTERN.exec(schedule.trim());
+  if (!match) return null;
+  return (match[1] ? Number(match[1]) : 1) * 60;
+}
+
+// Event deliveries registered for the mock organization. Distinct from
+// CAPABILITIES.eventTypes on purpose: a deployment can support an event type
+// that no webhook is registered to deliver, and preflight is what catches
+// that gap — the fixtures' event-type-not-delivered scenario depends on one
+// supported type staying unregistered here.
+const REGISTERED_EVENT_TYPES = CAPABILITIES.eventTypes.filter(
+  (type) => type !== "pull_request_review_comment.created",
+);
+
+// The deployment checks the contract fixtures record: a cron schedule below
+// triggers.cron.minIntervalSeconds, and an event type no webhook delivers.
+// Errors address the draft by dotted path, exactly as the fixtures do.
+function validateDraftTrigger(
+  trigger: DraftTrigger | undefined,
+): DraftValidationError[] {
+  if (!trigger) return [];
+
+  const cron = CAPABILITIES.triggers.cron;
+  if (trigger.type === "cron" && trigger.schedule && cron) {
+    const interval = cronIntervalSeconds(trigger.schedule);
+    if (interval !== null && interval < cron.minIntervalSeconds) {
+      return [
+        {
+          field: "trigger.schedule",
+          code: "interval_too_short",
+          message: `Minimum interval for this deployment is ${cron.minIntervalSeconds / 60} minutes.`,
+        },
+      ];
+    }
+  }
+
+  if (
+    trigger.type === "event" &&
+    trigger.on &&
+    !REGISTERED_EVENT_TYPES.includes(trigger.on)
+  ) {
+    const source = trigger.source === "github" ? "GitHub" : trigger.source;
+    return [
+      {
+        field: "trigger.on",
+        code: "event_type_not_delivered",
+        message: `No ${source} webhook delivering ${trigger.on} is registered for this organization.`,
+      },
+    ];
+  }
+
+  return [];
+}
+
+// Mutable copy for CRUD operations within the mock session
+const automations = new Map<string, Automation>(
+  MOCK_AUTOMATIONS_RESPONSE.automations.map((a) => [a.id, { ...a }]),
+);
+
+export const resetAutomationMockData = () => {
+  automations.clear();
+  MOCK_AUTOMATIONS_RESPONSE.automations.forEach((a) => {
+    automations.set(a.id, { ...a });
+  });
+};
+
+export const AUTOMATION_HANDLERS = [
+  // GET /api/automation/health — Health check
+  http.get("*/api/automation/health", async () => {
+    await delay(100);
+    return HttpResponse.json({ status: "ok" });
+  }),
+
+  // GET /api/automation/v1 — List automations
+  http.get("*/api/automation/v1", async ({ request }) => {
+    await delay(300);
+
+    const url = new URL(request.url);
+    const limit = Number(url.searchParams.get("limit") ?? "50");
+    const offset = Number(url.searchParams.get("offset") ?? "0");
+
+    const all = Array.from(automations.values());
+    const page = all.slice(offset, offset + limit);
+
+    const response: AutomationsResponse = {
+      automations: page,
+      total: all.length,
+    };
+
+    return HttpResponse.json(response);
+  }),
+
+  // GET /api/automation/v1/capabilities — What this deployment supports
+  http.get("*/api/automation/v1/capabilities", async () => {
+    await delay(200);
+    return HttpResponse.json(CAPABILITIES);
+  }),
+
+  // POST /api/automation/v1/validate — Preflight a draft without creating it
+  http.post("*/api/automation/v1/validate", async ({ request }) => {
+    await delay(200);
+
+    const body = (await request.clone().json()) as {
+      automationId?: string;
+      endpoint?: string;
+      draft?: { trigger?: DraftTrigger };
+    };
+
+    const errors = validateDraftTrigger(body.draft?.trigger);
+    const response: ValidateDraftResponse = {
+      valid: errors.length === 0,
+      errors,
+    };
+
+    return HttpResponse.json(response);
+  }),
+
+  // POST /api/automation/v1/uploads — Upload custom automation tarball
+  http.post("*/api/automation/v1/uploads", async ({ request }) => {
+    await delay(200);
+    const url = new URL(request.url);
+    const name = url.searchParams.get("name") || "automation";
+    return HttpResponse.json({
+      tarball_path: `oh-internal://uploads/${encodeURIComponent(name)}-${crypto.randomUUID()}.tar.gz`,
+    });
+  }),
+
+  // POST /api/automation/v1 — Create an automation from uploaded tarball
+  http.post("*/api/automation/v1", async ({ request }) => {
+    await delay(200);
+
+    const body = (await request.clone().json()) as {
+      name: string;
+      model?: string;
+      trigger: Automation["trigger"];
+      timeout?: number;
+      tarball_path?: string;
+      entrypoint?: string;
+      setup_script_path?: string;
+    };
+    const now = new Date().toISOString();
+    const automation: Automation = {
+      id: crypto.randomUUID(),
+      name: body.name,
+      prompt: null,
+      model: body.model ?? null,
+      trigger: body.trigger,
+      enabled: true,
+      created_at: now,
+      updated_at: now,
+      last_triggered_at: null,
+      ...(typeof body.timeout === "number" && { timeout: body.timeout }),
+      ...(typeof body.trigger.timezone === "string" && {
+        timezone: body.trigger.timezone,
+      }),
+    };
+
+    automations.set(automation.id, automation);
+    return HttpResponse.json(automation, { status: 201 });
+  }),
+
+  // POST /api/automation/v1/preset/:kind — Create a prompt/plugin automation
+  http.post("*/api/automation/v1/preset/:kind", async ({ params, request }) => {
+    await delay(200);
+
+    const body = (await request.clone().json()) as {
+      name: string;
+      prompt: string;
+      model?: string;
+      trigger: Automation["trigger"];
+      repos?: { url: string; ref?: string }[];
+      plugins?: { source: string }[];
+      timeout?: number;
+    };
+    const now = new Date().toISOString();
+    const automation: Automation = {
+      id: crypto.randomUUID(),
+      name: body.name,
+      prompt: body.prompt,
+      model: body.model ?? null,
+      trigger: body.trigger,
+      enabled: true,
+      created_at: now,
+      updated_at: now,
+      last_triggered_at: null,
+      ...(body.repos?.[0] && {
+        repository: body.repos[0].url,
+        branch: body.repos[0].ref,
+      }),
+      ...(body.plugins && {
+        plugins: body.plugins.map((plugin) => plugin.source),
+      }),
+      ...(typeof body.timeout === "number" && { timeout: body.timeout }),
+      ...(typeof body.trigger.timezone === "string" && {
+        timezone: body.trigger.timezone,
+      }),
+    };
+
+    if (params.kind !== "prompt" && params.kind !== "plugin") {
+      return HttpResponse.json(
+        { detail: "Unknown preset kind" },
+        { status: 404 },
+      );
+    }
+
+    automations.set(automation.id, automation);
+    return HttpResponse.json(automation, { status: 201 });
+  }),
+
+  // GET /api/automation/v1/:id/runs — List automation runs
+  http.get("*/api/automation/v1/:id/runs", async ({ params, request }) => {
+    await delay(200);
+
+    const id = params.id as string;
+    if (!automations.has(id)) {
+      return HttpResponse.json(
+        { detail: "Automation not found" },
+        { status: 404 },
+      );
+    }
+
+    const url = new URL(request.url);
+    const limit = Number(url.searchParams.get("limit") ?? "50");
+    const offset = Number(url.searchParams.get("offset") ?? "0");
+    const allRuns = MOCK_AUTOMATION_RUNS[id] ?? [];
+    const page = allRuns.slice(offset, offset + limit);
+    const statusCounts: AutomationRunsResponse["status_counts"] = {};
+    for (const run of allRuns) {
+      statusCounts[run.status] = (statusCounts[run.status] ?? 0) + 1;
+    }
+
+    const response: AutomationRunsResponse = {
+      runs: page,
+      total: allRuns.length,
+      status_counts: statusCounts,
+    };
+
+    return HttpResponse.json(response);
+  }),
+
+  // GET /api/automation/v1/:id — Get automation detail
+  http.get("*/api/automation/v1/:id", async ({ params }) => {
+    await delay(200);
+
+    const automation = automations.get(params.id as string);
+    if (!automation) {
+      return HttpResponse.json(
+        { detail: "Automation not found" },
+        { status: 404 },
+      );
+    }
+
+    return HttpResponse.json(automation);
+  }),
+
+  // PATCH /api/automation/v1/:id — Update automation (toggle enabled)
+  http.patch("*/api/automation/v1/:id", async ({ params, request }) => {
+    await delay(200);
+
+    const id = params.id as string;
+    // Clone the request before reading the body to avoid "Body has already been read" errors
+    // when MSW internally consumes the body during handler resolution.
+    const body = (await request.clone().json()) as Partial<Automation>;
+    const automation = automations.get(id);
+    if (!automation) {
+      return HttpResponse.json(
+        { detail: "Automation not found" },
+        { status: 404 },
+      );
+    }
+
+    const updated: Automation = {
+      ...automation,
+      ...body,
+      updated_at: new Date().toISOString(),
+    };
+    automations.set(id, updated);
+
+    return HttpResponse.json(updated);
+  }),
+
+  // POST /api/automation/v1/:id/dispatch — Manually trigger a run
+  http.post("*/api/automation/v1/:id/dispatch", async ({ params }) => {
+    await delay(200);
+
+    const id = params.id as string;
+    const automation = automations.get(id);
+    if (!automation) {
+      return HttpResponse.json(
+        { detail: "Automation not found" },
+        { status: 404 },
+      );
+    }
+
+    const run: AutomationRun = {
+      id: crypto.randomUUID(),
+      status: AutomationRunStatus.PENDING,
+      conversation_id: null,
+      bash_command_id: null,
+      error_detail: null,
+      // A freshly dispatched run has not reported a phase yet — the service
+      // sends the fields as null rather than omitting them.
+      phase_code: null,
+      phase_label: null,
+      phase_updated_at: null,
+      started_at: new Date().toISOString(),
+      completed_at: null,
+    };
+
+    return HttpResponse.json(run, { status: 201 });
+  }),
+
+  // DELETE /api/automation/v1/:id — Delete automation
+  http.delete("*/api/automation/v1/:id", async ({ params }) => {
+    await delay(200);
+
+    const id = params.id as string;
+    if (!automations.has(id)) {
+      return HttpResponse.json(
+        { detail: "Automation not found" },
+        { status: 404 },
+      );
+    }
+
+    automations.delete(id);
+    return new HttpResponse(null, { status: 204 });
+  }),
+];

src/mocks/automation-runs.mock.ts

@@ -0,0 +1,167 @@
+import { AutomationRunStatus } from "#/types/automation";
+import type { AutomationRun } from "#/types/automation";
+
+const daysAgo = (days: number, hour = 9) => {
+  const d = new Date(Date.now() - days * 86_400_000);
+  d.setHours(hour, 0, 0, 0);
+  return d.toISOString();
+};
+
+const minutesAgo = (minutes: number) =>
+  new Date(Date.now() - minutes * 60_000).toISOString();
+
+/** Omitting this entirely is a case too: an older service sends no phase. */
+interface PhaseFixture {
+  code: string | null;
+  label: string | null;
+  /** Minutes since the phase was last written; defaults to the run's start. */
+  ageMinutes?: number;
+}
+
+function phaseFields(phase: PhaseFixture | undefined, fallbackAt: string) {
+  if (!phase) return {};
+  return {
+    phase_code: phase.code,
+    phase_label: phase.label,
+    phase_updated_at:
+      phase.ageMinutes === undefined
+        ? fallbackAt
+        : minutesAgo(phase.ageMinutes),
+  };
+}
+
+function makeRun(
+  id: string,
+  status: AutomationRunStatus,
+  startedDaysAgo: number,
+  hour = 9,
+  hasConversation = true,
+  phase?: PhaseFixture,
+): AutomationRun {
+  const started = daysAgo(startedDaysAgo, hour);
+  return {
+    id,
+    status,
+    conversation_id: hasConversation ? `conv-${id}` : null,
+    // Runs that have a conversation also have a bash command; runs that
+    // failed before sandbox creation have neither.
+    bash_command_id: hasConversation ? `cmd-${id}` : null,
+    error_detail:
+      status === AutomationRunStatus.FAILED
+        ? "Process exited with code 1"
+        : null,
+    ...phaseFields(phase, started),
+    started_at: started,
+    completed_at: new Date(new Date(started).getTime() + 120_000).toISOString(),
+  };
+}
+
+/**
+ * A run that has not reached a terminal status, started relative to page load
+ * so its elapsed time keeps growing while the dashboard stays open. These are
+ * the rows the phase exists for: without one they render as a bare
+ * "Running"/"Pending" pill for however long the run takes.
+ */
+function makeInFlightRun(
+  id: string,
+  status: AutomationRunStatus.RUNNING | AutomationRunStatus.PENDING,
+  startedMinutesAgo: number,
+  hasConversation = true,
+  phase?: PhaseFixture,
+): AutomationRun {
+  const startedAt = minutesAgo(startedMinutesAgo);
+  return {
+    id,
+    status,
+    conversation_id: hasConversation ? `conv-${id}` : null,
+    bash_command_id: hasConversation ? `cmd-${id}` : null,
+    error_detail: null,
+    ...phaseFields(phase, startedAt),
+    started_at: startedAt,
+    completed_at: null,
+  };
+}
+
+// Newest run first: the cards and home rows read runs[0] as the latest, so
+// the in-flight rows below are the ones they show. Only three automations get
+// one: `latestRun` also drives health, "Last run" and the status badge, so a
+// never-terminal fixture pins all three to "running".
+export const MOCK_AUTOMATION_RUNS: Record<string, AutomationRun[]> = {
+  "a1000000-0000-0000-0000-000000000001": [
+    makeRun("r1-01", AutomationRunStatus.COMPLETED, 0),
+    makeRun("r1-02", AutomationRunStatus.COMPLETED, 1),
+    // Failed, keeping the phase it stopped at: died while the sandbox came up.
+    makeRun("r1-03", AutomationRunStatus.FAILED, 2, 9, true, {
+      code: "sandbox_provisioning",
+      label: null,
+    }),
+    // A phase on record that no screen shows, but the export still carries.
+    makeRun("r1-04", AutomationRunStatus.COMPLETED, 3, 9, true, {
+      code: "running_agent",
+      label: null,
+    }),
+    makeRun("r1-05", AutomationRunStatus.COMPLETED, 4),
+    makeRun("r1-06", AutomationRunStatus.COMPLETED, 7),
+    makeRun("r1-07", AutomationRunStatus.FAILED, 8),
+    makeRun("r1-08", AutomationRunStatus.COMPLETED, 9),
+    makeRun("r1-09", AutomationRunStatus.COMPLETED, 10),
+    makeRun("r1-10", AutomationRunStatus.COMPLETED, 11),
+  ],
+  "a1000000-0000-0000-0000-000000000002": [
+    // Queued: no sandbox or conversation yet, and only the phase says so.
+    makeInFlightRun("r2-00", AutomationRunStatus.PENDING, 2, false, {
+      code: "queued",
+      label: null,
+    }),
+    makeRun("r2-01", AutomationRunStatus.COMPLETED, 0, 1),
+    makeRun("r2-02", AutomationRunStatus.COMPLETED, 1, 1),
+    makeRun("r2-03", AutomationRunStatus.COMPLETED, 2, 1),
+    makeRun("r2-04", AutomationRunStatus.FAILED, 3, 1),
+    makeRun("r2-05", AutomationRunStatus.COMPLETED, 4, 1),
+  ],
+  "a1000000-0000-0000-0000-000000000003": [
+    // The case the issue is about: 52 minutes into a job that usually takes
+    // two, stuck on one step for 41 of them. The code is the automation's
+    // own, so its label is shown verbatim — and is long enough to be clipped.
+    makeInFlightRun("r3-00", AutomationRunStatus.RUNNING, 52, true, {
+      code: "diffing_docs_tree",
+      label: "Diffing 340 changed files against main",
+      ageMinutes: 41,
+    }),
+    makeRun("r3-01", AutomationRunStatus.COMPLETED, 1),
+    // Terminal statuses the backend emits besides COMPLETED/FAILED.
+    makeRun("r3-02", AutomationRunStatus.CANCELLED, 2),
+    makeRun("r3-03", AutomationRunStatus.SKIPPED, 3, 9, false),
+  ],
+  "a1000000-0000-0000-0000-000000000004": [
+    makeRun("r4-01", AutomationRunStatus.FAILED, 14, 11, false), // Failed before sandbox creation
+    makeRun("r4-02", AutomationRunStatus.COMPLETED, 21, 11),
+  ],
+  "a1000000-0000-0000-0000-000000000005": [],
+  "a1000000-0000-0000-0000-000000000006": [
+    // A label with no code: the service accepts that, so the UI must show it.
+    makeInFlightRun("r6-00", AutomationRunStatus.RUNNING, 13, true, {
+      code: null,
+      label: "Running QA checks on PR #4821",
+      ageMinutes: 4,
+    }),
+    // A code with no label: also accepted, and shown as the raw code.
+    makeInFlightRun("r6-06", AutomationRunStatus.RUNNING, 6, true, {
+      code: "checking_out",
+      label: null,
+      ageMinutes: 2,
+    }),
+    // No phase fields at all — an older service: a status pill, no empty
+    // slot. Below the head, so it costs no card its health.
+    makeInFlightRun("r6-07", AutomationRunStatus.RUNNING, 21),
+    makeRun("r6-01", AutomationRunStatus.COMPLETED, 0, 14),
+    makeRun("r6-02", AutomationRunStatus.COMPLETED, 0, 11),
+    makeRun("r6-03", AutomationRunStatus.FAILED, 1, 16),
+    makeRun("r6-04", AutomationRunStatus.COMPLETED, 2, 10),
+    makeRun("r6-05", AutomationRunStatus.COMPLETED, 3, 9),
+  ],
+  "a1000000-0000-0000-0000-000000000007": [
+    makeRun("r7-01", AutomationRunStatus.COMPLETED, 3, 15),
+    makeRun("r7-02", AutomationRunStatus.COMPLETED, 10, 12),
+  ],
+};

src/mocks/automations.mock.ts

@@ -0,0 +1,177 @@
+import type { AutomationsResponse } from "#/types/automation";
+
+/**
+ * Mock automations data matching the AutomationResponse schema from the backend.
+ *
+ * Backend schema fields: id, user_id, org_id, name, trigger (JSONB),
+ * tarball_path, setup_script_path, entrypoint, timeout, enabled,
+ * last_triggered_at, created_at, updated_at.
+ *
+ * The frontend Automation type only uses a subset of these fields.
+ * Additional backend fields are included here for API fidelity.
+ */
+
+const now = new Date().toISOString();
+const daysAgo = (days: number) =>
+  new Date(Date.now() - days * 86_400_000).toISOString();
+
+export const MOCK_AUTOMATIONS_RESPONSE: AutomationsResponse = {
+  automations: [
+    {
+      id: "a1000000-0000-0000-0000-000000000001",
+      name: "PR Triage Digest",
+      trigger: {
+        type: "cron",
+        schedule: "0 9 * * 1-5",
+        schedule_human: "Weekdays at 09:00",
+      },
+      enabled: true,
+      repository: "acme/frontend-app",
+      model: "triage-fast",
+      timeout: 600,
+      created_at: daysAgo(90),
+      updated_at: now,
+      prompt:
+        "Review newly opened pull requests in acme/frontend-app, identify risky changes, summarize likely impact, and prepare a concise digest with priority ordering for the engineering review channel.",
+      branch: "main",
+      plugins: ["GitHub", "Slack", "Linear"],
+      notification: "Slack digest to #eng-reviews",
+      timezone: "America/Los_Angeles",
+      last_triggered_at: daysAgo(0),
+    },
+    {
+      id: "a1000000-0000-0000-0000-000000000002",
+      name: "Nightly Security Pass",
+      trigger: {
+        type: "cron",
+        schedule: "30 1 * * *",
+        schedule_human: "Daily at 01:30",
+      },
+      enabled: true,
+      repository: "acme/backend-api",
+      model: "security-careful",
+      timeout: 900,
+      created_at: daysAgo(60),
+      updated_at: now,
+      prompt:
+        "Scan the acme/backend-api repository for known security vulnerabilities, outdated dependencies, and insecure code patterns. Produce a prioritized remediation summary.",
+      branch: "main",
+      plugins: ["GitHub"],
+      notification: "Email to security-team@acme.com",
+      timezone: "UTC",
+      last_triggered_at: daysAgo(0),
+    },
+    {
+      id: "a1000000-0000-0000-0000-000000000003",
+      name: "Docs Sync on Push",
+      trigger: {
+        type: "cron",
+        schedule: "*/5 * * * *",
+        schedule_human: "Runs on every push",
+      },
+      enabled: true,
+      repository: "acme/docs",
+      model: "docs-fast",
+      created_at: daysAgo(45),
+      updated_at: now,
+      prompt:
+        "Monitor acme/docs for new pushes. For each push, generate a changelog-ready summary of what changed and why.",
+      branch: "main",
+      plugins: ["GitHub", "Slack"],
+      notification: "Slack to #docs-updates",
+      timezone: "America/New_York",
+      last_triggered_at: daysAgo(1),
+    },
+    {
+      id: "a1000000-0000-0000-0000-000000000004",
+      name: "Release Readiness Review",
+      trigger: {
+        type: "cron",
+        schedule: "0 11 * * 5",
+        schedule_human: "Fridays at 11:00",
+      },
+      enabled: false,
+      repository: "acme/realtime-service",
+      model: "release-review",
+      created_at: daysAgo(80),
+      updated_at: now,
+      prompt:
+        "Compile a release readiness report: list open blockers, active incidents, and pending approvals for acme/realtime-service.",
+      branch: "release",
+      plugins: ["GitHub", "Linear"],
+      notification: "Slack to #releases",
+      timezone: "America/Chicago",
+      last_triggered_at: daysAgo(14),
+    },
+    {
+      id: "a1000000-0000-0000-0000-000000000005",
+      name: "Incident Webhook Summary",
+      trigger: {
+        type: "cron",
+        schedule: "0 */2 * * *",
+        schedule_human: "On incident webhook",
+      },
+      enabled: false,
+      repository: "acme/incident-service",
+      model: "incident-summary",
+      created_at: daysAgo(30),
+      updated_at: now,
+      prompt:
+        "Summarize incoming incident webhooks, categorize by severity, and post a digest to the on-call Slack channel.",
+      branch: "main",
+      plugins: ["Slack"],
+      notification: "Slack to #oncall",
+      timezone: "UTC",
+      last_triggered_at: null,
+    },
+    {
+      id: "a1000000-0000-0000-0000-000000000006",
+      name: "PR Review on Open",
+      trigger: {
+        type: "event",
+        source: "github",
+        on: "pull_request.opened",
+        filter: "repository.full_name == 'acme/frontend-app'",
+      },
+      enabled: true,
+      repository: "acme/frontend-app",
+      model: "review-fast",
+      timeout: 1800,
+      created_at: daysAgo(15),
+      updated_at: now,
+      prompt:
+        "When a new PR is opened, perform a thorough code review focusing on correctness, security, and performance. Post findings as inline comments.",
+      branch: "main",
+      plugins: ["GitHub"],
+      notification: "GitHub PR comment",
+      last_triggered_at: daysAgo(0),
+      // Template provenance, as the setup flow stores it. The other mock
+      // automations stay without one to exercise the no-statement path.
+      preset_metadata: {
+        template: { id: "github-pr-reviewer", version: "1.0.0", config: {} },
+      },
+    },
+    {
+      id: "a1000000-0000-0000-0000-000000000007",
+      name: "Release Notes Generator",
+      trigger: {
+        type: "event",
+        source: "github",
+        on: "release.published",
+        filter: "glob(release.tag_name, 'v*') && !release.prerelease",
+      },
+      enabled: true,
+      repository: "acme/backend-api",
+      model: "docs-fast",
+      created_at: daysAgo(10),
+      updated_at: now,
+      prompt:
+        "Generate comprehensive release notes from the commits since the last release. Include breaking changes, new features, and bug fixes.",
+      branch: "main",
+      plugins: ["GitHub"],
+      notification: "GitHub release body update",
+      last_triggered_at: daysAgo(3),
+    },
+  ],
+  total: 7,
+};

src/mocks/browser.ts

@@ -0,0 +1,4 @@
+import { setupWorker } from "msw/browser";
+import { handlers } from "./handlers";
+
+export const worker = setupWorker(...handlers);

src/mocks/canvas-extensions-handlers.test.ts

@@ -0,0 +1,83 @@
+/* eslint-disable local/no-direct-agent-server-fetch --
+   These fetches deliberately bypass the typed client to exercise the MSW
+   network-interception layer that dev:mock relies on. */
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  CANVAS_EXTENSION_DEMO_SOURCE,
+  resetCanvasExtensionsMockData,
+} from "#/mocks/canvas-extensions-handlers";
+
+afterEach(() => {
+  resetCanvasExtensionsMockData();
+});
+
+async function installDemo(): Promise<Response> {
+  return fetch("http://127.0.0.1:8000/api/canvas-extensions/install", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ source: CANVAS_EXTENSION_DEMO_SOURCE }),
+  });
+}
+
+describe("Canvas Extension MSW handlers", () => {
+  it("installs the fixture disabled and then enables it explicitly", async () => {
+    const installResponse = await installDemo();
+    expect(installResponse.status).toBe(200);
+    await expect(installResponse.json()).resolves.toMatchObject({
+      name: "demo-page",
+      enabled: false,
+      source: CANVAS_EXTENSION_DEMO_SOURCE,
+    });
+
+    const enableResponse = await fetch(
+      "http://127.0.0.1:8000/api/canvas-extensions/installed/demo-page",
+      {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ enabled: true }),
+      },
+    );
+    await expect(enableResponse.json()).resolves.toEqual({
+      name: "demo-page",
+      enabled: true,
+    });
+
+    const listResponse = await fetch(
+      "http://127.0.0.1:8000/api/canvas-extensions/installed",
+    );
+    await expect(listResponse.json()).resolves.toMatchObject({
+      canvas_extensions: [{ name: "demo-page", enabled: true }],
+    });
+  });
+
+  it("serves the fixture as JavaScript text", async () => {
+    await installDemo();
+
+    const response = await fetch(
+      "http://127.0.0.1:8000/api/canvas-extensions/installed/demo-page/bundle",
+    );
+
+    expect(response.headers.get("content-type")).toContain(
+      "application/javascript",
+    );
+    await expect(response.text()).resolves.toContain(
+      "export function activate",
+    );
+  });
+
+  it("rejects arbitrary sources in mock mode", async () => {
+    const response = await fetch(
+      "http://127.0.0.1:8000/api/canvas-extensions/install",
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ source: "github:example/unknown" }),
+      },
+    );
+
+    expect(response.status).toBe(400);
+    await expect(response.json()).resolves.toEqual({
+      detail: `Mock mode only installs '${CANVAS_EXTENSION_DEMO_SOURCE}'.`,
+    });
+  });
+});

src/mocks/canvas-extensions-handlers.ts

@@ -0,0 +1,169 @@
+import { http, HttpResponse } from "msw";
+import type {
+  CanvasExtensionManifest,
+  InstallCanvasExtensionRequest,
+  InstalledCanvasExtensionInfo,
+} from "#/types/canvas-extension";
+import demoManifestSource from "#/fixtures/canvas-extensions/demo-page/canvas-extension.json?raw";
+// eslint-disable-next-line import-x/extensions -- Vite requires the real filename before ?raw.
+import demoBundle from "#/fixtures/canvas-extensions/demo-page/extension.js?raw";
+
+export const CANVAS_EXTENSION_DEMO_SOURCE =
+  "src/fixtures/canvas-extensions/demo-page";
+
+const demoManifest = JSON.parse(demoManifestSource) as CanvasExtensionManifest;
+
+const MOCK_STORAGE_KEY = "openhands-canvas-extension-dev-installation";
+
+function readPersistedExtension(): InstalledCanvasExtensionInfo | null {
+  try {
+    const value = globalThis.sessionStorage?.getItem(MOCK_STORAGE_KEY);
+    return value ? (JSON.parse(value) as InstalledCanvasExtensionInfo) : null;
+  } catch {
+    return null;
+  }
+}
+
+let installedExtension = readPersistedExtension();
+
+function persistInstalledExtension(
+  extension: InstalledCanvasExtensionInfo | null,
+): void {
+  installedExtension = extension;
+  try {
+    if (extension) {
+      globalThis.sessionStorage?.setItem(
+        MOCK_STORAGE_KEY,
+        JSON.stringify(extension),
+      );
+    } else {
+      globalThis.sessionStorage?.removeItem(MOCK_STORAGE_KEY);
+    }
+  } catch {
+    // The module variable still provides an in-memory fallback.
+  }
+}
+
+function isDemoSource(source: string): boolean {
+  return source.replaceAll("\\", "/").endsWith(CANVAS_EXTENSION_DEMO_SOURCE);
+}
+
+function getRequestedName(
+  value: string | readonly string[] | undefined,
+): string {
+  if (!value) return "";
+  return decodeURIComponent(Array.isArray(value) ? value[0] : value);
+}
+
+function extensionNotFound(name: string) {
+  return HttpResponse.json(
+    { detail: `Canvas extension '${name}' is not installed.` },
+    { status: 404 },
+  );
+}
+
+function getInstalledExtension(
+  name: string,
+): InstalledCanvasExtensionInfo | null {
+  if (installedExtension?.name !== name) return null;
+  return installedExtension;
+}
+
+export function resetCanvasExtensionsMockData(): void {
+  persistInstalledExtension(null);
+}
+
+/**
+ * Browser-development implementation of the Canvas Extension API contract.
+ * It intentionally supports only the checked-in demo fixture. Production and
+ * ordinary dev stacks continue to use the active Agent Server exclusively.
+ */
+export const CANVAS_EXTENSIONS_HANDLERS = [
+  http.get("*/api/canvas-extensions/installed", () =>
+    HttpResponse.json({
+      canvas_extensions: installedExtension ? [installedExtension] : [],
+    }),
+  ),
+
+  http.post("*/api/canvas-extensions/install", async ({ request }) => {
+    const body = (await request.json()) as InstallCanvasExtensionRequest;
+    if (!body.source || !isDemoSource(body.source)) {
+      return HttpResponse.json(
+        {
+          detail: `Mock mode only installs '${CANVAS_EXTENSION_DEMO_SOURCE}'.`,
+        },
+        { status: 400 },
+      );
+    }
+
+    if (installedExtension && !body.force) {
+      return HttpResponse.json(
+        {
+          detail: `Canvas extension '${demoManifest.name}' is already installed.`,
+        },
+        { status: 409 },
+      );
+    }
+
+    persistInstalledExtension({
+      name: demoManifest.name,
+      version: demoManifest.version,
+      description: demoManifest.description,
+      enabled: false,
+      source: body.source,
+      resolved_ref: body.ref || "mock-working-tree",
+      repo_path: body.repo_path || null,
+      installed_at: new Date().toISOString(),
+      install_path: `/mock/canvas-extensions/${demoManifest.name}`,
+      // The real backend only returns `manifest` once OSS-10048 lands; the
+      // mock previews that shape so the demo fixture's pages work in dev mode.
+      manifest: demoManifest,
+    });
+
+    return HttpResponse.json(installedExtension);
+  }),
+
+  http.get("*/api/canvas-extensions/installed/:name/bundle", ({ params }) => {
+    const name = getRequestedName(params.name);
+    if (!getInstalledExtension(name)) return extensionNotFound(name);
+    return new HttpResponse(demoBundle, {
+      headers: {
+        "Content-Type": "application/javascript; charset=utf-8",
+        "Cache-Control": "no-cache",
+      },
+    });
+  }),
+
+  http.get("*/api/canvas-extensions/installed/:name", ({ params }) => {
+    const name = getRequestedName(params.name);
+    const extension = getInstalledExtension(name);
+    return extension ? HttpResponse.json(extension) : extensionNotFound(name);
+  }),
+
+  http.patch(
+    "*/api/canvas-extensions/installed/:name",
+    async ({ params, request }) => {
+      const name = getRequestedName(params.name);
+      const extension = getInstalledExtension(name);
+      if (!extension) return extensionNotFound(name);
+
+      const body = (await request.json()) as { enabled?: unknown };
+      if (typeof body.enabled !== "boolean") {
+        return HttpResponse.json(
+          { detail: "'enabled' must be a boolean." },
+          { status: 422 },
+        );
+      }
+
+      persistInstalledExtension({ ...extension, enabled: body.enabled });
+      return HttpResponse.json({ name, enabled: body.enabled });
+    },
+  ),
+
+  http.delete("*/api/canvas-extensions/installed/:name", ({ params }) => {
+    const name = getRequestedName(params.name);
+    if (!getInstalledExtension(name)) return extensionNotFound(name);
+    persistInstalledExtension(null);
+    return HttpResponse.json({ message: "Canvas extension uninstalled." });
+  }),
+];

src/mocks/conversation-handlers.ts

@@ -0,0 +1,488 @@
+import { http, delay, HttpResponse, passthrough } from "msw";
+import type { DirectConversationInfo } from "#/api/agent-server-adapter";
+import type { AppConversation } from "#/api/conversation-service/agent-server-conversation-service.types";
+import {
+  ExecutionStatus,
+  type OpenHandsEvent,
+} from "#/types/agent-server/core";
+import {
+  TABLE_DEMO_CONVERSATION_ID,
+  TABLE_DEMO_EVENTS,
+} from "#/fixtures/table-demo-conversation";
+import {
+  CANVAS_DEMO_CONVERSATION_ID,
+  CANVAS_DEMO_EVENTS,
+  CANVAS_DEMO_FILE_PATH,
+  CANVAS_DEMO_MARKDOWN,
+} from "#/fixtures/canvas-demo-conversation";
+
+/** Map from conversation id → events returned by GET /events/search */
+const CONVERSATION_EVENTS: Record<string, unknown[]> = {
+  [TABLE_DEMO_CONVERSATION_ID]: TABLE_DEMO_EVENTS,
+  [CANVAS_DEMO_CONVERSATION_ID]: CANVAS_DEMO_EVENTS,
+};
+
+const now = Date.now();
+const PAGINATION_LOCAL_CONVERSATION_ID = "pagination-local";
+const PAGINATION_CLOUD_CONVERSATION_ID = "pagination-cloud";
+const PAGINATION_EVENT_COUNT = 100;
+const PAGINATION_PAGE_DELAY_MS = 500;
+const PAGINATION_BASE_TIME = Date.UTC(2026, 4, 13, 0, 0, 0);
+
+type MockConversation = DirectConversationInfo & {
+  selected_repository?: string | null;
+  selected_branch?: string | null;
+  git_provider?: string | null;
+};
+
+type CloudProxyEnvelope = {
+  method?: string;
+  path?: string;
+};
+
+const conversations: MockConversation[] = [
+  {
+    id: "1",
+    title: "My New Project",
+    created_at: new Date(now).toISOString(),
+    updated_at: new Date(now).toISOString(),
+    execution_status: "waiting_for_confirmation",
+    // User-authored tags so the layouts menu's Tag Filters section and the
+    // card chips have something to show in mock mode.
+    tags: { project: "vault", work: "" },
+  },
+  {
+    id: "2",
+    title: "Repo Testing",
+    created_at: new Date(now - 2 * 24 * 60 * 60 * 1000).toISOString(),
+    updated_at: new Date(now - 2 * 24 * 60 * 60 * 1000).toISOString(),
+    execution_status: "idle",
+    selected_repository: "octocat/hello-world",
+    git_provider: "github",
+  },
+  {
+    id: "3",
+    title: "Another Project",
+    created_at: new Date(now - 5 * 24 * 60 * 60 * 1000).toISOString(),
+    updated_at: new Date(now - 5 * 24 * 60 * 60 * 1000).toISOString(),
+    execution_status: "idle",
+    selected_repository: "octocat/earth",
+    selected_branch: "main",
+  },
+  // Conversation whose sandbox has been removed (MISSING). The conversation
+  // history is still readable but the sandbox cannot be resumed — the chat
+  // input is replaced with a read-only archived banner.
+  {
+    id: "4",
+    title: "Archived Project",
+    created_at: new Date(now - 10 * 24 * 60 * 60 * 1000).toISOString(),
+    updated_at: new Date(now - 10 * 24 * 60 * 60 * 1000).toISOString(),
+    execution_status: "idle",
+    sandbox_status: "MISSING",
+  },
+  // Conversation whose sandbox encountered an unrecoverable error. Same
+  // read-only treatment but with the "Sandbox error" variant of the banner.
+  {
+    id: "5",
+    title: "Errored Project",
+    created_at: new Date(now - 7 * 24 * 60 * 60 * 1000).toISOString(),
+    updated_at: new Date(now - 7 * 24 * 60 * 60 * 1000).toISOString(),
+    execution_status: "idle",
+    sandbox_status: "ERROR",
+  },
+  {
+    id: PAGINATION_LOCAL_CONVERSATION_ID,
+    title: "Local pagination fixture",
+    created_at: new Date(now - 6 * 24 * 60 * 60 * 1000).toISOString(),
+    updated_at: new Date(now - 6 * 24 * 60 * 60 * 1000).toISOString(),
+    execution_status: "idle",
+    workspace: { working_dir: "/workspace/project" },
+  },
+  {
+    id: TABLE_DEMO_CONVERSATION_ID,
+    title: "Wide table demo",
+    created_at: new Date(now - 1 * 24 * 60 * 60 * 1000).toISOString(),
+    updated_at: new Date(now - 1 * 24 * 60 * 60 * 1000).toISOString(),
+    execution_status: "idle",
+    workspace: { working_dir: "/workspace/project" },
+  },
+  {
+    id: CANVAS_DEMO_CONVERSATION_ID,
+    title: "Generated canvas demo",
+    created_at: new Date(now - 12 * 60 * 60 * 1000).toISOString(),
+    updated_at: new Date(now - 12 * 60 * 60 * 1000).toISOString(),
+    execution_status: "idle",
+    workspace: { working_dir: "/workspace/project" },
+  },
+];
+
+const CONVERSATIONS = new Map<string, MockConversation>(
+  conversations.map((conversation) => [conversation.id, conversation]),
+);
+
+const paginationEventsByConversation = new Map<string, OpenHandsEvent[]>([
+  [
+    PAGINATION_LOCAL_CONVERSATION_ID,
+    createPaginationEvents("Local pagination message"),
+  ],
+  [
+    PAGINATION_CLOUD_CONVERSATION_ID,
+    createPaginationEvents("Cloud pagination message"),
+  ],
+]);
+
+function createPaginationEvent(
+  index: number,
+  messagePrefix: string,
+): OpenHandsEvent {
+  return {
+    id: `${messagePrefix.toLowerCase().replaceAll(" ", "-")}-${index}`,
+    timestamp: new Date(PAGINATION_BASE_TIME + index * 60_000).toISOString(),
+    source: "agent",
+    llm_message: {
+      role: "assistant",
+      content: [{ type: "text", text: `${messagePrefix} ${index}` }],
+    },
+    activated_skills: [],
+    extended_content: [],
+  };
+}
+
+function createPaginationEvents(messagePrefix: string): OpenHandsEvent[] {
+  return Array.from({ length: PAGINATION_EVENT_COUNT }, (_, index) =>
+    createPaginationEvent(index + 1, messagePrefix),
+  );
+}
+
+function searchPaginationEvents(
+  events: OpenHandsEvent[],
+  searchParams: URLSearchParams,
+) {
+  const limit = Number(searchParams.get("limit") ?? "100");
+  const timestampLt = searchParams.get("timestamp__lt");
+  const sortOrder = searchParams.get("sort_order");
+  const filtered = timestampLt
+    ? events.filter((event) => (event.timestamp ?? "") < timestampLt)
+    : events;
+  const sorted = [...filtered].sort((a, b) =>
+    sortOrder === "TIMESTAMP_DESC"
+      ? (b.timestamp ?? "").localeCompare(a.timestamp ?? "")
+      : (a.timestamp ?? "").localeCompare(b.timestamp ?? ""),
+  );
+
+  return {
+    items: sorted.slice(0, limit),
+    next_page_id: sorted.length > limit ? "next-page" : null,
+  };
+}
+
+async function maybeReturnPaginationEvents(
+  conversationId: string,
+  searchParams: URLSearchParams,
+) {
+  const events = paginationEventsByConversation.get(conversationId);
+  if (!events) return null;
+  if (searchParams.has("timestamp__lt")) {
+    await delay(PAGINATION_PAGE_DELAY_MS);
+  }
+  return searchPaginationEvents(events, searchParams);
+}
+
+function createCloudPaginationConversation(): AppConversation {
+  const createdAt = new Date(now - 6 * 24 * 60 * 60 * 1000).toISOString();
+  const updatedAt = createdAt;
+
+  return {
+    id: PAGINATION_CLOUD_CONVERSATION_ID,
+    created_by_user_id: null,
+    selected_repository: null,
+    selected_branch: null,
+    git_provider: null,
+    title: "Cloud pagination fixture",
+    trigger: null,
+    pr_number: [],
+    llm_model: "openhands/claude-haiku-4-5-20251001",
+    metrics: null,
+    created_at: createdAt,
+    updated_at: updatedAt,
+    execution_status: ExecutionStatus.IDLE,
+    conversation_url: null,
+    session_api_key: null,
+    sandbox_id: null,
+    workspace: { working_dir: "/workspace/project" },
+    public: false,
+    sub_conversation_ids: [],
+  };
+}
+
+const CLOUD_PAGINATION_CONVERSATION = createCloudPaginationConversation();
+
+function createConversationResponse(
+  conversation: MockConversation,
+): DirectConversationInfo {
+  return {
+    id: conversation.id,
+    title: conversation.title ?? null,
+    created_at: conversation.created_at,
+    updated_at: conversation.updated_at,
+    execution_status: conversation.execution_status ?? "idle",
+    sandbox_status: conversation.sandbox_status ?? null,
+    metrics: conversation.metrics ?? null,
+    agent: conversation.agent ?? null,
+    workspace: conversation.workspace ?? null,
+    tags: conversation.tags ?? null,
+  };
+}
+
+function listConversationResponses(ids?: string[] | null) {
+  if (!ids || ids.length === 0) {
+    return Array.from(CONVERSATIONS.values()).map(createConversationResponse);
+  }
+
+  return ids.map((id) => {
+    const conversation = CONVERSATIONS.get(id);
+    return conversation ? createConversationResponse(conversation) : null;
+  });
+}
+
+export const CONVERSATION_HANDLERS = [
+  http.get("*/api/conversations/search", async ({ request }) => {
+    const url = new URL(request.url);
+    const limit = Number(url.searchParams.get("limit") ?? "20");
+    const items = Array.from(CONVERSATIONS.values())
+      .sort((a, b) => b.updated_at.localeCompare(a.updated_at))
+      .slice(0, limit)
+      .map(createConversationResponse);
+
+    return HttpResponse.json({ items, next_page_id: null });
+  }),
+
+  http.get("*/api/conversations", async ({ request }) => {
+    const url = new URL(request.url);
+    // Axios serializes arrays as `ids[]=a&ids[]=b` (bracket notation).
+    // Fall back to plain `ids` to support both formats.
+    const ids =
+      url.searchParams.getAll("ids[]").length > 0
+        ? url.searchParams.getAll("ids[]")
+        : url.searchParams.getAll("ids");
+    return HttpResponse.json(listConversationResponses(ids));
+  }),
+
+  http.get("*/api/conversations/:conversationId", async ({ params }) => {
+    const conversationId = params.conversationId as string;
+    const conversation = CONVERSATIONS.get(conversationId);
+    if (conversation) {
+      return HttpResponse.json(createConversationResponse(conversation));
+    }
+    return HttpResponse.json(null, { status: 404 });
+  }),
+
+  http.post("*/api/conversations", async () => {
+    await delay();
+    const conversation: MockConversation = {
+      id: `${Math.floor(Math.random() * 100000)}`,
+      title: "New Conversation",
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+      execution_status: "idle",
+    };
+    CONVERSATIONS.set(conversation.id, conversation);
+    return HttpResponse.json(createConversationResponse(conversation), {
+      status: 201,
+    });
+  }),
+
+  http.patch(
+    "/api/conversations/:conversationId",
+    async ({ params, request }) => {
+      const conversationId = params.conversationId as string;
+      const conversation = CONVERSATIONS.get(conversationId);
+
+      if (conversation) {
+        const body = (await request.json()) as {
+          title?: string;
+          tags?: Record<string, string>;
+        } | null;
+        // PATCH replaces the complete tags map (agent-server semantics);
+        // title-only and tags-only patches both persist.
+        if (body?.title || body?.tags) {
+          CONVERSATIONS.set(conversationId, {
+            ...conversation,
+            ...(body.title ? { title: body.title } : {}),
+            ...(body.tags ? { tags: body.tags } : {}),
+            updated_at: new Date().toISOString(),
+          });
+          return HttpResponse.json(null, { status: 200 });
+        }
+      }
+      return HttpResponse.json(null, { status: 404 });
+    },
+  ),
+
+  http.delete("*/api/conversations/:conversationId", async ({ params }) => {
+    const conversationId = params.conversationId as string;
+    if (CONVERSATIONS.has(conversationId)) {
+      CONVERSATIONS.delete(conversationId);
+      return HttpResponse.json(null, { status: 200 });
+    }
+    return HttpResponse.json(null, { status: 404 });
+  }),
+
+  http.get("*/api/conversations/:conversationId/events/count", async () =>
+    HttpResponse.json(0),
+  ),
+
+  http.get(
+    "*/api/conversations/:conversationId/events/search",
+    async ({ params, request }) => {
+      const conversationId = params.conversationId as string;
+      const searchParams = new URL(request.url).searchParams;
+      const paginationPage = await maybeReturnPaginationEvents(
+        conversationId,
+        searchParams,
+      );
+      if (paginationPage) return HttpResponse.json(paginationPage);
+
+      const staticEvents = CONVERSATION_EVENTS[conversationId];
+      if (staticEvents) {
+        return HttpResponse.json(
+          searchPaginationEvents(
+            staticEvents as OpenHandsEvent[],
+            searchParams,
+          ),
+        );
+      }
+
+      return HttpResponse.json({ items: [], next_page_id: null });
+    },
+  ),
+
+  http.post("*/api/conversations/:conversationId/events", async () =>
+    HttpResponse.json({ ok: true }),
+  ),
+
+  // The generated-canvas fixture behaves like a real workspace artifact:
+  // after the chat chip opens the Files drawer, its static-session URL serves
+  // the same Markdown bytes carried by the file-editor observation.
+  http.get(
+    "*/api/conversations/:conversationId/workspace/*",
+    ({ params, request }) => {
+      const conversationId = params.conversationId?.toString();
+      const url = new URL(request.url);
+      if (
+        conversationId === CANVAS_DEMO_CONVERSATION_ID &&
+        url.pathname.endsWith(`/${CANVAS_DEMO_FILE_PATH}`)
+      ) {
+        return HttpResponse.text(CANVAS_DEMO_MARKDOWN, {
+          headers: { "Content-Type": "text/markdown; charset=utf-8" },
+        });
+      }
+      // Leave every other workspace-file GET on its previous bypass behavior
+      // so this fixture handler does not force 404s for unrelated mocks.
+      return passthrough();
+    },
+  ),
+
+  http.post("*/api/conversations/:conversationId/pause", async () =>
+    HttpResponse.json({ success: true }),
+  ),
+
+  http.post("*/api/conversations/:conversationId/interrupt", async () =>
+    HttpResponse.json({ success: true }),
+  ),
+
+  http.post("*/api/conversations/:conversationId/run", async () =>
+    HttpResponse.json({ success: true }),
+  ),
+
+  http.post("*/api/cloud-proxy", async ({ request }) => {
+    const envelope = (await request.json()) as CloudProxyEnvelope;
+    const upstreamPath = envelope.path ?? "/";
+    const upstreamUrl = new URL(upstreamPath, "https://mock-cloud.test");
+
+    if (upstreamUrl.pathname === "/api/v1/app-conversations") {
+      const ids = upstreamUrl.searchParams.getAll("ids");
+      if (ids.length > 0) {
+        return HttpResponse.json(
+          ids.map((id) =>
+            id === PAGINATION_CLOUD_CONVERSATION_ID
+              ? CLOUD_PAGINATION_CONVERSATION
+              : null,
+          ),
+        );
+      }
+    }
+
+    if (upstreamUrl.pathname === "/api/v1/app-conversations/search") {
+      return HttpResponse.json({
+        items: [CLOUD_PAGINATION_CONVERSATION],
+        next_page_id: null,
+      });
+    }
+
+    if (
+      upstreamUrl.pathname ===
+      `/api/v1/conversation/${PAGINATION_CLOUD_CONVERSATION_ID}/events/search`
+    ) {
+      const paginationPage = await maybeReturnPaginationEvents(
+        PAGINATION_CLOUD_CONVERSATION_ID,
+        upstreamUrl.searchParams,
+      );
+      return HttpResponse.json(paginationPage);
+    }
+
+    if (upstreamUrl.pathname === "/api/v1/settings") {
+      return HttpResponse.json({
+        llm_model: "openhands/claude-haiku-4-5-20251001",
+        llm_base_url: "",
+        llm_api_key: null,
+        llm_api_key_set: false,
+        search_api_key_set: false,
+        agent: "CodeActAgent",
+        language: "en",
+        user_consents_to_analytics: false,
+        provider_tokens_set: { github: "" },
+      });
+    }
+
+    if (upstreamUrl.pathname === "/api/keys/current") {
+      return HttpResponse.json({
+        id: "mock-key",
+        name: "Mock key",
+        org_id: "org-1",
+        user_id: "user-1",
+        auth_type: "api_key",
+      });
+    }
+
+    if (upstreamUrl.pathname === "/api/organizations") {
+      return HttpResponse.json({
+        items: [{ id: "org-1", name: "Mock Org", is_personal: true }],
+        current_org_id: "org-1",
+      });
+    }
+
+    if (upstreamUrl.pathname === "/api/organizations/org-1/me") {
+      return HttpResponse.json({ org_id: "org-1", user_id: "org-1" });
+    }
+
+    if (upstreamUrl.pathname === "/api/authenticate") {
+      return HttpResponse.json({ ok: true });
+    }
+
+    return HttpResponse.json({});
+  }),
+
+  http.post("*/api/conversations/:conversationId/ask_agent", async () =>
+    HttpResponse.json({ response: "Mock agent response" }),
+  ),
+
+  http.get("*/api/vscode/url", async () => HttpResponse.json({ url: null })),
+
+  http.post("*/api/skills", async () => HttpResponse.json({ skills: [] })),
+
+  http.post(
+    "/api/v1/conversations/:conversationId/pending-messages",
+    async () => HttpResponse.json({ id: "mock-pending-id", position: 0 }),
+  ),
+];

src/mocks/feedback-handlers.ts

@@ -0,0 +1,15 @@
+import { http, delay, HttpResponse } from "msw";
+
+export const FEEDBACK_HANDLERS = [
+  http.post("*/api/submit-feedback", async () => {
+    await delay(1200);
+    return HttpResponse.json({
+      statusCode: 200,
+      body: { message: "Success", link: "fake-url.com", password: "abc123" },
+    });
+  }),
+
+  http.post("*/api/submit-feedback", async () =>
+    HttpResponse.json({ statusCode: 200 }, { status: 200 }),
+  ),
+];

src/mocks/file-service-handlers.ts

@@ -0,0 +1,104 @@
+import { delay, http, HttpResponse } from "msw";
+
+export const FILE_VARIANTS_1 = ["file1.txt", "file2.txt", "file3.txt"];
+export const FILE_VARIANTS_2 = [
+  "reboot_skynet.exe",
+  "target_list.txt",
+  "terminator_blueprint.txt",
+];
+
+const MOCK_FILE_BROWSER_HOME = {
+  home: "/home/openhands",
+  favorites: [{ label: "Downloads", path: "/home/openhands/Downloads" }],
+  locations: [],
+};
+
+const MOCK_SUBDIRECTORIES_BY_PATH: Record<
+  string,
+  { name: string; path: string }[]
+> = {
+  "/projects": [
+    { name: "demo-app", path: "/projects/demo-app" },
+    { name: "sample-tools", path: "/projects/sample-tools" },
+    { name: "notes-service", path: "/projects/notes-service" },
+  ],
+  "/projects/demo-app": [
+    {
+      name: "web-client",
+      path: "/projects/demo-app/web-client",
+    },
+    {
+      name: "api-service",
+      path: "/projects/demo-app/api-service",
+    },
+  ],
+  "/projects/demo-app/web-client": [],
+};
+
+const shouldReturnProjectMock =
+  typeof import.meta.env.MODE === "string" && import.meta.env.MODE !== "test";
+
+export const FILE_SERVICE_HANDLERS = [
+  http.all("*/api/bash/execute_bash_command", async () =>
+    HttpResponse.json({
+      command: "",
+      exit_code: 0,
+      output: "",
+    }),
+  ),
+
+  http.get("*/api/file/home", async () =>
+    HttpResponse.json(MOCK_FILE_BROWSER_HOME),
+  ),
+
+  http.get("*/api/file/search_subdirs", async ({ request }) => {
+    const url = new URL(request.url);
+    const path = url.searchParams.get("path") ?? "";
+    const items = shouldReturnProjectMock
+      ? (MOCK_SUBDIRECTORIES_BY_PATH[path] ?? [])
+      : [];
+
+    return HttpResponse.json({
+      path,
+      items,
+      subdirs: items,
+      next_page_id: null,
+    });
+  }),
+
+  http.get("*/api/file/:path", async ({ params }) =>
+    HttpResponse.json({
+      path: `/${params.path?.toString() ?? "home"}`,
+      subdirs: [],
+    }),
+  ),
+
+  http.get(
+    "/api/conversations/:conversationId/list-files",
+    async ({ params }) => {
+      await delay();
+
+      const cid = params.conversationId?.toString();
+      if (!cid) return HttpResponse.json(null, { status: 400 });
+
+      return cid === "test-conversation-id-2"
+        ? HttpResponse.json(FILE_VARIANTS_2)
+        : HttpResponse.json(FILE_VARIANTS_1);
+    },
+  ),
+
+  http.get(
+    "/api/conversations/:conversationId/select-file",
+    async ({ request }) => {
+      await delay();
+
+      const url = new URL(request.url);
+      const file = url.searchParams.get("file")?.toString();
+      if (file) {
+        return HttpResponse.json({ code: `Content of ${file}` });
+      }
+
+      return HttpResponse.json(null, { status: 404 });
+    },
+  ),
+];

src/mocks/git-repository-handlers.ts

@@ -0,0 +1,259 @@
+import { delay, http, HttpResponse } from "msw";
+import { GitRepository, Branch, PaginatedBranchesResponse } from "#/types/git";
+import { Provider } from "#/types/settings";
+
+// Generate a list of mock repositories with realistic data
+const generateMockRepositories = (
+  count: number,
+  provider: Provider,
+): GitRepository[] =>
+  Array.from({ length: count }, (_, i) => ({
+    id: `${i + 1}`,
+    full_name: `user/repo-${i + 1}`,
+    git_provider: provider,
+    is_public: Math.random() > 0.3, // 70% chance of being public
+    stargazers_count: Math.floor(Math.random() * 1000),
+    pushed_at: new Date(
+      Date.now() - Math.random() * 90 * 24 * 60 * 60 * 1000,
+    ).toISOString(), // Last 90 days
+  }));
+
+// Generate mock branches for a repository
+const generateMockBranches = (count: number): Branch[] =>
+  Array.from({ length: count }, (_, i) => ({
+    name: (() => {
+      if (i === 0) return "main";
+      if (i === 1) return "develop";
+      return `feature/branch-${i}`;
+    })(),
+    commit_sha: `abc123${i.toString().padStart(3, "0")}`,
+    protected: i === 0, // main branch is protected
+    last_push_date: new Date(
+      Date.now() - Math.random() * 7 * 24 * 60 * 60 * 1000,
+    ).toISOString(),
+  }));
+
+// Mock repositories for each provider
+const MOCK_REPOSITORIES = {
+  github: generateMockRepositories(120, "github"),
+  gitlab: generateMockRepositories(120, "gitlab"),
+  bitbucket: generateMockRepositories(120, "bitbucket"),
+};
+
+// Mock branches (same for all repos for simplicity)
+const MOCK_BRANCHES = generateMockBranches(25);
+
+// ── Git workspace mock data ────────────────────────────────────────────────
+// Pre-seeded with one modified, one added, and one deleted file so mock-mode
+// conversations exercise the full file-list / diff-editor / deleted-file
+// placeholder UI.
+
+// Three representative files: modified, added, deleted.
+// Uses AgentServerGitChangeStatus values ("UPDATED", "ADDED", "DELETED") as
+// returned by the real /api/git/changes endpoint; AgentServerGitService maps
+// them via mapAnyGitStatusToClientStatus before handing them to the UI.
+const MOCK_GIT_CHANGES: Array<{ path: string; status: string }> = [
+  { path: "src/components/hello.tsx", status: "UPDATED" },
+  { path: "src/utils/new-helper.ts", status: "ADDED" },
+  { path: "src/old-module.py", status: "DELETED" },
+];
+
+export const GIT_REPOSITORY_HANDLERS = [
+  http.get("*/api/user/repositories", async ({ request }) => {
+    await delay(500); // Simulate network delay
+
+    const url = new URL(request.url);
+    const selectedProvider = url.searchParams.get("selected_provider");
+    const page = parseInt(url.searchParams.get("page") || "1", 10);
+    const perPage = parseInt(url.searchParams.get("per_page") || "30", 10);
+    const sort = url.searchParams.get("sort") || "pushed";
+    const installationId = url.searchParams.get("installation_id");
+
+    // Simulate authentication error if no provider token
+    if (!selectedProvider) {
+      return HttpResponse.json(
+        "Git provider token required. (such as GitHub).",
+        { status: 401 },
+      );
+    }
+
+    // Get repositories for the selected provider
+    const repositories =
+      MOCK_REPOSITORIES[selectedProvider as keyof typeof MOCK_REPOSITORIES] ||
+      [];
+
+    // Sort repositories based on the sort parameter
+    let sortedRepos = [...repositories];
+    if (sort === "pushed") {
+      sortedRepos.sort(
+        (a, b) =>
+          new Date(b.pushed_at!).getTime() - new Date(a.pushed_at!).getTime(),
+      );
+    } else if (sort === "stars") {
+      sortedRepos.sort(
+        (a, b) => (b.stargazers_count || 0) - (a.stargazers_count || 0),
+      );
+    }
+
+    // Handle installation filtering (for GitHub Apps)
+    if (installationId && selectedProvider === "github") {
+      // Simulate filtering by installation - in real API this would filter by access
+      const installationIndex = parseInt(installationId, 10) || 0;
+      const startRepo = installationIndex * 20; // Each installation has ~20 repos
+      sortedRepos = sortedRepos.slice(startRepo, startRepo + 20);
+    }
+
+    // Calculate pagination
+    const startIndex = (page - 1) * perPage;
+    const endIndex = startIndex + perPage;
+    const paginatedRepos = sortedRepos.slice(startIndex, endIndex);
+    const hasNextPage = endIndex < sortedRepos.length;
+    const hasPrevPage = page > 1;
+    const totalPages = Math.ceil(sortedRepos.length / perPage);
+
+    // Generate GitHub-style link header for pagination
+    let linkHeader = "";
+    if (hasNextPage || hasPrevPage) {
+      const links = [];
+      if (hasPrevPage) {
+        links.push(
+          `</api/user/repositories?page=${page - 1}&per_page=${perPage}>; rel="prev"`,
+        );
+      }
+      if (hasNextPage) {
+        links.push(
+          `</api/user/repositories?page=${page + 1}&per_page=${perPage}>; rel="next"`,
+        );
+      }
+      links.push(
+        `</api/user/repositories?page=${totalPages}&per_page=${perPage}>; rel="last"`,
+      );
+      links.push(
+        `</api/user/repositories?page=1&per_page=${perPage}>; rel="first"`,
+      );
+      linkHeader = links.join(", ");
+    }
+
+    // Add link_header to the first repository if pagination info exists
+    const responseRepos = [...paginatedRepos];
+    if (responseRepos.length > 0 && linkHeader) {
+      responseRepos[0] = { ...responseRepos[0], link_header: linkHeader };
+    }
+
+    // Return response as direct Repository array (matching real API)
+    return HttpResponse.json(responseRepos);
+  }),
+
+  http.get("*/api/user/search/repositories", async ({ request }) => {
+    await delay(300); // Simulate network delay
+
+    const url = new URL(request.url);
+    const query = url.searchParams.get("query") || "";
+    const selectedProvider = url.searchParams.get("selected_provider");
+    const perPage = parseInt(url.searchParams.get("per_page") || "5", 10);
+    const sort = url.searchParams.get("sort") || "stars";
+    const order = url.searchParams.get("order") || "desc";
+
+    // Simulate authentication error if no provider token
+    if (!selectedProvider) {
+      return HttpResponse.json("Git provider token required.", {
+        status: 401,
+      });
+    }
+
+    // Get repositories for the selected provider
+    const repositories =
+      MOCK_REPOSITORIES[selectedProvider as keyof typeof MOCK_REPOSITORIES] ||
+      [];
+
+    // Filter repositories by search query
+    const filteredRepos = repositories.filter((repo) =>
+      repo.full_name.toLowerCase().includes(query.toLowerCase()),
+    );
+
+    // Sort repositories
+    const sortedRepos = [...filteredRepos];
+    if (sort === "stars") {
+      sortedRepos.sort((a, b) => {
+        const aStars = a.stargazers_count || 0;
+        const bStars = b.stargazers_count || 0;
+        return order === "desc" ? bStars - aStars : aStars - bStars;
+      });
+    }
+
+    // Limit results
+    const limitedRepos = sortedRepos.slice(0, perPage);
+
+    return HttpResponse.json(limitedRepos);
+  }),
+
+  // Repository branches endpoint
+  http.get("*/api/user/repository/branches", async ({ request }) => {
+    await delay(300);
+
+    const url = new URL(request.url);
+    const repository = url.searchParams.get("repository");
+    const page = parseInt(url.searchParams.get("page") || "1", 10);
+    const perPage = parseInt(url.searchParams.get("per_page") || "30", 10);
+
+    if (!repository) {
+      return HttpResponse.json("Repository parameter is required", {
+        status: 400,
+      });
+    }
+
+    // Calculate pagination
+    const startIndex = (page - 1) * perPage;
+    const endIndex = startIndex + perPage;
+    const paginatedBranches = MOCK_BRANCHES.slice(startIndex, endIndex);
+    const hasNextPage = endIndex < MOCK_BRANCHES.length;
+
+    const response: PaginatedBranchesResponse = {
+      branches: paginatedBranches,
+      has_next_page: hasNextPage,
+      current_page: page,
+      per_page: perPage,
+      total_count: MOCK_BRANCHES.length,
+    };
+
+    return HttpResponse.json(response);
+  }),
+
+  // Search repository branches endpoint
+  http.get("*/api/user/search/branches", async ({ request }) => {
+    await delay(200);
+
+    const url = new URL(request.url);
+    const repository = url.searchParams.get("repository");
+    const query = url.searchParams.get("query") || "";
+    const perPage = parseInt(url.searchParams.get("per_page") || "30", 10);
+
+    if (!repository) {
+      return HttpResponse.json("Repository parameter is required", {
+        status: 400,
+      });
+    }
+
+    // Filter branches by search query
+    const filteredBranches = MOCK_BRANCHES.filter((branch) =>
+      branch.name.toLowerCase().includes(query.toLowerCase()),
+    );
+
+    // Limit results
+    const limitedBranches = filteredBranches.slice(0, perPage);
+
+    return HttpResponse.json(limitedBranches);
+  }),
+
+  http.get("*/api/git/changes", async () =>
+    HttpResponse.json(MOCK_GIT_CHANGES),
+  ),
+
+  http.get("*/api/git/diff", async () =>
+    HttpResponse.json({
+      original: 'def greet(name):\n    return f"Hello, {name}!"\n',
+      modified:
+        'def greet(name: str) -> str:\n    return f"Hello, {name}! Welcome."\n',
+    }),
+  ),
+];

src/mocks/handlers.ts

@@ -0,0 +1,60 @@
+import { FILE_SERVICE_HANDLERS } from "./file-service-handlers";
+import { SECRETS_HANDLERS } from "./secrets-handlers";
+import {
+  AGENT_PROFILES_HANDLERS,
+  resetMockAgentProfiles,
+  seedMockAgentProfiles,
+} from "./agent-profiles-handlers";
+import { GIT_REPOSITORY_HANDLERS } from "./git-repository-handlers";
+import {
+  SETTINGS_HANDLERS,
+  MOCK_DEFAULT_USER_SETTINGS,
+  resetTestHandlersMockSettings,
+} from "./settings-handlers";
+import { CONVERSATION_HANDLERS } from "./conversation-handlers";
+import { AUTH_HANDLERS } from "./auth-handlers";
+import { FEEDBACK_HANDLERS } from "./feedback-handlers";
+import { ANALYTICS_HANDLERS } from "./analytics-handlers";
+import {
+  AUTOMATION_HANDLERS,
+  resetAutomationMockData,
+} from "./automation-handlers";
+import { MCP_HANDLERS } from "./mcp-handlers";
+import {
+  WORKSPACES_HANDLERS,
+  resetMockWorkspaces,
+} from "./workspaces-handlers";
+import {
+  CANVAS_EXTENSIONS_HANDLERS,
+  resetCanvasExtensionsMockData,
+} from "./canvas-extensions-handlers";
+
+export const handlers = [
+  ...FILE_SERVICE_HANDLERS,
+  ...SECRETS_HANDLERS,
+  ...AGENT_PROFILES_HANDLERS,
+  ...GIT_REPOSITORY_HANDLERS,
+  ...SETTINGS_HANDLERS,
+  ...CONVERSATION_HANDLERS,
+  ...AUTH_HANDLERS,
+  ...FEEDBACK_HANDLERS,
+  ...ANALYTICS_HANDLERS,
+  ...AUTOMATION_HANDLERS,
+  ...MCP_HANDLERS,
+  ...WORKSPACES_HANDLERS,
+  ...CANVAS_EXTENSIONS_HANDLERS,
+];
+
+export {
+  MOCK_DEFAULT_USER_SETTINGS,
+  resetTestHandlersMockSettings,
+  resetAutomationMockData,
+  resetMockWorkspaces,
+  resetCanvasExtensionsMockData,
+};
+
+export {
+  AGENT_PROFILES_HANDLERS,
+  resetMockAgentProfiles,
+  seedMockAgentProfiles,
+};

src/mocks/node.ts

@@ -0,0 +1,4 @@
+import { setupServer } from "msw/node";
+import { handlers } from "./handlers";
+
+export const server = setupServer(...handlers);

src/mocks/secrets-handlers.ts

@@ -0,0 +1,94 @@
+import { http, HttpResponse } from "msw";
+
+/**
+ * In-memory secrets storage for mock agent-server API.
+ * Uses name as the key (agent-server uses name-based lookups, not IDs).
+ */
+const secrets = new Map<string, { value: string; description?: string }>([
+  ["OpenAI_API_Key", { value: "test-123", description: "OpenAI API Key" }],
+  [
+    "Google_Maps_API_Key",
+    { value: "test-123", description: "Google Maps API Key" },
+  ],
+]);
+
+/**
+ * Mock handlers for the agent-server secrets API.
+ * Routes: /api/settings/secrets and /api/settings/secrets/:name
+ *
+ * Uses wildcard "*" prefix to match both relative paths and absolute URLs
+ * (e.g., http://127.0.0.1:8000/api/...) since the code uses absolute URLs
+ * when VITE_BACKEND_BASE_URL is configured.
+ */
+export const SECRETS_HANDLERS = [
+  // GET /api/settings/secrets - List all secrets (names and descriptions only)
+  http.get("*/api/settings/secrets", async ({ request }) => {
+    // Exclude requests with a :name param (handled by the next handler)
+    const url = new URL(request.url);
+    const pathParts = url.pathname.split("/").filter(Boolean);
+    if (pathParts.length > 3) return undefined; // Let it pass through to :name handler
+
+    const secretsList = Array.from(secrets.entries()).map(
+      ([name, { description }]) => ({ name, description }),
+    );
+    return HttpResponse.json({ secrets: secretsList });
+  }),
+
+  // GET /api/settings/secrets/:name - Get secret value by name
+  http.get("*/api/settings/secrets/:name", async ({ params }) => {
+    const { name } = params;
+    if (typeof name !== "string") {
+      return HttpResponse.json({ detail: "Invalid name" }, { status: 400 });
+    }
+
+    const secret = secrets.get(name);
+    if (!secret) {
+      return HttpResponse.json({ detail: "Secret not found" }, { status: 404 });
+    }
+
+    return new HttpResponse(secret.value, {
+      headers: { "Content-Type": "text/plain" },
+    });
+  }),
+
+  // PUT /api/settings/secrets - Create or update a secret (upsert)
+  http.put("*/api/settings/secrets", async ({ request }) => {
+    const body = (await request.json()) as {
+      name: string;
+      value: string;
+      description?: string;
+    } | null;
+
+    if (!body?.name || !body?.value) {
+      return HttpResponse.json(
+        { detail: "name and value are required" },
+        { status: 400 },
+      );
+    }
+
+    secrets.set(body.name, {
+      value: body.value,
+      description: body.description,
+    });
+
+    return HttpResponse.json({
+      name: body.name,
+      description: body.description,
+    });
+  }),
+
+  // DELETE /api/settings/secrets/:name - Delete a secret by name
+  http.delete("*/api/settings/secrets/:name", async ({ params }) => {
+    const { name } = params;
+    if (typeof name !== "string") {
+      return HttpResponse.json({ detail: "Invalid name" }, { status: 400 });
+    }
+
+    const deleted = secrets.delete(name);
+    if (!deleted) {
+      return HttpResponse.json({ detail: "Secret not found" }, { status: 404 });
+    }
+
+    return HttpResponse.json({ deleted: true });
+  }),
+];

src/mocks/settings-handlers.ts

@@ -0,0 +1,1256 @@
+import { http, delay, HttpResponse } from "msw";
+import { WebClientConfig } from "#/api/option-service/option.types";
+import type { SaveProfileRequest } from "#/api/profiles-service/profiles-service.api";
+import { DEFAULT_SETTINGS } from "#/services/settings";
+import { Settings, SettingsValue } from "#/types/settings";
+import {
+  OPENAI_SUBSCRIPTION_DEVICE_POLL_PATH,
+  OPENAI_SUBSCRIPTION_DEVICE_START_PATH,
+  OPENAI_SUBSCRIPTION_LOGOUT_PATH,
+  OPENAI_SUBSCRIPTION_MODELS_PATH,
+  OPENAI_SUBSCRIPTION_STATUS_PATH,
+  OPENAI_SUBSCRIPTION_VENDOR,
+} from "#/constants/llm-subscription";
+
+/** Simple recursive merge — objects merge, scalars overwrite. */
+function deepMerge(
+  base: Record<string, unknown>,
+  patch: Record<string, unknown>,
+): Record<string, unknown> {
+  const result = { ...base };
+  for (const [key, value] of Object.entries(patch)) {
+    if (
+      value != null &&
+      typeof value === "object" &&
+      !Array.isArray(value) &&
+      typeof result[key] === "object" &&
+      result[key] != null &&
+      !Array.isArray(result[key])
+    ) {
+      result[key] = deepMerge(
+        result[key] as Record<string, unknown>,
+        value as Record<string, unknown>,
+      );
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+const DEFAULT_AGENT_SETTINGS = DEFAULT_SETTINGS.agent_settings ?? {};
+const llmDefaults = (DEFAULT_AGENT_SETTINGS as Record<string, unknown>).llm as
+  | Record<string, unknown>
+  | undefined;
+const DEFAULT_MODEL =
+  typeof llmDefaults?.model === "string"
+    ? llmDefaults.model
+    : "openhands/claude-opus-4-5-20251101";
+
+export const createMockWebClientConfig = (
+  overrides: Partial<WebClientConfig> = {},
+): WebClientConfig => ({
+  feature_flags: {
+    hide_llm_settings: false,
+    hide_users_page: false,
+    ...overrides.feature_flags,
+  },
+  providers_configured: [],
+  maintenance_start_time: null,
+  recaptcha_site_key: null,
+  faulty_models: [],
+  error_message: null,
+  updated_at: new Date().toISOString(),
+  ...overrides,
+});
+
+const MOCK_AGENT_SETTINGS_SCHEMA: NonNullable<
+  Settings["agent_settings_schema"]
+> = {
+  model_name: "AgentSettings",
+  sections: [
+    {
+      key: "general",
+      label: "General",
+      fields: [
+        {
+          key: "enable_sub_agents",
+          label: "Enable sub-agents",
+          description:
+            "Allow the agent to delegate work to specialized built-in sub-agents.",
+          section: "general",
+          section_label: "General",
+          value_type: "boolean",
+          default: false,
+          choices: [],
+          depends_on: [],
+          prominence: "major",
+          secret: false,
+          required: false,
+        },
+        {
+          key: "enable_switch_llm_tool",
+          label: "Enable LLM switching tool",
+          description:
+            "Allow the agent to move the conversation to another saved LLM profile on its own.",
+          section: "general",
+          section_label: "General",
+          value_type: "boolean",
+          default: true,
+          choices: [],
+          depends_on: [],
+          prominence: "major",
+          secret: false,
+          required: false,
+        },
+        {
+          key: "tool_concurrency_limit",
+          label: "Parallel tool calls",
+          description:
+            "Maximum number of tool calls to execute concurrently per agent step. 1 = sequential (default).",
+          section: "general",
+          section_label: "General",
+          value_type: "integer",
+          default: 1,
+          choices: [],
+          depends_on: [],
+          prominence: "major",
+          secret: false,
+          required: false,
+        },
+      ],
+    },
+    {
+      key: "llm",
+      label: "LLM",
+      fields: [
+        {
+          key: "llm.model",
+          label: "Model",
+          description: "Select the model to use for this conversation.",
+          section: "llm",
+          section_label: "LLM",
+          value_type: "string",
+          default: DEFAULT_MODEL,
+          choices: [],
+          depends_on: [],
+          prominence: "critical",
+          secret: false,
+          required: true,
+        },
+        {
+          key: "llm.api_key",
+          label: "API Key",
+          description:
+            "Provide the API key used to authenticate requests for the selected model.",
+
+          section: "llm",
+          section_label: "LLM",
+          value_type: "string",
+          default: null,
+          choices: [],
+          depends_on: [],
+          prominence: "critical",
+          secret: true,
+          required: false,
+        },
+        {
+          key: "llm.base_url",
+          description:
+            "Override the model provider's default API base URL when needed.",
+
+          label: "Base URL",
+          section: "llm",
+          section_label: "LLM",
+          value_type: "string",
+          default: null,
+          choices: [],
+          depends_on: [],
+          prominence: "critical",
+          secret: false,
+          required: false,
+        },
+        {
+          key: "llm.temperature",
+          label: "Temperature",
+          description: "Adjust randomness for non-deterministic model outputs.",
+          section: "llm",
+          section_label: "LLM",
+          value_type: "number",
+          default: null,
+          choices: [],
+          depends_on: [],
+          prominence: "minor",
+          secret: false,
+          required: false,
+        },
+      ],
+    },
+    {
+      key: "verification",
+      label: "Verification",
+      fields: [
+        {
+          key: "verification.critic_enabled",
+          label: "Enable Critic",
+          description:
+            "Enable an additional critic pass to review the agent's work.",
+          section: "verification",
+          section_label: "Verification",
+          value_type: "boolean",
+          default: false,
+          choices: [],
+          depends_on: [],
+          prominence: "critical",
+          secret: false,
+          required: false,
+        },
+        {
+          key: "verification.critic_mode",
+          label: "Critic Mode",
+          description: "Choose when the critic should review and intervene.",
+          section: "verification",
+          section_label: "Verification",
+          value_type: "string",
+          default: "finish_and_message",
+          choices: [
+            {
+              label: "finish_and_message",
+              value: "finish_and_message",
+            },
+            { label: "all_actions", value: "all_actions" },
+          ],
+          depends_on: ["verification.critic_enabled"],
+          prominence: "major",
+          secret: false,
+          required: false,
+        },
+        {
+          key: "verification.enable_iterative_refinement",
+          label: "Enable Iterative Refinement",
+          description:
+            "Let the critic send the agent back to refine its work when issues are found.",
+          section: "verification",
+          section_label: "Verification",
+          value_type: "boolean",
+          default: false,
+          choices: [],
+          depends_on: ["verification.critic_enabled"],
+          prominence: "critical",
+          secret: false,
+          required: false,
+        },
+        // Rendered as a full-width row (see FIELD_FULL_WIDTH_KEYS) below the
+        // two critical-prominence toggles so the input + OpenHands Cloud help
+        // link have room to breathe.
+        {
+          key: "verification.critic_api_key",
+          label: "Critic API Key",
+          description:
+            "If OpenHands is selected as your active LLM provider, leave this empty; the critic reuses the OpenHands Provider LLM Key.",
+          section: "verification",
+          section_label: "Verification",
+          value_type: "string",
+          default: null,
+          choices: [],
+          depends_on: ["verification.critic_enabled"],
+          prominence: "critical",
+          secret: true,
+          required: false,
+        },
+        {
+          key: "verification.critic_threshold",
+          label: "Critic Threshold",
+          description:
+            "Critic success threshold used for iterative refinement.",
+          section: "verification",
+          section_label: "Verification",
+          value_type: "number",
+          default: 0.6,
+          choices: [],
+          depends_on: [
+            "verification.critic_enabled",
+            "verification.enable_iterative_refinement",
+          ],
+          prominence: "minor",
+          secret: false,
+          required: false,
+        },
+        {
+          key: "verification.max_refinement_iterations",
+          label: "Max Refinement Iterations",
+          description:
+            "Maximum number of refinement attempts after critic feedback.",
+          section: "verification",
+          section_label: "Verification",
+          value_type: "integer",
+          default: 3,
+          choices: [],
+          depends_on: [
+            "verification.critic_enabled",
+            "verification.enable_iterative_refinement",
+          ],
+          prominence: "minor",
+          secret: false,
+          required: false,
+        },
+        {
+          key: "verification.critic_server_url",
+          label: "Critic Server URL",
+          description: "Override the critic service URL.",
+          section: "verification",
+          section_label: "Verification",
+          value_type: "string",
+          default: null,
+          choices: [],
+          depends_on: ["verification.critic_enabled"],
+          prominence: "minor",
+          secret: false,
+          required: false,
+        },
+        {
+          key: "verification.critic_model_name",
+          label: "Critic Model Name",
+          description: "Override the critic model name.",
+          section: "verification",
+          section_label: "Verification",
+          value_type: "string",
+          default: null,
+          choices: [],
+          depends_on: ["verification.critic_enabled"],
+          prominence: "minor",
+          secret: false,
+          required: false,
+        },
+      ],
+    },
+    {
+      key: "condenser",
+      label: "Condenser",
+      fields: [
+        {
+          description:
+            "Enable the default LLM-based condenser to summarize long conversation histories.",
+          key: "condenser.enable_default_condenser",
+          label: "Enable default condenser",
+          section: "condenser",
+          section_label: "Condenser",
+          value_type: "boolean",
+          default: true,
+          choices: [],
+          depends_on: [],
+          prominence: "critical",
+          secret: false,
+          required: true,
+        },
+        {
+          description:
+            "Maximum number of tokens the condenser keeps after summarization. Leave blank for unlimited.",
+          key: "condenser.condenser_max_size",
+          label: "Condenser max size",
+          section: "condenser",
+          section_label: "Condenser",
+          value_type: "integer",
+          default: null,
+          choices: [],
+          depends_on: [],
+          prominence: "major",
+          secret: false,
+          required: false,
+        },
+      ],
+    },
+    {
+      // Curated agent_context section (SDK fields_opt_in): only load_memory
+      // is exposed, never the raw AgentContext model. ``label`` mirrors the
+      // server's literal string ("Memory"); the GUI names the page itself via
+      // the SCHEMA$AGENT_CONTEXT$SECTION_LABEL translation, which wins.
+      key: "agent_context",
+      label: "Memory",
+      fields: [
+        {
+          description:
+            "The agent keeps notes under .openhands/memory/ and loads them at the start of each new conversation, learning your codebase and preferences over time.",
+          key: "agent_context.load_memory",
+          label: "Persistent memory",
+          section: "agent_context",
+          section_label: "Memory",
+          value_type: "boolean",
+          default: false,
+          choices: [],
+          depends_on: [],
+          prominence: "major",
+          secret: false,
+          required: false,
+        },
+      ],
+    },
+  ],
+};
+
+const MOCK_CONVERSATION_SETTINGS_SCHEMA: NonNullable<
+  Settings["conversation_settings_schema"]
+> = {
+  model_name: "ConversationSettings",
+  sections: [
+    {
+      key: "general",
+      label: "General",
+      fields: [
+        {
+          key: "max_iterations",
+          label: "Max iterations",
+          section: "general",
+          description:
+            "Maximum number of agent steps allowed before the conversation stops.",
+
+          section_label: "General",
+          value_type: "integer",
+          default: 500,
+          choices: [],
+          depends_on: [],
+          prominence: "major",
+          secret: false,
+          required: true,
+        },
+      ],
+    },
+    {
+      key: "verification",
+      label: "Verification",
+      fields: [
+        {
+          key: "confirmation_mode",
+          label: "Confirmation mode",
+          description:
+            "Pause for confirmation before the agent performs high-risk actions.",
+
+          section: "verification",
+          section_label: "Verification",
+          value_type: "boolean",
+          default: false,
+          choices: [],
+          depends_on: [],
+          prominence: "major",
+          secret: false,
+          required: true,
+        },
+        {
+          key: "security_analyzer",
+          label: "Security analyzer",
+          description:
+            "Choose how OpenHands should analyze actions before asking for confirmation.",
+
+          section: "verification",
+          section_label: "Verification",
+          value_type: "string",
+          default: "llm",
+          choices: [
+            { label: "llm", value: "llm" },
+            { label: "none", value: "none" },
+          ],
+          depends_on: ["confirmation_mode"],
+          prominence: "major",
+          secret: false,
+          required: false,
+        },
+      ],
+    },
+  ],
+};
+
+export const MOCK_DEFAULT_USER_SETTINGS: Settings = {
+  ...DEFAULT_SETTINGS,
+  provider_tokens_set: {},
+  agent_settings_schema: MOCK_AGENT_SETTINGS_SCHEMA,
+  agent_settings: {
+    ...DEFAULT_AGENT_SETTINGS,
+    verification: {
+      critic_enabled: false,
+      enable_iterative_refinement: false,
+    },
+    llm: {
+      ...(llmDefaults ?? {}),
+      api_key: null,
+      model: DEFAULT_MODEL,
+    },
+    condenser: {
+      enable_default_condenser: true,
+      condenser_max_size: null,
+    },
+    enable_sub_agents: false,
+    tool_concurrency_limit: 1,
+  },
+  conversation_settings_schema: MOCK_CONVERSATION_SETTINGS_SCHEMA,
+  conversation_settings: {
+    ...(DEFAULT_SETTINGS.conversation_settings ?? {}),
+  },
+};
+
+const MOCK_USER_PREFERENCES: {
+  settings: Settings | null;
+} = {
+  settings: structuredClone(MOCK_DEFAULT_USER_SETTINGS),
+};
+
+interface MockLlmProfile {
+  name: string;
+  config: Record<string, SettingsValue>;
+  api_key_set: boolean;
+}
+
+const MOCK_LLM_PROFILES: {
+  profiles: Map<string, MockLlmProfile>;
+  activeProfile: string | null;
+} = {
+  profiles: new Map(),
+  activeProfile: null,
+};
+
+let mockOpenAISubscriptionConnected = false;
+
+const getProfileNameParam = (value: unknown): string =>
+  decodeURIComponent(
+    Array.isArray(value) ? String(value[0] ?? "") : String(value ?? ""),
+  );
+
+const profileToListItem = (profile: MockLlmProfile) => ({
+  name: profile.name,
+  model: typeof profile.config.model === "string" ? profile.config.model : null,
+  base_url:
+    typeof profile.config.base_url === "string"
+      ? profile.config.base_url
+      : null,
+  api_key_set: profile.api_key_set,
+});
+
+const applyProfileToMockSettings = (profile: MockLlmProfile) => {
+  const current =
+    MOCK_USER_PREFERENCES.settings ||
+    structuredClone(MOCK_DEFAULT_USER_SETTINGS);
+
+  MOCK_USER_PREFERENCES.settings = {
+    ...current,
+    agent_settings: {
+      ...(current.agent_settings ?? {}),
+      llm: structuredClone(profile.config),
+    },
+    llm_api_key_set: profile.api_key_set,
+  };
+};
+
+const buildProfileDetail = (
+  profile: MockLlmProfile,
+  exposeSecrets: string | null,
+) => {
+  const config = structuredClone(profile.config);
+
+  if (profile.api_key_set && "api_key" in config) {
+    if (exposeSecrets === "encrypted") {
+      config.api_key = `gAAAAA_mock_encrypted_${profile.name}`;
+    } else if (exposeSecrets === "plaintext") {
+      // Keep the mock plaintext value.
+    } else {
+      config.api_key = null;
+    }
+  }
+
+  return {
+    name: profile.name,
+    config,
+    api_key_set: profile.api_key_set,
+  };
+};
+
+const saveMockProfile = (name: string, request: SaveProfileRequest) => {
+  const llm = structuredClone(
+    (request.llm ?? {}) as Record<string, SettingsValue>,
+  );
+
+  if (typeof llm.model !== "string" || llm.model.trim().length === 0) {
+    return null;
+  }
+
+  const profile: MockLlmProfile = {
+    name,
+    config: llm,
+    api_key_set:
+      typeof llm.api_key === "string" && llm.api_key.trim().length > 0,
+  };
+
+  MOCK_LLM_PROFILES.profiles.set(name, profile);
+
+  if (MOCK_LLM_PROFILES.activeProfile === name) {
+    applyProfileToMockSettings(profile);
+  }
+
+  return profile;
+};
+
+export const resetTestHandlersMockSettings = () => {
+  MOCK_USER_PREFERENCES.settings = structuredClone(MOCK_DEFAULT_USER_SETTINGS);
+  MOCK_LLM_PROFILES.profiles.clear();
+  MOCK_LLM_PROFILES.activeProfile = null;
+  mockOpenAISubscriptionConnected = false;
+};
+
+// Mock model data used by provider/model endpoints
+const MOCK_MODELS = [
+  "anthropic/claude-3.5",
+  "anthropic/claude-sonnet-4-20250514",
+  "anthropic/claude-sonnet-4-5-20250929",
+  "anthropic/claude-haiku-4-5-20251001",
+  "anthropic/claude-opus-4-5-20251101",
+  "anthropic/claude-opus-4-8",
+  "openai/gpt-3.5-turbo",
+  "openai/gpt-5.5",
+  "openai/gpt-4o",
+  "openai/gpt-4o-mini",
+  "openhands/claude-sonnet-4-20250514",
+  "openhands/claude-sonnet-4-5-20250929",
+  "openhands/claude-haiku-4-5-20251001",
+  "openhands/claude-opus-4-5-20251101",
+  "openai/gpt-5.6-sol",
+  "openai/gpt-6-astra",
+  "openhands/deepseek-v4-flash",
+  "openhands/glm-5.2",
+  "sambanova/Meta-Llama-3.1-8B-Instruct",
+];
+
+const MOCK_OPENAI_SUBSCRIPTION_MODELS = ["gpt-5.2", "gpt-5.3-codex"];
+
+const MOCK_VERIFIED_MODELS = new Set([
+  "anthropic/claude-opus-4-5-20251101",
+  "anthropic/claude-opus-4-8",
+  "anthropic/claude-sonnet-4-5-20250929",
+  "openai/gpt-5.5",
+  "openhands/claude-opus-4-5-20251101",
+  "openhands/claude-sonnet-4-5-20250929",
+  "openai/gpt-5.6-sol",
+  "openai/gpt-6-astra",
+  "openhands/deepseek-v4-flash",
+  "openhands/glm-5.2",
+]);
+
+// DB-driven free / default flags for the OpenHands provider. Mirrors the
+// enterprise verified-models seed used to render the "Free" badge and preselect
+// the default model.
+const MOCK_FREE_MODELS = new Set(["openhands/glm-5.2"]);
+const MOCK_DEFAULT_MODEL = "openhands/glm-5.2";
+
+const MOCK_VERIFIED_PROVIDERS = [
+  "openhands",
+  "anthropic",
+  "openai",
+  "mistral",
+  "gemini",
+  "deepseek",
+  "moonshot",
+  "minimax",
+];
+
+const MOCK_MODEL_PROVIDERS = Array.from(
+  new Set(
+    MOCK_MODELS.map((model) => model.split("/")[0]).filter(
+      (provider): provider is string => Boolean(provider),
+    ),
+  ),
+);
+
+const MOCK_VERIFIED_MODELS_BY_PROVIDER = MOCK_MODELS.reduce<
+  Record<string, string[]>
+>((acc, model) => {
+  if (!MOCK_VERIFIED_MODELS.has(model)) return acc;
+
+  const [provider, ...rest] = model.split("/");
+  if (!provider || rest.length === 0) return acc;
+
+  acc[provider] ??= [];
+  acc[provider].push(rest.join("/"));
+  return acc;
+}, {});
+
+// Matches the pinned `@openhands/typescript-client`, so mock mode models a
+// server that actually ships this schema. At 1.29.3 the mocked settings schema
+// advertised fields (`enable_switch_llm_tool`) that the mocked server's own
+// profile model would have rejected, and version-gated UI hid controls the
+// rest of the mocks were serving.
+const MOCK_AGENT_SERVER_VERSION = "1.36.1";
+
+// --- Handlers for options/config/settings ---
+// Uses wildcard "*" prefix to match both relative paths and absolute URLs
+// (e.g., http://127.0.0.1:8000/api/...) since the code uses absolute URLs
+// when VITE_BACKEND_BASE_URL is configured.
+
+export const SETTINGS_HANDLERS = [
+  http.get("*/server_info", async () =>
+    HttpResponse.json({
+      uptime: 0,
+      idle_time: 0,
+      version: MOCK_AGENT_SERVER_VERSION,
+      usable_tools: [
+        "terminal",
+        "file_editor",
+        "task_tracker",
+        "browser_tool_set",
+      ],
+      agents: ["CodeActAgent"],
+      default_agent: "CodeActAgent",
+      models: MOCK_MODELS,
+      security_analyzers: ["llm", "none"],
+    }),
+  ),
+
+  http.get("*/api/llm/models", async () =>
+    HttpResponse.json({ models: MOCK_MODELS }),
+  ),
+
+  http.get("*/api/llm/models/verified", async () =>
+    HttpResponse.json({ models: MOCK_VERIFIED_MODELS_BY_PROVIDER }),
+  ),
+
+  http.get("*/api/llm/providers", async () =>
+    HttpResponse.json({ providers: MOCK_MODEL_PROVIDERS }),
+  ),
+
+  http.get(`*${OPENAI_SUBSCRIPTION_MODELS_PATH}`, async () =>
+    HttpResponse.json({
+      vendor: OPENAI_SUBSCRIPTION_VENDOR,
+      models: MOCK_OPENAI_SUBSCRIPTION_MODELS,
+    }),
+  ),
+
+  http.get(`*${OPENAI_SUBSCRIPTION_STATUS_PATH}`, async () =>
+    HttpResponse.json({
+      connected: mockOpenAISubscriptionConnected,
+      account_email: mockOpenAISubscriptionConnected
+        ? "mock-chatgpt@example.com"
+        : null,
+      expires_at: null,
+    }),
+  ),
+
+  http.post(`*${OPENAI_SUBSCRIPTION_DEVICE_START_PATH}`, async () =>
+    HttpResponse.json({
+      device_code: "mock-device-code",
+      user_code: "MOCK-CODE",
+      verification_uri: "https://auth.openai.com/activate",
+      verification_uri_complete:
+        "https://auth.openai.com/activate?user_code=MOCK-CODE",
+      interval: 1,
+      expires_in: 900,
+    }),
+  ),
+
+  http.post(`*${OPENAI_SUBSCRIPTION_DEVICE_POLL_PATH}`, async () => {
+    mockOpenAISubscriptionConnected = true;
+    return HttpResponse.json({
+      connected: true,
+      account_email: "mock-chatgpt@example.com",
+      expires_at: null,
+    });
+  }),
+
+  http.post(`*${OPENAI_SUBSCRIPTION_LOGOUT_PATH}`, async () => {
+    mockOpenAISubscriptionConnected = false;
+    return HttpResponse.json({ connected: false });
+  }),
+
+  // V0 (legacy) models endpoint – still used for default_model
+  http.get("*/api/options/models", async () =>
+    HttpResponse.json({
+      models: MOCK_MODELS,
+      verified_models: [
+        "claude-opus-4-5-20251101",
+        "claude-sonnet-4-5-20250929",
+      ],
+      verified_providers: MOCK_VERIFIED_PROVIDERS,
+      default_model: "openai/gpt-5.6-sol",
+    }),
+  ),
+
+  // V1 providers search
+  http.get("*/api/v1/config/providers/search", async ({ request }) => {
+    const url = new URL(request.url);
+    const query = url.searchParams.get("query")?.toLowerCase();
+    const verifiedEq = url.searchParams.get("verified__eq");
+
+    // Build unique provider list from models
+    const seen = new Set<string>();
+    let providers: { name: string; verified: boolean }[] = [];
+    for (const model of MOCK_MODELS) {
+      const [providerName] = model.split("/");
+      if (providerName && !seen.has(providerName)) {
+        seen.add(providerName);
+        providers.push({
+          name: providerName,
+          verified: MOCK_VERIFIED_PROVIDERS.includes(providerName),
+        });
+      }
+    }
+
+    if (query) {
+      providers = providers.filter((p) => p.name.toLowerCase().includes(query));
+    }
+    if (verifiedEq !== null && verifiedEq !== undefined) {
+      const wantVerified = verifiedEq === "true";
+      providers = providers.filter((p) => p.verified === wantVerified);
+    }
+
+    return HttpResponse.json({ items: providers, next_page_id: null });
+  }),
+
+  // V1 models search
+  http.get("*/api/v1/config/models/search", async ({ request }) => {
+    const url = new URL(request.url);
+    const query = url.searchParams.get("query")?.toLowerCase();
+    const verifiedEq = url.searchParams.get("verified__eq");
+    const providerEq = url.searchParams.get("provider__eq");
+
+    let models = MOCK_MODELS.map((m) => {
+      const [provider, ...rest] = m.split("/");
+      const name = rest.join("/");
+      return {
+        provider: provider || null,
+        name,
+        verified: MOCK_VERIFIED_MODELS.has(m),
+        free: MOCK_FREE_MODELS.has(m),
+        default: m === MOCK_DEFAULT_MODEL,
+      };
+    });
+
+    if (providerEq) {
+      models = models.filter((m) => m.provider === providerEq);
+    }
+    if (query) {
+      models = models.filter((m) => m.name.toLowerCase().includes(query));
+    }
+    if (verifiedEq !== null && verifiedEq !== undefined) {
+      const wantVerified = verifiedEq === "true";
+      models = models.filter((m) => m.verified === wantVerified);
+    }
+
+    return HttpResponse.json({ items: models, next_page_id: null });
+  }),
+
+  http.get("*/api/options/security-analyzers", async () =>
+    HttpResponse.json(["llm", "none"]),
+  ),
+
+  http.get("*/api/profiles", async () =>
+    HttpResponse.json({
+      profiles: Array.from(MOCK_LLM_PROFILES.profiles.values()).map(
+        profileToListItem,
+      ),
+      active_profile: MOCK_LLM_PROFILES.activeProfile,
+    }),
+  ),
+
+  http.get("*/api/profiles/:name", async ({ params, request }) => {
+    const name = getProfileNameParam(params.name);
+    const profile = MOCK_LLM_PROFILES.profiles.get(name);
+
+    if (!profile) {
+      return HttpResponse.json(
+        { detail: `Profile '${name}' not found` },
+        { status: 404 },
+      );
+    }
+
+    return HttpResponse.json(
+      buildProfileDetail(profile, request.headers.get("X-Expose-Secrets")),
+    );
+  }),
+
+  http.post("*/api/profiles/:name", async ({ params, request }) => {
+    const name = getProfileNameParam(params.name);
+    const body = (await request.json()) as SaveProfileRequest | null;
+
+    if (!body) {
+      return HttpResponse.json({ detail: "Empty body" }, { status: 400 });
+    }
+
+    const profile = saveMockProfile(name, body);
+    if (!profile) {
+      return HttpResponse.json(
+        { detail: "Profile requires llm.model" },
+        { status: 400 },
+      );
+    }
+
+    return HttpResponse.json(
+      { name: profile.name, message: `Profile '${profile.name}' saved` },
+      { status: 201 },
+    );
+  }),
+
+  http.delete("*/api/profiles/:name", async ({ params }) => {
+    const name = getProfileNameParam(params.name);
+    MOCK_LLM_PROFILES.profiles.delete(name);
+
+    if (MOCK_LLM_PROFILES.activeProfile === name) {
+      MOCK_LLM_PROFILES.activeProfile = null;
+    }
+
+    return HttpResponse.json({
+      name,
+      message: `Profile '${name}' deleted`,
+    });
+  }),
+
+  http.post("*/api/profiles/:name/rename", async ({ params, request }) => {
+    const name = getProfileNameParam(params.name);
+    const body = (await request.json()) as { new_name?: string } | null;
+    const newName = body?.new_name?.trim() ?? "";
+    const profile = MOCK_LLM_PROFILES.profiles.get(name);
+
+    if (!profile) {
+      return HttpResponse.json(
+        { detail: `Profile '${name}' not found` },
+        { status: 404 },
+      );
+    }
+
+    if (!newName) {
+      return HttpResponse.json(
+        { detail: "new_name is required" },
+        { status: 400 },
+      );
+    }
+
+    if (newName !== name && MOCK_LLM_PROFILES.profiles.has(newName)) {
+      return HttpResponse.json(
+        { detail: `Profile '${newName}' already exists` },
+        { status: 409 },
+      );
+    }
+
+    MOCK_LLM_PROFILES.profiles.delete(name);
+    const renamedProfile = { ...profile, name: newName };
+    MOCK_LLM_PROFILES.profiles.set(newName, renamedProfile);
+
+    if (MOCK_LLM_PROFILES.activeProfile === name) {
+      MOCK_LLM_PROFILES.activeProfile = newName;
+      applyProfileToMockSettings(renamedProfile);
+    }
+
+    return HttpResponse.json({
+      name: newName,
+      message: `Profile '${name}' renamed to '${newName}'`,
+    });
+  }),
+
+  http.post("*/api/profiles/:name/activate", async ({ params }) => {
+    const name = getProfileNameParam(params.name);
+    const profile = MOCK_LLM_PROFILES.profiles.get(name);
+
+    if (!profile) {
+      return HttpResponse.json(
+        { detail: `Profile '${name}' not found` },
+        { status: 404 },
+      );
+    }
+
+    MOCK_LLM_PROFILES.activeProfile = name;
+    applyProfileToMockSettings(profile);
+
+    return HttpResponse.json({
+      name,
+      message: `Profile '${name}' activated and applied to current settings`,
+      llm_applied: true,
+    });
+  }),
+
+  http.get("*/api/v1/web-client/config", () => {
+    const config: WebClientConfig = {
+      feature_flags: {
+        hide_llm_settings: false,
+        hide_users_page: false,
+      },
+      providers_configured: [],
+      maintenance_start_time: null,
+      recaptcha_site_key: null,
+      faulty_models: [],
+      error_message: null,
+      updated_at: new Date().toISOString(),
+    };
+
+    return HttpResponse.json(config);
+  }),
+
+  http.get("*/api/settings/conversation-schema", async () => {
+    await delay();
+    return HttpResponse.json(MOCK_CONVERSATION_SETTINGS_SCHEMA);
+  }),
+
+  http.get("*/api/v1/settings/conversation-schema", async () => {
+    await delay();
+    return HttpResponse.json(MOCK_CONVERSATION_SETTINGS_SCHEMA);
+  }),
+
+  http.get("*/api/v1/settings", async () => {
+    await delay();
+    const { settings } = MOCK_USER_PREFERENCES;
+
+    if (!settings) return HttpResponse.json(null, { status: 404 });
+
+    return HttpResponse.json(settings);
+  }),
+
+  // New settings API endpoints (GET /api/settings with X-Expose-Secrets header support)
+  http.get("*/api/settings", async ({ request }) => {
+    // Exclude sub-paths like /api/settings/agent-schema (handled by separate handlers)
+    const url = new URL(request.url);
+    const pathParts = url.pathname.split("/").filter(Boolean);
+    if (pathParts.length > 2) return undefined;
+
+    await delay();
+    const { settings } = MOCK_USER_PREFERENCES;
+
+    const DEFAULT_APP_PREFERENCES = {
+      language: null,
+      user_consents_to_analytics: null,
+      enable_sound_notifications: null,
+      git_user_name: null,
+      git_user_email: null,
+      title_llm_profile: null,
+      disabled_skills: [],
+    };
+
+    if (!settings) {
+      return HttpResponse.json({
+        agent_settings: {},
+        conversation_settings: {},
+        llm_api_key_is_set: false,
+        misc_settings: { app_preferences: DEFAULT_APP_PREFERENCES },
+      });
+    }
+
+    const exposeSecrets = request.headers.get("X-Expose-Secrets");
+
+    // Build agent_settings, handling secrets based on header
+    const agentSettings = structuredClone(
+      settings.agent_settings ?? {},
+    ) as Record<string, unknown>;
+    const llm = agentSettings.llm as Record<string, unknown> | undefined;
+    if (llm?.api_key) {
+      if (exposeSecrets === "encrypted") {
+        // Return a mock "encrypted" value
+        llm.api_key = `gAAAAA_mock_encrypted_${String(llm.api_key).slice(0, 8)}`;
+      } else if (exposeSecrets === "plaintext") {
+        // Keep as-is (plaintext)
+      } else {
+        // Redact
+        llm.api_key = "**********";
+      }
+    }
+
+    const llmApiKeySet =
+      !!settings.llm_api_key_set ||
+      (!!(settings.agent_settings as Record<string, unknown> | undefined)
+        ?.llm &&
+        !!(
+          (settings.agent_settings as Record<string, unknown>).llm as Record<
+            string,
+            unknown
+          >
+        )?.api_key);
+
+    // Reuse the persisted misc_settings.app_preferences for repeat fetches,
+    // but always fall back to the default-empty block so the GUI sees a
+    // deterministic shape on first read.
+    const storedMisc = (settings as Record<string, unknown>).misc_settings as
+      | { app_preferences?: Record<string, unknown> }
+      | undefined;
+    const appPreferences = {
+      ...DEFAULT_APP_PREFERENCES,
+      ...(storedMisc?.app_preferences ?? {}),
+    };
+
+    return HttpResponse.json({
+      agent_settings: agentSettings,
+      conversation_settings: settings.conversation_settings ?? {},
+      llm_api_key_is_set: llmApiKeySet,
+      misc_settings: { app_preferences: appPreferences },
+    });
+  }),
+
+  // PATCH /api/settings - incremental updates
+  http.patch("*/api/settings", async ({ request }) => {
+    await delay();
+    const body = (await request.json()) as {
+      agent_settings_diff?: Record<string, unknown>;
+      conversation_settings_diff?: Record<string, SettingsValue>;
+      misc_settings_diff?: {
+        app_preferences?: Record<string, unknown>;
+      };
+    } | null;
+
+    if (!body) {
+      return HttpResponse.json({ error: "Empty body" }, { status: 400 });
+    }
+
+    if (
+      !body.agent_settings_diff &&
+      !body.conversation_settings_diff &&
+      !body.misc_settings_diff
+    ) {
+      return HttpResponse.json(
+        {
+          error:
+            "At least one of agent_settings_diff, conversation_settings_diff, or misc_settings_diff must be provided",
+        },
+        { status: 400 },
+      );
+    }
+
+    const current =
+      MOCK_USER_PREFERENCES.settings ||
+      structuredClone(MOCK_DEFAULT_USER_SETTINGS);
+    const nextSettings: Settings = { ...current };
+
+    if (body.agent_settings_diff) {
+      const merged = deepMerge(
+        (current.agent_settings ?? {}) as Record<string, unknown>,
+        body.agent_settings_diff,
+      );
+      nextSettings.agent_settings = merged as Settings["agent_settings"];
+
+      // Sync llm_api_key_set
+      const llm = merged.llm as Record<string, unknown> | undefined;
+      if (
+        llm?.api_key &&
+        typeof llm.api_key === "string" &&
+        llm.api_key.trim().length > 0
+      ) {
+        nextSettings.llm_api_key_set = true;
+      }
+    }
+
+    if (body.conversation_settings_diff) {
+      nextSettings.conversation_settings = {
+        ...(current.conversation_settings ?? {}),
+        ...body.conversation_settings_diff,
+      };
+    }
+
+    if (body.misc_settings_diff) {
+      const existingMisc = (current as Record<string, unknown>)
+        .misc_settings as
+        | { app_preferences?: Record<string, unknown> }
+        | undefined;
+      // Deep-merge: nested `app_preferences` overlays field-by-field;
+      // `disabled_skills` lists are replaced wholesale. This mirrors the
+      // SDK's `_deep_merge` behaviour for the two-level shape currently
+      // stored in `misc_settings`.
+      const nextMisc: { app_preferences?: Record<string, unknown> } = {
+        ...(existingMisc ?? {}),
+      };
+      if (body.misc_settings_diff.app_preferences) {
+        nextMisc.app_preferences = {
+          ...(existingMisc?.app_preferences ?? {}),
+          ...body.misc_settings_diff.app_preferences,
+        };
+      }
+      (nextSettings as Record<string, unknown>).misc_settings = nextMisc;
+    }
+
+    MOCK_USER_PREFERENCES.settings = nextSettings;
+
+    // Return the updated settings (without secrets exposed)
+    return HttpResponse.json({
+      agent_settings: nextSettings.agent_settings ?? {},
+      conversation_settings: nextSettings.conversation_settings ?? {},
+      llm_api_key_is_set: nextSettings.llm_api_key_set ?? false,
+      misc_settings: ((nextSettings as Record<string, unknown>)
+        .misc_settings as
+        | { app_preferences?: Record<string, unknown> }
+        | undefined) ?? { app_preferences: {} },
+    });
+  }),
+
+  http.post("*/api/mcp/test", async () => {
+    await delay();
+    return HttpResponse.json({ ok: true, tools: ["mock_tool"] });
+  }),
+
+  http.get("*/api/settings/agent-schema", async () => {
+    await delay();
+    return HttpResponse.json(MOCK_AGENT_SETTINGS_SCHEMA);
+  }),
+
+  http.get("*/api/v1/settings/agent-schema", async () => {
+    await delay();
+    return HttpResponse.json(MOCK_AGENT_SETTINGS_SCHEMA);
+  }),
+
+  http.post("*/api/v1/settings", async ({ request }) => {
+    await delay();
+    const body = (await request.json()) as Record<string, unknown> | null;
+
+    if (body) {
+      const current =
+        MOCK_USER_PREFERENCES.settings ||
+        structuredClone(MOCK_DEFAULT_USER_SETTINGS);
+
+      if ("agent_settings" in body || "conversation_settings" in body) {
+        return HttpResponse.json(
+          {
+            error: "Use *_diff nested settings payloads",
+            keys: ["agent_settings", "conversation_settings"].filter(
+              (key) => key in body,
+            ),
+          },
+          { status: 422 },
+        );
+      }
+
+      const nextSettings: Settings = { ...current };
+
+      const agentSettingsPatch = body.agent_settings_diff as
+        | Record<string, unknown>
+        | undefined;
+      if (agentSettingsPatch) {
+        const merged = deepMerge(
+          (current.agent_settings ?? {}) as Record<string, unknown>,
+          agentSettingsPatch,
+        );
+        nextSettings.agent_settings = merged as Settings["agent_settings"];
+      }
+
+      const conversationSettingsPatch = body.conversation_settings_diff as
+        | Record<string, SettingsValue>
+        | undefined;
+      if (conversationSettingsPatch) {
+        nextSettings.conversation_settings = {
+          ...(current.conversation_settings ?? {}),
+          ...conversationSettingsPatch,
+        };
+      }
+
+      // Apply top-level fields (excluding nested settings)
+      for (const [key, value] of Object.entries(body)) {
+        if (
+          key !== "agent_settings_diff" &&
+          key !== "conversation_settings_diff" &&
+          key !== "agent_settings_schema" &&
+          key !== "conversation_settings_schema"
+        ) {
+          (nextSettings as Record<string, unknown>)[key] = value;
+        }
+      }
+
+      MOCK_USER_PREFERENCES.settings = nextSettings;
+      return HttpResponse.json(null, { status: 200 });
+    }
+
+    return HttpResponse.json(null, { status: 400 });
+  }),
+
+  // POST /api/mcp/test – MCP server connectivity check before install.
+  // Returns ok:true so the install modal can proceed to save and close.
+  http.post("*/api/mcp/test", async () => {
+    await delay();
+    return HttpResponse.json({ ok: true, tools: [] });
+  }),
+];

src/mocks/should-start-mock-worker.ts

@@ -0,0 +1,9 @@
+export function shouldStartMockWorker({
+  mockApi = import.meta.env.VITE_MOCK_API,
+  hasWindow = typeof window !== "undefined",
+}: {
+  mockApi?: string;
+  hasWindow?: boolean;
+} = {}): boolean {
+  return hasWindow && mockApi === "true";
+}

src/mocks/workspaces-handlers.ts

@@ -0,0 +1,105 @@
+import { http, HttpResponse } from "msw";
+import type {
+  WorkspaceItem,
+  WorkspaceParentItem,
+  WorkspacesListResponse,
+} from "@openhands/typescript-client/clients";
+
+/**
+ * MSW handlers for the agent-server's `/api/workspaces` and
+ * `/api/auth/workspace-session` endpoints used by `useLocalWorkspaces`,
+ * `WorkspacesService`, and `useWorkspaceSession`.
+ *
+ * Without these handlers, mock-mode renders of the home / sidebar /
+ * conversation pages let those requests fall through to the Vite proxy
+ * (`127.0.0.1:8000` ECONNREFUSED), which spams logs and surfaces
+ * global error toasts in mock-mode screens.
+ *
+ * The mock keeps an in-memory list so the install / remove flow round-trips
+ * cleanly within a single page load. State resets on every test reload.
+ */
+
+let workspaces: WorkspaceItem[] = [];
+let workspaceParents: WorkspaceParentItem[] = [];
+
+function snapshot(): WorkspacesListResponse {
+  return {
+    workspaces: workspaces.map((w) => ({ ...w })),
+    workspaceParents: workspaceParents.map((p) => ({ ...p })),
+  };
+}
+
+export function resetMockWorkspaces(): void {
+  workspaces = [];
+  workspaceParents = [];
+}
+
+export const WORKSPACES_HANDLERS = [
+  http.get("*/api/workspaces", async () => HttpResponse.json(snapshot())),
+
+  http.post("*/api/workspaces", async ({ request }) => {
+    // `workspaces` is the top-level key used by WorkspacesClient.addWorkspaces()
+    // in @openhands/typescript-client — aligns with the agent-server SDK contract.
+    const body = (await request.json()) as { workspaces?: WorkspaceItem[] };
+    for (const incoming of body.workspaces ?? []) {
+      const existingIndex = workspaces.findIndex(
+        (w) => w.path === incoming.path,
+      );
+      if (existingIndex >= 0) {
+        workspaces[existingIndex] = { ...incoming };
+      } else {
+        workspaces.push({ ...incoming });
+      }
+    }
+    return HttpResponse.json(snapshot());
+  }),
+
+  http.delete("*/api/workspaces", async ({ request }) => {
+    const url = new URL(request.url);
+    const path = url.searchParams.get("path");
+    const before = workspaces.length;
+    workspaces = workspaces.filter((w) => w.path !== path);
+    // WorkspacesService.removeWorkspace() discards the response body (returns
+    // void), so the shape here is mock-only and not coupled to the real contract.
+    return HttpResponse.json({ deleted: workspaces.length !== before });
+  }),
+
+  http.post("*/api/workspaces/parents", async ({ request }) => {
+    const body = (await request.json()) as { parents?: WorkspaceParentItem[] };
+    for (const incoming of body.parents ?? []) {
+      const existingIndex = workspaceParents.findIndex(
+        (p) => p.path === incoming.path,
+      );
+      if (existingIndex >= 0) {
+        workspaceParents[existingIndex] = { ...incoming };
+      } else {
+        workspaceParents.push({ ...incoming });
+      }
+    }
+    return HttpResponse.json(snapshot());
+  }),
+
+  http.delete("*/api/workspaces/parents", async ({ request }) => {
+    const url = new URL(request.url);
+    const path = url.searchParams.get("path");
+    const before = workspaceParents.length;
+    workspaceParents = workspaceParents.filter((p) => p.path !== path);
+    // WorkspacesService.removeWorkspaceParent() discards the response body
+    // (returns void), so the shape here is mock-only and not coupled to the
+    // real contract.
+    return HttpResponse.json({ deleted: workspaceParents.length !== before });
+  }),
+
+  // Workspace static-asset session: minted on conversation pages by
+  // `useWorkspaceSession`. The real endpoint sets an HttpOnly cookie; in
+  // mock mode we just acknowledge the POST/DELETE so the call doesn't fall
+  // through to the Vite proxy.
+  http.post("*/api/auth/workspace-session", async () =>
+    HttpResponse.json({ ok: true }),
+  ),
+
+  http.delete(
+    "*/api/auth/workspace-session",
+    async () => new HttpResponse(null, { status: 204 }),
+  ),
+];

src/stores/agent-store.ts

@@ -0,0 +1,21 @@
+import { create } from "zustand";
+import { AgentState } from "#/types/agent-state";
+
+interface AgentStateData {
+  curAgentState: AgentState;
+}
+
+interface AgentStore extends AgentStateData {
+  setCurrentAgentState: (state: AgentState) => void;
+  reset: () => void;
+}
+
+const initialState: AgentStateData = {
+  curAgentState: AgentState.LOADING,
+};
+
+export const useAgentStore = create<AgentStore>((set) => ({
+  ...initialState,
+  setCurrentAgentState: (state: AgentState) => set({ curAgentState: state }),
+  reset: () => set(initialState),
+}));

src/stores/archived-conversations-store.ts

@@ -0,0 +1,84 @@
+import { create } from "zustand";
+import { persist, createJSONStorage } from "zustand/middleware";
+
+export const ARCHIVED_CONVERSATIONS_STORAGE_KEY = "archived-conversations";
+
+interface ArchivedConversationsState {
+  archivesByBackendId: Record<string, string[]>;
+}
+
+interface ArchivedConversationsActions {
+  archiveConversation: (backendId: string, conversationId: string) => void;
+  removeArchivedConversation: (
+    backendId: string,
+    conversationId: string,
+  ) => void;
+  isArchived: (backendId: string, conversationId: string) => boolean;
+}
+
+type ArchivedConversationsStore = ArchivedConversationsState &
+  ArchivedConversationsActions;
+
+const initialState: ArchivedConversationsState = {
+  archivesByBackendId: {},
+};
+
+function getArchivesForBackend(
+  archivesByBackendId: Record<string, string[]>,
+  backendId: string,
+): string[] {
+  return archivesByBackendId[backendId] ?? [];
+}
+
+export const useArchivedConversationsStore =
+  create<ArchivedConversationsStore>()(
+    persist(
+      (set, get) => ({
+        ...initialState,
+
+        archiveConversation: (backendId, conversationId) => {
+          const current = getArchivesForBackend(
+            get().archivesByBackendId,
+            backendId,
+          );
+          if (current.includes(conversationId)) {
+            return;
+          }
+          set((state) => ({
+            archivesByBackendId: {
+              ...state.archivesByBackendId,
+              [backendId]: [conversationId, ...current],
+            },
+          }));
+        },
+
+        removeArchivedConversation: (backendId, conversationId) => {
+          const current = getArchivesForBackend(
+            get().archivesByBackendId,
+            backendId,
+          );
+          if (!current.includes(conversationId)) {
+            return;
+          }
+          set((state) => ({
+            archivesByBackendId: {
+              ...state.archivesByBackendId,
+              [backendId]: current.filter((id) => id !== conversationId),
+            },
+          }));
+        },
+
+        isArchived: (backendId, conversationId) =>
+          getArchivesForBackend(get().archivesByBackendId, backendId).includes(
+            conversationId,
+          ),
+      }),
+      {
+        name: ARCHIVED_CONVERSATIONS_STORAGE_KEY,
+        storage: createJSONStorage(() => localStorage),
+        partialize: (state): ArchivedConversationsState => ({
+          archivesByBackendId: state.archivesByBackendId,
+        }),
+      },
+    ),
+  );

src/stores/browser-store.ts

@@ -0,0 +1,26 @@
+import { create } from "zustand";
+
+interface BrowserState {
+  // URL of the last page the agent navigated to in the browser panel.
+  url: string;
+  // Base64-encoded screenshot of the browser window, when the tool provides one.
+  screenshotSrc: string;
+}
+
+interface BrowserStore extends BrowserState {
+  setUrl: (url: string) => void;
+  setScreenshotSrc: (screenshotSrc: string) => void;
+  reset: () => void;
+}
+
+const initialState: BrowserState = {
+  url: "",
+  screenshotSrc: "",
+};
+
+export const useBrowserStore = create<BrowserStore>((set) => ({
+  ...initialState,
+  setUrl: (url: string) => set({ url }),
+  setScreenshotSrc: (screenshotSrc: string) => set({ screenshotSrc }),
+  reset: () => set(initialState),
+}));

src/stores/btw-store.ts

@@ -0,0 +1,81 @@
+import { create } from "zustand";
+import { devtools } from "zustand/middleware";
+import { v4 as uuidv4 } from "uuid";
+
+export type BtwStatus = "pending" | "done" | "error";
+
+export interface BtwEntry {
+  id: string;
+  question: string;
+  response?: string;
+  status: BtwStatus;
+}
+
+interface BtwState {
+  entriesByConversation: Record<string, BtwEntry[]>;
+}
+
+interface BtwActions {
+  addPending: (conversationId: string, question: string) => string;
+  resolve: (conversationId: string, id: string, response: string) => void;
+  fail: (conversationId: string, id: string, error: string) => void;
+  dismiss: (conversationId: string, id: string) => void;
+}
+
+type BtwStore = BtwState & BtwActions;
+
+const initialState: BtwState = { entriesByConversation: {} };
+
+const updateEntries = (
+  state: BtwState,
+  conversationId: string,
+  updater: (entries: BtwEntry[]) => BtwEntry[],
+): Pick<BtwState, "entriesByConversation"> => ({
+  entriesByConversation: {
+    ...state.entriesByConversation,
+    [conversationId]: updater(
+      state.entriesByConversation[conversationId] ?? [],
+    ),
+  },
+});
+
+export const useBtwStore = create<BtwStore>()(
+  devtools(
+    (set) => ({
+      ...initialState,
+      addPending: (conversationId, question) => {
+        const id = uuidv4();
+        set((s) =>
+          updateEntries(s, conversationId, (entries) => [
+            ...entries,
+            { id, question, status: "pending" },
+          ]),
+        );
+        return id;
+      },
+      resolve: (conversationId, id, response) =>
+        set((s) =>
+          updateEntries(s, conversationId, (entries) =>
+            entries.map((e) =>
+              e.id === id ? { ...e, response, status: "done" } : e,
+            ),
+          ),
+        ),
+      fail: (conversationId, id, error) =>
+        set((s) =>
+          updateEntries(s, conversationId, (entries) =>
+            entries.map((e) =>
+              e.id === id ? { ...e, response: error, status: "error" } : e,
+            ),
+          ),
+        ),
+      dismiss: (conversationId, id) =>
+        set((s) =>
+          updateEntries(s, conversationId, (entries) =>
+            entries.filter((e) => e.id !== id),
+          ),
+        ),
+    }),
+    { name: "BtwStore" },
+  ),
+);

src/stores/command-menu-store.ts

@@ -0,0 +1,15 @@
+import { create } from "zustand";
+
+interface CommandMenuState {
+  isOpen: boolean;
+  open: () => void;
+  close: () => void;
+  toggle: () => void;
+}
+
+export const useCommandMenuStore = create<CommandMenuState>((set) => ({
+  isOpen: false,
+  open: () => set({ isOpen: true }),
+  close: () => set({ isOpen: false }),
+  toggle: () => set((state) => ({ isOpen: !state.isOpen })),
+}));

src/stores/command-store.ts

@@ -0,0 +1,26 @@
+import { create } from "zustand";
+
+export type Command = {
+  content: string;
+  type: "input" | "output";
+};
+
+interface CommandState {
+  commands: Command[];
+  appendInput: (content: string) => void;
+  appendOutput: (content: string) => void;
+  clearTerminal: () => void;
+}
+
+export const useCommandStore = create<CommandState>((set) => ({
+  commands: [],
+  appendInput: (content: string) =>
+    set((state) => ({
+      commands: [...state.commands, { content, type: "input" }],
+    })),
+  appendOutput: (content: string) =>
+    set((state) => ({
+      commands: [...state.commands, { content, type: "output" }],
+    })),
+  clearTerminal: () => set({ commands: [] }),
+}));

src/stores/conversation-panel-preferences-store.ts

@@ -0,0 +1,241 @@
+import { create } from "zustand";
+import { persist, createJSONStorage } from "zustand/middleware";
+import {
+  DEFAULT_OLDER_CONVERSATION_CUTOFF,
+  isOlderConversationCutoff,
+  type AutomationFilterMode,
+  type ConversationSortField,
+  type OlderConversationCutoff,
+  type OrganizeMode,
+  type ThreadScope,
+} from "#/components/features/conversation-panel/conversation-panel-list-helpers";
+
+/**
+ * User-toggleable display preferences for the sidebar conversation list
+ * (the layouts menu and the advanced-options modal behind it). These are
+ * intentionally persisted to localStorage (via the same `zustand/persist`
+ * pattern used by `home-store` and `workspaces-store`) so the menu state
+ * survives full reloads.
+ *
+ * Every persisted narrowing field must have a control that can see and undo
+ * it, or a reload silently hides conversations with nothing on screen to say
+ * why — see `ConversationActiveTagFilters`.
+ *
+ * To add a new preference exposed by those menus:
+ *   1. Add a field here with a sensible default in `initialState`.
+ *   2. Add matching `setX`/`toggleX` actions below.
+ *   3. Read/write through the store in `conversation-panel.tsx`.
+ * No additional plumbing (storage keys, sanitization, etc.) is required —
+ * `persist` handles migration of unknown fields gracefully.
+ */
+interface ConversationPanelPreferencesState {
+  showOlderConversations: boolean;
+  /**
+   * Age threshold used when `showOlderConversations` is false. Conversations
+   * last updated before this interval are hidden.
+   */
+  olderConversationCutoff: OlderConversationCutoff;
+  showArchivedConversations: boolean;
+  showRepoBranchMetadata: boolean;
+  showLlmProfiles: boolean;
+  showTagsMetadata: boolean;
+  showHoverMetadata: boolean;
+  organizeMode: OrganizeMode;
+  conversationSort: ConversationSortField;
+  threadScope: ThreadScope;
+  automationFilterMode: AutomationFilterMode;
+  selectedAutomationNames: string[];
+  selectedTagFacets: string[];
+  groupFolderOrder: string[];
+}
+
+/** The complete preference bundle controlled by conversation layout presets. */
+export type LayoutSettingsSlice = Pick<
+  ConversationPanelPreferencesState,
+  | "organizeMode"
+  | "conversationSort"
+  | "threadScope"
+  | "showOlderConversations"
+  | "showRepoBranchMetadata"
+  | "showLlmProfiles"
+  | "showTagsMetadata"
+  | "showHoverMetadata"
+>;
+
+export const DEFAULT_LAYOUT_SETTINGS: LayoutSettingsSlice = {
+  organizeMode: "chronological",
+  conversationSort: "updated",
+  threadScope: "all",
+  showOlderConversations: true,
+  showRepoBranchMetadata: false,
+  showLlmProfiles: false,
+  showTagsMetadata: true,
+  showHoverMetadata: true,
+};
+
+interface ConversationPanelPreferencesActions {
+  setShowOlderConversations: (value: boolean) => void;
+  toggleShowOlderConversations: () => void;
+  setOlderConversationCutoff: (value: OlderConversationCutoff) => void;
+  setShowArchivedConversations: (value: boolean) => void;
+  toggleShowArchivedConversations: () => void;
+  setShowRepoBranchMetadata: (value: boolean) => void;
+  toggleShowRepoBranchMetadata: () => void;
+  setShowLlmProfiles: (value: boolean) => void;
+  toggleShowLlmProfiles: () => void;
+  setShowTagsMetadata: (value: boolean) => void;
+  toggleShowTagsMetadata: () => void;
+  setShowHoverMetadata: (value: boolean) => void;
+  toggleShowHoverMetadata: () => void;
+  setOrganizeMode: (value: OrganizeMode) => void;
+  setConversationSort: (value: ConversationSortField) => void;
+  setThreadScope: (value: ThreadScope) => void;
+  setAutomationFilterMode: (value: AutomationFilterMode) => void;
+  toggleAutomationName: (name: string) => void;
+  /**
+   * Clears both facet selections (tags and automation names) — the two
+   * narrowings the active-filter strip renders as chips.
+   *
+   * Deliberately leaves `automationFilterMode` alone: the strip shows no chip
+   * for the mode, and it must not silently switch a surface it doesn't show.
+   * The mode keeps its own rows in the advanced-options modal.
+   */
+  clearFilterSelections: () => void;
+  toggleTagFacet: (facet: string) => void;
+  /** Applies a layout preset's partial bundle in one set(). */
+  applyLayoutSettings: (settings: Partial<LayoutSettingsSlice>) => void;
+  setGroupFolderOrder: (order: readonly string[]) => void;
+}
+
+type ConversationPanelPreferencesStore = ConversationPanelPreferencesState &
+  ConversationPanelPreferencesActions;
+
+const initialState: ConversationPanelPreferencesState = {
+  ...DEFAULT_LAYOUT_SETTINGS,
+  olderConversationCutoff: DEFAULT_OLDER_CONVERSATION_CUTOFF,
+  showArchivedConversations: false,
+  automationFilterMode: "all",
+  selectedAutomationNames: [],
+  selectedTagFacets: [],
+  groupFolderOrder: [],
+};
+
+export const useConversationPanelPreferencesStore =
+  create<ConversationPanelPreferencesStore>()(
+    persist(
+      (set) => ({
+        ...initialState,
+
+        setShowOlderConversations: (value) =>
+          set(() => ({ showOlderConversations: value })),
+        toggleShowOlderConversations: () =>
+          set((state) => ({
+            showOlderConversations: !state.showOlderConversations,
+          })),
+        setOlderConversationCutoff: (value) =>
+          set(() => ({
+            olderConversationCutoff: isOlderConversationCutoff(value)
+              ? value
+              : DEFAULT_OLDER_CONVERSATION_CUTOFF,
+          })),
+
+        setShowArchivedConversations: (value) =>
+          set(() => ({ showArchivedConversations: value })),
+        toggleShowArchivedConversations: () =>
+          set((state) => ({
+            showArchivedConversations: !state.showArchivedConversations,
+          })),
+
+        setShowRepoBranchMetadata: (value) =>
+          set(() => ({ showRepoBranchMetadata: value })),
+        toggleShowRepoBranchMetadata: () =>
+          set((state) => ({
+            showRepoBranchMetadata: !state.showRepoBranchMetadata,
+          })),
+
+        setShowLlmProfiles: (value) => set(() => ({ showLlmProfiles: value })),
+        toggleShowLlmProfiles: () =>
+          set((state) => ({
+            showLlmProfiles: !state.showLlmProfiles,
+          })),
+
+        setShowTagsMetadata: (value) =>
+          set(() => ({ showTagsMetadata: value })),
+        toggleShowTagsMetadata: () =>
+          set((state) => ({
+            showTagsMetadata: !state.showTagsMetadata,
+          })),
+
+        setShowHoverMetadata: (value) =>
+          set(() => ({ showHoverMetadata: value })),
+        toggleShowHoverMetadata: () =>
+          set((state) => ({
+            showHoverMetadata: !state.showHoverMetadata,
+          })),
+
+        setOrganizeMode: (value) => set(() => ({ organizeMode: value })),
+        setConversationSort: (value) =>
+          set(() => ({ conversationSort: value })),
+        setThreadScope: (value) => set(() => ({ threadScope: value })),
+        setAutomationFilterMode: (value) =>
+          set((state) => ({
+            automationFilterMode: value,
+            // Name selections only make sense in only-automations mode;
+            // leaving the mode clears them (self-healing — a stale selection
+            // must never silently narrow an unfiltered-looking list).
+            selectedAutomationNames:
+              value === "only-automations" ? state.selectedAutomationNames : [],
+          })),
+        toggleAutomationName: (name) =>
+          set((state) => ({
+            selectedAutomationNames: state.selectedAutomationNames.includes(
+              name,
+            )
+              ? state.selectedAutomationNames.filter(
+                  (existing) => existing !== name,
+                )
+              : [...state.selectedAutomationNames, name],
+          })),
+        clearFilterSelections: () =>
+          set(() => ({
+            selectedTagFacets: [],
+            selectedAutomationNames: [],
+          })),
+        toggleTagFacet: (facet) =>
+          set((state) => ({
+            selectedTagFacets: state.selectedTagFacets.includes(facet)
+              ? state.selectedTagFacets.filter((existing) => existing !== facet)
+              : [...state.selectedTagFacets, facet],
+          })),
+        setGroupFolderOrder: (order) =>
+          set(() => ({ groupFolderOrder: [...order] })),
+
+        applyLayoutSettings: (settings) => set(() => ({ ...settings })),
+      }),
+      {
+        name: "conversation-panel-preferences",
+        storage: createJSONStorage(() => localStorage),
+        // Only persist the data fields — actions are recreated on each load.
+        partialize: (state): ConversationPanelPreferencesState => ({
+          showOlderConversations: state.showOlderConversations,
+          olderConversationCutoff: isOlderConversationCutoff(
+            state.olderConversationCutoff,
+          )
+            ? state.olderConversationCutoff
+            : DEFAULT_OLDER_CONVERSATION_CUTOFF,
+          showArchivedConversations: state.showArchivedConversations,
+          showRepoBranchMetadata: state.showRepoBranchMetadata,
+          showLlmProfiles: state.showLlmProfiles,
+          showTagsMetadata: state.showTagsMetadata,
+          showHoverMetadata: state.showHoverMetadata,
+          organizeMode: state.organizeMode,
+          conversationSort: state.conversationSort,
+          threadScope: state.threadScope,
+          automationFilterMode: state.automationFilterMode,
+          selectedAutomationNames: state.selectedAutomationNames,
+          selectedTagFacets: state.selectedTagFacets,
+          groupFolderOrder: state.groupFolderOrder,
+        }),
+      },
+    ),
+  );

src/stores/conversation-state-store.ts

@@ -0,0 +1,41 @@
+import { create } from "zustand";
+import { ExecutionStatus } from "#/types/agent-server/core/base/common";
+
+interface ConversationStateStore {
+  /**
+   * Latest execution status per conversation, fed by the main and planning
+   * WebSocket handlers. Scoped by conversation id so the planning helper
+   * conversation's own run/idle transitions can never overwrite the main
+   * conversation's status (or vice versa) — see conversation-websocket-context.tsx.
+   */
+  executionStatusByConversation: Record<string, ExecutionStatus>;
+
+  /**
+   * Set the agent status for a specific conversation.
+   */
+  setExecutionStatus: (
+    conversationId: string,
+    execution_status: ExecutionStatus,
+  ) => void;
+
+  /**
+   * Reset the store to initial state
+   */
+  reset: () => void;
+}
+
+export const useConversationStateStore = create<ConversationStateStore>(
+  (set) => ({
+    executionStatusByConversation: {},
+
+    setExecutionStatus: (conversationId, execution_status) =>
+      set((state) => ({
+        executionStatusByConversation: {
+          ...state.executionStatusByConversation,
+          [conversationId]: execution_status,
+        },
+      })),
+
+    reset: () => set({ executionStatusByConversation: {} }),
+  }),
+);

src/stores/conversation-store.ts

@@ -0,0 +1,396 @@
+import { create } from "zustand";
+import { devtools } from "zustand/middleware";
+import {
+  getConversationState,
+  setConversationState,
+} from "#/utils/conversation-local-storage";
+
+export type ConversationTab =
+  | "files"
+  | "commits"
+  | "browser"
+  | "terminal"
+  | "planner"
+  | "tasklist"
+  | "usage";
+
+export type ConversationMode = "code" | "plan";
+
+export type CommitsPaneSection = "uncommitted";
+
+export interface IMessageToSend {
+  text: string;
+  timestamp: number;
+}
+
+interface ConversationState {
+  isRightPanelShown: boolean;
+  isOverviewPanelShown: boolean;
+  isOverviewPanelPeeked: boolean;
+  selectedTab: ConversationTab | null;
+  commitsAutoExpandSection: CommitsPaneSection | null;
+  images: File[];
+  files: File[];
+  /** Image file names (e.g. pasted screenshots) to send via file upload instead of vision embed. */
+  imagesMarkedUploadAsFile: string[];
+  /** Image file names attached in chat (controls per-image upload-as-file UI). */
+  pastedImageNames: string[];
+  loadingFiles: string[]; // File names currently being processed
+  loadingImages: string[]; // Image names currently being processed
+  messageToSend: IMessageToSend | null;
+  /** One-shot restore request consumed by the chat input when empty. */
+  messageRestoreIfEmpty: IMessageToSend | null;
+  shouldShownAgentLoading: boolean;
+  submittedMessage: string | null;
+  shouldHideSuggestions: boolean; // New state to hide suggestions when input expands
+  hasRightPanelToggled: boolean;
+  planContent: string | null;
+  conversationMode: ConversationMode;
+  subConversationTaskId: string | null; // Task ID for cloud sub-conversation creation
+  localPlanningConversationId: string | null;
+}
+
+interface ConversationActions {
+  setIsRightPanelShown: (isRightPanelShown: boolean) => void;
+  setIsOverviewPanelShown: (isOverviewPanelShown: boolean) => void;
+  setIsOverviewPanelPeeked: (isOverviewPanelPeeked: boolean) => void;
+  setSelectedTab: (selectedTab: ConversationTab | null) => void;
+  setCommitsAutoExpandSection: (
+    commitsAutoExpandSection: CommitsPaneSection | null,
+  ) => void;
+  setShouldShownAgentLoading: (shouldShownAgentLoading: boolean) => void;
+  setShouldHideSuggestions: (shouldHideSuggestions: boolean) => void;
+  addImages: (images: File[]) => void;
+  addFiles: (files: File[]) => void;
+  toggleImageUploadAsFile: (fileName: string) => void;
+  markImagesAsPasted: (fileNames: string[]) => void;
+  removeImage: (index: number) => void;
+  removeFile: (index: number) => void;
+  clearImages: () => void;
+  clearFiles: () => void;
+  clearAllFiles: () => void;
+  addFileLoading: (fileName: string) => void;
+  removeFileLoading: (fileName: string) => void;
+  addImageLoading: (imageName: string) => void;
+  removeImageLoading: (imageName: string) => void;
+  clearAllLoading: () => void;
+  setMessageToSend: (text: string) => void;
+  clearMessageToSend: () => void;
+  restoreMessageToInputIfEmpty: (text: string) => void;
+  clearMessageRestoreIfEmpty: () => void;
+  setSubmittedMessage: (message: string | null) => void;
+  resetConversationState: () => void;
+  setHasRightPanelToggled: (hasRightPanelToggled: boolean) => void;
+  setConversationMode: (conversationMode: ConversationMode) => void;
+  setSubConversationTaskId: (taskId: string | null) => void;
+  setLocalPlanningConversationId: (conversationId: string | null) => void;
+  setPlanContent: (planContent: string | null) => void;
+}
+
+type ConversationStore = ConversationState & ConversationActions;
+
+const getConversationIdFromLocation = (): string | null => {
+  if (typeof window === "undefined") {
+    return null;
+  }
+
+  const match = window.location.pathname.match(/\/conversations\/([^/]+)/);
+  return match ? match[1] : null;
+};
+
+const getInitialConversationMode = (): ConversationMode => {
+  if (typeof window === "undefined") {
+    return "code";
+  }
+
+  const conversationId = getConversationIdFromLocation();
+  if (!conversationId) {
+    return "code";
+  }
+
+  const state = getConversationState(conversationId);
+  return state.conversationMode;
+};
+
+export const useConversationStore = create<ConversationStore>()(
+  devtools(
+    (set) => ({
+      // Initial state.
+      //
+      // The right-side drawer (`isRightPanelShown` / `hasRightPanelToggled`)
+      // is intentionally *session-only* state: it always starts closed on
+      // app load (or on opening a fresh/existing conversation after a
+      // restart), but it survives in-app navigation because the Zustand
+      // store stays alive across React Router transitions. Persisting the
+      // open/closed state in localStorage made the panel feel sticky in
+      // a way users didn't expect — they want a clean, focused chat view
+      // when they come back to the app and only want the panel back when
+      // they themselves opened it during the current session.
+      isRightPanelShown: false,
+      isOverviewPanelShown: false,
+      isOverviewPanelPeeked: false,
+      selectedTab: "files" as ConversationTab,
+      commitsAutoExpandSection: null,
+      images: [],
+      files: [],
+      imagesMarkedUploadAsFile: [],
+      pastedImageNames: [],
+      loadingFiles: [],
+      loadingImages: [],
+      messageToSend: null,
+      messageRestoreIfEmpty: null,
+      shouldShownAgentLoading: false,
+      submittedMessage: null,
+      shouldHideSuggestions: false,
+      hasRightPanelToggled: false,
+      planContent: null,
+      conversationMode: getInitialConversationMode(),
+      subConversationTaskId: null,
+      localPlanningConversationId: null,
+
+      // Actions
+      setIsRightPanelShown: (isRightPanelShown) =>
+        set({ isRightPanelShown }, false, "setIsRightPanelShown"),
+
+      setIsOverviewPanelShown: (isOverviewPanelShown) =>
+        set(
+          { isOverviewPanelShown, isOverviewPanelPeeked: false },
+          false,
+          "setIsOverviewPanelShown",
+        ),
+
+      setIsOverviewPanelPeeked: (isOverviewPanelPeeked) =>
+        set({ isOverviewPanelPeeked }, false, "setIsOverviewPanelPeeked"),
+
+      setSelectedTab: (selectedTab) =>
+        set({ selectedTab }, false, "setSelectedTab"),
+
+      setCommitsAutoExpandSection: (commitsAutoExpandSection) =>
+        set({ commitsAutoExpandSection }, false, "setCommitsAutoExpandSection"),
+
+      setShouldShownAgentLoading: (shouldShownAgentLoading) =>
+        set({ shouldShownAgentLoading }, false, "setShouldShownAgentLoading"),
+
+      setShouldHideSuggestions: (shouldHideSuggestions) =>
+        set({ shouldHideSuggestions }, false, "setShouldHideSuggestions"),
+
+      addImages: (images) =>
+        set(
+          (state) => ({ images: [...state.images, ...images] }),
+          false,
+          "addImages",
+        ),
+
+      addFiles: (files) =>
+        set(
+          (state) => ({ files: [...state.files, ...files] }),
+          false,
+          "addFiles",
+        ),
+
+      toggleImageUploadAsFile: (fileName) =>
+        set(
+          (state) => {
+            const marked = new Set(state.imagesMarkedUploadAsFile);
+            if (marked.has(fileName)) {
+              marked.delete(fileName);
+            } else {
+              marked.add(fileName);
+            }
+            return { imagesMarkedUploadAsFile: [...marked] };
+          },
+          false,
+          "toggleImageUploadAsFile",
+        ),
+
+      markImagesAsPasted: (fileNames) =>
+        set(
+          (state) => {
+            const merged = new Set([...state.pastedImageNames, ...fileNames]);
+            return { pastedImageNames: [...merged] };
+          },
+          false,
+          "markImagesAsPasted",
+        ),
+
+      removeImage: (index) =>
+        set(
+          (state) => {
+            const removed = state.images[index];
+            const newImages = [...state.images];
+            newImages.splice(index, 1);
+            return {
+              images: newImages,
+              imagesMarkedUploadAsFile: removed
+                ? state.imagesMarkedUploadAsFile.filter(
+                    (name) => name !== removed.name,
+                  )
+                : state.imagesMarkedUploadAsFile,
+              pastedImageNames: removed
+                ? state.pastedImageNames.filter((name) => name !== removed.name)
+                : state.pastedImageNames,
+            };
+          },
+          false,
+          "removeImage",
+        ),
+
+      removeFile: (index) =>
+        set(
+          (state) => {
+            const newFiles = [...state.files];
+            newFiles.splice(index, 1);
+            return { files: newFiles };
+          },
+          false,
+          "removeFile",
+        ),
+
+      clearImages: () => set({ images: [] }, false, "clearImages"),
+
+      clearFiles: () => set({ files: [] }, false, "clearFiles"),
+
+      clearAllFiles: () =>
+        set(
+          {
+            images: [],
+            files: [],
+            imagesMarkedUploadAsFile: [],
+            pastedImageNames: [],
+            loadingFiles: [],
+            loadingImages: [],
+          },
+          false,
+          "clearAllFiles",
+        ),
+
+      addFileLoading: (fileName) =>
+        set(
+          (state) => {
+            if (!state.loadingFiles.includes(fileName)) {
+              return { loadingFiles: [...state.loadingFiles, fileName] };
+            }
+            return state;
+          },
+          false,
+          "addFileLoading",
+        ),
+
+      removeFileLoading: (fileName) =>
+        set(
+          (state) => ({
+            loadingFiles: state.loadingFiles.filter(
+              (name) => name !== fileName,
+            ),
+          }),
+          false,
+          "removeFileLoading",
+        ),
+
+      addImageLoading: (imageName) =>
+        set(
+          (state) => {
+            if (!state.loadingImages.includes(imageName)) {
+              return { loadingImages: [...state.loadingImages, imageName] };
+            }
+            return state;
+          },
+          false,
+          "addImageLoading",
+        ),
+
+      removeImageLoading: (imageName) =>
+        set(
+          (state) => ({
+            loadingImages: state.loadingImages.filter(
+              (name) => name !== imageName,
+            ),
+          }),
+          false,
+          "removeImageLoading",
+        ),
+
+      clearAllLoading: () =>
+        set({ loadingFiles: [], loadingImages: [] }, false, "clearAllLoading"),
+
+      setMessageToSend: (text) =>
+        set(
+          {
+            messageToSend: {
+              text,
+              timestamp: Date.now(),
+            },
+          },
+          false,
+          "setMessageToSend",
+        ),
+
+      // One-shot consume: clear after the composer applies it, so a never-sent
+      // value can't replay into another conversation's composer on remount.
+      clearMessageToSend: () =>
+        set({ messageToSend: null }, false, "clearMessageToSend"),
+
+      restoreMessageToInputIfEmpty: (text) =>
+        set(
+          {
+            messageRestoreIfEmpty: {
+              text,
+              timestamp: Date.now(),
+            },
+          },
+          false,
+          "restoreMessageToInputIfEmpty",
+        ),
+
+      clearMessageRestoreIfEmpty: () =>
+        set(
+          { messageRestoreIfEmpty: null },
+          false,
+          "clearMessageRestoreIfEmpty",
+        ),
+
+      setSubmittedMessage: (submittedMessage) =>
+        set({ submittedMessage }, false, "setSubmittedMessage"),
+
+      resetConversationState: () =>
+        set(
+          {
+            shouldHideSuggestions: false,
+            conversationMode: getInitialConversationMode(),
+            subConversationTaskId: null,
+            localPlanningConversationId: null,
+            planContent: null,
+          },
+          false,
+          "resetConversationState",
+        ),
+
+      setHasRightPanelToggled: (hasRightPanelToggled) =>
+        set({ hasRightPanelToggled }, false, "setHasRightPanelToggled"),
+
+      setConversationMode: (conversationMode) => {
+        const conversationId = getConversationIdFromLocation();
+        if (conversationId) {
+          setConversationState(conversationId, { conversationMode });
+        }
+        set({ conversationMode }, false, "setConversationMode");
+      },
+
+      setSubConversationTaskId: (subConversationTaskId) =>
+        set({ subConversationTaskId }, false, "setSubConversationTaskId"),
+
+      setLocalPlanningConversationId: (localPlanningConversationId) =>
+        set(
+          { localPlanningConversationId },
+          false,
+          "setLocalPlanningConversationId",
+        ),
+
+      setPlanContent: (planContent) =>
+        set({ planContent }, false, "setPlanContent"),
+    }),
+    {
+      name: "conversation-store",
+    },
+  ),
+);

src/stores/error-message-store.ts

@@ -0,0 +1,66 @@
+import { create } from "zustand";
+import type { ErrorClassification } from "@openhands/typescript-client";
+
+/**
+ * "connection" errors auto-clear once connectivity recovers; "conversation"
+ * errors (e.g. a wrong API key) are sticky and clear only on an explicit user
+ * action (dismiss, retry, new message).
+ */
+export type ErrorMessageType = "connection" | "conversation";
+
+interface ErrorMessageState {
+  errorMessage: string | null;
+  errorType: ErrorMessageType | null;
+  /**
+   * Structured error code from a ConversationErrorEvent/ServerErrorEvent (e.g.
+   * "ACPAuthRequired"), used to render a code-specific header + recovery action.
+   * null for errors that carry no code (connection errors, plain strings).
+   */
+  errorCode: string | null;
+  errorClassification: ErrorClassification | null;
+}
+
+interface ErrorMessageActions {
+  setErrorMessage: (
+    message: string,
+    type?: ErrorMessageType,
+    code?: string | null,
+    classification?: ErrorClassification | null,
+  ) => void;
+  removeErrorMessage: () => void;
+  /** Clears the error only when it is a transient connection error. */
+  clearConnectionError: () => void;
+}
+
+type ErrorMessageStore = ErrorMessageState & ErrorMessageActions;
+
+const initialState: ErrorMessageState = {
+  errorMessage: null,
+  errorType: null,
+  errorCode: null,
+  errorClassification: null,
+};
+
+export const useErrorMessageStore = create<ErrorMessageStore>((set) => ({
+  ...initialState,
+
+  setErrorMessage: (
+    message: string,
+    type: ErrorMessageType = "conversation",
+    code: string | null = null,
+    classification: ErrorClassification | null = null,
+  ) =>
+    set(() => ({
+      errorMessage: message,
+      errorType: type,
+      errorCode: code,
+      errorClassification: classification,
+    })),
+
+  removeErrorMessage: () => set(() => ({ ...initialState })),
+
+  clearConnectionError: () =>
+    set((state) =>
+      state.errorType === "connection" ? { ...initialState } : state,
+    ),
+}));

src/stores/event-message-store.ts

@@ -0,0 +1,26 @@
+import { create } from "zustand";
+
+type SubmittedEventId = string | number;
+
+interface EventMessageState {
+  submittedEventIds: SubmittedEventId[];
+}
+
+interface EventMessageStore extends EventMessageState {
+  addSubmittedEventId: (id: SubmittedEventId) => void;
+  removeSubmittedEventId: (id: SubmittedEventId) => void;
+}
+
+export const useEventMessageStore = create<EventMessageStore>((set) => ({
+  submittedEventIds: [],
+  addSubmittedEventId: (id) =>
+    set((state) => ({
+      submittedEventIds: [...state.submittedEventIds, id],
+    })),
+  removeSubmittedEventId: (id) =>
+    set((state) => ({
+      submittedEventIds: state.submittedEventIds.filter(
+        (eventId) => eventId !== id,
+      ),
+    })),
+}));

src/stores/files-tab-store.ts

@@ -0,0 +1,140 @@
+import { create } from "zustand";
+import { setConversationState } from "#/utils/conversation-local-storage";
+
+interface FilesTabState {
+  selectedPath: string | null;
+  // The conversation a selection belongs to. A file picked in one
+  // conversation must not leak into another (it usually doesn't exist in the
+  // other conversation's workspace, see issue #1350), so every selection is
+  // tagged with its conversation and the files tab ignores a path owned by a
+  // different conversation.
+  selectedConversationId: string | null;
+  /**
+   * Ordered list of files the user or agent has opened in the current
+   * conversation. The quick-row tab strip renders only these paths.
+   */
+  openPaths: string[];
+  setSelectedPath: (
+    path: string | null,
+    conversationId?: string | null,
+  ) => void;
+  /** Remove a path from the open-tab strip; selects a neighbor when needed. */
+  closeOpenPath: (path: string) => void;
+  /**
+   * Replace in-memory open-tab state for a conversation (used when mounting
+   * / switching conversations so a refresh can restore localStorage).
+   * Does not write back to localStorage.
+   */
+  hydrateForConversation: (
+    conversationId: string,
+    openPaths: string[],
+    selectedPath: string | null,
+  ) => void;
+}
+
+function withOpenedPath(
+  openPaths: string[],
+  path: string,
+  sameConversation: boolean,
+): string[] {
+  if (!sameConversation) return [path];
+  if (openPaths.includes(path)) return openPaths;
+  return [...openPaths, path];
+}
+
+function selectNeighborAfterClose(
+  openPaths: string[],
+  closedPath: string,
+  selectedPath: string | null,
+): string | null {
+  if (selectedPath !== closedPath) return selectedPath;
+  const closedIndex = openPaths.indexOf(closedPath);
+  const remaining = openPaths.filter((path) => path !== closedPath);
+  if (remaining.length === 0) return null;
+  // Prefer the tab that slides into the closed slot (right neighbor), else left.
+  return remaining[Math.min(closedIndex, remaining.length - 1)] ?? null;
+}
+
+function resolveSelectedPath(
+  openPaths: string[],
+  selectedPath: string | null,
+): string | null {
+  if (selectedPath && openPaths.includes(selectedPath)) return selectedPath;
+  return null;
+}
+
+function persistOpenState(
+  conversationId: string | null | undefined,
+  openPaths: string[],
+  selectedPath: string | null,
+) {
+  if (!conversationId) return;
+  setConversationState(conversationId, {
+    filesTabOpenPaths: openPaths,
+    filesTabSelectedPath: selectedPath,
+  });
+}
+
+// Hoisted out of files-tab.tsx local state so non-React callers (e.g. the
+// canvas_ui tool dispatcher in the WebSocket context) can drive selection.
+export const useFilesTabStore = create<FilesTabState>((set) => ({
+  selectedPath: null,
+  selectedConversationId: null,
+  openPaths: [],
+  setSelectedPath: (selectedPath, conversationId = null) =>
+    set((state) => {
+      if (selectedPath === null) {
+        const switchedConversation =
+          conversationId !== state.selectedConversationId;
+        const next = {
+          selectedPath: null as string | null,
+          selectedConversationId: conversationId,
+          // Drop open tabs when the active conversation changes so paths
+          // from conversation A never appear as tabs in conversation B.
+          // Callers that switch conversations should prefer
+          // `hydrateForConversation` so persisted tabs can be restored.
+          openPaths: switchedConversation ? [] : state.openPaths,
+        };
+        persistOpenState(conversationId, next.openPaths, next.selectedPath);
+        return next;
+      }
+
+      const sameConversation = state.selectedConversationId === conversationId;
+      const next = {
+        selectedPath,
+        selectedConversationId: conversationId,
+        openPaths: withOpenedPath(
+          state.openPaths,
+          selectedPath,
+          sameConversation,
+        ),
+      };
+      persistOpenState(conversationId, next.openPaths, next.selectedPath);
+      return next;
+    }),
+  closeOpenPath: (path) =>
+    set((state) => {
+      if (!state.openPaths.includes(path)) return state;
+      const selectedPath = selectNeighborAfterClose(
+        state.openPaths,
+        path,
+        state.selectedPath,
+      );
+      const next = {
+        openPaths: state.openPaths.filter((openPath) => openPath !== path),
+        selectedPath,
+      };
+      persistOpenState(
+        state.selectedConversationId,
+        next.openPaths,
+        next.selectedPath,
+      );
+      return next;
+    }),
+  hydrateForConversation: (conversationId, openPaths, selectedPath) =>
+    set({
+      selectedConversationId: conversationId,
+      openPaths,
+      selectedPath: resolveSelectedPath(openPaths, selectedPath),
+    }),
+}));

src/stores/free-models-store.ts

@@ -0,0 +1,53 @@
+import { create } from "zustand";
+import type { FreeModelSet } from "#/utils/format-model-name";
+
+interface FreeModelsState {
+  /**
+   * DB-driven set of free ``provider/model`` ids (the same channel that carries
+   * `verified`). Empty on backends without free metadata (e.g. the local
+   * agent-server), so consumers uniformly treat "not in set" as paid.
+   */
+  freeModels: FreeModelSet;
+  /** DB-driven default OpenHands model id (``openhands/<model>``), or null. */
+  defaultModel: string | null;
+  /** True once the backend flags query has settled at least once. */
+  defaultModelReady: boolean;
+}
+
+interface FreeModelsActions {
+  /**
+   * Replaces the DB-driven flags. Called once by the app-level hydrator
+   * ({@link useHydrateFreeModels}) after the backend model list is fetched, so
+   * leaf components can read the flags synchronously via zustand selectors
+   * without needing a QueryClientProvider in scope.
+   */
+  setFlags: (flags: {
+    freeModels: FreeModelSet;
+    defaultModel: string | null;
+  }) => void;
+  markDefaultModelReady: () => void;
+  resetFlags: () => void;
+}
+
+type FreeModelsStore = FreeModelsState & FreeModelsActions;
+
+const EMPTY_FREE_MODELS: FreeModelSet = new Set<string>();
+
+export const useFreeModelsStore = create<FreeModelsStore>()((set) => ({
+  freeModels: EMPTY_FREE_MODELS,
+  defaultModel: null,
+  defaultModelReady: false,
+  setFlags: (flags) =>
+    set({
+      freeModels: flags.freeModels,
+      defaultModel: flags.defaultModel,
+      defaultModelReady: true,
+    }),
+  markDefaultModelReady: () => set({ defaultModelReady: true }),
+  resetFlags: () =>
+    set({
+      freeModels: EMPTY_FREE_MODELS,
+      defaultModel: null,
+      defaultModelReady: false,
+    }),
+}));