Add files using upload-large-folder tool

src/extensions/canvas-extension-module-loader.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import {
+  assertCanvasExtensionModule,
+  InvalidCanvasExtensionModuleError,
+} from "#/extensions/canvas-extension-module-loader";
+
+describe("assertCanvasExtensionModule", () => {
+  it("accepts a module namespace with an activate export", () => {
+    expect(() =>
+      assertCanvasExtensionModule({ activate: () => undefined }),
+    ).not.toThrow();
+  });
+
+  it("rejects modules that do not implement the host lifecycle", () => {
+    expect(() => assertCanvasExtensionModule({ default: {} })).toThrow(
+      InvalidCanvasExtensionModuleError,
+    );
+  });
+});

src/extensions/canvas-extension-module-loader.ts

@@ -0,0 +1,42 @@
+import type { CanvasExtensionModule } from "#/types/canvas-extension";
+
+export class InvalidCanvasExtensionModuleError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidCanvasExtensionModuleError";
+  }
+}
+
+export function assertCanvasExtensionModule(
+  value: unknown,
+): asserts value is CanvasExtensionModule {
+  if (
+    typeof value !== "object" ||
+    value === null ||
+    !("activate" in value) ||
+    typeof value.activate !== "function"
+  ) {
+    throw new InvalidCanvasExtensionModuleError(
+      'Canvas Extension entrypoint must export an "activate" function.',
+    );
+  }
+}
+
+/**
+ * Import an authenticated, self-contained ESM bundle without putting the
+ * Agent Server session key in a URL. The source has already been fetched by
+ * Canvas through its authenticated HTTP client.
+ */
+export async function loadCanvasExtensionModule(
+  source: string,
+): Promise<CanvasExtensionModule> {
+  const blob = new Blob([source], { type: "text/javascript" });
+  const moduleUrl = URL.createObjectURL(blob);
+  try {
+    const imported: unknown = await import(/* @vite-ignore */ moduleUrl);
+    assertCanvasExtensionModule(imported);
+    return imported;
+  } finally {
+    URL.revokeObjectURL(moduleUrl);
+  }
+}

src/hooks/use-acp-credential-form.ts

@@ -0,0 +1,114 @@
+import React from "react";
+import { useSearchSecrets } from "#/hooks/query/use-get-secrets";
+import { useSaveAcpSecrets } from "#/hooks/use-save-acp-secrets";
+import {
+  getAcpCredentialConflicts,
+  getAcpProviderSecrets,
+  type ACPProviderSecretField,
+} from "#/constants/acp-providers";
+
+export interface AcpCredentialForm {
+  /** Credential fields for ``providerKey`` (see {@link getAcpProviderSecrets}). */
+  fields: ACPProviderSecretField[];
+  /** Current (unsaved) input values, keyed by field name. */
+  values: Record<string, string>;
+  setValue: (name: string, value: string) => void;
+  /** Whether a secret with this name is already saved on the backend. */
+  secretExists: (name: string) => boolean;
+  /** Typed now (non-blank) or previously saved. */
+  hasValueFor: (name: string) => boolean;
+  /** ``[credential, conflicting]`` pairs currently both set (typed or saved). */
+  conflicts: Array<[string, string]>;
+  /** Whether a credential (a ``secret`` field — API key, OAuth token, or
+   * file-content blob) is already saved on the backend for this provider. This
+   * is the backend-truthful auth signal that works on Docker/cloud, where the
+   * host-login probe can't run (agent-canvas#1244). A non-credential field (a
+   * base URL or GCP scalar) being set does not count. */
+  credentialsConfigured: boolean;
+  /** Whether the active backend can materialise file-content (``multiline``)
+   * credentials to disk. False on cloud (agent-canvas#1016), where such a
+   * credential would be orphaned. */
+  consumesFileCredentials: boolean;
+  /** At least one field has a non-blank typed value. */
+  isDirty: boolean;
+  /** Persist the filled fields; resolves ``true`` when everything saved.
+   * ``silent`` suppresses the success toast so a caller saving credentials
+   * alongside other state can emit a single combined confirmation. */
+  save: (options?: { silent?: boolean }) => Promise<boolean>;
+  reset: () => void;
+  isSaving: boolean;
+}
+
+/**
+ * Shared state + derived values for the ACP credential forms (the onboarding
+ * step and the Settings → Agent section): the provider's field list, the typed
+ * values, existing-secret lookups, the credential-conflict pairs, and the save
+ * flow ({@link useSaveAcpSecrets}). Values reset when ``providerKey`` changes —
+ * typed-but-unsaved input belongs to the previous provider's fields.
+ */
+export function useAcpCredentialForm(
+  providerKey: string | null | undefined,
+): AcpCredentialForm {
+  const { data: existingSecrets } = useSearchSecrets();
+  const fields = React.useMemo(
+    () => getAcpProviderSecrets(providerKey),
+    [providerKey],
+  );
+  const [values, setValues] = React.useState<Record<string, string>>({});
+
+  // Both local and cloud agent-servers materialise file-content credentials
+  // (Codex auth.json, Gemini Vertex SA) via the SDK's acp_file_secrets: locally
+  // from the user's machine, on cloud from the per-user encrypted secret store
+  // routed through agent_context.secrets at conversation start (the cloud
+  // backend pins an SDK that materialises reserved file secrets). So a pasted
+  // file blob is consumable on every supported backend.
+  const consumesFileCredentials = true;
+  const { saveFilled, isSaving } = useSaveAcpSecrets(
+    fields,
+    consumesFileCredentials,
+  );
+
+  React.useEffect(() => {
+    setValues({});
+  }, [providerKey]);
+
+  const secretExists = React.useCallback(
+    (name: string) =>
+      (existingSecrets ?? []).some((secret) => secret.name === name),
+    [existingSecrets],
+  );
+
+  const hasValueFor = React.useCallback(
+    (name: string) => Boolean(values[name]?.trim()) || secretExists(name),
+    [values, secretExists],
+  );
+
+  const setValue = React.useCallback(
+    (name: string, value: string) =>
+      setValues((prev) => ({ ...prev, [name]: value })),
+    [],
+  );
+
+  const reset = React.useCallback(() => setValues({}), []);
+
+  return {
+    fields,
+    values,
+    setValue,
+    secretExists,
+    hasValueFor,
+    conflicts: getAcpCredentialConflicts(providerKey, hasValueFor),
+    // `=== true` is the intended strict check: only a credential-bearing field
+    // (API key, OAuth token, file blob) counts — never a base URL or GCP scalar,
+    // which omit `secret` entirely. A field must never set `secret: false` to
+    // opt out; omit the flag instead.
+    credentialsConfigured: fields.some(
+      (field) => field.secret === true && secretExists(field.name),
+    ),
+    consumesFileCredentials,
+    isDirty: fields.some((field) => Boolean(values[field.name]?.trim())),
+    save: (options) => saveFilled(values, options),
+    reset,
+    isSaving,
+  };
+}

src/hooks/use-active-agent-profile.ts

@@ -0,0 +1,32 @@
+import type { AgentKind } from "@openhands/typescript-client";
+import type { AgentProfileSummary } from "#/api/agent-profiles-service/agent-profiles-service.api";
+import { useAgentProfiles } from "#/hooks/query/use-agent-profiles";
+
+/**
+ * The agent profile the user has activated — the authoritative "current agent"
+ * now that Settings → Agent IS the profile library (#1571). `activate` is
+ * pointer-only and never writes `settings.agent_settings`, so the active
+ * profile — not the global agent settings — is the source of truth for what
+ * kind of agent (OpenHands vs ACP) is in effect.
+ */
+export function useActiveAgentProfile(): {
+  activeProfile: AgentProfileSummary | null;
+  isLoading: boolean;
+} {
+  const { data, isLoading } = useAgentProfiles();
+  const activeId = data?.active_agent_profile_id ?? null;
+  const activeProfile =
+    data?.profiles?.find((p) => p.id != null && p.id === activeId) ?? null;
+  return { activeProfile, isLoading };
+}
+
+/**
+ * The effective agent kind from the active profile. `undefined` while the
+ * profile list is loading or when no profile is active — callers should fall
+ * back to `settings.agent_settings.agent_kind` in that window to avoid a flash
+ * of the wrong (OpenHands-default) UI.
+ */
+export function useActiveAgentKind(): AgentKind | undefined {
+  const { activeProfile } = useActiveAgentProfile();
+  return activeProfile?.agent_kind;
+}

src/hooks/use-agent-state.test.tsx

@@ -0,0 +1,73 @@
+import { act, renderHook } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { useAgentState } from "./use-agent-state";
+import { useActiveConversation } from "./query/use-active-conversation";
+import { useOptionalConversationId } from "./use-conversation-id";
+import { useConversationStateStore } from "#/stores/conversation-state-store";
+import { AgentState } from "#/types/agent-state";
+import { ExecutionStatus } from "#/types/agent-server/core/base/common";
+
+const TEST_CONVERSATION_ID = "test-conversation-id";
+
+vi.mock("./query/use-active-conversation", () => ({
+  useActiveConversation: vi.fn(),
+}));
+
+vi.mock("./use-conversation-id", () => ({
+  useOptionalConversationId: vi.fn(),
+}));
+
+describe("useAgentState", () => {
+  const mockUseActiveConversation = vi.mocked(useActiveConversation);
+  const mockUseOptionalConversationId = vi.mocked(useOptionalConversationId);
+
+  beforeEach(() => {
+    act(() => {
+      useConversationStateStore.getState().reset();
+    });
+
+    mockUseActiveConversation.mockReturnValue({
+      data: null,
+    } as ReturnType<typeof useActiveConversation>);
+
+    mockUseOptionalConversationId.mockReturnValue({
+      conversationId: TEST_CONVERSATION_ID,
+    });
+  });
+
+  it("prefers live websocket execution status over cached conversation status", () => {
+    mockUseActiveConversation.mockReturnValue({
+      data: {
+        execution_status: ExecutionStatus.FINISHED,
+      },
+    } as ReturnType<typeof useActiveConversation>);
+
+    act(() => {
+      useConversationStateStore
+        .getState()
+        .setExecutionStatus(TEST_CONVERSATION_ID, ExecutionStatus.RUNNING);
+    });
+
+    const { result } = renderHook(() => useAgentState());
+
+    expect(result.current.executionStatus).toBe(ExecutionStatus.RUNNING);
+    expect(result.current.curAgentState).toBe(AgentState.RUNNING);
+  });
+
+  it("falls back to cached conversation execution status when live state is empty", () => {
+    mockUseActiveConversation.mockReturnValue({
+      data: {
+        execution_status: ExecutionStatus.WAITING_FOR_CONFIRMATION,
+      },
+    } as ReturnType<typeof useActiveConversation>);
+
+    const { result } = renderHook(() => useAgentState());
+
+    expect(result.current.executionStatus).toBe(
+      ExecutionStatus.WAITING_FOR_CONFIRMATION,
+    );
+    expect(result.current.curAgentState).toBe(
+      AgentState.AWAITING_USER_CONFIRMATION,
+    );
+  });
+});

src/hooks/use-agent-state.ts

@@ -0,0 +1,107 @@
+import { useMemo } from "react";
+import { useActiveConversation } from "#/hooks/query/use-active-conversation";
+import { useOptionalConversationId } from "#/hooks/use-conversation-id";
+import { useConversationStateStore } from "#/stores/conversation-state-store";
+import { useConversationStore } from "#/stores/conversation-store";
+import { AgentState } from "#/types/agent-state";
+import { ExecutionStatus } from "#/types/agent-server/core/base/common";
+
+/**
+ * Maps agent execution status to AgentState
+ */
+function mapExecutionStatusToAgentState(
+  status: ExecutionStatus | null,
+): AgentState {
+  if (!status) {
+    return AgentState.LOADING;
+  }
+
+  switch (status) {
+    case ExecutionStatus.IDLE:
+      return AgentState.AWAITING_USER_INPUT;
+    case ExecutionStatus.RUNNING:
+      return AgentState.RUNNING;
+    case ExecutionStatus.PAUSED:
+      return AgentState.PAUSED;
+    case ExecutionStatus.WAITING_FOR_CONFIRMATION:
+      return AgentState.AWAITING_USER_CONFIRMATION;
+    case ExecutionStatus.FINISHED:
+      return AgentState.FINISHED;
+    case ExecutionStatus.ERROR:
+      return AgentState.ERROR;
+    case ExecutionStatus.STUCK:
+      return AgentState.ERROR; // Map STUCK to ERROR for now
+    default:
+      return AgentState.LOADING;
+  }
+}
+
+export interface UseAgentStateResult {
+  curAgentState: AgentState;
+  executionStatus?: ExecutionStatus | null;
+}
+
+/**
+ * Returns the current agent state from conversation execution status.
+ *
+ * Defaults to the conversation in the current route. Pass `conversationId`
+ * to read another conversation's status instead — e.g. a local planner
+ * helper conversation, whose run/idle transitions are tracked separately
+ * from the main conversation's (see conversation-state-store.ts).
+ */
+export function useAgentState(conversationId?: string): UseAgentStateResult {
+  const { conversationId: routeConversationId } = useOptionalConversationId();
+  const targetConversationId = conversationId ?? routeConversationId;
+  const isRouteConversation =
+    !conversationId || conversationId === routeConversationId;
+
+  const liveExecutionStatus = useConversationStateStore((state) =>
+    targetConversationId
+      ? (state.executionStatusByConversation[targetConversationId] ?? null)
+      : null,
+  );
+  // The REST fallback only ever describes the route's own conversation, so it
+  // only applies when no other conversation was explicitly requested.
+  const routeConversationExecutionStatus =
+    useActiveConversation().data?.execution_status ?? null;
+  const fallbackExecutionStatus = isRouteConversation
+    ? routeConversationExecutionStatus
+    : null;
+
+  const executionStatus = liveExecutionStatus ?? fallbackExecutionStatus;
+  const curAgentState = useMemo(
+    () => mapExecutionStatusToAgentState(executionStatus),
+    [executionStatus],
+  );
+
+  return { curAgentState, executionStatus };
+}
+
+export interface UsePlanningAgentStateResult {
+  localPlanningConversationId: string | null;
+  curPlanningAgentState: AgentState;
+  /** Running or loading. `false` (not "unknown") when there's no planner yet. */
+  isPlanningAgentRunning: boolean;
+}
+
+/**
+ * The local planner helper's own state — read separately from the main
+ * conversation's via `useAgentState` since the two run independently.
+ */
+export function usePlanningAgentState(): UsePlanningAgentStateResult {
+  const localPlanningConversationId = useConversationStore(
+    (state) => state.localPlanningConversationId,
+  );
+  const { curAgentState: curPlanningAgentState } = useAgentState(
+    localPlanningConversationId ?? undefined,
+  );
+  const isPlanningAgentRunning =
+    !!localPlanningConversationId &&
+    (curPlanningAgentState === AgentState.RUNNING ||
+      curPlanningAgentState === AgentState.LOADING);
+  return {
+    localPlanningConversationId,
+    curPlanningAgentState,
+    isPlanningAgentRunning,
+  };
+}

src/hooks/use-auto-refresh-files-on-edit.ts

@@ -0,0 +1,151 @@
+import { useEffect, useRef } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+
+import { useEventStore, type OHEvent } from "#/stores/use-event-store";
+import { useWorkspaceMutationCounter } from "#/stores/use-workspace-mutation-counter";
+
+// `kind` values we treat as a file-mutation observation.
+const FILE_EDIT_OBSERVATION_KINDS = new Set([
+  "FileEditorObservation",
+  "StrReplaceEditorObservation",
+  "PlanningFileEditorObservation",
+]);
+
+// Commands on the str-replace-editor family that don't change anything on
+// disk. We don't want to invalidate caches for those.
+const READ_ONLY_COMMANDS = new Set(["view"]);
+
+// Bash observations are how `git commit` / `git push` (and any file edit
+// done through the shell) arrive, so they must refresh the Diff view too.
+// Legacy agent-servers emit `ExecuteBashObservation`; the current SDK
+// emits `TerminalObservation`.
+const BASH_OBSERVATION_KINDS = new Set([
+  "ExecuteBashObservation",
+  "TerminalObservation",
+]);
+
+function isFileMutationObservation(event: OHEvent): boolean {
+  // ObservationEvents have `source: "environment"` and an `observation`
+  // field — narrow to that shape without pulling in the whole event union.
+  const obs = (event as { observation?: { kind?: string; command?: string } })
+    .observation;
+  if (!obs || typeof obs.kind !== "string") return false;
+  if (!FILE_EDIT_OBSERVATION_KINDS.has(obs.kind)) return false;
+  if (obs.command && READ_ONLY_COMMANDS.has(obs.command)) return false;
+  return true;
+}
+
+// Note: `READ_ONLY_COMMANDS` intentionally doesn't apply here — for bash
+// observations `command` is the whole shell command line, not a
+// file-editor sub-command.
+function isBashObservation(event: OHEvent): boolean {
+  const obs = (event as { observation?: { kind?: string } }).observation;
+  return (
+    !!obs &&
+    typeof obs.kind === "string" &&
+    BASH_OBSERVATION_KINDS.has(obs.kind)
+  );
+}
+
+/**
+ * Watches the conversation event stream and invalidates the workspace file
+ * queries whenever the agent commits a file-editor mutation (create / edit /
+ * insert / undo_edit). This keeps the Files tab's list, content view and
+ * diff view in sync with what the agent has actually written to disk,
+ * without requiring the user to click refresh manually.
+ *
+ * Bash observations also refresh the git-diff queries (`file_changes` /
+ * `file_diff`) — a `git commit` or `git push` changes what the Diff view
+ * should display, and shell commands can edit files too. They deliberately
+ * do NOT touch the workspace file queries or the workspace mutation
+ * counter: bumping the counter reloads canvas iframes, and doing that for
+ * every shell command the agent runs would cause constant flicker.
+ * Invalidation only refetches actively-mounted queries, so the cost is
+ * limited to when the Files tab is open.
+ *
+ * Mount this hook inside any component that should drive auto-refresh —
+ * the Files tab is the obvious caller. Multiple mounts are safe because
+ * React Query coalesces overlapping invalidations.
+ */
+export function useAutoRefreshFilesOnEdit(): void {
+  const queryClient = useQueryClient();
+  const events = useEventStore((state) => state.events);
+  const bumpWorkspaceMutationCounter = useWorkspaceMutationCounter(
+    (state) => state.bump,
+  );
+
+  // Track which events we've already reacted to. Two parallel stores:
+  //
+  // 1. `processedIdsRef` — keys events that *have* an id. The event store
+  //    re-sorts on insert when out-of-order events arrive (an older event
+  //    can land *between* two newer ones already in the array), so we
+  //    cannot use a `slice(processedCount)` trick — it would miss a
+  //    late-arriving older event because the array length grew but the
+  //    tail we just diffed didn't contain it. Using a Set of ids is O(n)
+  //    per render in the worst case but small in practice and immune to
+  //    reordering. Type matches the event store's own dedup set
+  //    (`Set<string | number>` in `use-event-store.ts`) so a stray
+  //    numeric id (legacy server payload, hand-crafted test event, …)
+  //    can't sneak past.
+  //
+  // 2. `processedEventsRef` — keys events that have NO id. We cannot put
+  //    a literal `undefined` into the id Set: that would make the second,
+  //    third, … id-less arrival collide on the same `undefined` key and
+  //    silently skip them. We also cannot just skip dedup for id-less
+  //    events: the events array is rebuilt on every store mutation but
+  //    its element references are stable, so the same id-less event
+  //    appears in the array forever and would re-bump the workspace
+  //    mutation counter on every subsequent re-render. Keying by object
+  //    reference (via a WeakSet) gives us "process each id-less event
+  //    exactly once" — durable, free, no held-onto memory after the
+  //    store clears.
+  const processedIdsRef = useRef<Set<string | number>>(new Set());
+  const processedEventsRef = useRef<WeakSet<OHEvent>>(new WeakSet());
+
+  useEffect(() => {
+    let hasNewFileEdits = false;
+    let hasNewBashCommands = false;
+    for (const event of events) {
+      const id: string | number | undefined =
+        "id" in event ? event.id : undefined;
+      const alreadyProcessed =
+        id !== undefined
+          ? processedIdsRef.current.has(id)
+          : processedEventsRef.current.has(event);
+      // Inverted predicate so we avoid `continue` (banned by repo lint).
+      if (!alreadyProcessed) {
+        if (id !== undefined) {
+          processedIdsRef.current.add(id);
+        } else {
+          processedEventsRef.current.add(event);
+        }
+        if (isFileMutationObservation(event)) hasNewFileEdits = true;
+        else if (isBashObservation(event)) hasNewBashCommands = true;
+      }
+    }
+
+    if (!hasNewFileEdits && !hasNewBashCommands) return;
+
+    // Editor and bash mutations both change what the git Diff view shows —
+    // including the per-file diff content of an already-expanded file.
+    // The commits list refreshes too (a `git commit` arrives as a bash
+    // observation); per-commit queries (`commit_changes` /
+    // `commit_file_diff`) are sha-addressed and immutable, so they are
+    // deliberately NOT invalidated.
+    queryClient.invalidateQueries({ queryKey: ["file_changes"] });
+    queryClient.invalidateQueries({ queryKey: ["file_diff"] });
+    queryClient.invalidateQueries({ queryKey: ["git_commits"] });
+
+    if (hasNewFileEdits) {
+      queryClient.invalidateQueries({ queryKey: ["workspace-files"] });
+      queryClient.invalidateQueries({ queryKey: ["workspace-file-content"] });
+      // Force iframes / <img> tags pointing at the static workspace
+      // fileserver to re-fetch. Without this they happily keep showing the
+      // stale (browser-cached) bytes even after the agent has rewritten the
+      // file on disk — e.g. tweaking style.css would silently have no
+      // visible effect on the rendered index.html until the user reloaded
+      // the whole canvas.
+      bumpWorkspaceMutationCounter();
+    }
+  }, [events, queryClient, bumpWorkspaceMutationCounter]);
+}

src/hooks/use-await-context-compaction.test.ts

@@ -0,0 +1,178 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import useMetricsStore from "#/stores/metrics-store";
+import { useEventStore } from "#/stores/use-event-store";
+import type { OpenHandsEvent } from "#/types/agent-server/core";
+import {
+  buildContextCompactionResult,
+  useAwaitContextCompaction,
+} from "./use-await-context-compaction";
+
+function condensationEvent(id: string): OpenHandsEvent {
+  return {
+    id,
+    timestamp: new Date().toISOString(),
+    source: "environment",
+    kind: "Condensation",
+    forgotten_event_ids: ["a", "b"],
+  } as OpenHandsEvent;
+}
+
+describe("buildContextCompactionResult", () => {
+  it("computes tokens saved without going negative", () => {
+    expect(buildContextCompactionResult(1000, 400, "compacted")).toEqual({
+      beforeToken: 1000,
+      afterToken: 400,
+      savedToken: 600,
+      outcome: "compacted",
+    });
+    expect(buildContextCompactionResult(400, 500, "no_change").savedToken).toBe(
+      0,
+    );
+  });
+});
+
+describe("useAwaitContextCompaction", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    useEventStore.getState().clearEvents();
+    useMetricsStore.getState().setMetrics({
+      cost: null,
+      max_budget_per_task: null,
+      usage: {
+        prompt_tokens: 0,
+        completion_tokens: 0,
+        cache_read_tokens: 0,
+        cache_write_tokens: 0,
+        context_window: 100_000,
+        per_turn_token: 10_000,
+      },
+    });
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    useEventStore.getState().clearEvents();
+  });
+
+  it("reports tokens freed once condensation lands and metrics drop", () => {
+    const onComplete = vi.fn();
+
+    renderHook(() =>
+      useAwaitContextCompaction({
+        beforeToken: 10_000,
+        onComplete,
+      }),
+    );
+
+    act(() => {
+      useEventStore.getState().addEvent(condensationEvent("cond-1"));
+      useMetricsStore.getState().setMetrics({
+        cost: null,
+        max_budget_per_task: null,
+        usage: {
+          prompt_tokens: 0,
+          completion_tokens: 0,
+          cache_read_tokens: 0,
+          cache_write_tokens: 0,
+          context_window: 100_000,
+          per_turn_token: 4_000,
+        },
+      });
+    });
+
+    expect(onComplete).toHaveBeenCalledWith({
+      beforeToken: 10_000,
+      afterToken: 4_000,
+      savedToken: 6_000,
+      outcome: "compacted",
+    });
+  });
+
+  it("finishes after the settle window when metrics do not drop", () => {
+    const onComplete = vi.fn();
+
+    renderHook(() =>
+      useAwaitContextCompaction({
+        beforeToken: 10_000,
+        onComplete,
+      }),
+    );
+
+    act(() => {
+      useEventStore.getState().addEvent(condensationEvent("cond-2"));
+    });
+    expect(onComplete).not.toHaveBeenCalled();
+
+    act(() => {
+      vi.advanceTimersByTime(2_500);
+    });
+
+    expect(onComplete).toHaveBeenCalledWith({
+      beforeToken: 10_000,
+      afterToken: 10_000,
+      savedToken: 0,
+      outcome: "no_change",
+    });
+  });
+
+  it("reports timeout when no condensation event arrives in time", () => {
+    const onComplete = vi.fn();
+
+    renderHook(() =>
+      useAwaitContextCompaction({
+        beforeToken: 10_000,
+        onComplete,
+      }),
+    );
+
+    act(() => {
+      vi.advanceTimersByTime(90_000);
+    });
+
+    expect(onComplete).toHaveBeenCalledWith({
+      beforeToken: 10_000,
+      afterToken: 10_000,
+      savedToken: 0,
+      outcome: "timeout",
+    });
+  });
+
+  it("detects a condensation that landed before the post-ack effect started", () => {
+    // The condense POST can return only after the server already emitted its
+    // Condensation event. The pre-request baseline (captured before the POST
+    // fired) must not contain it, so it still counts as new.
+    const baseline = new Set(useEventStore.getState().eventIds);
+    act(() => {
+      useEventStore.getState().addEvent(condensationEvent("cond-early"));
+      useMetricsStore.getState().setMetrics({
+        cost: null,
+        max_budget_per_task: null,
+        usage: {
+          prompt_tokens: 0,
+          completion_tokens: 0,
+          cache_read_tokens: 0,
+          cache_write_tokens: 0,
+          context_window: 100_000,
+          per_turn_token: 4_000,
+        },
+      });
+    });
+
+    const onComplete = vi.fn();
+    renderHook(() =>
+      useAwaitContextCompaction({
+        beforeToken: 10_000,
+        baselineEventIds: baseline,
+        onComplete,
+      }),
+    );
+
+    expect(onComplete).toHaveBeenCalledWith({
+      beforeToken: 10_000,
+      afterToken: 4_000,
+      savedToken: 6_000,
+      outcome: "compacted",
+    });
+  });
+});

src/hooks/use-chat-input-model-state.ts

@@ -0,0 +1,121 @@
+import { useActiveConversation } from "#/hooks/query/use-active-conversation";
+import { useSettings } from "#/hooks/query/use-settings";
+import {
+  type AcpModelContext,
+  useAcpModelContext,
+} from "#/hooks/use-acp-model-context";
+import { useActiveBackend } from "#/contexts/active-backend-context";
+import { useCanManageOrgProfiles } from "#/hooks/use-can-manage-org-profiles";
+import { useActiveAcpProfileDetail } from "#/hooks/query/use-active-acp-profile-detail";
+import { useOptionalConversationId } from "#/hooks/use-conversation-id";
+import {
+  getAcpPreferredDefaultModel,
+  getAcpProvider,
+  labelForAcpModel,
+  resolveEffectiveAcpModel,
+  type ACPModelOption,
+} from "#/constants/acp-providers";
+
+export interface ChatInputModelState {
+  isAcpContext: boolean;
+  displayModel: string | null;
+  currentModelId: string | null;
+  availableAcpModels: ACPModelOption[];
+  showAcpPicker: boolean;
+  switchConversationId: string | null;
+  destinationPath: AcpModelContext["destinationPath"];
+  destinationLabel: string;
+}
+
+export function useChatInputModelState(): ChatInputModelState {
+  const { data: conversation } = useActiveConversation();
+  const { data: settings } = useSettings();
+  const { conversationId } = useOptionalConversationId();
+  const { backend } = useActiveBackend();
+  const canManageOrgProfiles = useCanManageOrgProfiles();
+  // The active ACP AgentProfile's own fields are the conversation launch
+  // source (activation never writes agent_settings, so the global settings
+  // may describe a different provider). Null in a conversation, while
+  // loading, when the active profile isn't ACP, or on legacy backends
+  // without the profiles surface — settings are the fallback in that window.
+  const activeAcpProfile = useActiveAcpProfileDetail();
+  const {
+    isActiveAcpConversation,
+    isHomeAcp,
+    isAcpContext,
+    destinationPath,
+    destinationLabel,
+  } = useAcpModelContext();
+
+  const settingsAcpServerKey =
+    typeof settings?.agent_settings?.acp_server === "string"
+      ? settings.agent_settings.acp_server
+      : null;
+  const acpServerKey = isActiveAcpConversation
+    ? conversation?.acp_server
+    : isHomeAcp
+      ? (activeAcpProfile?.acp_server ?? settingsAcpServerKey)
+      : null;
+  const acpProvider = isAcpContext ? getAcpProvider(acpServerKey) : undefined;
+
+  const settingsAcpModel =
+    typeof settings?.agent_settings?.acp_model === "string"
+      ? settings.agent_settings.acp_model
+      : null;
+  // Home: read the model from the same source as the server key — mixing the
+  // profile's provider with a stale settings model could pair e.g. a codex
+  // provider with a claude model.
+  const acpConfiguredModel =
+    isHomeAcp && activeAcpProfile
+      ? activeAcpProfile.acp_model
+      : settingsAcpModel;
+
+  let currentModelId: string | null = null;
+  if (isActiveAcpConversation) {
+    // ACP conversations store llm_model as the acp_model (persisted at
+    // creation time). Use it directly if available; fall back to the
+    // settings-configured model or provider default so the chip stays visible.
+    currentModelId =
+      conversation?.llm_model ??
+      resolveEffectiveAcpModel({
+        configured: acpConfiguredModel,
+        providerDefault: getAcpPreferredDefaultModel(acpServerKey),
+      });
+  } else if (isHomeAcp) {
+    currentModelId = resolveEffectiveAcpModel({
+      configured: acpConfiguredModel,
+      // Preferred default (Vertex-safe for Gemini) — must match what the
+      // start request would substitute for an unconfigured model.
+      providerDefault: getAcpPreferredDefaultModel(acpServerKey),
+    });
+  } else {
+    currentModelId = conversation?.llm_model ?? settings?.llm_model ?? null;
+  }
+
+  const displayModel =
+    currentModelId && isAcpContext
+      ? (labelForAcpModel(acpServerKey, currentModelId) ?? currentModelId)
+      : currentModelId;
+  const availableAcpModels = acpProvider?.available_models ?? [];
+  // A home-page pick persists into the active ACP profile, which on cloud is
+  // org-owned — hide the selectable rows from members who'd only get a 403.
+  // Conversation-scoped switches (blank or started) stay member-allowed.
+  const canPersistHomeAcpModel =
+    !isHomeAcp || backend.kind !== "cloud" || canManageOrgProfiles;
+  const showAcpPicker =
+    isAcpContext && availableAcpModels.length > 0 && canPersistHomeAcpModel;
+  const switchConversationId = isActiveAcpConversation
+    ? (conversationId ?? null)
+    : null;
+
+  return {
+    isAcpContext,
+    displayModel,
+    currentModelId,
+    availableAcpModels,
+    showAcpPicker,
+    switchConversationId,
+    destinationPath,
+    destinationLabel,
+  };
+}

src/hooks/use-conversation-overview-git-diff-stats.ts

@@ -0,0 +1,81 @@
+import { useMemo } from "react";
+import { useQueries } from "@tanstack/react-query";
+import AgentServerGitService from "#/api/git-service/agent-server-git-service.api";
+import { useActiveConversation } from "#/hooks/query/use-active-conversation";
+import { useUnifiedGetGitChanges } from "#/hooks/query/use-unified-get-git-changes";
+import { useConversationId } from "#/hooks/use-conversation-id";
+import { useRuntimeIsReady } from "#/hooks/use-runtime-is-ready";
+import { getGitPath } from "#/utils/get-git-path";
+import {
+  countGitChangeDiffStats,
+  sumGitDiffLineStats,
+} from "#/utils/git-diff-stats";
+
+export function useConversationOverviewGitDiffStats() {
+  const { conversationId } = useConversationId();
+  const { data: conversation } = useActiveConversation();
+  const runtimeIsReady = useRuntimeIsReady();
+  const {
+    data: gitChanges,
+    isLoading: isLoadingChanges,
+    isSuccess: isChangesSuccess,
+    isError: isChangesError,
+  } = useUnifiedGetGitChanges();
+
+  const conversationUrl = conversation?.conversation_url;
+  const sessionApiKey = conversation?.session_api_key;
+  const gitPath = useMemo(
+    () =>
+      getGitPath(
+        conversation?.selected_repository,
+        conversation?.workspace?.working_dir?.trim(),
+      ),
+    [conversation?.selected_repository, conversation?.workspace?.working_dir],
+  );
+
+  const diffCandidates = useMemo(
+    () => (gitChanges ?? []).filter((change) => change.status !== "D"),
+    [gitChanges],
+  );
+
+  const diffQueries = useQueries({
+    queries: diffCandidates.map((change) => ({
+      queryKey: [
+        "conversation_overview_file_diff",
+        conversationId,
+        conversationUrl,
+        sessionApiKey,
+        gitPath,
+        change.path,
+      ],
+      queryFn: async () =>
+        AgentServerGitService.getGitChangeDiff(
+          conversationId!,
+          conversationUrl,
+          sessionApiKey,
+          `${gitPath}/${change.path}`,
+        ),
+      enabled:
+        runtimeIsReady && !!conversationId && isChangesSuccess && !!change.path,
+      staleTime: 1000 * 60 * 5,
+      meta: {
+        disableToast: true,
+      },
+    })),
+  });
+
+  const isLoadingDiffs = diffQueries.some((query) => query.isLoading);
+  const totals = sumGitDiffLineStats(
+    diffQueries.flatMap((query) =>
+      query.data ? [countGitChangeDiffStats(query.data)] : [],
+    ),
+  );
+
+  return {
+    additions: totals.additions,
+    deletions: totals.deletions,
+    changeCount: gitChanges?.length ?? 0,
+    isLoading: isLoadingChanges || isLoadingDiffs,
+    isError: isChangesError,
+  };
+}

src/hooks/use-debounce.ts

@@ -0,0 +1,12 @@
+import { useEffect, useState } from "react";
+
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebouncedValue(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+
+  return debouncedValue;
+}

src/hooks/use-device-flow.ts

@@ -0,0 +1,200 @@
+import React from "react";
+import {
+  startDeviceFlow,
+  pollForToken,
+  DeviceFlowError,
+  type DeviceAuthorizationResponse,
+} from "#/api/device-flow-client";
+import {
+  trackCloudDeviceAuthorizationStarted,
+  trackCloudDeviceAuthorizationSucceeded,
+  type CloudConnectionSource,
+} from "#/services/cloud-funnel-analytics";
+
+export type DeviceFlowStatus =
+  | "idle"
+  | "starting"
+  | "awaiting_authorization"
+  | "success"
+  | "error";
+
+export interface DeviceFlowState {
+  status: DeviceFlowStatus;
+  /** The verification URL to show/open for the user */
+  verificationUrl: string | null;
+  /** User code to display as fallback */
+  userCode: string | null;
+  /** The resulting API key on success */
+  apiKey: string | null;
+  /** Error message if status is "error" */
+  error: string | null;
+  /** Error code for programmatic handling */
+  errorCode: string | null;
+}
+
+export interface UseDeviceFlowReturn extends DeviceFlowState {
+  /** Start the device flow authentication */
+  start: StartDeviceFlow;
+  /** Cancel an in-progress flow */
+  cancel: () => void;
+  /** Reset state back to idle */
+  reset: () => void;
+}
+
+type StartDeviceFlow = (
+  host: string,
+  analyticsSource?: CloudConnectionSource,
+) => void;
+
+const initialState: DeviceFlowState = {
+  status: "idle",
+  verificationUrl: null,
+  userCode: null,
+  apiKey: null,
+  error: null,
+  errorCode: null,
+};
+
+/**
+ * React hook for managing OAuth 2.0 Device Flow authentication.
+ *
+ * Usage:
+ * ```tsx
+ * const { status, verificationUrl, apiKey, error, start, cancel, reset } = useDeviceFlow();
+ *
+ * // Start auth
+ * start("https://app.all-hands.dev");
+ *
+ * // Open browser when awaiting
+ * if (status === "awaiting_authorization" && verificationUrl) {
+ *   window.open(verificationUrl, "_blank");
+ * }
+ *
+ * // Use API key on success
+ * if (status === "success" && apiKey) {
+ *   setApiKeyField(apiKey);
+ * }
+ * ```
+ */
+export function useDeviceFlow(): UseDeviceFlowReturn {
+  const [state, setState] = React.useState<DeviceFlowState>(initialState);
+  const abortControllerRef = React.useRef<AbortController | null>(null);
+
+  const start: StartDeviceFlow = React.useCallback((host, analyticsSource) => {
+    // Cancel any existing flow
+    abortControllerRef.current?.abort();
+    const abortController = new AbortController();
+    abortControllerRef.current = abortController;
+
+    setState({
+      ...initialState,
+      status: "starting",
+    });
+
+    (async () => {
+      let authResponse: DeviceAuthorizationResponse;
+
+      try {
+        authResponse = await startDeviceFlow(host);
+      } catch (error) {
+        if (abortController.signal.aborted) return;
+
+        const message =
+          error instanceof Error
+            ? error.message
+            : "Failed to start device flow";
+        const code = error instanceof DeviceFlowError ? error.code : undefined;
+
+        setState({
+          ...initialState,
+          status: "error",
+          error: message,
+          errorCode: code ?? null,
+        });
+        return;
+      }
+
+      if (abortController.signal.aborted) return;
+
+      trackCloudDeviceAuthorizationStarted(host, analyticsSource);
+
+      setState({
+        ...initialState,
+        status: "awaiting_authorization",
+        verificationUrl: authResponse.verification_uri_complete,
+        userCode: authResponse.user_code,
+      });
+
+      try {
+        const tokenResponse = await pollForToken(
+          host,
+          authResponse.device_code,
+          {
+            interval: authResponse.interval,
+            signal: abortController.signal,
+          },
+        );
+
+        if (abortController.signal.aborted) return;
+
+        trackCloudDeviceAuthorizationSucceeded(host, analyticsSource);
+
+        setState({
+          ...initialState,
+          status: "success",
+          apiKey: tokenResponse.access_token,
+        });
+      } catch (error) {
+        // Early return if component unmounted or user cancelled
+        if (abortController.signal.aborted) return;
+
+        // Defensive: handle cancellation errors that may slip through
+        // (currently pollForToken only throws "cancelled" when signal.aborted,
+        // which is caught above, but this guards against future changes)
+        const isCancel =
+          error instanceof DeviceFlowError && error.code === "cancelled";
+        if (isCancel) {
+          setState(initialState);
+          return;
+        }
+
+        const message =
+          error instanceof Error ? error.message : "Authorization failed";
+        const code = error instanceof DeviceFlowError ? error.code : undefined;
+
+        setState({
+          ...initialState,
+          status: "error",
+          error: message,
+          errorCode: code ?? null,
+        });
+      }
+    })();
+  }, []);
+
+  const cancel = React.useCallback(() => {
+    abortControllerRef.current?.abort();
+    abortControllerRef.current = null;
+    setState(initialState);
+  }, []);
+
+  const reset = React.useCallback(() => {
+    abortControllerRef.current?.abort();
+    abortControllerRef.current = null;
+    setState(initialState);
+  }, []);
+
+  // Cleanup on unmount
+  React.useEffect(() => {
+    return () => {
+      abortControllerRef.current?.abort();
+    };
+  }, []);
+
+  return {
+    ...state,
+    start,
+    cancel,
+    reset,
+  };
+}

src/hooks/use-ensure-active-profile.ts

@@ -0,0 +1,51 @@
+import { useEffect, useRef } from "react";
+import { useActiveBackend } from "#/contexts/active-backend-context";
+import { useLlmProfiles } from "#/hooks/query/use-llm-profiles";
+import { useActivateLlmProfile } from "#/hooks/mutation/use-activate-llm-profile";
+
+/**
+ * Local-mode UX policy: keep an LLM profile active whenever at least one
+ * exists, so the agent always has a usable LLM without a manual "activate"
+ * step. This lives in the client on purpose — the agent-server is a neutral
+ * API that returns `active_profile` as stored (possibly pointing at a deleted
+ * profile); other consumers (e.g. SaaS) own the LLM differently.
+ *
+ * When profiles exist but none is the active one — never activated, or the
+ * active profile was deleted — it activates the first profile that has an API
+ * key (falling back to the first profile). With zero profiles it does nothing:
+ * that genuine "no LLM" state is surfaced by the gate/banner.
+ */
+export function useEnsureActiveProfile(): void {
+  const { backend } = useActiveBackend();
+  const isLocal = backend.kind === "local";
+  const { data: profilesData } = useLlmProfiles();
+  const { mutate: activate, isPending } = useActivateLlmProfile();
+
+  // Remember the last profile we tried to activate so we don't re-fire while
+  // the mutation + refetch settle, or hammer a profile whose activation fails.
+  const attemptedRef = useRef<string | null>(null);
+
+  // A backend switch is a clean slate for the above guard.
+  useEffect(() => {
+    attemptedRef.current = null;
+  }, [backend.id]);
+
+  useEffect(() => {
+    if (!isLocal || isPending || !profilesData) return;
+
+    const { profiles, active_profile: activeProfile } = profilesData;
+    const activeValid =
+      activeProfile != null && profiles.some((p) => p.name === activeProfile);
+
+    if (profiles.length === 0 || activeValid) {
+      attemptedRef.current = null;
+      return;
+    }
+
+    // Prefer a profile with a key so the result is immediately usable.
+    const target = profiles.find((p) => p.api_key_set) ?? profiles[0];
+    if (attemptedRef.current === target.name) return;
+    attemptedRef.current = target.name;
+    activate(target.name);
+  }, [isLocal, profilesData, isPending, activate]);
+}

src/hooks/use-handle-plan-click.ts

@@ -0,0 +1,251 @@
+import { useCallback, useEffect, type MouseEvent } from "react";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useTranslation } from "react-i18next";
+import { I18nKey } from "#/i18n/declaration";
+import { useConversationStore } from "#/stores/conversation-store";
+import { useActiveConversation } from "#/hooks/query/use-active-conversation";
+import { useCreateConversation } from "#/hooks/mutation/use-create-conversation";
+import {
+  displayErrorToast,
+  displaySuccessToast,
+} from "#/utils/custom-toast-handlers";
+import {
+  getConversationState,
+  setConversationState,
+} from "#/utils/conversation-local-storage";
+import { useActiveBackend } from "#/contexts/active-backend-context";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import { getStoredConversationMetadata } from "#/api/conversation-metadata-store";
+import {
+  CONVERSATION_QUERY_KEYS,
+  LOCAL_PLANNER_MUTATION_KEYS,
+} from "#/hooks/query/query-keys";
+import { useSubConversations } from "#/hooks/query/use-sub-conversations";
+import { findPlannerConversationId } from "#/utils/plan-file";
+import { invalidateConversationQueries } from "#/hooks/mutation/conversation-mutation-utils";
+
+function useCreateLocalPlanningConversationMutation(options: {
+  onCreated: (planningConversationId: string) => void;
+  onInitialized: () => void;
+  onFailed: () => void;
+}) {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationKey: LOCAL_PLANNER_MUTATION_KEYS.create,
+    mutationFn: (variables: {
+      parentConversationId: string;
+      initialMessage?: string;
+    }) =>
+      AgentServerConversationService.createLocalPlanningConversation(
+        variables.parentConversationId,
+        variables.initialMessage,
+      ),
+    onSuccess: (planningConversation, variables) => {
+      options.onCreated(planningConversation.id);
+      invalidateConversationQueries(
+        queryClient,
+        variables.parentConversationId,
+      );
+      queryClient.invalidateQueries({
+        queryKey: CONVERSATION_QUERY_KEYS.subConversations,
+      });
+      options.onInitialized();
+    },
+    onError: options.onFailed,
+  });
+}
+
+function restorePlanningConversationIds(options: {
+  conversationId: string;
+  serverPlanningConversationId: string | null;
+  subConversationTaskId: string | null;
+  localPlanningConversationId: string | null;
+  setSubConversationTaskId: (taskId: string | null) => void;
+  setLocalPlanningConversationId: (conversationId: string | null) => void;
+}) {
+  const storedState = getConversationState(options.conversationId);
+  if (storedState.subConversationTaskId && !options.subConversationTaskId) {
+    options.setSubConversationTaskId(storedState.subConversationTaskId);
+  }
+
+  // Server first: `sub_conversation_ids` is derived by the agent-server from
+  // the planner's `parent_conversation_id`, so it survives cleared site data
+  // and follows the user to another browser. The localStorage hint is only the
+  // fallback for agent-servers older than 1.37.1, which drop the parent link.
+  const restoredId =
+    options.serverPlanningConversationId ??
+    getStoredConversationMetadata(options.conversationId)
+      ?.local_planning_conversation_id ??
+    null;
+
+  if (restoredId && restoredId !== options.localPlanningConversationId) {
+    options.setLocalPlanningConversationId(restoredId);
+  }
+}
+
+/**
+ * Custom hook that encapsulates the logic for handling plan creation.
+ * Returns a function that can be called to create a plan conversation and
+ * the pending state of the conversation creation.
+ *
+ * @returns An object containing handlePlanClick function and isCreatingConversation boolean
+ */
+export const useHandlePlanClick = () => {
+  const { t } = useTranslation("openhands");
+  const { backend } = useActiveBackend();
+  const {
+    setConversationMode,
+    setSubConversationTaskId,
+    subConversationTaskId,
+    setLocalPlanningConversationId,
+    localPlanningConversationId,
+  } = useConversationStore();
+  const { data: conversation } = useActiveConversation();
+  const { mutate: createConversation, isPending: isCreatingCloudConversation } =
+    useCreateConversation();
+  const {
+    mutate: createLocalPlanningConversation,
+    isPending: isCreatingLocalPlanningConversation,
+  } = useCreateLocalPlanningConversationMutation({
+    onCreated: setLocalPlanningConversationId,
+    onInitialized: () => {
+      displaySuccessToast(
+        t(I18nKey.PLANNING_AGENTT$PLANNING_AGENT_INITIALIZED),
+      );
+    },
+    // handlePlanClick sets conversationMode("plan") before this mutation
+    // starts. On failure, back out of that mode instead of stranding the
+    // user in plan mode with no planner to talk to.
+    onFailed: () => {
+      setConversationMode("code");
+      displayErrorToast(t(I18nKey.CONVERSATION$ERROR_STARTING_CONVERSATION));
+    },
+  });
+
+  // On local backends the agent-server reports the planner helper back on the
+  // parent's `sub_conversation_ids` (it was created with
+  // `parent_conversation_id`), so that is the authoritative handle. Cloud
+  // sub-conversations are driven by their own task/socket plumbing.
+  const isLocalBackend = backend.kind !== "cloud";
+  const { data: rawSubConversations } = useSubConversations(
+    isLocalBackend ? conversation?.sub_conversation_ids : undefined,
+  );
+
+  const serverPlanningConversationId = isLocalBackend
+    ? findPlannerConversationId(rawSubConversations, conversation?.id)
+    : null;
+
+  // Restore planning conversation ids on conversation load. This handles page
+  // refreshes while cloud or local planning conversation creation is in
+  // progress, and recovers the local planner after browser storage is lost.
+  useEffect(() => {
+    if (!conversation?.id) return;
+
+    restorePlanningConversationIds({
+      conversationId: conversation.id,
+      serverPlanningConversationId,
+      subConversationTaskId,
+      localPlanningConversationId,
+      setSubConversationTaskId,
+      setLocalPlanningConversationId,
+    });
+  }, [
+    conversation?.id,
+    serverPlanningConversationId,
+    localPlanningConversationId,
+    setLocalPlanningConversationId,
+    subConversationTaskId,
+    setSubConversationTaskId,
+  ]);
+
+  const hasCloudPlanner = !!(
+    (conversation?.sub_conversation_ids &&
+      conversation.sub_conversation_ids.length > 0) ||
+    subConversationTaskId
+  );
+  // Whether a planner helper already exists for this conversation — callers
+  // (e.g. the `/plan <task>` interceptor) use this to decide whether they can
+  // send a message to the planner immediately, or must wait for creation.
+  const hasPlanner = isLocalBackend
+    ? !!(localPlanningConversationId || serverPlanningConversationId)
+    : hasCloudPlanner;
+
+  const handlePlanClick = useCallback(
+    (
+      event?: MouseEvent<HTMLButtonElement> | KeyboardEvent,
+      initialMessage?: string,
+    ) => {
+      event?.preventDefault();
+      event?.stopPropagation();
+
+      setConversationMode("plan");
+
+      if (backend.kind !== "cloud") {
+        // Guard on the server-reported helper, the store, and the mutation's
+        // own in-flight state — the last one stops two rapid invocations
+        // (e.g. a double-click) from both passing before either updates and
+        // creating two planners for the same parent.
+        if (
+          !conversation?.id ||
+          localPlanningConversationId ||
+          serverPlanningConversationId ||
+          isCreatingLocalPlanningConversation
+        ) {
+          return;
+        }
+        createLocalPlanningConversation({
+          parentConversationId: conversation.id,
+          initialMessage,
+        });
+        return;
+      }
+
+      if (hasCloudPlanner || !conversation?.id) {
+        return;
+      }
+
+      createConversation(
+        {
+          parentConversationId: conversation.id,
+          agentType: "plan",
+          entryPoint: "plan_sub_conversation",
+          ...(initialMessage ? { query: initialMessage } : {}),
+        },
+        {
+          onSuccess: (data) => {
+            displaySuccessToast(
+              t(I18nKey.PLANNING_AGENTT$PLANNING_AGENT_INITIALIZED),
+            );
+            if (data.task_id) {
+              setSubConversationTaskId(data.task_id);
+              setConversationState(conversation.id, {
+                subConversationTaskId: data.task_id,
+              });
+            }
+          },
+        },
+      );
+    },
+    [
+      backend.kind,
+      conversation,
+      createConversation,
+      createLocalPlanningConversation,
+      hasCloudPlanner,
+      isCreatingLocalPlanningConversation,
+      localPlanningConversationId,
+      serverPlanningConversationId,
+      setConversationMode,
+      setSubConversationTaskId,
+      t,
+    ],
+  );
+
+  return {
+    handlePlanClick,
+    hasPlanner,
+    isCreatingConversation:
+      isCreatingCloudConversation || isCreatingLocalPlanningConversation,
+  };
+};

src/hooks/use-handle-runtime-active.ts

@@ -0,0 +1,10 @@
+import { RUNTIME_INACTIVE_STATES } from "#/types/agent-state";
+import { useAgentState } from "#/hooks/use-agent-state";
+
+export const useHandleRuntimeActive = () => {
+  const { curAgentState } = useAgentState();
+
+  const runtimeActive = !RUNTIME_INACTIVE_STATES.includes(curAgentState);
+
+  return { runtimeActive };
+};

src/hooks/use-handle-ws-events.ts

@@ -0,0 +1,63 @@
+import React from "react";
+import { generateAgentStateChangeEvent } from "#/services/agent-state-service";
+import { AgentState } from "#/types/agent-state";
+import { displayErrorToast } from "#/utils/custom-toast-handlers";
+import { useEventStore } from "#/stores/use-event-store";
+import { useSendMessage } from "#/hooks/use-send-message";
+import {
+  isAgentErrorEvent,
+  isAgentServerEvent,
+} from "#/types/agent-server/type-guards";
+
+interface ServerError {
+  error: boolean | string;
+  message: string;
+  [key: string]: unknown;
+}
+
+const isServerError = (data: object): data is ServerError => "error" in data;
+
+const isTypedErrorEvent = (
+  event: object,
+): event is { type: "error"; message?: unknown } =>
+  "type" in event && event.type === "error";
+
+export const useHandleWSEvents = () => {
+  const { send } = useSendMessage();
+  const events = useEventStore((state) => state.events);
+
+  React.useEffect(() => {
+    if (!events.length) {
+      return;
+    }
+    const event = events[events.length - 1];
+
+    // V1 agent errors are surfaced inline in the chat log (and via the error
+    // banner), so don't double-notify with a toast.
+    if (isAgentServerEvent(event) && isAgentErrorEvent(event)) {
+      return;
+    }
+
+    if (isServerError(event)) {
+      if (event.error_code === 401) {
+        displayErrorToast("Session expired.");
+        return;
+      }
+
+      if (typeof event.error === "string") {
+        displayErrorToast(event.error);
+      } else {
+        displayErrorToast(event.message);
+      }
+      return;
+    }
+
+    if (isTypedErrorEvent(event)) {
+      const message: string = `${event.message ?? ""}`;
+      if (message.startsWith("Agent reached maximum")) {
+        // We set the agent state to paused here - if the user clicks resume, it auto updates the max iterations
+        send(generateAgentStateChangeEvent(AgentState.PAUSED));
+      }
+    }
+  }, [events.length]);
+};

src/hooks/use-llm-configured.test.tsx

@@ -0,0 +1,176 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import OptionService from "#/api/option-service/option-service.api";
+import ProfilesService from "#/api/profiles-service/profiles-service.api";
+import {
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { DEFAULT_SETTINGS } from "#/services/settings";
+import { useLlmConfigured } from "./use-llm-configured";
+
+vi.mock("#/api/settings-service/settings-service.api", () => ({
+  default: {
+    getSettings: vi.fn(),
+  },
+}));
+
+vi.mock("#/api/option-service/option-service.api", () => ({
+  default: {
+    getConfig: vi.fn(),
+  },
+}));
+
+vi.mock("#/api/profiles-service/profiles-service.api", () => ({
+  default: {
+    listProfiles: vi.fn(),
+    getProfile: vi.fn(),
+  },
+}));
+
+const localBackend: Backend = {
+  id: "test-local",
+  name: "Test Local",
+  host: "http://localhost:8001",
+  apiKey: "test-key",
+  kind: "local",
+};
+
+function renderLlmConfiguredHook() {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+    },
+  });
+
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={queryClient}>
+      <ActiveBackendProvider>{children}</ActiveBackendProvider>
+    </QueryClientProvider>
+  );
+
+  return renderHook(() => useLlmConfigured(), { wrapper });
+}
+
+describe("useLlmConfigured", () => {
+  const mockGetSettings = vi.mocked(SettingsService.getSettings);
+  const mockGetConfig = vi.mocked(OptionService.getConfig);
+  const mockListProfiles = vi.mocked(ProfilesService.listProfiles);
+  const mockGetProfile = vi.mocked(ProfilesService.getProfile);
+
+  beforeEach(() => {
+    setRegisteredBackends([localBackend]);
+    setActiveSelection({ backendId: localBackend.id });
+
+    mockGetSettings.mockResolvedValue({
+      ...DEFAULT_SETTINGS,
+      llm_api_key_set: false,
+      agent_settings: {
+        ...(DEFAULT_SETTINGS.agent_settings ?? {}),
+        agent_kind: "openhands",
+        llm: {
+          model: "openai/gpt-5.5",
+          auth_type: "subscription",
+          subscription_vendor: "openai",
+        },
+      },
+    });
+    mockGetConfig.mockResolvedValue({
+      feature_flags: { hide_llm_settings: false },
+    } as Awaited<ReturnType<typeof OptionService.getConfig>>);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+    setActiveSelection(null);
+    setRegisteredBackends([]);
+  });
+
+  it("treats an active subscription LLM profile without an API key as configured", async () => {
+    mockListProfiles.mockResolvedValue({
+      active_profile: "gpt-5.5-sub",
+      profiles: [
+        {
+          name: "gpt-5.5-sub",
+          model: "gpt-5.5",
+          base_url: "https://chatgpt.com/backend-api/codex",
+          api_key_set: false,
+        },
+      ],
+    });
+    mockGetProfile.mockResolvedValue({
+      name: "gpt-5.5-sub",
+      api_key_set: false,
+      config: {
+        model: "openai/gpt-5.5",
+        auth_type: "subscription",
+        subscription_vendor: "openai",
+      },
+    });
+
+    const { result } = renderLlmConfiguredHook();
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.isConfigured).toBe(true);
+    expect(mockGetProfile).toHaveBeenCalledWith("gpt-5.5-sub");
+  });
+
+  it("uses the api_key_set fast path for an API-key profile without fetching profile detail", async () => {
+    mockListProfiles.mockResolvedValue({
+      active_profile: "gpt-5.5",
+      profiles: [
+        {
+          name: "gpt-5.5",
+          model: "gpt-5.5",
+          base_url: "https://api.openai.com/v1",
+          api_key_set: true,
+        },
+      ],
+    });
+
+    const { result } = renderLlmConfiguredHook();
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.isConfigured).toBe(true);
+    // The fast path must not fetch active profile detail.
+    expect(mockGetProfile).not.toHaveBeenCalled();
+  });
+
+  it("treats a no-key, non-subscription local profile as not configured", async () => {
+    mockListProfiles.mockResolvedValue({
+      active_profile: "gpt-5.5",
+      profiles: [
+        {
+          name: "gpt-5.5",
+          model: "gpt-5.5",
+          base_url: "https://api.openai.com/v1",
+          api_key_set: false,
+        },
+      ],
+    });
+    mockGetProfile.mockResolvedValue({
+      name: "gpt-5.5",
+      api_key_set: false,
+      config: {
+        model: "openai/gpt-5.5",
+        // No auth_type: "subscription" — this is a plain key-less profile,
+        // not a subscription-authenticated one, so it must be unconfigured.
+      },
+    });
+
+    const { result } = renderLlmConfiguredHook();
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.isConfigured).toBe(false);
+    // Detail is fetched because the profile is local + active + key-less.
+    expect(mockGetProfile).toHaveBeenCalledWith("gpt-5.5");
+  });
+});

src/hooks/use-migrate-enabled-skills.ts

@@ -0,0 +1,43 @@
+import { useEffect, useRef } from "react";
+import { isNoBackend } from "#/api/backend-registry/active-store";
+import { useActiveBackend } from "#/contexts/active-backend-context";
+import { useSaveSettings } from "#/hooks/mutation/use-save-settings";
+import { useSettings } from "#/hooks/query/use-settings";
+import {
+  migrateSkillEnablement,
+  toSkillEnablement,
+} from "#/utils/skill-enablement";
+
+/**
+ * Move a workspace to an explicit `enabled_skills` allow-list, once.
+ *
+ * It runs at the app root, not on the Customize page: until it has run the
+ * resolver falls back to the curated default, which would silently drop
+ * catalog skills an existing workspace had switched on. Local only — cloud
+ * never reads the field.
+ */
+export function useMigrateEnabledSkills(): void {
+  const { backend } = useActiveBackend();
+  const isLocal = backend.kind === "local" && !isNoBackend(backend);
+  const { data: settings, isLoading, isError } = useSettings();
+  const { mutate: saveSettings } = useSaveSettings();
+
+  // One attempt per backend: the save invalidates the settings query, so
+  // without this the refetch would re-enter before the write is visible.
+  const migratedBackendRef = useRef<string | null>(null);
+
+  useEffect(() => {
+    migratedBackendRef.current = null;
+  }, [backend.id]);
+
+  useEffect(() => {
+    if (!isLocal || isLoading || isError || !settings) return;
+    if (migratedBackendRef.current === backend.id) return;
+
+    migratedBackendRef.current = backend.id;
+    const migrated = migrateSkillEnablement(toSkillEnablement(settings));
+    // Silent on failure: the resolver's fallback keeps the session working and
+    // the next app load retries.
+    if (migrated) saveSettings(migrated);
+  }, [isLocal, isLoading, isError, settings, backend.id, saveSettings]);
+}

src/hooks/use-pinned-home-route.ts

@@ -0,0 +1,113 @@
+import { useLocalStorage } from "@uidotdev/usehooks";
+import { useCallback, useMemo } from "react";
+import {
+  getActiveBackend,
+  isNoBackend,
+} from "#/api/backend-registry/active-store";
+import { useActiveBackend } from "#/contexts/active-backend-context";
+import {
+  automationListPath,
+  hasAutomationInterface,
+} from "#/manifests/automation-interface";
+
+export const PINNED_HOME_ROUTE_KEY = "oh:pinned-home-route";
+
+/** Sidebar Customize entry; also the pin target, so the two cannot drift. */
+export const CUSTOMIZE_PATH = "/customize";
+
+/**
+ * The pin is stored per backend + org: it may reference a surface that only
+ * exists on the backend that set it (e.g. /automations requires that
+ * deployment's interface manifest) — a shared key would let one backend
+ * redirect `/` on another.
+ */
+export function getPinnedHomeRouteKey(
+  backendId: string,
+  orgId: string | null,
+): string {
+  return `${PINNED_HOME_ROUTE_KEY}:${backendId}:${orgId ?? "-"}`;
+}
+
+/**
+ * Whether `path` may serve as the home route right now. Shared by the
+ * sidebar pin affordance and the `/` loader, so a stored pin that stops
+ * resolving (backend switch, manifest absent) is ignored rather than an
+ * error. `/` is never pinnable, which makes a redirect loop impossible.
+ * Canvas Extensions pages can later add an `/extensions/…` branch here
+ * without any storage or loader change.
+ */
+export function isPinnableRoute(path: string): boolean {
+  if (path === CUSTOMIZE_PATH) return true;
+  if (path === automationListPath()) return hasAutomationInterface();
+  return false;
+}
+
+function sanitizePinnedRoute(value: unknown): string | null {
+  if (typeof value !== "string" || !value) return null;
+  return isPinnableRoute(value) ? value : null;
+}
+
+/**
+ * Synchronous pin read for route loaders (no React context). Reads the key
+ * `usePinnedHomeRoute` writes; `useLocalStorage` JSON-serializes values, so
+ * parse defensively and treat anything unreadable as "no pin". An invalid
+ * pin is ignored, not cleared — it may become valid again (e.g. the
+ * automations interface returning after a backend switch back).
+ */
+export function readPinnedHomeRoute(): string | null {
+  const active = getActiveBackend();
+  if (isNoBackend(active.backend)) return null;
+
+  let raw: string | null = null;
+  try {
+    raw = window.localStorage.getItem(
+      getPinnedHomeRouteKey(active.backend.id, active.orgId),
+    );
+  } catch {
+    return null;
+  }
+  if (raw === null) return null;
+
+  try {
+    return sanitizePinnedRoute(JSON.parse(raw));
+  } catch {
+    return null;
+  }
+}
+
+/** Pin state for the home route: `/` redirects to the pinned sidebar page. */
+export function usePinnedHomeRoute() {
+  const active = useActiveBackend();
+  const [rawPinnedRoute, setRawPinnedRoute] = useLocalStorage<string | null>(
+    getPinnedHomeRouteKey(active.backend.id, active.orgId),
+    null,
+  );
+
+  const pinnedRoute = useMemo(
+    () => sanitizePinnedRoute(rawPinnedRoute),
+    [rawPinnedRoute],
+  );
+
+  const isPinnedRoute = useCallback(
+    (path: string) => pinnedRoute === path,
+    [pinnedRoute],
+  );
+
+  const togglePinnedRoute = useCallback(
+    (path: string) => {
+      if (pinnedRoute === path) {
+        setRawPinnedRoute(null);
+        return;
+      }
+      if (!isPinnableRoute(path)) return;
+      setRawPinnedRoute(path);
+    },
+    [pinnedRoute, setRawPinnedRoute],
+  );
+
+  return {
+    pinnedRoute,
+    isPinnedRoute,
+    togglePinnedRoute,
+  };
+}

src/hooks/use-popover-fixed-placement.ts

@@ -0,0 +1,56 @@
+import React from "react";
+
+export interface FixedPlacementBox {
+  top: number;
+  left: number;
+  width: number;
+}
+
+/**
+ * Position a popover with `position: fixed`, anchored below the trigger and
+ * clamped within the viewport. Used by the conversation-panel "+ New
+ * conversation" menus when they're rendered inside an overflow-hidden
+ * sidebar and would otherwise be clipped.
+ *
+ * Returns the measured `{ top, left, width }` box (or `null` when the
+ * popover is closed or fixed placement is disabled). The hook also wires
+ * up window resize + capture-phase scroll listeners so the box follows the
+ * trigger as the page moves.
+ */
+export function usePopoverFixedPlacement(
+  triggerRef: React.RefObject<HTMLElement | null>,
+  options: { open: boolean; enabled: boolean; targetWidth?: number },
+): FixedPlacementBox | null {
+  const { open, enabled, targetWidth = 16 * 16 } = options;
+  const [box, setBox] = React.useState<FixedPlacementBox | null>(null);
+
+  const measure = React.useCallback(() => {
+    const el = triggerRef.current;
+    if (!el) return;
+    const r = el.getBoundingClientRect();
+    const gutter = 8;
+    const width = Math.min(targetWidth, window.innerWidth - gutter * 2);
+    let left = r.right - width;
+    if (left < gutter) left = gutter;
+    if (left + width > window.innerWidth - gutter) {
+      left = Math.max(gutter, window.innerWidth - gutter - width);
+    }
+    setBox({ top: r.bottom + 4, left, width });
+  }, [triggerRef, targetWidth]);
+
+  React.useLayoutEffect(() => {
+    if (!open || !enabled) {
+      setBox(null);
+      return undefined;
+    }
+    measure();
+    window.addEventListener("resize", measure);
+    window.addEventListener("scroll", measure, true);
+    return () => {
+      window.removeEventListener("resize", measure);
+      window.removeEventListener("scroll", measure, true);
+    };
+  }, [open, enabled, measure]);
+
+  return box;
+}

src/hooks/use-resizable-drawer-width.ts

@@ -0,0 +1,126 @@
+import {
+  useCallback,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type RefObject,
+} from "react";
+import { useLocalStorage } from "@uidotdev/usehooks";
+
+const PANEL_DRAG_SHIELD_Z_INDEX = 200;
+
+type ResizableDrawerEdge = "left" | "right";
+
+interface UseResizableDrawerWidthOptions {
+  containerRef: RefObject<HTMLElement | null>;
+  defaultWidth: number;
+  minWidth: number;
+  maxWidth: number;
+  storageKey: string;
+  enabled?: boolean;
+  /**
+   * Which side of the container the panel is anchored to.
+   * - `"right"` (default): width grows leftward from the container's right edge
+   * - `"left"`: width grows rightward from the container's left edge
+   */
+  edge?: ResizableDrawerEdge;
+}
+
+export function useResizableDrawerWidth({
+  containerRef,
+  defaultWidth,
+  minWidth,
+  maxWidth,
+  storageKey,
+  enabled = true,
+  edge = "right",
+}: UseResizableDrawerWidthOptions) {
+  const [persistedWidth, setPersistedWidth] = useLocalStorage<number>(
+    storageKey,
+    defaultWidth,
+  );
+
+  const clampWidth = useCallback(
+    (width: number) => Math.max(minWidth, Math.min(maxWidth, width)),
+    [minWidth, maxWidth],
+  );
+
+  const [drawerWidth, setDrawerWidth] = useState(() =>
+    clampWidth(persistedWidth),
+  );
+  const [isDragging, setIsDragging] = useState(false);
+  const drawerWidthRef = useRef(drawerWidth);
+
+  drawerWidthRef.current = drawerWidth;
+
+  const handleMouseDown = useCallback(
+    (event: React.MouseEvent) => {
+      if (!enabled) {
+        return;
+      }
+      event.preventDefault();
+      setIsDragging(true);
+    },
+    [enabled],
+  );
+
+  const handleMouseMove = useCallback(
+    (event: MouseEvent) => {
+      if (!isDragging || !containerRef.current) {
+        return;
+      }
+
+      const containerRect = containerRef.current.getBoundingClientRect();
+      const nextWidth =
+        edge === "left"
+          ? event.clientX - containerRect.left
+          : containerRect.right - event.clientX;
+      setDrawerWidth(clampWidth(nextWidth));
+    },
+    [clampWidth, containerRef, edge, isDragging],
+  );
+
+  const handleMouseUp = useCallback(() => {
+    if (!isDragging) {
+      return;
+    }
+    setIsDragging(false);
+    setPersistedWidth(drawerWidthRef.current);
+  }, [isDragging, setPersistedWidth]);
+
+  useLayoutEffect(() => {
+    if (!isDragging) {
+      return undefined;
+    }
+
+    const shield = document.createElement("div");
+    shield.setAttribute("aria-hidden", "true");
+    shield.dataset.panelDragShield = "";
+    Object.assign(shield.style, {
+      position: "fixed",
+      inset: "0",
+      zIndex: String(PANEL_DRAG_SHIELD_Z_INDEX),
+      cursor: "ew-resize",
+    });
+    document.body.appendChild(shield);
+
+    document.addEventListener("mousemove", handleMouseMove);
+    document.addEventListener("mouseup", handleMouseUp);
+    document.body.style.cursor = "ew-resize";
+    document.body.style.userSelect = "none";
+
+    return () => {
+      document.removeEventListener("mousemove", handleMouseMove);
+      document.removeEventListener("mouseup", handleMouseUp);
+      document.body.style.cursor = "";
+      document.body.style.userSelect = "";
+      shield.remove();
+    };
+  }, [handleMouseMove, handleMouseUp, isDragging]);
+
+  return {
+    drawerWidth,
+    isDragging,
+    handleMouseDown,
+  };
+}

src/hooks/use-skill-installs.ts

@@ -0,0 +1,33 @@
+import { useCallback, useMemo } from "react";
+import { useEventStore } from "#/stores/use-event-store";
+import { useSkillInstallBannerStore } from "#/stores/skill-install-banner-store";
+import { detectSkillInstalls } from "#/utils/skill-install-events";
+
+/**
+ * Skill installs performed by the agent in this conversation (via the
+ * bundled add-skill flow), minus the ones the user dismissed. The event
+ * store is global, so results are scoped to the conversation it currently
+ * holds — a mismatched id (remount race) yields no installs.
+ */
+export const useSkillInstalls = (conversationId: string | null | undefined) => {
+  const events = useEventStore((s) => s.events);
+  const loadedConversationId = useEventStore((s) => s.loadedConversationId);
+  const dismissedEventIds = useSkillInstallBannerStore(
+    (s) => s.dismissedEventIds,
+  );
+  const dismiss = useSkillInstallBannerStore((s) => s.dismiss);
+
+  const installs = useMemo(() => {
+    if (!conversationId || conversationId !== loadedConversationId) return [];
+    return detectSkillInstalls(events).filter(
+      (install) => !dismissedEventIds[install.eventId],
+    );
+  }, [conversationId, loadedConversationId, events, dismissedEventIds]);
+
+  const dismissAll = useCallback(
+    () => dismiss(installs.map((install) => install.eventId)),
+    [dismiss, installs],
+  );
+
+  return { installs, dismissAll };
+};

src/hooks/use-task-list.ts

@@ -0,0 +1,48 @@
+import { useMemo } from "react";
+import { useEventStore } from "#/stores/use-event-store";
+import { isObservationEvent } from "#/types/agent-server/type-guards";
+import type { TaskTrackerObservation } from "#/types/agent-server/core/base/observation";
+import type { ObservationEvent } from "#/types/agent-server/core/events/observation-event";
+
+export interface TaskListItem {
+  id: string;
+  title: string;
+  status: "todo" | "in_progress" | "done";
+  notes?: string;
+}
+
+function getTaskListFromEvent(
+  event: ReturnType<typeof useEventStore.getState>["events"][number],
+): TaskListItem[] | null {
+  if (
+    isObservationEvent(event) &&
+    event.observation.kind === "TaskTrackerObservation"
+  ) {
+    const obs = (event as ObservationEvent<TaskTrackerObservation>).observation;
+    if (obs.command === "plan") {
+      return obs.task_list.map((t, i) => ({
+        id: String(i + 1),
+        title: t.title,
+        status: t.status,
+        notes: t.notes || undefined,
+      }));
+    }
+  }
+
+  return null;
+}
+
+export function useTaskList() {
+  const events = useEventStore((state) => state.events);
+
+  return useMemo(() => {
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+      const taskList = getTaskListFromEvent(events[i]);
+      if (taskList) {
+        return { taskList, hasTaskList: taskList.length > 0 };
+      }
+    }
+
+    return { taskList: [] as TaskListItem[], hasTaskList: false };
+  }, [events]);
+}

src/hooks/use-tracking.ts

@@ -0,0 +1,500 @@
+import React from "react";
+import { Provider } from "#/types/settings";
+import type { BackendKind } from "#/api/backend-registry/types";
+import type { WorkspaceMode } from "#/api/conversation-metadata-store";
+import type { CloudConnectionSource } from "#/services/cloud-funnel-analytics";
+import { getCachedAgentServerVersion } from "#/api/agent-server-compatibility";
+import { useActiveBackend } from "#/contexts/active-backend-context";
+import { useAutomationSdkVersion } from "#/hooks/query/use-automation-sdk-version";
+import {
+  type BackendConnectionMethod,
+  getBackendTelemetryProperties,
+} from "#/services/telemetry-context";
+import { setTelemetryBackendContext, trackEvent } from "#/services/telemetry";
+
+/**
+ * Stable semantic identifier for an onboarding link or CTA. Identifies the
+ * destination, never the clicked element or its text.
+ */
+export type OnboardingLinkId =
+  | "configure_llm"
+  | "start_conversation"
+  | "schedule_task"
+  | "customize_agent"
+  | "connect_mcp"
+  | "join_slack"
+  | "open_docs";
+
+/** Controlled destination category for `onboarding_link_clicked`. */
+export type OnboardingLinkDestinationType =
+  | "community"
+  | "integration"
+  | "documentation"
+  | "settings"
+  | "conversation"
+  | "automation";
+
+/** Onboarding surface that presented the link. */
+export type OnboardingLinkSurface = "landing_checklist" | "onboarding_modal";
+
+/**
+ * Hook that provides tracking functions with automatic data collection
+ * from available hooks (settings, etc.)
+ *
+ * All events require explicit user consent. The shared PostHog client enforces
+ * the canonical consent configured by telemetry.ts; this hook must not gate on
+ * backend settings because they can be stale while a backend changes.
+ */
+export const useTracking = () => {
+  const { backend } = useActiveBackend();
+  const automationSdkVersion = useAutomationSdkVersion();
+
+  const getBackendTelemetryContext = React.useCallback(
+    () => ({
+      backendKind: backend.kind,
+      agentServerVersion:
+        backend.kind === "local"
+          ? getCachedAgentServerVersion(backend.host)
+          : null,
+      automationSdkVersion: automationSdkVersion ?? null,
+    }),
+    [automationSdkVersion, backend.host, backend.kind],
+  );
+
+  React.useEffect(() => {
+    setTelemetryBackendContext(getBackendTelemetryContext());
+  }, [getBackendTelemetryContext]);
+
+  // Common properties included in all tracking events
+  const commonProperties = {
+    current_url: window.location.href,
+  };
+
+  /**
+   * PostHog enforces the canonical consent state configured by telemetry.ts.
+   * Backend settings are not a capture gate because they can be stale while a
+   * backend is being added or switched.
+   */
+  const track = (event: string, properties: Record<string, unknown> = {}) => {
+    setTelemetryBackendContext(getBackendTelemetryContext());
+    void trackEvent(event, { ...commonProperties, ...properties });
+  };
+
+  const trackLoginButtonClick = ({ provider }: { provider: Provider }) => {
+    track("login_button_clicked", { provider });
+  };
+
+  const trackConversationCreated = ({
+    conversationId,
+    taskId,
+    hasRepository,
+    gitProvider,
+    hasWorkspace,
+    workspaceMode,
+    hasInitialQuery,
+    agentType,
+    hasParentConversation,
+    entryPoint,
+  }: {
+    conversationId: string;
+    taskId?: string;
+    hasRepository: boolean;
+    gitProvider?: Provider;
+    hasWorkspace: boolean;
+    workspaceMode?: WorkspaceMode;
+    hasInitialQuery: boolean;
+    agentType?: "default" | "plan";
+    hasParentConversation: boolean;
+    entryPoint?: string;
+  }) => {
+    track("conversation_start_requested", {
+      conversation_id: conversationId,
+      task_id: taskId,
+      is_start_task: conversationId.startsWith("task-"),
+      has_repository: hasRepository,
+      git_provider: gitProvider,
+      has_workspace: hasWorkspace,
+      workspace_mode: workspaceMode,
+      has_initial_query: hasInitialQuery,
+      agent_type: agentType,
+      has_parent_conversation: hasParentConversation,
+      entry_point: entryPoint,
+    });
+  };
+
+  const trackPushButtonClick = () => {
+    track("push_button_clicked");
+  };
+
+  const trackPullButtonClick = () => {
+    track("pull_button_clicked");
+  };
+
+  const trackCreatePrButtonClick = () => {
+    track("create_pr_button_clicked");
+  };
+
+  const trackUserSignupCompleted = () => {
+    track("user_signup_completed", {
+      signup_timestamp: new Date().toISOString(),
+    });
+  };
+
+  const trackPrebuiltAutomationEnabled = ({
+    automationId,
+    automationName,
+    automationCategory,
+  }: {
+    automationId?: string;
+    automationName: string;
+    automationCategory?: string;
+  }) => {
+    track("prebuilt_automation_enabled", {
+      automation_id: automationId,
+      automation_name: automationName,
+      automation_category: automationCategory,
+    });
+  };
+
+  /**
+   * The setup funnel: opened → validated → created, or failed.
+   *
+   * A manifest declares no analytics of its own, so the stages are the same for
+   * every entry and only the id it carries varies.
+   */
+  const trackAutomationSetupOpened = ({
+    automationId,
+  }: {
+    automationId: string;
+  }) => {
+    track("automation_setup_opened", { automation_id: automationId });
+  };
+
+  const trackAutomationSetupValidated = ({
+    automationId,
+  }: {
+    automationId: string;
+  }) => {
+    track("automation_setup_validated", { automation_id: automationId });
+  };
+
+  const trackAutomationSetupCreated = ({
+    automationId,
+    setupMode,
+  }: {
+    automationId: string;
+    setupMode: string;
+  }) => {
+    track("automation_setup_created", {
+      automation_id: automationId,
+      setup_mode: setupMode,
+    });
+  };
+
+  const trackAutomationSetupFailed = ({
+    automationId,
+    setupMode,
+  }: {
+    automationId: string;
+    setupMode: string;
+  }) => {
+    track("automation_setup_failed", {
+      automation_id: automationId,
+      setup_mode: setupMode,
+    });
+  };
+
+  const trackInitialQuerySubmitted = ({
+    entryPoint,
+    queryCharacterLength,
+    replayJsonSize,
+  }: {
+    entryPoint: string;
+    queryCharacterLength: number;
+    replayJsonSize?: number;
+  }) => {
+    track("initial_query_submitted", {
+      entry_point: entryPoint,
+      query_character_length: queryCharacterLength,
+      replay_json_size: replayJsonSize,
+    });
+  };
+
+  const trackUserMessageSent = ({
+    sessionMessageCount,
+    currentMessageLength,
+  }: {
+    sessionMessageCount: number;
+    currentMessageLength: number;
+  }) => {
+    track("user_message_sent", {
+      session_message_count: sessionMessageCount,
+      current_message_length: currentMessageLength,
+    });
+  };
+
+  const trackDownloadVsCodeButtonClicked = () => {
+    track("download_via_vscode_button_clicked");
+  };
+
+  const trackSettingsSaved = ({
+    llmModel,
+    llmApiKeySet,
+    searchApiKeySet,
+    remoteRuntimeResourceFactor,
+  }: {
+    llmModel: unknown;
+    llmApiKeySet: "SET" | "UNSET";
+    searchApiKeySet: "SET" | "UNSET";
+    remoteRuntimeResourceFactor?: unknown;
+  }) => {
+    track("settings_saved", {
+      LLM_MODEL: llmModel,
+      LLM_API_KEY_SET: llmApiKeySet,
+      SEARCH_API_KEY_SET: searchApiKeySet,
+      REMOTE_RUNTIME_RESOURCE_FACTOR: remoteRuntimeResourceFactor,
+    });
+  };
+
+  const trackMcpConfigUpdated = ({
+    sseServersCount,
+    stdioServersCount,
+  }: {
+    sseServersCount: number;
+    stdioServersCount: number;
+  }) => {
+    track("mcp_config_updated", {
+      has_mcp_config: true,
+      sse_servers_count: sseServersCount,
+      stdio_servers_count: stdioServersCount,
+    });
+  };
+
+  const trackDownloadTrajectoryButtonClicked = () => {
+    track("download_trajectory_button_clicked");
+  };
+
+  const trackConversationExported = (format: "markdown" | "html") => {
+    track("conversation_exported", { format });
+  };
+
+  const trackAutomationCreatedButton = ({
+    backendKind,
+  }: {
+    backendKind: BackendKind;
+  }) => {
+    track("automation_created_button", { backend_kind: backendKind });
+  };
+
+  const trackAutomationExecuted = ({
+    backendKind,
+  }: {
+    backendKind: BackendKind;
+  }) => {
+    track("automation_executed", { backend_kind: backendKind });
+  };
+
+  const trackAutomationDeleted = ({
+    backendKind,
+  }: {
+    backendKind: BackendKind;
+  }) => {
+    track("automation_deleted", { backend_kind: backendKind });
+  };
+
+  const trackAutomationDisableButton = ({
+    backendKind,
+  }: {
+    backendKind: BackendKind;
+  }) => {
+    track("automation_disable_button", { backend_kind: backendKind });
+  };
+
+  const trackAutomationEdited = ({
+    backendKind,
+  }: {
+    backendKind: BackendKind;
+  }) => {
+    track("automation_edited", { backend_kind: backendKind });
+  };
+
+  const trackAutomationExported = ({
+    backendKind,
+  }: {
+    backendKind: BackendKind;
+  }) => {
+    track("automation_exported", { backend_kind: backendKind });
+  };
+
+  const trackAutomationActivityLogExported = ({
+    backendKind,
+    format,
+  }: {
+    backendKind: BackendKind;
+    format: "json" | "csv";
+  }) => {
+    track("automation_activity_log_exported", {
+      backend_kind: backendKind,
+      format,
+    });
+  };
+
+  const trackAutomationImported = ({
+    backendKind,
+  }: {
+    backendKind: BackendKind;
+  }) => {
+    track("automation_imported", { backend_kind: backendKind });
+  };
+
+  const trackGitSyncConfigUpdated = ({
+    backendKind,
+  }: {
+    backendKind: BackendKind;
+  }) => {
+    track("git_sync_config_updated", { backend_kind: backendKind });
+  };
+
+  const trackGitSyncTriggered = ({
+    backendKind,
+  }: {
+    backendKind: BackendKind;
+  }) => {
+    track("git_sync_triggered", { backend_kind: backendKind });
+  };
+
+  const trackBackendAdded = ({
+    backendKind,
+    connectionMethod,
+    hasApiKey,
+    source,
+    agentServerVersion,
+    backendVersion,
+  }: {
+    backendKind: BackendKind;
+    connectionMethod: BackendConnectionMethod;
+    hasApiKey: boolean;
+    source?: CloudConnectionSource;
+    agentServerVersion?: string | null;
+    backendVersion?: string | null;
+  }) => {
+    track("backend_added", {
+      ...getBackendTelemetryProperties({
+        backendKind,
+        agentServerVersion,
+        backendVersion,
+        connectionMethod,
+      }),
+      has_api_key: hasApiKey,
+      source,
+    });
+  };
+
+  const trackOnboardingStarted = () => {
+    track("onboarding_started");
+  };
+
+  const trackOnboardingStepViewed = ({
+    step,
+    stepIndex,
+    totalSteps,
+    agent,
+  }: {
+    step: string;
+    stepIndex: number;
+    totalSteps: number;
+    agent: string;
+  }) => {
+    track("onboarding_step_viewed", {
+      step,
+      step_index: stepIndex,
+      total_steps: totalSteps,
+      agent,
+    });
+  };
+
+  const trackOnboardingCompleted = ({ agent }: { agent: string }) => {
+    track("onboarding_completed", { agent });
+  };
+
+  const trackOnboardingSkipped = ({
+    step,
+    stepIndex,
+    totalSteps,
+    agent,
+  }: {
+    step: string;
+    stepIndex: number;
+    totalSteps: number;
+    agent: string;
+  }) => {
+    track("onboarding_skipped", {
+      step,
+      step_index: stepIndex,
+      total_steps: totalSteps,
+      agent,
+    });
+  };
+
+  const trackOnboardingLinkClicked = ({
+    linkId,
+    destinationType,
+    surface,
+    checklistItem,
+    stepId,
+    isExternal,
+  }: {
+    linkId: OnboardingLinkId;
+    destinationType: OnboardingLinkDestinationType;
+    surface: OnboardingLinkSurface;
+    checklistItem?: Exclude<OnboardingLinkId, "open_docs">;
+    stepId?: string;
+    isExternal: boolean;
+  }) => {
+    track("onboarding_link_clicked", {
+      link_id: linkId,
+      destination_type: destinationType,
+      surface,
+      checklist_item: checklistItem,
+      step_id: stepId,
+      is_external: isExternal,
+    });
+  };
+
+  return {
+    trackLoginButtonClick,
+    trackConversationCreated,
+    trackPushButtonClick,
+    trackPullButtonClick,
+    trackCreatePrButtonClick,
+    trackUserSignupCompleted,
+    trackPrebuiltAutomationEnabled,
+    trackAutomationSetupOpened,
+    trackAutomationSetupValidated,
+    trackAutomationSetupCreated,
+    trackAutomationSetupFailed,
+    trackInitialQuerySubmitted,
+    trackUserMessageSent,
+    trackDownloadVsCodeButtonClicked,
+    trackSettingsSaved,
+    trackMcpConfigUpdated,
+    trackDownloadTrajectoryButtonClicked,
+    trackConversationExported,
+    trackAutomationCreatedButton,
+    trackAutomationExecuted,
+    trackAutomationDeleted,
+    trackAutomationDisableButton,
+    trackAutomationEdited,
+    trackAutomationExported,
+    trackAutomationActivityLogExported,
+    trackAutomationImported,
+    trackGitSyncConfigUpdated,
+    trackGitSyncTriggered,
+    trackBackendAdded,
+    trackOnboardingStarted,
+    trackOnboardingStepViewed,
+    trackOnboardingCompleted,
+    trackOnboardingSkipped,
+    trackOnboardingLinkClicked,
+  };
+};

src/hooks/use-user-providers.ts

@@ -0,0 +1,17 @@
+import React from "react";
+import { convertRawProvidersToList } from "#/utils/convert-raw-providers-to-list";
+import { useSettings } from "./query/use-settings";
+
+export const useUserProviders = () => {
+  const { data: settings, isLoading: isLoadingSettings } = useSettings();
+
+  const providers = React.useMemo(
+    () => convertRawProvidersToList(settings?.provider_tokens_set),
+    [settings?.provider_tokens_set],
+  );
+
+  return {
+    providers,
+    isLoadingSettings,
+  };
+};

src/styles/agent-server-ui-style-scope.ts

@@ -0,0 +1,117 @@
+export const AGENT_SERVER_UI_SCOPE_ATTRIBUTE = "data-agent-server-ui";
+export const AGENT_SERVER_UI_SCOPE_SELECTOR = `[${AGENT_SERVER_UI_SCOPE_ATTRIBUTE}]`;
+export const AGENT_SERVER_UI_DEFAULT_THEME = "dark" as const;
+
+export type AgentServerUITheme = "dark" | "light" | "default";
+
+/** Brand tokens controlled by color themes — not inlined on AgentServerUIRoot. */
+export const AGENT_SERVER_UI_THEMEABLE_BRAND_VARIABLES = [
+  "--oh-color-primary",
+  "--oh-accent",
+  "--oh-warning",
+] as const;
+
+export type AgentServerUIThemeableBrandVariable =
+  (typeof AGENT_SERVER_UI_THEMEABLE_BRAND_VARIABLES)[number];
+
+export const AGENT_SERVER_UI_DEFAULT_CSS_VARIABLES = {
+  // Brand/button colors (--oh-color-primary, --oh-accent, --oh-warning) live in
+  // tailwind.css and are overridden at runtime by applyColorTheme(); keep them
+  // out of inline defaults so theme tokens are not blocked by element.style.
+  "--oh-color-logo": "#cfb755",
+  "--oh-color-base": "var(--cool-grey-950)",
+  "--oh-color-base-secondary": "var(--cool-grey-925)",
+  "--oh-color-danger": "#e76a5e",
+  "--oh-color-success": "#a5e75e",
+  "--oh-color-basic": "var(--cool-grey-400)",
+  "--oh-color-tertiary": "var(--cool-grey-800)",
+  "--oh-color-tertiary-light": "var(--cool-grey-300)",
+  "--oh-color-content": "var(--cool-grey-100)",
+  "--oh-color-content-2": "var(--cool-grey-50)",
+  "--oh-background": "var(--cool-grey-950)",
+  "--oh-foreground": "var(--cool-grey-100)",
+  "--oh-surface": "var(--cool-grey-925)",
+  "--oh-surface-foreground": "var(--cool-grey-100)",
+  "--oh-surface-raised": "var(--cool-grey-900)",
+  "--oh-surface-deep": "var(--cool-grey-975)",
+  "--oh-overlay": "var(--cool-grey-925)",
+  "--oh-overlay-foreground": "var(--cool-grey-100)",
+  "--oh-muted": "var(--cool-grey-400)",
+  "--oh-text-secondary": "var(--cool-grey-300)",
+  "--oh-text-tertiary": "var(--cool-grey-200)",
+  "--oh-text-dim": "var(--cool-grey-500)",
+  "--oh-text-subtle": "var(--cool-grey-600)",
+  "--oh-interactive-hover": "var(--cool-grey-700)",
+  "--oh-interactive-hover-low": "var(--cool-grey-900)",
+  "--oh-interactive-active": "var(--cool-grey-800)",
+  "--oh-interactive-selected": "var(--cool-grey-600)",
+  "--oh-scrollbar": "color-mix(in srgb, var(--cool-grey-400) 30%, transparent)",
+  "--oh-scrollbar-hover":
+    "color-mix(in srgb, var(--cool-grey-400) 50%, transparent)",
+  "--oh-default": "var(--cool-grey-800)",
+  "--oh-default-foreground": "var(--cool-grey-100)",
+  "--oh-accent-foreground": "var(--cool-grey-950)",
+  "--oh-success": "#a5e75e",
+  "--oh-success-foreground": "var(--cool-grey-950)",
+  "--oh-warning-foreground": "var(--cool-grey-950)",
+  "--oh-danger": "#e76a5e",
+  "--oh-danger-foreground": "var(--cool-grey-50)",
+  "--oh-segment": "var(--cool-grey-925)",
+  "--oh-segment-foreground": "var(--cool-grey-100)",
+  "--oh-border-width": "1px",
+  "--oh-field-border-width": "1px",
+  "--oh-border": "var(--cool-grey-700)",
+  "--oh-border-input": "var(--cool-grey-600)",
+  "--oh-border-subtle": "var(--cool-grey-800)",
+  "--oh-separator": "rgba(113, 120, 136, 0.5)",
+  "--oh-focus": "#ffffff",
+  "--oh-status-success": "#1FBD53",
+  "--oh-status-error": "#FF684E",
+  "--oh-link": "var(--cool-grey-100)",
+  "--oh-radius": "8px",
+  "--oh-field-radius": "8px",
+  "--oh-surface-shadow": "none",
+  "--oh-overlay-shadow": "none",
+  "--oh-field-shadow": "none",
+  "--oh-bg-dark": "var(--cool-grey-950)",
+  "--oh-bg-light": "var(--cool-grey-900)",
+  "--oh-bg-input": "var(--cool-grey-800)",
+  "--oh-bg-workspace": "var(--cool-grey-925)",
+  "--oh-text-editor-base": "var(--cool-grey-400)",
+  "--oh-text-editor-active": "var(--cool-grey-300)",
+  "--oh-bg-editor-sidebar": "var(--cool-grey-925)",
+  "--oh-bg-editor-active": "var(--cool-grey-900)",
+  "--oh-border-editor-sidebar": "var(--cool-grey-800)",
+  "--oh-bg-neutral-muted":
+    "color-mix(in srgb, var(--cool-grey-300) 20%, transparent)",
+} as const;
+
+export type AgentServerUICssVariableName =
+  | keyof typeof AGENT_SERVER_UI_DEFAULT_CSS_VARIABLES
+  | AgentServerUIThemeableBrandVariable;
+
+export type AgentServerUIStyleOverrides = Partial<
+  Record<AgentServerUICssVariableName, string>
+>;
+
+const GLOBAL_SCOPE_SELECTORS = new Set([":root", "body", "html"]);
+
+export function transformAgentServerUISelector(
+  prefix: string,
+  selector: string,
+  prefixedSelector: string,
+): string {
+  if (selector.includes(prefix)) {
+    return selector;
+  }
+
+  if (selector.includes(":host")) {
+    return selector.replaceAll(":host", prefix);
+  }
+
+  if (GLOBAL_SCOPE_SELECTORS.has(selector.trim())) {
+    return prefix;
+  }
+
+  return prefixedSelector;
+}

src/utils/acp-auth-display.ts

@@ -0,0 +1,46 @@
+import type { AcpAuthStatus } from "#/hooks/query/use-acp-auth-status";
+
+/**
+ * Resolved display state for the ACP auth banner.
+ *
+ * - ``"signed-in"`` — the host-login probe confirmed a session (native backend).
+ * - ``"checking"`` — the first probe is still in flight.
+ * - ``"configured"`` — the probe can't confirm a login (e.g. a container with no
+ *   interactive CLI, or a cloud backend where the probe doesn't run), but a
+ *   credential for the provider exists in the active backend's secret store.
+ * - ``"none"`` — no confirmed login and no stored credential; show nothing.
+ */
+export type AcpAuthDisplay = "signed-in" | "checking" | "configured" | "none";
+
+interface AcpAuthDisplayInput {
+  /** Result of the host-login probe (only meaningful on a native backend). */
+  status: AcpAuthStatus;
+  /** True while the first probe for this provider is in flight. */
+  isChecking: boolean;
+  /**
+   * Whether a credential for the provider exists in the active backend's secret
+   * store. Unlike {@link status}, this signal is available on Docker and cloud
+   * backends, so it can convey an accurate state where the probe goes silent.
+   */
+  credentialsConfigured: boolean;
+}
+
+/**
+ * Decide what the ACP auth banner should show, given the (host-only) login
+ * probe and the backend-truthful "a credential is stored" signal.
+ *
+ * Precedence preserves the existing banner behavior — a probe-confirmed login
+ * wins, then the in-flight spinner — and only adds ``"configured"`` in the gap
+ * that previously rendered nothing. A stored credential never reports as
+ * ``"signed-in"``: only the probe can confirm an actual host login. See #1244.
+ */
+export function resolveAcpAuthDisplay({
+  status,
+  isChecking,
+  credentialsConfigured,
+}: AcpAuthDisplayInput): AcpAuthDisplay {
+  if (status === "authenticated") return "signed-in";
+  if (isChecking) return "checking";
+  if (credentialsConfigured) return "configured";
+  return "none";
+}

src/utils/acp-command.ts

@@ -0,0 +1,189 @@
+// ``shell-quote`` is a CJS module that does ``module.exports = { parse, quote }``;
+// Vite's ESM interop can resolve a default/namespace import but not named
+// imports against that shape (the dev server crashes with "does not provide
+// an export named 'parse'"). Namespace import works on both the dev server
+// and the Rollup-based prod build. Used only for the ``quote`` direction —
+// see ``parseCommand`` below for why we don't use ``shell-quote.parse``.
+import * as shellQuote from "shell-quote";
+
+const { quote } = shellQuote;
+
+/**
+ * Parse a single-string command into argv tokens for ``acp_command``.
+ *
+ * Used by the Settings → Agent textarea — the user types one human-readable
+ * command (e.g. ``bash -c "echo hello world"``) and we convert it into the
+ * ``string[]`` shape that the agent-server's ``ACPAgent.acp_command``
+ * expects. The agent-server passes that array straight to
+ * ``subprocess.create_subprocess_exec``; no shell is involved on the spawn
+ * side, so this parser only needs to handle argv-style word splitting
+ * with quote/escape support — *not* shell metasyntax.
+ *
+ * Why a custom tokenizer and **not** ``shell-quote.parse``:
+ *
+ * ``shell-quote.parse`` treats ``?``, ``*``, ``$VAR``, redirects, and
+ * comments as shell syntax and emits non-string AST nodes for them.
+ * Filtering to strings would silently drop entire argv tokens. The
+ * concrete data-corruption case is a URL with a query string —
+ *
+ *     node acp.js --endpoint https://example.com/acp?tenant=abc
+ *
+ * ``shell-quote`` reads ``?tenant=abc`` as a glob pattern and returns
+ * ``["node","acp.js","--endpoint",{op:"glob",…}]``, so the saved
+ * ``acp_command`` becomes ``["node","acp.js","--endpoint"]`` — the URL
+ * vanishes. The agent-server then spawns a broken command and the user
+ * gets a confusing runtime error far from the configuration UI.
+ *
+ * The replacement tokenizer treats every non-whitespace, non-quote
+ * character as part of the current token: ``?``, ``*``, ``$``, ``|``,
+ * ``>``, ``#``, backticks all round-trip verbatim. Shell-only constructs
+ * (pipes, redirects, env-var expansion, command substitution) would
+ * land as literal argv entries — which is what the user typed and what
+ * ``subprocess.create_subprocess_exec`` will see. That's correct: a
+ * user who types ``foo | bar`` into the Settings → Agent textarea is
+ * configuring a literal command, not a shell pipeline; ``foo`` doesn't
+ * actually pipe into ``bar``, but neither does it silently disappear.
+ *
+ * Quoting rules supported:
+ *   - whitespace separates tokens
+ *   - single quotes: literal until the next ``'`` (no escapes inside,
+ *     matching POSIX shell)
+ *   - double quotes: literal until the next ``"`` (with ``\\"`` and
+ *     ``\\\\`` honored as escapes; no $-expansion)
+ *   - backslash outside quotes: escapes the next character (whitespace,
+ *     quote, or anything else — turns it into a literal)
+ *   - explicit empty quoted segments (``""`` / ``''``) produce an
+ *     empty-string token, matching the round-trip rule in
+ *     ``formatCommand``
+ *
+ * Unterminated quotes are tolerated: the current token closes at EOF
+ * with whatever was accumulated. A throw here would crash the
+ * Settings → Agent page mid-render; the Save button is already gated
+ * on a non-empty argv so a recoverable miss can't be silently saved
+ * either way.
+ */
+export function parseCommand(value: string): string[] {
+  const tokens: string[] = [];
+  let i = 0;
+  let current = "";
+  let inToken = false;
+
+  while (i < value.length) {
+    const ch = value[i];
+
+    if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r") {
+      if (inToken) {
+        tokens.push(current);
+        current = "";
+        inToken = false;
+      }
+      i += 1;
+      continue;
+    }
+
+    if (ch === "'") {
+      // Single-quoted segment: literal until the next single quote.
+      // No escapes inside (POSIX shell semantics).
+      inToken = true;
+      i += 1;
+      while (i < value.length && value[i] !== "'") {
+        current += value[i];
+        i += 1;
+      }
+      // Skip the closing quote if present. Unterminated → EOF closes.
+      if (i < value.length) i += 1;
+      continue;
+    }
+
+    if (ch === '"') {
+      // Double-quoted segment: literal with backslash escapes for
+      // ``\\"`` and ``\\\\``. We intentionally do NOT expand $VAR
+      // (so a user typing ``"--key=$X"`` keeps it literal — the
+      // agent-server doesn't run a shell anyway). Other backslash
+      // sequences pass through verbatim (matches what most users
+      // expect when copying paths with backslashes from Windows
+      // examples; corner-case differences from POSIX aren't worth
+      // the complexity here).
+      inToken = true;
+      i += 1;
+      while (i < value.length && value[i] !== '"') {
+        if (value[i] === "\\" && i + 1 < value.length) {
+          const next = value[i + 1];
+          if (next === '"' || next === "\\") {
+            current += next;
+            i += 2;
+            continue;
+          }
+        }
+        current += value[i];
+        i += 1;
+      }
+      if (i < value.length) i += 1;
+      continue;
+    }
+
+    if (ch === "\\" && i + 1 < value.length) {
+      // Unquoted backslash escapes the next character (whitespace,
+      // quote, glob char, anything). Useful for typing literal spaces
+      // in a path or escaping a literal quote.
+      inToken = true;
+      current += value[i + 1];
+      i += 2;
+      continue;
+    }
+
+    // Every other character — including ``?``, ``*``, ``$``, ``|``,
+    // ``>``, ``#``, ``&``, ``;``, ``(``, ``)`` — is a literal part of
+    // the current token. Shell-metasyntax filtering happens at the
+    // OS/shell boundary, which we don't cross.
+    inToken = true;
+    current += ch;
+    i += 1;
+  }
+
+  if (inToken) {
+    tokens.push(current);
+  }
+  return tokens;
+}
+
+// Tokens that need shell-quoting when rendering back to a string —
+// whitespace, quotes, backslashes, redirects/pipes/globs, and the
+// command-separators. ``@``, ``/``, ``-``, ``.``, ``+``, ``=`` and
+// other punctuation that's common in package names and URLs are
+// safe in argv-only contexts (the agent-server execs the array, no
+// shell intermediary), so we leave them alone — otherwise
+// ``npx -y @org/pkg`` would render as ``npx -y \@org/pkg`` and that's
+// a hostile read-back in the textarea.
+//
+// Note: ``?``, ``*``, ``$``, ``|``, ``>``, ``#``, ``&``, ``;``, ``(``,
+// ``)`` no longer carry shell meaning in {@link parseCommand} (which
+// is purely an argv tokenizer), so a token containing them would
+// round-trip fine without quoting. We still quote on output because
+// users frequently switch between this textarea and an actual shell
+// (copy-paste workflows), and quoting matches the conservative
+// expectation "if it would need quoting in a shell, show it quoted."
+const SHELL_UNSAFE = /[\s"'\\$`&|;<>(){}*?#!~[\]]/;
+
+/**
+ * Render a ``string[]`` argv back into a single string the textarea
+ * can display. Tokens that *would* need shell quoting (whitespace,
+ * quotes, redirects, …) go through ``shell-quote.quote`` for correct
+ * escaping; tokens that are already shell-safe (the overwhelming
+ * majority of package names and CLI flags) round-trip verbatim. The
+ * output remains a valid input to {@link parseCommand}.
+ */
+export function formatCommand(command: readonly string[]): string {
+  return command
+    .map((tok) =>
+      // Quote any token that:
+      //   * contains a shell-significant character (whitespace, quotes,
+      //     redirects, …), so it doesn't get re-split on parse, OR
+      //   * is the empty string — without explicit quoting,
+      //     ``["bash", "-c", ""]`` would render as ``"bash -c "`` and
+      //     round-trip back to ``["bash", "-c"]``, silently dropping
+      //     the (rare but valid) empty argument.
+      SHELL_UNSAFE.test(tok) || tok === "" ? quote([tok]) : tok,
+    )
+    .join(" ");
+}

src/utils/acp-error-codes.ts

@@ -0,0 +1,29 @@
+import { I18nKey } from "#/i18n/declaration";
+
+/**
+ * Structured `code` values the SDK's ACPAgent puts on a ConversationErrorEvent
+ * (see software-agent-sdk `acp_agent.py`). The banner uses them to show a
+ * code-specific header and, for credential failures, a recovery action.
+ */
+export const ACP_AUTH_REQUIRED_CODE = "ACPAuthRequired";
+
+const ACP_ERROR_HEADER_KEYS: Record<string, I18nKey> = {
+  ACPAuthRequired: I18nKey.ERROR$ACP_AUTH_REQUIRED_TITLE,
+  // Spawn/init/prompt/usage-policy failures share the generic "Agent error"
+  // header; their detail already carries the specific cause.
+  ACPSpawnError: I18nKey.CHAT_INTERFACE$AGENT_ERROR_MESSAGE,
+  ACPInitError: I18nKey.CHAT_INTERFACE$AGENT_ERROR_MESSAGE,
+  ACPPromptError: I18nKey.CHAT_INTERFACE$AGENT_ERROR_MESSAGE,
+  UsagePolicyRefusal: I18nKey.CHAT_INTERFACE$AGENT_ERROR_MESSAGE,
+};
+
+/** Localized header key for an error code, or null when the code is unknown. */
+export function getAcpErrorHeaderKey(code?: string | null): I18nKey | null {
+  if (!code) return null;
+  return ACP_ERROR_HEADER_KEYS[code] ?? null;
+}
+
+/** Whether the error is a credential failure that warrants a re-auth action. */
+export function isAcpAuthErrorCode(code?: string | null): boolean {
+  return code === ACP_AUTH_REQUIRED_CODE;
+}

src/utils/agent-state-emoji.ts

@@ -0,0 +1,32 @@
+import { ExecutionStatus } from "#/types/agent-server/core/base/common";
+
+/**
+ * Maps a conversation's execution status to a single emoji that visually
+ * conveys the agent's state in the browser tab title.
+ *
+ *   ✅ green check — agent finished or is otherwise waiting on the user
+ *   🟢 green circle — agent is actively running
+ *   ⚪ gray circle — agent is paused/stopped
+ *   🔴 red circle — agent is in an error state
+ *
+ * Returns null when the status is unknown so callers can omit the prefix.
+ */
+export function getAgentStateEmoji(
+  status: ExecutionStatus | null | undefined,
+): string | null {
+  switch (status) {
+    case ExecutionStatus.RUNNING:
+      return "🟢";
+    case ExecutionStatus.FINISHED:
+    case ExecutionStatus.IDLE:
+    case ExecutionStatus.WAITING_FOR_CONFIRMATION:
+      return "✅";
+    case ExecutionStatus.PAUSED:
+      return "⚪";
+    case ExecutionStatus.ERROR:
+    case ExecutionStatus.STUCK:
+      return "🔴";
+    default:
+      return null;
+  }
+}

src/utils/api-error-message.ts

@@ -0,0 +1,38 @@
+import axios from "axios";
+
+/**
+ * Extract the parsed response body from a failed API call.
+ *
+ * Handles both transports the app uses: local agent-server calls that
+ * throw an `AxiosError` (body under `error.response.data`) and cloud
+ * calls through the shared TypeScript client that throw an `HttpError`
+ * (parsed body directly under `error.response`).
+ */
+export function getApiErrorBody(error: unknown): unknown {
+  if (axios.isAxiosError(error)) return error.response?.data;
+  if (error instanceof Error && "response" in error) {
+    return (error as { response?: unknown }).response;
+  }
+  return undefined;
+}
+
+/**
+ * Extract a human-readable message from a failed API call. Prefers the
+ * server-provided `message`/`detail` fields, then the `Error` message,
+ * then `fallback`.
+ */
+export function getApiErrorMessage(error: unknown, fallback: string): string {
+  const body = getApiErrorBody(error);
+
+  if (body && typeof body === "object") {
+    const { message, detail } = body as {
+      message?: unknown;
+      detail?: unknown;
+    };
+    if (typeof message === "string" && message) return message;
+    if (typeof detail === "string" && detail) return detail;
+  }
+
+  if (error instanceof Error && error.message) return error.message;
+  return fallback;
+}

src/utils/automation-activity-log-export.ts

@@ -0,0 +1,186 @@
+import type {
+  ActivityLogExportFormat,
+  Automation,
+  AutomationRun,
+  AutomationRunExportRow,
+} from "#/types/automation";
+import { downloadBlob } from "#/utils/utils";
+import AutomationService from "#/api/automation-service/automation-service.api";
+
+const EXPORT_PAGE_SIZE = 100;
+
+const CSV_COLUMNS = [
+  "run_id",
+  "automation_id",
+  "automation_name",
+  "trigger",
+  "start_time",
+  "end_time",
+  "duration_seconds",
+  "status",
+  "conversation_id",
+  "conversation_url",
+  "error",
+  // Appended rather than grouped with the other run metrics so existing
+  // consumers that read the CSV by column position keep working.
+  "cost",
+  "phase",
+] as const;
+
+export function getActivityLogExportFilename(
+  automation: Pick<Automation, "id" | "name">,
+  format: ActivityLogExportFormat,
+): string {
+  const slug = automation.name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return `${slug || automation.id}.activity-log.${format}`;
+}
+
+function csvEscape(value: string): string {
+  if (/[",\n\r]/.test(value)) {
+    return `"${value.replace(/"/g, '""')}"`;
+  }
+  return value;
+}
+
+export function serializeActivityLogRowsCsv(
+  rows: AutomationRunExportRow[],
+): string {
+  const lines: string[] = [CSV_COLUMNS.join(",")];
+  for (const row of rows) {
+    const values = CSV_COLUMNS.map((key) => {
+      const raw = row[key];
+      if (raw == null) return "";
+      if (key === "trigger") {
+        return csvEscape(JSON.stringify(raw));
+      }
+      return csvEscape(String(raw));
+    });
+    lines.push(values.join(","));
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export function buildConversationUrl(
+  conversationId: string | null,
+  conversationBaseUrl?: string,
+): string | null {
+  if (!conversationId) return null;
+  const path = `/conversations/${conversationId}`;
+  if (!conversationBaseUrl) return path;
+  return `${conversationBaseUrl.replace(/\/$/, "")}${path}`;
+}
+
+export function mapAutomationRunToExportRow(
+  run: AutomationRun,
+  automation: Pick<Automation, "id" | "name" | "trigger">,
+  conversationBaseUrl?: string,
+): AutomationRunExportRow {
+  const start = run.started_at || null;
+  const end = run.completed_at;
+  let duration_seconds: number | null = null;
+  if (start && end) {
+    duration_seconds =
+      (new Date(end).getTime() - new Date(start).getTime()) / 1000;
+  }
+
+  return {
+    run_id: run.id,
+    automation_id: automation.id,
+    automation_name: automation.name,
+    trigger: automation.trigger,
+    start_time: start,
+    end_time: end,
+    duration_seconds,
+    status: run.status,
+    conversation_id: run.conversation_id,
+    conversation_url: buildConversationUrl(
+      run.conversation_id,
+      conversationBaseUrl,
+    ),
+    error: run.error_detail,
+    // Exports carry the raw number and leave formatting to the consumer; the
+    // Activity Log row is the only place that renders it as USD.
+    cost: run.cost ?? null,
+    // Deliberately not filtered through `shouldShowRunPhase`: that predicate
+    // decides what is worth a user's attention on screen, and hides the phase
+    // of a run whose status already says everything. An export is a record,
+    // not a screen — a completed run's last phase is real data, and dropping
+    // it here would make the phase of a run that finished indistinguishable
+    // from one that never reported a phase at all.
+    //
+    // Falling back to the label: without it, a phase reported with only a
+    // label would export as an empty cell, indistinguishable from no phase.
+    // Trimmed rather than nullish-coalesced: the service stores a
+    // whitespace-only field as sent — it rejects only a phase blank on
+    // *both* — so `??` would let a blank code suppress a real label, which
+    // is exactly the empty cell this fallback exists to prevent.
+    phase: run.phase_code?.trim() || run.phase_label?.trim() || null,
+  };
+}
+
+/**
+ * Page ``GET /v1/{id}/runs`` until complete, then project export rows locally.
+ */
+export async function fetchAllActivityLogExportRows(
+  automation: Pick<Automation, "id" | "name" | "trigger">,
+  conversationBaseUrl?: string,
+): Promise<AutomationRunExportRow[]> {
+  const rows: AutomationRunExportRow[] = [];
+  let offset = 0;
+  let total = Number.POSITIVE_INFINITY;
+
+  while (offset < total) {
+    const page = await AutomationService.listAutomationRuns(automation.id, {
+      limit: EXPORT_PAGE_SIZE,
+      offset,
+    });
+
+    for (const run of page.runs) {
+      rows.push(
+        mapAutomationRunToExportRow(run, automation, conversationBaseUrl),
+      );
+    }
+    total = page.total;
+    offset += page.runs.length;
+    if (page.runs.length === 0) break;
+  }
+
+  return rows;
+}
+
+/**
+ * Page the runs list endpoint and download one CSV or JSON file.
+ */
+export async function downloadActivityLogExport(options: {
+  automation: Pick<Automation, "id" | "name" | "trigger">;
+  format: ActivityLogExportFormat;
+  conversationBaseUrl?: string;
+}): Promise<void> {
+  const { automation, format, conversationBaseUrl } = options;
+  const rows = await fetchAllActivityLogExportRows(
+    automation,
+    conversationBaseUrl,
+  );
+
+  if (format === "json") {
+    downloadBlob(
+      new Blob(
+        [`${JSON.stringify({ runs: rows, total: rows.length }, null, 2)}\n`],
+        { type: "application/json" },
+      ),
+      getActivityLogExportFilename(automation, "json"),
+    );
+    return;
+  }
+
+  downloadBlob(
+    new Blob([serializeActivityLogRowsCsv(rows)], {
+      type: "text/csv;charset=utf-8",
+    }),
+    getActivityLogExportFilename(automation, "csv"),
+  );
+}

src/utils/automation-catalog.ts

@@ -0,0 +1,185 @@
+import {
+  AUTOMATION_CATALOG,
+  type RecommendedAutomation,
+} from "@openhands/extensions/automations";
+import {
+  SKILLS_CATALOG,
+  type SkillCatalogEntry,
+} from "@openhands/extensions/skills";
+import type { LucideIcon } from "lucide-react";
+import { MANIFEST_ICON_BY_SLUG } from "#/components/features/manifest/manifest-icons";
+import { interpolateValues } from "#/manifests/manifest-template";
+import type { Automation } from "#/types/automation";
+
+/**
+ * Reading a published automation catalog entry.
+ *
+ * The catalog states each thing once and leaves the rest to be derived, so an
+ * entry no longer carries its own launch command or a flat list of required
+ * integration ids. This module is the single place that performs those
+ * derivations, so the components consuming the catalog stay unaware of how it
+ * is shaped.
+ */
+
+const SKILL_BY_NAME = new Map<string, SkillCatalogEntry>(
+  SKILLS_CATALOG.map((skill) => [skill.name, skill]),
+);
+
+/**
+ * The glyph a card shows in place of its integration logos, or null when it
+ * has none to show and the logos speak for it.
+ *
+ * An entry naming the service it talks to is recognised by that service's
+ * logo; one whose identity is the work itself declares a slug instead. The
+ * lookup is a guard as much as a mapping — the catalog is published elsewhere,
+ * so a slug this host has no artwork for falls back rather than rendering
+ * nothing.
+ */
+export function getAutomationIcon(
+  automation: RecommendedAutomation,
+): LucideIcon | null {
+  const slug = automation.icon;
+  if (!slug) return null;
+  return (
+    (MANIFEST_ICON_BY_SLUG as Record<string, LucideIcon | undefined>)[slug] ??
+    null
+  );
+}
+
+/** Every integration the entry declares, in declaration order. */
+export function getIntegrationIds(automation: RecommendedAutomation): string[] {
+  return Object.keys(automation.requires.integrations);
+}
+
+/**
+ * The integrations that gate this automation. One marked `required: false` can
+ * be connected later, during setup, so it is still worth showing on the card
+ * but must never stand between the user and a launch.
+ */
+export function getRequiredIntegrationIds(
+  automation: RecommendedAutomation,
+): string[] {
+  return Object.entries(automation.requires.integrations)
+    .filter(([, requirement]) => requirement.required !== false)
+    .map(([id]) => id);
+}
+
+/**
+ * The command that invokes this automation's skill, or null when that skill is
+ * invoked by description instead.
+ *
+ * The command is declared once, in the owning skill's own `triggers`; the
+ * catalog names that skill only where it differs from the entry id.
+ */
+export function findAutomationCommand(
+  automation: Pick<RecommendedAutomation, "id" | "skill">,
+): string | null {
+  const skill = SKILL_BY_NAME.get(automation.skill ?? automation.id);
+  return skill?.triggers[0] ?? null;
+}
+
+/**
+ * What launching an automation card hands to the agent.
+ *
+ * The resolved command is passed through as-is: API routing (host, auth) is
+ * discovered by the agent at runtime from `<RUNTIME_SERVICES>` in the system
+ * prompt, and the skills themselves carry the instructions for reading that
+ * block. An automation whose skill declares no command has the request spelled
+ * out instead. Both are instructions to the agent rather than user-facing UI
+ * copy, so they are intentionally in English and not localized.
+ */
+export function getAutomationLaunchPrompt(
+  automation: RecommendedAutomation,
+): string {
+  return (
+    findAutomationCommand(automation) ??
+    `Set up the ${automation.name} automation`
+  );
+}
+
+const CATALOG_ENTRY_BY_ID = new Map<string, RecommendedAutomation>(
+  AUTOMATION_CATALOG.map((entry) => [entry.id, entry]),
+);
+
+/** Rejects markup the same way the catalog schema's copy rule does. */
+const MARKUP_PATTERN = /<[A-Za-z/!]/;
+
+/** Every `{{` an impact phrase opens must be the count placeholder. */
+const FOREIGN_PLACEHOLDER_PATTERN = /\{\{(?!count\}\})/;
+
+const COUNT_PLACEHOLDER = "{{count}}";
+
+interface AutomationImpactCopy {
+  one: string;
+  other: string;
+}
+
+function isImpactPhrase(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    !MARKUP_PATTERN.test(value) &&
+    !FOREIGN_PLACEHOLDER_PATTERN.test(value)
+  );
+}
+
+/**
+ * The entry's `impact` value statement, or null when it declares none this
+ * host can honor. The catalog is published elsewhere, so the field is read
+ * off the raw entry and validated here rather than trusted from the package
+ * types — which also keeps this module compiling against a pinned package
+ * that predates the field. A basis other than `completed-runs` is a counter
+ * this host does not know how to compute, so it renders nothing rather than
+ * a number the phrase was not written for.
+ */
+function readImpactCopy(
+  entry: RecommendedAutomation,
+): AutomationImpactCopy | null {
+  const { impact } = entry as unknown as Record<string, unknown>;
+  if (typeof impact !== "object" || impact === null) return null;
+  const { basis, one, other } = impact as Record<string, unknown>;
+  if (basis !== "completed-runs") return null;
+  if (!isImpactPhrase(one) || !isImpactPhrase(other)) return null;
+  if (!other.includes(COUNT_PLACEHOLDER)) return null;
+  return { one, other };
+}
+
+/**
+ * The catalog entry an installed automation was created from, via the
+ * `template` provenance its setup stored — the only join back to the catalog.
+ * Null for automations without provenance: imports, agent-built ones, and
+ * entries whose setup publishes no version.
+ */
+function getAutomationTemplateEntry(
+  automation: Automation,
+): RecommendedAutomation | null {
+  const metadata = automation.preset_metadata;
+  if (typeof metadata !== "object" || metadata === null) return null;
+  const { template } = metadata as Record<string, unknown>;
+  if (typeof template !== "object" || template === null) return null;
+  const { id } = template as Record<string, unknown>;
+  if (typeof id !== "string" || id.length === 0) return null;
+  return CATALOG_ENTRY_BY_ID.get(id) ?? null;
+}
+
+/**
+ * The value statement an automation card shows for its completed runs, or
+ * null when there is nothing defensible to say: no template provenance, no
+ * honored `impact` declaration, an unknown count (older service with more
+ * history than the sample), or a count of zero — absence, never a zero-value
+ * claim. Provenance persists across prompt edits, so a reworked automation
+ * keeps its template's phrase; the phrases are run-shaped, which keeps them
+ * true for as long as the automation runs at all.
+ */
+export function resolveAutomationImpactStatement(
+  automation: Automation,
+  completedTotal: number | null,
+): string | null {
+  if (completedTotal === null || completedTotal < 1) return null;
+  const entry = getAutomationTemplateEntry(automation);
+  if (!entry) return null;
+  const copy = readImpactCopy(entry);
+  if (!copy) return null;
+  const phrase = completedTotal === 1 ? copy.one : copy.other;
+  return interpolateValues(phrase, { count: completedTotal.toLocaleString() });
+}

src/utils/automation-disabled-reason.ts

@@ -0,0 +1,65 @@
+import { I18nKey } from "#/i18n/declaration";
+import type { Automation } from "#/types/automation";
+
+/** Detail `source` values written by the automation service on disable. */
+const MANUAL_DETAIL_SOURCES = new Set(["user"]);
+/** Top-level `disabled_reason` values written for user-initiated disables. */
+const MANUAL_REASON_VALUES = new Set(["manual", "manual_delete"]);
+
+/**
+ * Whether an automation is inactive *because* of a recorded disablement
+ * reason (vs. simply toggled off by an older client path, or an automation
+ * service that predates disablement tracking).
+ *
+ * The automation service overwrites `disabled_reason`/`disabled_detail`/
+ * `disabled_at` on every disable and clears them on every re-enable, so when
+ * an automation is `enabled === false` and carries a `disabled_reason`, that
+ * reason is the latest reason it went inactive.
+ */
+export function hasDisablementReason(
+  automation: Pick<Automation, "enabled" | "disabled_reason">,
+): boolean {
+  return !automation.enabled && Boolean(automation.disabled_reason);
+}
+
+/**
+ * Whether the recorded disablement was user-initiated (manual toggle / delete)
+ * rather than an automatic pause for failing runs.
+ */
+export function isManualDisable(
+  automation: Pick<Automation, "disabled_reason" | "disabled_detail">,
+): boolean {
+  const reason = automation.disabled_reason;
+  if (reason && MANUAL_REASON_VALUES.has(reason)) return true;
+  const source = automation.disabled_detail?.source;
+  if (source && MANUAL_DETAIL_SOURCES.has(source)) return true;
+  return false;
+}
+
+export interface DisablementReasonDisplay {
+  /**
+   * Full reason text to render. For automatic disables this is the backend's
+   * human-readable `disabled_reason` (already phrased for users, e.g.
+   * "Paused automatically: auth — ..."). For manual disables the backend
+   * stores the opaque "manual" string, so we substitute a localized label.
+   */
+  text: string;
+}
+
+/**
+ * Resolve the disablement reason into display text. Returns `null` when the
+ * automation is not inactive-for-a-recorded-reason.
+ */
+export function getDisablementReasonDisplay(
+  automation: Pick<
+    Automation,
+    "enabled" | "disabled_reason" | "disabled_detail"
+  >,
+  t: (key: I18nKey) => string,
+): DisablementReasonDisplay | null {
+  if (!hasDisablementReason(automation)) return null;
+  if (isManualDisable(automation)) {
+    return { text: t(I18nKey.AUTOMATIONS$DETAIL$DISABLED_MANUAL) };
+  }
+  return { text: automation.disabled_reason as string };
+}

src/utils/automation-export.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from "vitest";
+import type { Automation } from "#/types/automation";
+import {
+  AutomationFileValidationError,
+  parseAutomationFile,
+  serializeAutomation,
+} from "./automation-export";
+
+const cronAutomation: Automation = {
+  id: "automation-1",
+  name: "Daily review",
+  trigger: {
+    type: "cron",
+    schedule: "0 9 * * *",
+    schedule_human: "Daily at 09:00",
+  },
+  enabled: true,
+  repository: "openhands/agent-canvas",
+  branch: "main",
+  model: "fast",
+  prompt: "Review open pull requests.",
+  plugins: ["github:openhands/extensions"],
+  notification: "Post a summary",
+  timezone: "America/Los_Angeles",
+  created_at: "2026-07-01T00:00:00Z",
+  updated_at: "2026-07-02T00:00:00Z",
+  last_triggered_at: "2026-07-03T00:00:00Z",
+};
+
+describe("automation export files", () => {
+  it("round-trips a cron automation without server-assigned fields", () => {
+    const exported = serializeAutomation(cronAutomation);
+
+    expect(exported).toEqual({
+      version: 1,
+      kind: "automation",
+      spec: {
+        name: cronAutomation.name,
+        trigger: cronAutomation.trigger,
+        enabled: true,
+        repository: cronAutomation.repository,
+        model: cronAutomation.model,
+        prompt: cronAutomation.prompt,
+        branch: cronAutomation.branch,
+        plugins: cronAutomation.plugins,
+        notification: cronAutomation.notification,
+        timezone: cronAutomation.timezone,
+      },
+    });
+    expect(parseAutomationFile(exported)).toEqual(exported.spec);
+    expect(exported.spec).not.toHaveProperty("id");
+    expect(exported.spec).not.toHaveProperty("created_at");
+    expect(exported.spec).not.toHaveProperty("updated_at");
+    expect(exported.spec).not.toHaveProperty("last_triggered_at");
+  });
+
+  it("round-trips event trigger fields", () => {
+    const exported = serializeAutomation({
+      ...cronAutomation,
+      trigger: {
+        type: "event",
+        source: "github",
+        on: ["pull_request.opened", "pull_request.synchronize"],
+        filter: "repository.full_name == 'openhands/agent-canvas'",
+      },
+      timezone: undefined,
+    });
+
+    expect(parseAutomationFile(exported).trigger).toEqual(
+      exported.spec.trigger,
+    );
+  });
+
+  it("preserves a positive timeout through an export/import round-trip", () => {
+    const withTimeout: Automation = { ...cronAutomation, timeout: 900 };
+
+    const exported = serializeAutomation(withTimeout);
+
+    expect(parseAutomationFile(exported).timeout).toBe(900);
+  });
+
+  it("reports every malformed field with its path", () => {
+    const malformed = {
+      version: 2,
+      kind: "workflow",
+      spec: {
+        name: "",
+        prompt: null,
+        enabled: "yes",
+        trigger: { type: "event", source: 42, on: [] },
+        plugins: ["github:openhands/extensions", 42],
+        model: false,
+        timeout: -5,
+      },
+    };
+
+    expect(() => parseAutomationFile(malformed)).toThrow(
+      AutomationFileValidationError,
+    );
+
+    try {
+      parseAutomationFile(malformed);
+    } catch (error) {
+      expect(error).toBeInstanceOf(AutomationFileValidationError);
+      expect((error as AutomationFileValidationError).issues).toEqual(
+        expect.arrayContaining([
+          "version: expected 1",
+          'kind: expected "automation"',
+          "spec.name: expected a non-empty string",
+          "spec.prompt: expected a non-empty string",
+          "spec.enabled: expected a boolean",
+          "spec.trigger.source: expected a string",
+          "spec.trigger.source: required for an event trigger",
+          "spec.trigger.on: expected a string or a non-empty array of strings",
+          "spec.trigger.on: required for an event trigger",
+          "spec.plugins: expected an array of non-empty strings",
+          "spec.model: expected a non-empty string or null",
+          "spec.timeout: expected a positive integer",
+        ]),
+      );
+    }
+  });
+
+  it("rejects non-object files and missing specs", () => {
+    expect(() => parseAutomationFile(null)).toThrow(
+      "file: expected a JSON object",
+    );
+    expect(() =>
+      parseAutomationFile({ version: 1, kind: "automation" }),
+    ).toThrow("spec: expected an object");
+  });
+});

src/utils/automation-schedule.ts

@@ -0,0 +1,262 @@
+import { I18nKey } from "#/i18n/declaration";
+
+export type SchedulePresetKind = "daily" | "weekdays" | "weekly";
+
+export interface PresetSchedule {
+  kind: SchedulePresetKind;
+  hour: number;
+  minute: number;
+  weekday?: number;
+}
+
+export interface CustomSchedule {
+  kind: "custom";
+  raw: string;
+  hour?: number;
+  minute?: number;
+}
+
+export type ParsedSchedule = PresetSchedule | CustomSchedule;
+
+const SINGLE_INT = /^(\d+)$/;
+
+function parseSingleInt(
+  field: string,
+  min: number,
+  max: number,
+): number | null {
+  const match = field.match(SINGLE_INT);
+  if (!match) return null;
+  const value = Number(match[1]);
+  if (Number.isNaN(value) || value < min || value > max) return null;
+  return value;
+}
+
+export function parseCronSchedule(
+  cron: string | undefined | null,
+): ParsedSchedule {
+  const raw = (cron ?? "").trim();
+  if (!raw) return { kind: "custom", raw: "" };
+
+  const fields = raw.split(/\s+/);
+  if (fields.length !== 5) return { kind: "custom", raw };
+
+  const [minuteField, hourField, domField, monthField, dowField] = fields;
+
+  const minute = parseSingleInt(minuteField, 0, 59);
+  const hour = parseSingleInt(hourField, 0, 23);
+
+  if (minute === null || hour === null) {
+    return { kind: "custom", raw };
+  }
+  if (domField !== "*" || monthField !== "*") {
+    return { kind: "custom", raw, hour, minute };
+  }
+
+  if (dowField === "*" || dowField === "0-6") {
+    return { kind: "daily", hour, minute };
+  }
+  if (dowField === "1-5") {
+    return { kind: "weekdays", hour, minute };
+  }
+  const weekday = parseSingleInt(dowField, 0, 6);
+  if (weekday !== null) {
+    return { kind: "weekly", hour, minute, weekday };
+  }
+  return { kind: "custom", raw, hour, minute };
+}
+
+export function buildCronSchedule(input: PresetSchedule): string {
+  const { kind, hour, minute, weekday } = input;
+  switch (kind) {
+    case "daily":
+      return `${minute} ${hour} * * *`;
+    case "weekdays":
+      return `${minute} ${hour} * * 1-5`;
+    case "weekly":
+      return `${minute} ${hour} * * ${weekday ?? 1}`;
+    default: {
+      const _exhaustive: never = kind;
+      return _exhaustive;
+    }
+  }
+}
+
+export function formatTimeOfDay(hour: number, minute: number): string {
+  const hh = String(hour).padStart(2, "0");
+  const mm = String(minute).padStart(2, "0");
+  return `${hh}:${mm}`;
+}
+
+export function parseTimeOfDay(
+  value: string,
+): { hour: number; minute: number } | null {
+  const match = value.match(/^(\d{1,2}):(\d{2})$/);
+  if (!match) return null;
+  const hour = Number(match[1]);
+  const minute = Number(match[2]);
+  if (
+    Number.isNaN(hour) ||
+    Number.isNaN(minute) ||
+    hour < 0 ||
+    hour > 23 ||
+    minute < 0 ||
+    minute > 59
+  ) {
+    return null;
+  }
+  return { hour, minute };
+}
+
+export function formatEventOn(on: string | string[] | undefined): string {
+  if (!on) return "—";
+  if (Array.isArray(on)) return on.join(", ");
+  return on;
+}
+
+/** Example expression shown when the cron field is empty. */
+export const CRON_EXPRESSION_EXAMPLE = "*/10 * * * *";
+
+// The service validates with croniter, so this must accept everything croniter
+// does: five fields, optionally plus seconds and then year, or an alias.
+const CRON_ALIASES = new Set([
+  "@yearly",
+  "@annually",
+  "@monthly",
+  "@weekly",
+  "@daily",
+  "@midnight",
+  "@hourly",
+]);
+
+const CRON_MIN_FIELDS = 5;
+const CRON_MAX_FIELDS = 7;
+
+// Seconds and year are appended after these, so the positions always hold.
+const CRON_FIELD_BOUNDS: readonly (readonly [number, number])[] = [
+  [0, 59], // minute
+  [0, 23], // hour
+  [1, 31], // day of month
+  [1, 12], // month
+  [0, 7], // day of week — croniter spells Sunday 0 and 7
+];
+
+const DAY_OF_MONTH_INDEX = 2;
+const MONTH_INDEX = 3;
+
+// Indexed from 1. February is 29: the 29th does fire, in leap years.
+const MAX_DAYS_IN_MONTH = [0, 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+
+const MONTH_NAMES = "JAN|FEB|MAR|APR|MAY|JUN|JUL|AUG|SEP|OCT|NOV|DEC";
+const DAY_NAMES = "SUN|MON|TUE|WED|THU|FRI|SAT";
+
+// croniter does not bound the step: `*/90` is accepted.
+const NUMERIC_TERM = /^(\*|\d+(?:-\d+)?)(?:\/(\d+))?$/;
+
+/** Vocabulary beyond plain numbers, matched but not expanded. */
+const EXTRA_TERM_PATTERNS: readonly (RegExp | null)[] = [
+  null, // minute
+  null, // hour
+  /^(?:\?|L|\d+W)$/i, // `?`, `L`, `15W`
+  new RegExp(`^(?:${MONTH_NAMES})(?:-(?:${MONTH_NAMES}))?(?:/\\d+)?$`, "i"),
+  // `SUN`, `MON-FRI#2`, `5#3`, `?` — but no `L`, which croniter rejects here.
+  new RegExp(
+    `^(?:(?:${DAY_NAMES}|\\d+)(?:-(?:${DAY_NAMES}|\\d+))?(?:/\\d+)?(?:#\\d+)?|\\?)$`,
+    "i",
+  ),
+];
+
+type CronFieldParse =
+  | { kind: "invalid" }
+  /** Well-formed, but not expanded, so it constrains nothing. */
+  | { kind: "unmodelled" }
+  | { kind: "values"; values: number[] };
+
+function parseCronField(
+  field: string,
+  [min, max]: readonly [number, number],
+  extraPattern: RegExp | null,
+): CronFieldParse {
+  const values = new Set<number>();
+
+  for (const term of field.split(",")) {
+    const match = term.match(NUMERIC_TERM);
+    if (!match) {
+      if (extraPattern?.test(term)) return { kind: "unmodelled" };
+      return { kind: "invalid" };
+    }
+
+    const [, rangePart, stepPart] = match;
+    const step = stepPart === undefined ? 1 : Number(stepPart);
+    if (step < 1) return { kind: "invalid" };
+
+    if (rangePart === "*") {
+      for (let value = min; value <= max; value += step) values.add(value);
+      continue;
+    }
+
+    const [startPart, endPart] = rangePart.split("-");
+    const start = parseSingleInt(startPart, min, max);
+    if (start === null) return { kind: "invalid" };
+    if (endPart === undefined) {
+      values.add(start);
+      continue;
+    }
+    const end = parseSingleInt(endPart, min, max);
+    if (end === null) return { kind: "invalid" };
+    // croniter wraps a reversed range like `5-1`; that wrap is not modelled.
+    if (end < start) return { kind: "unmodelled" };
+    for (let value = start; value <= end; value += step) values.add(value);
+  }
+
+  return { kind: "values", values: [...values] };
+}
+
+export type CronScheduleValidation =
+  | { schedule: string }
+  | { errorKey: I18nKey };
+
+/**
+ * Validate a raw cron expression from the edit form — `parseCronSchedule` only
+ * classifies against the presets, reporting arbitrary text as `custom`.
+ *
+ * One-sided by design: rejects only what croniter certainly rejects, and defers
+ * on anything it does not model.
+ */
+export function validateCronSchedule(raw: string): CronScheduleValidation {
+  const schedule = raw.trim();
+  if (!schedule) return { errorKey: I18nKey.AUTOMATIONS$ERROR_CRON_INVALID };
+
+  if (schedule.startsWith("@")) {
+    return CRON_ALIASES.has(schedule.toLowerCase())
+      ? { schedule }
+      : { errorKey: I18nKey.AUTOMATIONS$ERROR_CRON_INVALID };
+  }
+
+  const fields = schedule.split(/\s+/);
+  if (fields.length < CRON_MIN_FIELDS || fields.length > CRON_MAX_FIELDS) {
+    return { errorKey: I18nKey.AUTOMATIONS$ERROR_CRON_INVALID };
+  }
+
+  const parsed = CRON_FIELD_BOUNDS.map((bounds, index) =>
+    parseCronField(fields[index], bounds, EXTRA_TERM_PATTERNS[index]),
+  );
+  if (parsed.some((field) => field.kind === "invalid")) {
+    return { errorKey: I18nKey.AUTOMATIONS$ERROR_CRON_INVALID };
+  }
+
+  // croniter parses `0 0 31 2 *` and then finds no fire time for it.
+  const days = parsed[DAY_OF_MONTH_INDEX];
+  const months = parsed[MONTH_INDEX];
+  if (
+    days.kind === "values" &&
+    months.kind === "values" &&
+    !months.values.some((month) =>
+      days.values.some((day) => day <= MAX_DAYS_IN_MONTH[month]),
+    )
+  ) {
+    return { errorKey: I18nKey.AUTOMATIONS$ERROR_CRON_UNREACHABLE };
+  }
+
+  return { schedule };
+}

src/utils/automation-stack-section.ts

@@ -0,0 +1,2 @@
+/** Shared bottom inset for stacked home sections (recommended rail, pinned). */
+export const AUTOMATION_STACK_SECTION_BOTTOM_CLASS = "pb-12";

src/utils/automation-timeout.ts

@@ -0,0 +1,37 @@
+import { I18nKey } from "#/i18n/declaration";
+
+/**
+ * Per-automation run timeout defaults. The deployment reports the maximum it
+ * enforces through capability discovery.
+ */
+export const AUTOMATION_TIMEOUT_DEFAULT_SECONDS = 600; // 10 minutes
+
+export type AutomationTimeoutValidation =
+  | { value: number | null }
+  | { errorKey: I18nKey };
+
+/**
+ * Validate a raw timeout string from the edit form. A blank string means "use
+ * the server default" (resolved as `null`). Otherwise the value must be a
+ * positive integer. When capability discovery supplies a ceiling, values above
+ * it are rejected before the request reaches the service.
+ */
+export function validateAutomationTimeout(
+  raw: string,
+  maxSeconds?: number,
+): AutomationTimeoutValidation {
+  const trimmed = raw.trim();
+  if (!trimmed) return { value: null };
+
+  const seconds = Number(trimmed);
+  if (!Number.isInteger(seconds)) {
+    return { errorKey: I18nKey.AUTOMATIONS$ERROR_TIMEOUT_INVALID_NUMBER };
+  }
+  if (seconds <= 0) {
+    return { errorKey: I18nKey.AUTOMATIONS$ERROR_TIMEOUT_POSITIVE };
+  }
+  if (maxSeconds !== undefined && seconds > maxSeconds) {
+    return { errorKey: I18nKey.AUTOMATIONS$ERROR_TIMEOUT_MAX_EXCEEDED };
+  }
+  return { value: seconds };
+}

src/utils/cache-utils.ts

@@ -0,0 +1,61 @@
+import { QueryClient } from "@tanstack/react-query";
+import type { ActionEvent } from "#/types/agent-server/core/events/action-event";
+import { useModelStore } from "#/stores/model-store";
+import { stripWorkspacePrefix } from "./path-utils";
+
+/**
+ * Cache invalidation utilities for TanStack Query
+ */
+
+/**
+ * Handle cache invalidation for ActionEvent
+ * Invalidates relevant query caches based on the action type
+ *
+ * @param event - The ActionEvent to process
+ * @param conversationId - The conversation ID for cache keys
+ * @param queryClient - The TanStack Query client instance
+ */
+export const handleActionEventCacheInvalidation = (
+  event: ActionEvent,
+  conversationId: string,
+  queryClient: QueryClient,
+) => {
+  const { action } = event;
+
+  // Invalidate file_changes cache for file-related actions
+  if (
+    action.kind === "StrReplaceEditorAction" ||
+    action.kind === "FileEditorAction" ||
+    action.kind === "ExecuteBashAction"
+  ) {
+    queryClient.invalidateQueries(
+      {
+        queryKey: ["file_changes", conversationId],
+      },
+      { cancelRefetch: false },
+    );
+  }
+
+  // Invalidate specific file diff cache for file modifications
+  if (
+    (action.kind === "StrReplaceEditorAction" ||
+      action.kind === "FileEditorAction") &&
+    action.path
+  ) {
+    const strippedPath = stripWorkspacePrefix(action.path);
+    queryClient.invalidateQueries({
+      queryKey: ["file_diff", conversationId, strippedPath],
+    });
+  }
+
+  // When the agent autonomously swaps the LLM via SwitchLLMTool, refresh the
+  // conversation so SwitchProfileButton / ChatInputModel pick up the new
+  // `llm_model`, and drop any previously-set optimistic profile name (it
+  // would now misrepresent the agent's choice).
+  if (event.tool_name === "SwitchLLMTool") {
+    queryClient.invalidateQueries({
+      queryKey: ["user", "conversation", conversationId],
+    });
+    useModelStore.getState().clearActiveProfile(conversationId);
+  }
+};

src/utils/constants.ts

@@ -0,0 +1,127 @@
+import { SlashCommandItem } from "#/hooks/chat/use-slash-command";
+
+export const JSON_VIEW_THEME = {
+  base00: "transparent", // background
+  base01: "var(--cool-grey-900)", // lighter background
+  base02: "var(--cool-grey-700)", // selection background
+  base03: "var(--cool-grey-600)", // comments, invisibles
+  base04: "var(--cool-grey-500)", // dark foreground
+  base05: "var(--cool-grey-200)", // default foreground
+  base06: "var(--cool-grey-100)", // light foreground
+  base07: "#ffffff", // light background
+  base08: "#ff5370", // variables, red
+  base09: "#f78c6c", // integers, orange
+  base0A: "#ffcb6b", // booleans, yellow
+  base0B: "#c3e88d", // strings, green
+  base0C: "#89ddff", // support, cyan
+  base0D: "#82aaff", // functions, blue
+  base0E: "#c792ea", // keywords, purple
+  base0F: "#ff5370", // deprecated, red
+};
+
+export const PRODUCT_URL = {
+  PRODUCTION: "https://app.all-hands.dev",
+};
+
+export const SETTINGS_FORM = {
+  LABEL_CLASSNAME: "text-[11px] font-medium leading-4 tracking-[0.11px]",
+};
+
+// Chat input constants
+export const CHAT_INPUT = {
+  HEIGHT_THRESHOLD: 100, // Height in pixels when suggestions should be hidden
+};
+
+// UI tolerance constants
+export const EPS = 1.5; // px tolerance for "near min" height comparisons
+
+/** The /btw slash command — asks a side question via the ask_agent endpoint. */
+export const BTW_COMMAND = "/btw";
+
+/** The /model slash command — lists or switches the conversation's LLM profile. */
+export const MODEL_COMMAND = "/model";
+
+/** The /goal slash command — drives the agent toward an objective, judging completion each round. */
+export const GOAL_COMMAND = "/goal";
+
+/** The /plan slash command — switches the conversation into Plan mode. */
+export const PLAN_COMMAND = "/plan";
+
+/** The /code slash command — switches the conversation back to Code mode. */
+export const CODE_COMMAND = "/code";
+
+/** Built-in slash commands surfaced in the menu for V1 conversations. */
+export const BUILT_IN_COMMANDS: SlashCommandItem[] = [
+  {
+    skill: {
+      name: "new",
+      type: "agentskills",
+      source: null,
+      content: "Creates a new conversation using the same runtime",
+      triggers: ["/new"],
+    },
+    command: "/new",
+  },
+  {
+    skill: {
+      name: "btw",
+      type: "agentskills",
+      source: null,
+      content: "Ask the agent a side question without derailing the main task",
+      triggers: [BTW_COMMAND],
+    },
+    command: BTW_COMMAND,
+  },
+  {
+    skill: {
+      name: "model",
+      type: "agentskills",
+      source: null,
+      content:
+        "List saved LLM profiles, or switch the conversation LLM profile with /model <name>",
+      triggers: [MODEL_COMMAND],
+    },
+    command: MODEL_COMMAND,
+  },
+  {
+    skill: {
+      name: "goal",
+      type: "agentskills",
+      source: null,
+      content:
+        "Drive the agent toward an objective until a judge says it's done — /goal <objective> or /goal --max <n> <objective>",
+      triggers: [GOAL_COMMAND],
+    },
+    command: GOAL_COMMAND,
+  },
+  {
+    skill: {
+      name: "plan",
+      type: "agentskills",
+      source: null,
+      content:
+        "Switch the conversation into Plan mode, or start planning immediately with /plan <task>",
+      triggers: [PLAN_COMMAND],
+    },
+    command: PLAN_COMMAND,
+  },
+  {
+    skill: {
+      name: "code",
+      type: "agentskills",
+      source: null,
+      content:
+        "Switch the conversation back to Code mode, or resume immediately with /code <task>",
+      triggers: [CODE_COMMAND],
+    },
+    command: CODE_COMMAND,
+  },
+];
+
+// Skill content metadata prefixes
+export const METADATA_PREFIXES: readonly string[] = [
+  "The following information has been included",
+  "It may or may not be relevant",
+  "Skill location:",
+  "(Use this path to resolve",
+];

src/utils/conversation-archive-status.ts

@@ -0,0 +1,7 @@
+import type { SandboxStatus } from "#/api/conversation-service/agent-server-conversation-service.types";
+
+export function isArchivedSandboxStatus(
+  sandboxStatus: SandboxStatus | null | undefined,
+): boolean {
+  return sandboxStatus === "MISSING" || sandboxStatus === "ERROR";
+}

src/utils/conversation-local-storage.ts

@@ -0,0 +1,437 @@
+import { useEffect, useState } from "react";
+import type {
+  ConversationTab,
+  ConversationMode,
+} from "#/stores/conversation-store";
+import type { ViewMode } from "#/components/features/files-tab/view-mode";
+import {
+  DEFAULT_UNPINNED_OVERVIEW_GIT_PARTS,
+  DEFAULT_UNPINNED_OVERVIEW_SECTIONS,
+  VALID_CONVERSATION_OVERVIEW_GIT_PARTS,
+  VALID_CONVERSATION_OVERVIEW_SECTIONS,
+} from "#/components/features/conversation/conversation-overview-sections";
+
+export const LOCAL_STORAGE_KEYS = {
+  CONVERSATION_STATE: "conversation-state",
+  PENDING_TASK_DRAFT: "pending-task-draft",
+} as const;
+
+const CONVERSATION_STATE_UPDATED_EVENT = "conversation-state-updated";
+
+type ConversationStateUpdatedDetail = {
+  conversationId: string;
+};
+
+/**
+ * Consolidated conversation state stored in a single localStorage key.
+ *
+ * NOTE: the right-drawer open/closed state is intentionally *not* persisted
+ * here. Users expect the drawer to start closed every time the app is
+ * (re)loaded and only stay open when they opened it themselves during the
+ * current session. That state lives in the in-memory Zustand
+ * `useConversationStore` (`isRightPanelShown` / `hasRightPanelToggled`)
+ * which survives in-app navigation but resets on full reloads. Older
+ * builds wrote a `rightPanelShown` field into this blob; we accept and
+ * silently ignore that field on read so we don't churn old localStorage.
+ */
+export interface ConversationState {
+  selectedTab: ConversationTab | null;
+  unpinnedTabs: string[];
+  unpinnedOverviewSections?: string[];
+  unpinnedOverviewGitParts?: string[];
+  conversationMode: ConversationMode;
+  subConversationTaskId: string | null;
+  draftMessage: string | null;
+  rightPanelShown?: boolean;
+  /**
+   * Legacy Files-tab Diff/Files toggle preference. Kept for blob
+   * compatibility; the Files surface no longer hosts Diff/Commits
+   * (those live in the sibling Commits conversation tab).
+   */
+  filesTabDiffView: boolean | null;
+  /** User's persisted choice for the Files tab Rich/Plain content toggle. */
+  filesTabContentViewMode: ViewMode;
+  /** Whether the left-hand file tree is visible in the Files tab. */
+  filesTabTreeVisible?: boolean;
+  /** Open file tabs in the Files quick-row (basenames, closable). */
+  filesTabOpenPaths?: string[];
+  /** Currently selected path among `filesTabOpenPaths`, if any. */
+  filesTabSelectedPath?: string | null;
+}
+
+const DEFAULT_CONVERSATION_STATE: ConversationState = {
+  selectedTab: "files",
+  unpinnedTabs: [],
+  unpinnedOverviewSections: [...DEFAULT_UNPINNED_OVERVIEW_SECTIONS],
+  unpinnedOverviewGitParts: [...DEFAULT_UNPINNED_OVERVIEW_GIT_PARTS],
+  conversationMode: "code",
+  subConversationTaskId: null,
+  draftMessage: null,
+  rightPanelShown: false,
+  filesTabDiffView: null,
+  filesTabContentViewMode: "rich",
+  filesTabTreeVisible: true,
+  filesTabOpenPaths: [],
+  filesTabSelectedPath: null,
+};
+
+const VALID_CONVERSATION_TABS: ReadonlySet<ConversationTab> = new Set([
+  "files",
+  "commits",
+  "browser",
+  "terminal",
+  "planner",
+  "tasklist",
+  "usage",
+]);
+
+// Tab keys that *used to* exist and were removed during the Files tab
+// refactor. We strip these out of any persisted state on read so that
+// returning users don't keep ghost entries (in `selectedTab` or
+// `unpinnedTabs`) forever — the UI has no way to surface them again to
+// be re-pinned or re-selected. We deliberately use an explicit denylist
+// here rather than a strict "whitelist against VALID_CONVERSATION_TABS"
+// filter because `unpinnedTabs` is typed `string[]` and other parts of
+// the app legitimately store arbitrary tab keys in it (sub-conversation
+// tab ids etc.).
+const REMOVED_CONVERSATION_TABS: ReadonlySet<string> = new Set([
+  "editor",
+  "served",
+  "app",
+  "vscode",
+]);
+
+const VALID_VIEW_MODES: ReadonlySet<ViewMode> = new Set(["rich", "plain"]);
+
+function sanitizeStoredState(
+  stored: Record<string, unknown>,
+): Partial<ConversationState> {
+  let result: Partial<ConversationState> = stored as Partial<ConversationState>;
+
+  if (
+    result.selectedTab != null &&
+    (REMOVED_CONVERSATION_TABS.has(result.selectedTab) ||
+      (result.selectedTab as string) === "changes" ||
+      !VALID_CONVERSATION_TABS.has(result.selectedTab as ConversationTab))
+  ) {
+    const selectedTab = result.selectedTab as string;
+    result = { ...result };
+    if (selectedTab === "changes") {
+      result.selectedTab = "commits";
+    } else {
+      delete result.selectedTab;
+    }
+  }
+
+  if (result.unpinnedTabs) {
+    const filtered = result.unpinnedTabs.filter(
+      (tab) => tab !== "changes" && !REMOVED_CONVERSATION_TABS.has(tab),
+    );
+    if (filtered.length !== result.unpinnedTabs.length) {
+      result = { ...result, unpinnedTabs: filtered };
+    }
+  }
+
+  if (result.unpinnedOverviewSections) {
+    const filtered = result.unpinnedOverviewSections.filter((section) =>
+      VALID_CONVERSATION_OVERVIEW_SECTIONS.has(section),
+    );
+    if (filtered.length !== result.unpinnedOverviewSections.length) {
+      result = { ...result, unpinnedOverviewSections: filtered };
+    }
+  }
+
+  if (result.unpinnedOverviewGitParts) {
+    const filtered = result.unpinnedOverviewGitParts.filter((part) =>
+      VALID_CONVERSATION_OVERVIEW_GIT_PARTS.has(part),
+    );
+    if (filtered.length !== result.unpinnedOverviewGitParts.length) {
+      result = { ...result, unpinnedOverviewGitParts: filtered };
+    }
+  }
+
+  // Drop a corrupt/manually-edited `filesTabContentViewMode` so it falls
+  // back to the typed default ("rich") instead of leaking a junk string
+  // into ViewMode-typed consumers. TypeScript can't help us here — the
+  // value comes from `JSON.parse(localStorage.getItem(...))` which is
+  // unknown at runtime.
+  if (
+    result.filesTabContentViewMode != null &&
+    !VALID_VIEW_MODES.has(result.filesTabContentViewMode)
+  ) {
+    result = { ...result };
+    delete result.filesTabContentViewMode;
+  }
+
+  if (
+    result.rightPanelShown != null &&
+    typeof result.rightPanelShown !== "boolean"
+  ) {
+    result = { ...result };
+    delete result.rightPanelShown;
+  }
+
+  if (
+    result.filesTabTreeVisible != null &&
+    typeof result.filesTabTreeVisible !== "boolean"
+  ) {
+    result = { ...result };
+    delete result.filesTabTreeVisible;
+  }
+
+  if (result.filesTabOpenPaths != null) {
+    if (!Array.isArray(result.filesTabOpenPaths)) {
+      result = { ...result };
+      delete result.filesTabOpenPaths;
+    } else {
+      const filtered = result.filesTabOpenPaths.filter(
+        (path): path is string => typeof path === "string" && path.length > 0,
+      );
+      if (filtered.length !== result.filesTabOpenPaths.length) {
+        result = { ...result, filesTabOpenPaths: filtered };
+      }
+    }
+  }
+
+  if (
+    result.filesTabSelectedPath != null &&
+    typeof result.filesTabSelectedPath !== "string"
+  ) {
+    result = { ...result };
+    delete result.filesTabSelectedPath;
+  }
+
+  return result;
+}
+
+/**
+ * Check if a conversation ID is a temporary task ID that should not be persisted.
+ * Task IDs have the format "task-{uuid}" and are used during V1 conversation initialization.
+ */
+export function isTaskConversationId(conversationId: string): boolean {
+  return conversationId.startsWith("task-");
+}
+
+/**
+ * Whether persistence should be skipped for this conversation id.
+ *
+ * Skips:
+ *  - empty string ids (callers outside of a conversation route, e.g.
+ *    rendered inside a unit test without a NavigationProvider)
+ *  - "task-..." ids used as placeholders during V1 conversation
+ *    initialization
+ */
+function shouldSkipPersistence(conversationId: string): boolean {
+  return conversationId === "" || isTaskConversationId(conversationId);
+}
+
+/**
+ * Get the full conversation state from localStorage.
+ */
+export function getConversationState(
+  conversationId: string,
+): ConversationState {
+  if (shouldSkipPersistence(conversationId)) {
+    return DEFAULT_CONVERSATION_STATE;
+  }
+  try {
+    const key = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`;
+    const item = localStorage.getItem(key);
+    if (item !== null) {
+      return {
+        ...DEFAULT_CONVERSATION_STATE,
+        ...sanitizeStoredState(JSON.parse(item)),
+      };
+    }
+    return DEFAULT_CONVERSATION_STATE;
+  } catch {
+    return DEFAULT_CONVERSATION_STATE;
+  }
+}
+
+/**
+ * Set the conversation state in localStorage, merging with existing state.
+ */
+export function setConversationState(
+  conversationId: string,
+  updates: Partial<ConversationState>,
+): void {
+  if (shouldSkipPersistence(conversationId)) {
+    return;
+  }
+  try {
+    const key = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`;
+    const currentState = getConversationState(conversationId);
+    const newState = { ...currentState, ...updates };
+    localStorage.setItem(key, JSON.stringify(newState));
+    if (typeof window !== "undefined") {
+      window.dispatchEvent(
+        new CustomEvent<ConversationStateUpdatedDetail>(
+          CONVERSATION_STATE_UPDATED_EVENT,
+          { detail: { conversationId } },
+        ),
+      );
+    }
+  } catch (err) {
+    console.warn("Failed to set conversation localStorage", err);
+  }
+}
+
+function getPendingTaskDraftKey(taskId: string): string {
+  return `${LOCAL_STORAGE_KEYS.PENDING_TASK_DRAFT}-${taskId}`;
+}
+
+export function setPendingTaskDraft(
+  taskId: string | null | undefined,
+  draftMessage: string,
+): void {
+  if (!taskId) return;
+  try {
+    localStorage.setItem(getPendingTaskDraftKey(taskId), draftMessage);
+  } catch (err) {
+    console.warn("Failed to store pending task draft", err);
+  }
+}
+
+export function consumePendingTaskDraft(
+  taskId: string | null | undefined,
+): string | null {
+  if (!taskId) return null;
+  try {
+    const key = getPendingTaskDraftKey(taskId);
+    const draft = localStorage.getItem(key);
+    localStorage.removeItem(key);
+    return draft;
+  } catch (err) {
+    console.warn("Failed to consume pending task draft", err);
+    return null;
+  }
+}
+
+export function clearConversationLocalStorage(conversationId: string) {
+  try {
+    const key = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`;
+    localStorage.removeItem(key);
+    if (typeof window !== "undefined") {
+      window.dispatchEvent(
+        new CustomEvent<ConversationStateUpdatedDetail>(
+          CONVERSATION_STATE_UPDATED_EVENT,
+          { detail: { conversationId } },
+        ),
+      );
+    }
+  } catch (err) {
+    console.warn(
+      "Failed to clear conversation localStorage",
+      conversationId,
+      err,
+    );
+  }
+}
+
+/**
+ * React hook for conversation-scoped localStorage state.
+ * Returns the full state and individual setters for each property.
+ *
+ * The right-drawer open state is deliberately not represented here —
+ * see the note on `ConversationState` for the rationale.
+ */
+export function useConversationLocalStorageState(conversationId: string): {
+  state: ConversationState;
+  setSelectedTab: (tab: ConversationTab | null) => void;
+  setUnpinnedTabs: (tabs: string[]) => void;
+  setUnpinnedOverviewSections?: (sections: string[]) => void;
+  setUnpinnedOverviewGitParts?: (parts: string[]) => void;
+  setConversationMode: (mode: ConversationMode) => void;
+  setDraftMessage: (message: string | null) => void;
+  setRightPanelShown?: (shown: boolean) => void;
+  setFilesTabDiffView: (diffView: boolean | null) => void;
+  setFilesTabContentViewMode: (mode: ViewMode) => void;
+  setFilesTabTreeVisible?: (visible: boolean) => void;
+  setFilesTabOpenState?: (
+    openPaths: string[],
+    selectedPath: string | null,
+  ) => void;
+} {
+  const [state, setState] = useState<ConversationState>(() =>
+    getConversationState(conversationId),
+  );
+
+  useEffect(() => {
+    if (typeof window === "undefined") {
+      return undefined;
+    }
+
+    const key = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`;
+
+    const syncState = () => {
+      setState(getConversationState(conversationId));
+    };
+
+    const handleStorage = (event: StorageEvent) => {
+      if (event.key === key) {
+        syncState();
+      }
+    };
+
+    const handleConversationStateUpdated = (event: Event) => {
+      const customEvent = event as CustomEvent<ConversationStateUpdatedDetail>;
+      if (customEvent.detail?.conversationId === conversationId) {
+        syncState();
+      }
+    };
+
+    // Ensure this hook reflects latest state for the current conversation ID.
+    syncState();
+
+    window.addEventListener("storage", handleStorage);
+    window.addEventListener(
+      CONVERSATION_STATE_UPDATED_EVENT,
+      handleConversationStateUpdated,
+    );
+
+    return () => {
+      window.removeEventListener("storage", handleStorage);
+      window.removeEventListener(
+        CONVERSATION_STATE_UPDATED_EVENT,
+        handleConversationStateUpdated,
+      );
+    };
+  }, [conversationId]);
+
+  const updateState = (updates: Partial<ConversationState>) => {
+    if (shouldSkipPersistence(conversationId)) {
+      // No durable storage for this id (empty / task placeholder), but the
+      // hook is still useful as ephemeral in-memory state — update the
+      // local React mirror directly so toggles in the UI behave normally
+      // until a real conversation id arrives.
+      setState((prev) => ({ ...prev, ...updates }));
+      return;
+    }
+    setConversationState(conversationId, updates);
+  };
+
+  return {
+    state,
+    setSelectedTab: (tab) => updateState({ selectedTab: tab }),
+    setUnpinnedTabs: (tabs) => updateState({ unpinnedTabs: tabs }),
+    setUnpinnedOverviewSections: (sections) =>
+      updateState({ unpinnedOverviewSections: sections }),
+    setUnpinnedOverviewGitParts: (parts) =>
+      updateState({ unpinnedOverviewGitParts: parts }),
+    setConversationMode: (mode) => updateState({ conversationMode: mode }),
+    setDraftMessage: (message) => updateState({ draftMessage: message }),
+    setRightPanelShown: (shown) => updateState({ rightPanelShown: shown }),
+    setFilesTabDiffView: (diffView) =>
+      updateState({ filesTabDiffView: diffView }),
+    setFilesTabContentViewMode: (mode) =>
+      updateState({ filesTabContentViewMode: mode }),
+    setFilesTabTreeVisible: (visible) =>
+      updateState({ filesTabTreeVisible: visible }),
+    setFilesTabOpenState: (openPaths, selectedPath) =>
+      updateState({
+        filesTabOpenPaths: openPaths,
+        filesTabSelectedPath: selectedPath,
+      }),
+  };
+}

src/utils/conversation-metrics.ts

@@ -0,0 +1,79 @@
+import type {
+  MetricsSnapshot,
+  RuntimeConversationInfo,
+  RuntimeConversationStats,
+  TokenUsage,
+} from "#/api/conversation-service/agent-server-conversation-service.types";
+
+/**
+ * TypeScript equivalent of the get_combined_metrics method from the Python SDK
+ * Combines metrics from all LLM usage IDs in a conversation's stats
+ */
+export function combineUsageMetrics(
+  stats: RuntimeConversationStats | null | undefined,
+): MetricsSnapshot {
+  if (!stats?.usage_to_metrics) {
+    return {
+      accumulated_cost: 0,
+      max_budget_per_task: null,
+      accumulated_token_usage: null,
+    };
+  }
+
+  let totalCost = 0;
+  let maxBudgetPerTask: number | null = null;
+  let combinedTokenUsage: TokenUsage | null = null;
+
+  // Iterate through all metrics and combine them
+  for (const metrics of Object.values(stats.usage_to_metrics)) {
+    // Add up costs
+    totalCost += metrics.accumulated_cost;
+
+    // Keep the max budget per task if any is set
+    if (maxBudgetPerTask === null && metrics.max_budget_per_task !== null) {
+      maxBudgetPerTask = metrics.max_budget_per_task;
+    }
+
+    // Combine token usage
+    if (metrics.accumulated_token_usage) {
+      if (combinedTokenUsage === null) {
+        combinedTokenUsage = { ...metrics.accumulated_token_usage };
+      } else {
+        combinedTokenUsage = {
+          prompt_tokens:
+            combinedTokenUsage.prompt_tokens +
+            metrics.accumulated_token_usage.prompt_tokens,
+          completion_tokens:
+            combinedTokenUsage.completion_tokens +
+            metrics.accumulated_token_usage.completion_tokens,
+          cache_read_tokens:
+            combinedTokenUsage.cache_read_tokens +
+            metrics.accumulated_token_usage.cache_read_tokens,
+          cache_write_tokens:
+            combinedTokenUsage.cache_write_tokens +
+            metrics.accumulated_token_usage.cache_write_tokens,
+          context_window: Math.max(
+            combinedTokenUsage.context_window,
+            metrics.accumulated_token_usage.context_window,
+          ),
+          per_turn_token: Math.max(
+            combinedTokenUsage.per_turn_token,
+            metrics.accumulated_token_usage.per_turn_token,
+          ),
+        };
+      }
+    }
+  }
+
+  return {
+    accumulated_cost: totalCost,
+    max_budget_per_task: maxBudgetPerTask,
+    accumulated_token_usage: combinedTokenUsage,
+  };
+}
+
+export function getCombinedMetrics(
+  conversationInfo: RuntimeConversationInfo,
+): MetricsSnapshot {
+  return combineUsageMetrics(conversationInfo.stats);
+}

src/utils/conversation-overview-project-scope.ts

@@ -0,0 +1,116 @@
+import type { Automation } from "#/types/automation";
+import type { SkillInfo } from "#/types/settings";
+import {
+  getSkillScope,
+  SKILL_SCOPE_ORDER,
+  type SkillScope,
+} from "#/utils/skill-scope";
+
+export const CONVERSATION_OVERVIEW_PROJECT_SCOPE = {
+  project: "project",
+  all: "all",
+} as const;
+
+export type ConversationOverviewProjectScope =
+  (typeof CONVERSATION_OVERVIEW_PROJECT_SCOPE)[keyof typeof CONVERSATION_OVERVIEW_PROJECT_SCOPE];
+
+export function normalizeRepositoryName(
+  repository: string | null | undefined,
+): string | null {
+  if (!repository?.trim()) {
+    return null;
+  }
+  return repository
+    .trim()
+    .toLowerCase()
+    .replace(/\.git$/, "");
+}
+
+export function isAutomationForRepository(
+  automation: Pick<Automation, "repository">,
+  repository: string | null | undefined,
+): boolean {
+  const target = normalizeRepositoryName(repository);
+  const automationRepo = normalizeRepositoryName(automation.repository);
+  if (!target || !automationRepo) {
+    return false;
+  }
+  return automationRepo === target;
+}
+
+export function isSkillForProject(
+  skill: SkillInfo,
+  projectDir?: string | null,
+): boolean {
+  return getSkillScope(skill, projectDir) === "project";
+}
+
+export function filterAutomationsByProjectScope(
+  automations: Automation[],
+  scope: ConversationOverviewProjectScope,
+  repository: string | null | undefined,
+): Automation[] {
+  if (scope === CONVERSATION_OVERVIEW_PROJECT_SCOPE.all) {
+    return automations;
+  }
+  return automations.filter((automation) =>
+    isAutomationForRepository(automation, repository),
+  );
+}
+
+export function filterSkillsByProjectScope(
+  skills: SkillInfo[],
+  scope: ConversationOverviewProjectScope,
+  projectDir?: string | null,
+): SkillInfo[] {
+  if (scope === CONVERSATION_OVERVIEW_PROJECT_SCOPE.all) {
+    return skills;
+  }
+  return skills.filter((skill) => isSkillForProject(skill, projectDir));
+}
+
+export function sortAutomationsByProjectRelevance(
+  automations: Automation[],
+  repository: string | null | undefined,
+): Automation[] {
+  return [...automations].sort((left, right) => {
+    const leftMatch = isAutomationForRepository(left, repository) ? 0 : 1;
+    const rightMatch = isAutomationForRepository(right, repository) ? 0 : 1;
+    if (leftMatch !== rightMatch) {
+      return leftMatch - rightMatch;
+    }
+    return left.name.localeCompare(right.name);
+  });
+}
+
+export function sortSkillsByProjectRelevance(
+  skills: SkillInfo[],
+  projectDir?: string | null,
+): SkillInfo[] {
+  return [...skills].sort((left, right) => {
+    const leftScope = getSkillScope(left, projectDir);
+    const rightScope = getSkillScope(right, projectDir);
+    const leftOrder = SKILL_SCOPE_ORDER.indexOf(leftScope as SkillScope);
+    const rightOrder = SKILL_SCOPE_ORDER.indexOf(rightScope as SkillScope);
+    if (leftOrder !== rightOrder) {
+      return leftOrder - rightOrder;
+    }
+    return left.name.localeCompare(right.name);
+  });
+}
+
+export function countAutomationsForRepository(
+  automations: readonly Automation[],
+  repository: string | null | undefined,
+): number {
+  return automations.filter((automation) =>
+    isAutomationForRepository(automation, repository),
+  ).length;
+}
+
+export function countSkillsForProject(
+  skills: readonly SkillInfo[],
+  projectDir?: string | null,
+): number {
+  return skills.filter((skill) => isSkillForProject(skill, projectDir)).length;
+}

src/utils/convert-image-to-base-64.ts

@@ -0,0 +1,9 @@
+export const convertImageToBase64 = (file: File): Promise<string> =>
+  new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onloadend = () => {
+      resolve(reader.result as string);
+    };
+    reader.onerror = reject;
+    reader.readAsDataURL(file);
+  });

src/utils/convert-raw-providers-to-list.ts

@@ -0,0 +1,14 @@
+import { Provider } from "#/types/settings";
+
+export const convertRawProvidersToList = (
+  raw: Partial<Record<Provider, string | null>> | undefined,
+): Provider[] => {
+  if (!raw) return [];
+  const list: Provider[] = [];
+  for (const key of Object.keys(raw)) {
+    if (key) {
+      list.push(key as Provider);
+    }
+  }
+  return list;
+};

src/utils/custom-toast-handlers.tsx

@@ -0,0 +1,150 @@
+import React, { CSSProperties, ReactNode } from "react";
+import { CircleX } from "lucide-react";
+import toast, { ToastOptions } from "react-hot-toast";
+import { OH_STATUS_ERROR_COLOR } from "#/constants/status-colors";
+import { calculateToastDuration } from "./toast-duration";
+import { cn } from "#/utils/utils";
+import i18n from "#/i18n";
+import { I18nKey } from "#/i18n/declaration";
+import {
+  isBackendRequestTimeoutMessage,
+  isCorsOrNetworkErrorMessage,
+} from "./user-facing-error";
+
+// react-hot-toast accepts only CSSProperties via the style option — cannot use className
+const TOAST_STYLE: CSSProperties = {
+  background: "var(--oh-color-tertiary)",
+  border: "1px solid var(--oh-border-input)",
+  color: "#fff",
+  borderRadius: "var(--oh-radius)",
+  maxWidth: "400px",
+  wordBreak: "break-word",
+  overflowWrap: "anywhere",
+  whiteSpace: "pre-wrap",
+};
+
+export const TOAST_OPTIONS: ToastOptions = {
+  position: "top-right",
+  style: TOAST_STYLE,
+};
+
+const ERROR_TOAST_STYLE: CSSProperties = {
+  ...TOAST_STYLE,
+  color: "var(--oh-muted)",
+};
+
+/** Icon + message row; center icon for single-line text, top-align when wrapped. */
+export function ErrorToastContent({ message }: { message: ReactNode }) {
+  const contentRef = React.useRef<HTMLSpanElement>(null);
+  const [isMultiLine, setIsMultiLine] = React.useState(false);
+
+  React.useLayoutEffect(() => {
+    const content = contentRef.current;
+    if (!content) {
+      return undefined;
+    }
+
+    const updateIsMultiLine = () => {
+      const lineHeight = Number.parseFloat(
+        getComputedStyle(content).lineHeight,
+      );
+      if (!Number.isFinite(lineHeight) || lineHeight <= 0) {
+        setIsMultiLine(false);
+        return;
+      }
+
+      setIsMultiLine(content.getBoundingClientRect().height > lineHeight * 1.5);
+    };
+
+    updateIsMultiLine();
+
+    const observer = new ResizeObserver(updateIsMultiLine);
+    observer.observe(content);
+
+    return () => observer.disconnect();
+  }, [message]);
+
+  return (
+    <div
+      className={cn(
+        "flex min-w-0 gap-2",
+        isMultiLine ? "items-start" : "items-center",
+      )}
+    >
+      <CircleX
+        aria-hidden
+        className="h-4 w-4 shrink-0"
+        strokeWidth={2}
+        style={{ color: OH_STATUS_ERROR_COLOR }}
+      />
+      <span
+        ref={contentRef}
+        className="min-w-0 flex-1 text-sm leading-5 [word-break:break-word] [overflow-wrap:anywhere]"
+      >
+        {message}
+      </span>
+    </div>
+  );
+}
+
+export const ERROR_TOAST_OPTIONS: ToastOptions = {
+  ...TOAST_OPTIONS,
+  icon: null,
+  style: ERROR_TOAST_STYLE,
+};
+
+export const displayErrorToast = (error: string | null | undefined) => {
+  let errorMessage = error || i18n.t(I18nKey.STATUS$ERROR);
+  if (isCorsOrNetworkErrorMessage(errorMessage)) {
+    errorMessage = i18n.t(I18nKey.ERROR$CORS_OR_NETWORK);
+  } else if (isBackendRequestTimeoutMessage(errorMessage)) {
+    errorMessage = i18n.t(I18nKey.ERROR$BACKEND_REQUEST_TIMEOUT);
+  }
+  const duration = calculateToastDuration(errorMessage, 4000);
+  toast(<ErrorToastContent message={errorMessage} />, {
+    ...ERROR_TOAST_OPTIONS,
+    duration,
+  });
+};
+
+export const displaySuccessToast = (message: string) => {
+  const duration = calculateToastDuration(message, 5000);
+  toast.success(
+    <span className="[word-break:break-word] [overflow-wrap:anywhere]">
+      {message}
+    </span>,
+    { ...TOAST_OPTIONS, duration },
+  );
+};
+
+export const displaySuccessToastWithLink = (
+  message: string,
+  linkLabel: string,
+  href: string,
+) => {
+  const duration = calculateToastDuration(`${message} ${linkLabel}`, 5000);
+  toast.success(
+    <span className="[word-break:break-word] [overflow-wrap:anywhere]">
+      {message}{" "}
+      <a className="underline hover:no-underline" href={href}>
+        {linkLabel}
+      </a>
+    </span>,
+    { ...TOAST_OPTIONS, duration },
+  );
+};
+
+/**
+ * Neutral, non-success notice — used when an action completed but the outcome
+ * is qualified (e.g. a secret was saved but the active backend can't consume it
+ * yet). Renders without the success checkmark so it doesn't read as "all good".
+ */
+export const displayWarningToast = (message: string) => {
+  const duration = calculateToastDuration(message, 6000);
+  toast(
+    <span className="[word-break:break-word] [overflow-wrap:anywhere]">
+      {message}
+    </span>,
+    { ...TOAST_OPTIONS, icon: "⚠️", duration },
+  );
+};

src/utils/derive-profile-name.ts

@@ -0,0 +1,49 @@
+/**
+ * Profile name validation pattern.
+ * Profile names: 1-64 chars, must start with alphanumeric, then alphanumerics
+ * or '.', '_', '-'. Blocks empty names, path separators, leading dots
+ * (hidden files / path traversal), and shell-special characters.
+ */
+export const PROFILE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+/**
+ * Shared profile name validation. Any whitespace (including leading/trailing)
+ * makes the value invalid. When `isRequired`, empty values are invalid;
+ * otherwise empty is valid.
+ */
+export function isProfileNameValid(
+  value: string,
+  { isRequired = false }: { isRequired?: boolean } = {},
+): boolean {
+  if (value === "") return !isRequired;
+  return PROFILE_NAME_PATTERN.test(value);
+}
+
+/**
+ * Derive a profile name from a model string.
+ * Extracts the model portion after the provider prefix (e.g., "openai/gpt-4" -> "gpt-4")
+ * and sanitizes it to match the profile name pattern.
+ */
+export function deriveProfileNameFromModel(model: string): string {
+  // Extract the model name after the last slash (provider/model format)
+  const parts = model.split("/");
+  const modelName = parts[parts.length - 1] || model;
+
+  // Sanitize: replace invalid characters with dashes
+  let sanitized = modelName
+    .replace(/[^A-Za-z0-9._-]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+  // Ensure it starts with alphanumeric
+  if (sanitized && !/^[A-Za-z0-9]/.test(sanitized)) {
+    sanitized = `profile-${sanitized}`;
+  }
+
+  // Truncate to 64 characters
+  if (sanitized.length > 64) {
+    sanitized = sanitized.substring(0, 64).replace(/-+$/, "");
+  }
+
+  return sanitized || "default-profile";
+}

src/utils/dropdown-classes.ts

@@ -0,0 +1,90 @@
+import { cn } from "#/utils/utils";
+import { formControlShellClassName } from "#/utils/form-control-classes";
+
+/** Snap hover colors instantly — no transition-colors delay on menus/dropdowns. */
+export const dropdownInstantColorClassName = "transition-none";
+
+/** 2px vertical gap between rows in a dropdown/context menu list. */
+export const dropdownMenuListGapClassName = "gap-0.5";
+
+/** Standard horizontal gap between a row icon and its label. */
+export const dropdownMenuRowGapClassName = "gap-2";
+
+/** Flex column shell for a dropdown menu item list. */
+export const dropdownMenuListClassName = cn(
+  "flex flex-col",
+  dropdownMenuListGapClassName,
+);
+
+/** Combobox/select trigger shell with instant hover colors. */
+export const dropdownTriggerShellClassName = cn(
+  "bg-tertiary border border-[var(--oh-border-input)] rounded p-2",
+  "flex items-center gap-2",
+  formControlShellClassName,
+  dropdownInstantColorClassName,
+  "group w-full gap-2 px-3 text-[var(--oh-muted)] hover:text-white",
+);
+
+/** Standard white-label menu row. */
+export const dropdownMenuRowClassName = cn(
+  "group flex w-full cursor-pointer items-center rounded px-2 py-2 text-left text-sm font-normal text-white",
+  dropdownMenuRowGapClassName,
+  "hover:bg-[var(--oh-interactive-hover)] disabled:cursor-not-allowed disabled:opacity-60",
+  dropdownInstantColorClassName,
+);
+
+/** Menu row using foreground token (context menus). */
+export const dropdownMenuRowForegroundClassName = cn(
+  "group flex w-full cursor-pointer items-center rounded px-2 py-2 text-start text-sm font-normal",
+  dropdownMenuRowGapClassName,
+  "text-[var(--oh-foreground)] hover:bg-[var(--oh-interactive-hover)]",
+  "disabled:cursor-not-allowed disabled:opacity-50 disabled:hover:bg-transparent",
+  dropdownInstantColorClassName,
+);
+
+/** Icon inside a menu row — muted until row hover/focus. */
+export const dropdownMenuRowIconClassName = cn(
+  "shrink-0 text-[var(--oh-muted)] group-hover:text-white group-focus-visible:text-white",
+  dropdownInstantColorClassName,
+);
+
+/** Wrapper for SVG/React icon nodes inside a menu row. */
+export const dropdownMenuRowIconWrapperClassName = cn(
+  "flex size-4 shrink-0 items-center justify-center [&_svg]:text-current",
+  dropdownMenuRowIconClassName,
+);
+
+/** Enum/filter dropdown trigger chip. */
+export const dropdownFilterTriggerClassName = cn(
+  "inline-flex cursor-pointer items-center gap-1.5 rounded-lg border px-3 py-2 text-sm font-medium",
+  "border-[var(--oh-border)] bg-base-secondary text-white",
+  "focus-visible:border-white/40 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-white/20",
+  dropdownInstantColorClassName,
+);
+
+/**
+ * Scroll cap for the switch-profile menu: four two-line rows
+ * (p-2 + leading-5 title + gap-0.5 + leading-4 subtitle) plus list gaps.
+ */
+export const switchProfileMenuListScrollClassName = cn(
+  dropdownMenuListClassName,
+  "overflow-y-auto custom-scrollbar-always",
+  "max-h-[13.875rem]",
+);
+
+/**
+ * Tall sidebar/context menus: cap height to the viewport and scroll with the
+ * custom scrollbar when content overflows (no scrollbar when everything fits).
+ */
+export const dropdownMenuViewportScrollClassName = cn(
+  "overflow-y-auto custom-scrollbar",
+  "max-h-[min(60vh,calc(100dvh-5rem))]",
+);
+
+/** Footer action row inside a dropdown panel. */
+export const dropdownFooterActionClassName = cn(
+  "group flex w-full items-center rounded-md px-2 py-2 text-sm font-normal text-white",
+  dropdownMenuRowGapClassName,
+  "hover:bg-[var(--oh-interactive-hover)]",
+  dropdownInstantColorClassName,
+);

src/utils/enqueue-home-task-pending-message.ts

@@ -0,0 +1,30 @@
+import { partitionImagesForUpload } from "#/components/features/chat/utils/chat-input.utils";
+import { useOptimisticUserMessageStore } from "#/stores/optimistic-user-message-store";
+import { convertImageToBase64 } from "#/utils/convert-image-to-base-64";
+
+/**
+ * Shows the user's first message immediately on cloud start-task routes
+ * (`/conversations/task-{uuid}`) while the sandbox provisions.
+ */
+export async function enqueueHomeTaskPendingMessage(options: {
+  conversationId: string;
+  text: string;
+  images: File[];
+  imagesMarkedUploadAsFile: string[];
+}): Promise<void> {
+  const { imagesToEmbed } = partitionImagesForUpload(
+    options.images,
+    options.imagesMarkedUploadAsFile,
+  );
+  const imageUrls = await Promise.all(
+    imagesToEmbed.map((image) => convertImageToBase64(image)),
+  );
+
+  useOptimisticUserMessageStore.getState().enqueuePendingMessage({
+    conversationId: options.conversationId,
+    text: options.text,
+    content: options.text,
+    imageUrls,
+    fileUrls: [],
+  });
+}