Add files using upload-large-folder tool

src/api/README.md

@@ -0,0 +1,98 @@
+# API Services Guide
+
+## Overview
+
+Services are the abstraction layer between frontend components and backend APIs. Local agent-server API access should use `@openhands/typescript-client` classes directly, with shared connection options from `src/api/agent-server-client-options.ts` for the active local backend host, session API key, and workspace defaults.
+
+Cloud-specific APIs should use the cloud service modules/proxy helpers instead of local agent-server clients.
+
+Each service is a plain object with async methods.
+
+## Structure
+
+Each service lives in its own directory:
+
+```
+src/api/
+└── feature-service/
+    ├── feature-service.api.ts    # Service methods
+    └── feature.types.ts          # Types and interfaces
+```
+
+## Creating a Service
+
+Use an object literal with named export. Use object destructuring for parameters to make calls self-documenting. Prefer typed `@openhands/typescript-client` classes over generic HTTP calls. If a needed endpoint is missing, add it to `@openhands/typescript-client` first.
+
+```typescript
+// feature-service/feature-service.api.ts
+import { FeatureClient } from "@openhands/typescript-client/clients";
+import { getAgentServerClientOptions } from "../agent-server-client-options";
+import { Feature, CreateFeatureParams } from "./feature.types";
+
+export const featureService = {
+  getFeature: async ({ id }: { id: string }): Promise<Feature> => {
+    return new FeatureClient(getAgentServerClientOptions()).getFeature(id);
+  },
+
+  createFeature: async (params: CreateFeatureParams): Promise<Feature> => {
+    return new FeatureClient(getAgentServerClientOptions()).createFeature(params);
+  },
+};
+```
+
+### Types
+
+Define app-specific types in a separate file within the same directory when the TypeScript client models are not sufficient:
+
+```typescript
+// feature-service/feature.types.ts
+export interface Feature {
+  id: string;
+  name: string;
+  description: string;
+}
+
+export interface CreateFeatureParams {
+  name: string;
+  description: string;
+}
+```
+
+## Usage
+
+> [!IMPORTANT]
+> **Don't call services directly in components.** Wrap them in TanStack Query hooks.
+>
+> Why? TanStack Query provides:
+>
+> - **Caching** - Avoid redundant network requests
+> - **Deduplication** - Multiple components requesting the same data share one request
+> - **Loading/error states** - Built-in `isLoading`, `isError`, `data` states
+> - **Background refetching** - Data stays fresh automatically
+>
+> Hooks location:
+>
+> - `src/hooks/query/` for data fetching (`useQuery`)
+> - `src/hooks/mutation/` for writes/updates (`useMutation`)
+
+```typescript
+// src/hooks/query/use-feature.ts
+import { useQuery } from "@tanstack/react-query";
+import { featureService } from "#/api/feature-service/feature-service.api";
+
+export const useFeature = (id: string) => {
+  return useQuery({
+    queryKey: ["feature", id],
+    queryFn: () => featureService.getFeature({ id }),
+  });
+};
+```
+
+## Naming Conventions
+
+| Item         | Convention               | Example                  |
+| ------------ | ------------------------ | ------------------------ |
+| Directory    | `feature-service/`       | `secrets-service/`       |
+| Service file | `feature-service.api.ts` | `secrets-service.api.ts` |
+| Types file   | `feature.types.ts`       | `secrets.types.ts`       |
+| Export name  | `featureService`         | `secretsService`         |

src/api/agent-canvas-updates.test.ts

@@ -0,0 +1,41 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { fetchLatestAgentCanvasVersion } from "./agent-canvas-updates";
+
+function stubFetchResponse(response: Partial<Response>) {
+  const fetchMock = vi.fn().mockResolvedValue(response as Response);
+  vi.stubGlobal("fetch", fetchMock);
+  return fetchMock;
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("fetchLatestAgentCanvasVersion", () => {
+  it("fetches the npm registry latest dist-tag and returns the trimmed version", async () => {
+    const fetchMock = stubFetchResponse({
+      ok: true,
+      json: async () => ({ version: " 1.6.0 " }),
+    });
+
+    await expect(fetchLatestAgentCanvasVersion()).resolves.toBe("1.6.0");
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://registry.npmjs.org/@openhands/agent-canvas/latest",
+      expect.objectContaining({ headers: { Accept: "application/json" } }),
+    );
+  });
+
+  it("rejects when the registry responds with an error status", async () => {
+    stubFetchResponse({ ok: false, status: 503 });
+
+    await expect(fetchLatestAgentCanvasVersion()).rejects.toThrow("503");
+  });
+
+  it("rejects when the response has no usable version field", async () => {
+    stubFetchResponse({ ok: true, json: async () => ({ version: 42 }) });
+
+    await expect(fetchLatestAgentCanvasVersion()).rejects.toThrow(
+      "missing version",
+    );
+  });
+});

src/api/agent-canvas-updates.ts

@@ -0,0 +1,37 @@
+/**
+ * Source of truth for "is a newer Agent Canvas published?".
+ *
+ * The npm registry `latest` dist-tag endpoint is CORS-open and returns the
+ * abbreviated packument for that version as JSON. Isolated here so the
+ * release channel can change (e.g. GitHub releases) without touching the
+ * query hook or the settings update card.
+ */
+const NPM_LATEST_VERSION_URL =
+  "https://registry.npmjs.org/@openhands/agent-canvas/latest";
+
+export const AGENT_CANVAS_RELEASE_NOTES_URL =
+  "https://github.com/OpenHands/OpenHands/releases";
+
+/** Literal shell commands — intentionally not localized. */
+export const AGENT_CANVAS_UPDATE_COMMANDS = {
+  npm: "npm install -g @openhands/agent-canvas@latest",
+  docker: "docker pull ghcr.io/openhands/agent-canvas:latest",
+} as const;
+
+export async function fetchLatestAgentCanvasVersion(
+  signal?: AbortSignal,
+): Promise<string> {
+  const response = await fetch(NPM_LATEST_VERSION_URL, {
+    signal,
+    headers: { Accept: "application/json" },
+  });
+  if (!response.ok) {
+    throw new Error(`npm registry responded ${response.status}`);
+  }
+  const body: unknown = await response.json();
+  const version = (body as { version?: unknown } | null)?.version;
+  if (typeof version !== "string" || !version.trim()) {
+    throw new Error("npm registry response missing version");
+  }
+  return version.trim();
+}

src/api/agent-server-adapter.test.ts

@@ -0,0 +1,704 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { CANVAS_UI_CLIENT_TOOL_NAME } from "#/constants/canvas-ui";
+import { LAUNCH_CHILD_CONVERSATION_TOOL_NAME } from "#/constants/child-conversation";
+import { DEFAULT_SETTINGS } from "#/services/settings";
+import type { Settings } from "#/types/settings";
+import {
+  AGENT_CANVAS_SOURCE,
+  CLIENT_SOURCE_TAG_KEY,
+  buildStartConversationRequest,
+  buildStartPlanningConversationRequest,
+  buildStartPlanningConversationRequestWithEncryptedSettings,
+  toConversationPage,
+} from "./agent-server-adapter";
+import SettingsService from "./settings-service/settings-service.api";
+import AgentProfilesService from "./agent-profiles-service/agent-profiles-service.api";
+import ProfilesService from "./profiles-service/profiles-service.api";
+
+vi.mock("./settings-service/settings-service.api", () => ({
+  default: { getSettingsForConversation: vi.fn() },
+}));
+vi.mock("./secrets-service", () => ({
+  SecretsService: { getSecrets: vi.fn().mockResolvedValue([]) },
+}));
+vi.mock("./agent-profiles-service/agent-profiles-service.api", () => ({
+  default: { listProfiles: vi.fn() },
+}));
+vi.mock("./profiles-service/profiles-service.api", () => ({
+  default: { getProfile: vi.fn() },
+}));
+
+const encryptedValue = "gAAAAAencrypted-mcp-header";
+
+function makeSettings(agentSettings: Settings["agent_settings"]): Settings {
+  return {
+    ...DEFAULT_SETTINGS,
+    agent_settings: agentSettings,
+    conversation_settings: {
+      confirmation_mode: false,
+      security_analyzer: null,
+      max_iterations: 20,
+    },
+  };
+}
+
+function getAgentContextSkillNames(
+  payload: ReturnType<typeof buildStartConversationRequest>,
+): Array<string | undefined> {
+  const agentSettings = payload.agent_settings as
+    | {
+        agent_context?: {
+          skills?: Array<{ name?: string }>;
+        };
+      }
+    | undefined;
+  return agentSettings?.agent_context?.skills?.map((skill) => skill.name) ?? [];
+}
+
+function getPlannerAgentContextSkillNames(payload: {
+  agent: { agent_context?: { skills?: Array<{ name?: string }> } };
+}): Array<string | undefined> {
+  return payload.agent.agent_context?.skills?.map((skill) => skill.name) ?? [];
+}
+
+describe("buildStartConversationRequest", () => {
+  it("marks OpenHands start requests as encrypted when MCP headers are encrypted", () => {
+    const agentSettings = {
+      agent_kind: "openhands",
+      llm: {
+        model: "litellm_proxy/openai/gpt-5.5",
+        api_key: "gAAAAAencrypted-llm-api-key",
+      },
+      mcp_config: {
+        linear: {
+          url: "https://mcp.linear.app/mcp",
+          transport: "http",
+          headers: {
+            Authorization: encryptedValue,
+          },
+        },
+      },
+    };
+    const settings = makeSettings(agentSettings);
+
+    const payload = buildStartConversationRequest({
+      settings,
+      encryptedAgentSettings: agentSettings,
+      encryptedConversationSettings: settings.conversation_settings!,
+      secretsEncrypted: true,
+    });
+
+    expect(payload.agent_settings!.agent_kind).toBe("openhands");
+    expect(payload.agent_settings!.mcp_config).toEqual(
+      agentSettings.mcp_config,
+    );
+    expect(payload.secrets_encrypted).toBe(true);
+  });
+
+  it("marks ACP start requests as encrypted when MCP headers are encrypted", () => {
+    const agentSettings = {
+      agent_kind: "acp",
+      acp_server: "codex",
+      acp_command: ["codex-acp"],
+      acp_model: "gpt-5.5/medium",
+      mcp_config: {
+        linear: {
+          url: "https://mcp.linear.app/mcp",
+          transport: "http",
+          headers: {
+            Authorization: encryptedValue,
+          },
+        },
+      },
+    };
+    const settings = makeSettings(agentSettings);
+
+    const payload = buildStartConversationRequest({
+      settings,
+      encryptedAgentSettings: agentSettings,
+      encryptedConversationSettings: settings.conversation_settings!,
+      secretsEncrypted: true,
+    });
+
+    expect(payload.agent_settings!.agent_kind).toBe("acp");
+    expect(payload.agent_settings!.mcp_config).toEqual(
+      agentSettings.mcp_config,
+    );
+    expect(payload.secrets_encrypted).toBe(true);
+  });
+
+  it("builds a raw planning agent request for local Planner", () => {
+    const agentSettings = {
+      agent_kind: "openhands",
+      llm: {
+        model: "openhands/minimax-m2.7",
+        api_key: "gAAAAAencrypted-llm-api-key",
+      },
+    };
+
+    const payload = buildStartPlanningConversationRequest({
+      encryptedAgentSettings: agentSettings,
+      workingDir: "/workspace/project/agent-canvas",
+      parentConversationId: "parent-1",
+      secretsEncrypted: true,
+      customSecrets: [{ name: "CUSTOM_TOKEN" }],
+    });
+
+    expect(payload.agent).toMatchObject({
+      kind: "Agent",
+      system_prompt_filename: "system_prompt_planning.j2",
+      system_prompt_kwargs: {
+        plan_structure: expect.stringContaining("OBJECTIVE"),
+      },
+      llm: {
+        model: "openhands/minimax-m2.7",
+        api_key: "gAAAAAencrypted-llm-api-key",
+      },
+      tools: [
+        { name: "glob", params: {} },
+        { name: "grep", params: {} },
+        {
+          name: "planning_file_editor",
+          params: {
+            plan_path: "/workspace/project/agent-canvas/.agents_tmp/PLAN.md",
+          },
+        },
+      ],
+      // Matches the SDK planning preset's get_planning_condenser.
+      condenser: {
+        kind: "LLMSummarizingCondenser",
+        max_size: 100,
+        keep_first: 6,
+        llm: {
+          model: "openhands/minimax-m2.7",
+          usage_id: "planning_condenser",
+        },
+      },
+    });
+    expect(payload.agent_settings).toBeUndefined();
+    expect(payload.worktree).toBe(false);
+    expect(payload.tags).toEqual({ plannerparent: "parent-1" });
+    expect(payload.secrets_encrypted).toBe(true);
+    expect(payload.secrets).toHaveProperty("CUSTOM_TOKEN");
+  });
+
+  it("links the local planner to its parent server-side so the relationship survives storage loss", () => {
+    const payload = buildStartPlanningConversationRequest({
+      encryptedAgentSettings: {
+        agent_kind: "openhands",
+        llm: { model: "openhands/minimax-m2.7" },
+      },
+      workingDir: "/workspace/project",
+      parentConversationId: "parent-1",
+    });
+
+    // The agent-server derives the parent's `sub_conversation_ids` from this,
+    // which is what makes the planner recoverable without localStorage.
+    expect(payload.parent_conversation_id).toBe("parent-1");
+  });
+
+  it("defaults the planner's max_iterations to 500 when not provided", () => {
+    const payload = buildStartPlanningConversationRequest({
+      encryptedAgentSettings: {
+        agent_kind: "openhands",
+        llm: { model: "openhands/minimax-m2.7" },
+      },
+      workingDir: "/workspace/project",
+      parentConversationId: "parent-1",
+    });
+
+    expect(payload.max_iterations).toBe(500);
+  });
+
+  it("uses the caller-provided max_iterations instead of the hardcoded default", () => {
+    const payload = buildStartPlanningConversationRequest({
+      encryptedAgentSettings: {
+        agent_kind: "openhands",
+        llm: { model: "openhands/minimax-m2.7" },
+      },
+      workingDir: "/workspace/project",
+      parentConversationId: "parent-1",
+      maxIterations: 250,
+    });
+
+    expect(payload.max_iterations).toBe(250);
+  });
+
+  it("omits local planner helper conversations from paginated conversation results", () => {
+    const page = toConversationPage({
+      items: [
+        {
+          id: "main-1",
+          created_at: "2024-01-01T00:00:00.000Z",
+          updated_at: "2024-01-01T00:00:00.000Z",
+          execution_status: "idle",
+          tags: {},
+        },
+        {
+          id: "plan-1",
+          created_at: "2024-01-01T00:00:00.000Z",
+          updated_at: "2024-01-01T00:00:00.000Z",
+          execution_status: "idle",
+          tags: { plannerparent: "main-1" },
+        },
+      ],
+    });
+
+    expect(page.items.map((item) => item.id)).toEqual(["main-1"]);
+  });
+
+  it("keeps ACP start requests unencrypted when no encrypted MCP values are present", () => {
+    const agentSettings = {
+      agent_kind: "acp",
+      acp_server: "codex",
+      acp_command: ["codex-acp"],
+      acp_model: "gpt-5.5/medium",
+      mcp_config: {
+        publicDocs: {
+          url: "https://docs.example.com/mcp",
+          transport: "http",
+        },
+      },
+    };
+    const settings = makeSettings(agentSettings);
+
+    const payload = buildStartConversationRequest({
+      settings,
+      encryptedAgentSettings: agentSettings,
+      encryptedConversationSettings: settings.conversation_settings!,
+      secretsEncrypted: true,
+    });
+
+    expect(payload.agent_settings!.agent_kind).toBe("acp");
+    expect(payload.secrets_encrypted).toBeUndefined();
+  });
+
+  it("ships only allow-listed catalog skills to a OpenHands conversation context", () => {
+    const settings = makeSettings({
+      agent_kind: "openhands",
+      llm: {
+        model: "litellm_proxy/openai/gpt-5.5",
+        api_key: "sk-test",
+      },
+      agent_context: {
+        skills: [
+          { name: "disabled-custom", content: "disabled" },
+          { name: "enabled-custom", content: "enabled" },
+        ],
+      },
+    });
+    settings.disabled_skills = ["agent-memory", "disabled-custom"];
+
+    const payload = buildStartConversationRequest({ settings });
+    const skillNames = getAgentContextSkillNames(payload);
+
+    // `agent-memory` is default-enabled, so this asserts the deny-list still
+    // wins over the allow-list — the case that matters before the one-shot
+    // migration has run.
+    expect(skillNames).not.toContain("agent-memory");
+    expect(skillNames).not.toContain("disabled-custom");
+    // Skills already on the agent context are user-authored and stay opt-out.
+    expect(skillNames).toContain("enabled-custom");
+    // No `enabled_skills` on the settings means the curated default applies:
+    // `add-skill` is flagged `defaultEnabled` in the catalog, `add-javadoc` is
+    // not, and shipping every catalog skill is what OpenHands#16302 reported.
+    expect(skillNames).toContain("add-skill");
+    expect(skillNames).not.toContain("add-javadoc");
+
+    expect(payload.agent_settings?.agent_context?.disabled_skills).toEqual([
+      "agent-memory",
+      "disabled-custom",
+    ]);
+  });
+
+  it("ships only allow-listed catalog skills to a ACP conversation context", () => {
+    const settings = makeSettings({
+      agent_kind: "acp",
+      acp_server: "codex",
+      acp_command: ["codex-acp"],
+      acp_model: "gpt-5.5/medium",
+      agent_context: {
+        skills: [
+          { name: "disabled-custom", content: "disabled" },
+          { name: "enabled-custom", content: "enabled" },
+        ],
+      },
+    });
+    settings.disabled_skills = ["agent-memory", "disabled-custom"];
+
+    const payload = buildStartConversationRequest({ settings });
+    const skillNames = getAgentContextSkillNames(payload);
+
+    // `agent-memory` is default-enabled, so this asserts the deny-list still
+    // wins over the allow-list — the case that matters before the one-shot
+    // migration has run.
+    expect(skillNames).not.toContain("agent-memory");
+    expect(skillNames).not.toContain("disabled-custom");
+    // Skills already on the agent context are user-authored and stay opt-out.
+    expect(skillNames).toContain("enabled-custom");
+    // No `enabled_skills` on the settings means the curated default applies:
+    // `add-skill` is flagged `defaultEnabled` in the catalog, `add-javadoc` is
+    // not, and shipping every catalog skill is what OpenHands#16302 reported.
+    expect(skillNames).toContain("add-skill");
+    expect(skillNames).not.toContain("add-javadoc");
+
+    expect(payload.agent_settings?.agent_context?.disabled_skills).toEqual([
+      "agent-memory",
+      "disabled-custom",
+    ]);
+  });
+
+  it("loads a catalog skill the opening slash command invokes", () => {
+    // An automation card fills the chat input with the skill's own command
+    // (`findAutomationCommand`), and 18 of the catalog's 24 slash commands
+    // belong to skills that are off by default — without this the card would
+    // silently do nothing.
+    const settings = makeSettings({
+      agent_kind: "openhands",
+      llm: { model: "litellm_proxy/openai/gpt-5.5", api_key: "sk-test" },
+    });
+
+    const payload = buildStartConversationRequest({
+      settings,
+      query: "/standup-digest:setup",
+    });
+
+    expect(getAgentContextSkillNames(payload)).toContain(
+      "slack-standup-digest",
+    );
+  });
+
+  it("does not admit a skill named mid-sentence rather than invoked", () => {
+    const settings = makeSettings({
+      agent_kind: "openhands",
+      llm: { model: "litellm_proxy/openai/gpt-5.5", api_key: "sk-test" },
+    });
+
+    const payload = buildStartConversationRequest({
+      settings,
+      query: "tell me what /standup-digest:setup would do",
+    });
+
+    expect(getAgentContextSkillNames(payload)).not.toContain(
+      "slack-standup-digest",
+    );
+  });
+
+  it("lets an invoked skill override a stored deny entry for that conversation", () => {
+    const settings = makeSettings({
+      agent_kind: "openhands",
+      llm: { model: "litellm_proxy/openai/gpt-5.5", api_key: "sk-test" },
+    });
+    settings.disabled_skills = ["slack-standup-digest"];
+
+    const payload = buildStartConversationRequest({
+      settings,
+      query: "/standup-digest:setup",
+    });
+
+    expect(getAgentContextSkillNames(payload)).toContain(
+      "slack-standup-digest",
+    );
+  });
+});
+
+describe("buildStartPlanningConversationRequestWithEncryptedSettings", () => {
+  const globallyActiveSettings = {
+    agentSettings: {
+      agent_kind: "openhands",
+      llm: {
+        model: "openhands/globally-active-model",
+        api_key: "gAAAAAglobal-key",
+        base_url: "https://global.example.com",
+      },
+    },
+    conversationSettings: {},
+    secretsEncrypted: true,
+    skillEnablement: { disabledSkills: [] },
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(SettingsService.getSettingsForConversation).mockResolvedValue(
+      globallyActiveSettings,
+    );
+    vi.mocked(AgentProfilesService.listProfiles).mockResolvedValue({
+      profiles: [
+        {
+          id: "profile-parent",
+          name: "parent-profile",
+          agent_kind: "openhands",
+          revision: 1,
+          llm_profile_ref: "parent-llm",
+          mcp_server_refs: null,
+        },
+      ],
+      active_agent_profile_id: "profile-other",
+    });
+    vi.mocked(ProfilesService.getProfile).mockResolvedValue({
+      name: "parent-llm",
+      api_key_set: true,
+      config: {
+        model: "openhands/parent-profile-model",
+        api_key: "gAAAAAparent-key",
+        base_url: "https://parent.example.com",
+      },
+    });
+  });
+
+  it("pins the planner to the parent's launched profile, not the globally active one", async () => {
+    const payload =
+      await buildStartPlanningConversationRequestWithEncryptedSettings({
+        workingDir: "/workspace/project",
+        parentConversationId: "parent-1",
+        parentAgentProfileId: "profile-parent",
+      });
+
+    expect(ProfilesService.getProfile).toHaveBeenCalledWith(
+      "parent-llm",
+      "encrypted",
+    );
+    expect(payload.agent.llm).toMatchObject({
+      model: "openhands/parent-profile-model",
+      api_key: "gAAAAAparent-key",
+      base_url: "https://parent.example.com",
+    });
+  });
+
+  it("falls back to global settings when the parent was not launched from a profile", async () => {
+    const payload =
+      await buildStartPlanningConversationRequestWithEncryptedSettings({
+        workingDir: "/workspace/project",
+        parentConversationId: "parent-1",
+        parentAgentProfileId: null,
+      });
+
+    expect(AgentProfilesService.listProfiles).not.toHaveBeenCalled();
+    expect(payload.agent.llm).toMatchObject({
+      model: "openhands/globally-active-model",
+    });
+  });
+
+  it("prefers the parent conversation's current active_profile over its launched agent profile", async () => {
+    // The conversation launched under "parent-profile" (-> "parent-llm"), but
+    // was later switched to a different LLM profile via /model or the
+    // agent's own SwitchLLMTool — active_profile tracks that switch.
+    vi.mocked(ProfilesService.getProfile).mockImplementation(async (name) =>
+      name === "switched-llm"
+        ? {
+            name: "switched-llm",
+            api_key_set: true,
+            config: {
+              model: "openhands/switched-model",
+              api_key: "gAAAAAswitched-key",
+              base_url: "https://switched.example.com",
+            },
+          }
+        : {
+            name: "parent-llm",
+            api_key_set: true,
+            config: {
+              model: "openhands/parent-profile-model",
+              api_key: "gAAAAAparent-key",
+              base_url: "https://parent.example.com",
+            },
+          },
+    );
+
+    const payload =
+      await buildStartPlanningConversationRequestWithEncryptedSettings({
+        workingDir: "/workspace/project",
+        parentConversationId: "parent-1",
+        parentActiveProfileName: "switched-llm",
+        parentAgentProfileId: "profile-parent",
+      });
+
+    expect(ProfilesService.getProfile).toHaveBeenCalledWith(
+      "switched-llm",
+      "encrypted",
+    );
+    // The launched agent profile must not even be consulted once
+    // active_profile resolves successfully.
+    expect(AgentProfilesService.listProfiles).not.toHaveBeenCalled();
+    expect(payload.agent.llm).toMatchObject({
+      model: "openhands/switched-model",
+      api_key: "gAAAAAswitched-key",
+      base_url: "https://switched.example.com",
+    });
+  });
+
+  it("falls back to the launched agent profile when active_profile can't be resolved", async () => {
+    vi.mocked(ProfilesService.getProfile).mockImplementation(async (name) => {
+      if (name === "dangling-llm") throw new Error("not found");
+      return {
+        name: "parent-llm",
+        api_key_set: true,
+        config: {
+          model: "openhands/parent-profile-model",
+          api_key: "gAAAAAparent-key",
+          base_url: "https://parent.example.com",
+        },
+      };
+    });
+
+    const payload =
+      await buildStartPlanningConversationRequestWithEncryptedSettings({
+        workingDir: "/workspace/project",
+        parentConversationId: "parent-1",
+        parentActiveProfileName: "dangling-llm",
+        parentAgentProfileId: "profile-parent",
+      });
+
+    expect(payload.agent.llm).toMatchObject({
+      model: "openhands/parent-profile-model",
+    });
+  });
+
+  it("falls back to global settings when the parent's profile reference dangles", async () => {
+    vi.mocked(AgentProfilesService.listProfiles).mockResolvedValue({
+      profiles: [],
+      active_agent_profile_id: null,
+    });
+
+    const payload =
+      await buildStartPlanningConversationRequestWithEncryptedSettings({
+        workingDir: "/workspace/project",
+        parentConversationId: "parent-1",
+        parentAgentProfileId: "profile-parent",
+      });
+
+    expect(ProfilesService.getProfile).not.toHaveBeenCalled();
+    expect(payload.agent.llm).toMatchObject({
+      model: "openhands/globally-active-model",
+    });
+  });
+
+  it("mirrors the parent's configured max_iterations instead of hardcoding a lower cap", async () => {
+    vi.mocked(SettingsService.getSettingsForConversation).mockResolvedValue({
+      ...globallyActiveSettings,
+      conversationSettings: { max_iterations: 1000 },
+    });
+
+    const payload =
+      await buildStartPlanningConversationRequestWithEncryptedSettings({
+        workingDir: "/workspace/project",
+        parentConversationId: "parent-1",
+      });
+
+    expect(payload.max_iterations).toBe(1000);
+  });
+
+  it("falls back to 500 when the parent has no configured max_iterations", async () => {
+    const payload =
+      await buildStartPlanningConversationRequestWithEncryptedSettings({
+        workingDir: "/workspace/project",
+        parentConversationId: "parent-1",
+      });
+
+    expect(payload.max_iterations).toBe(500);
+  });
+
+  it("applies the full skill enablement to the planner's agent context, mirroring the code agent", async () => {
+    // Both lists, because they cover different populations (#16302): the
+    // allow-list gates the bundled catalog, the deny-list still wins over it.
+    // `add-javadoc` is a catalog skill outside the recommended defaults, so
+    // it only loads because the allow-list names it.
+    vi.mocked(SettingsService.getSettingsForConversation).mockResolvedValue({
+      ...globallyActiveSettings,
+      skillEnablement: {
+        enabledSkills: ["add-javadoc", "agent-memory"],
+        disabledSkills: ["agent-memory"],
+      },
+    });
+
+    const payload =
+      await buildStartPlanningConversationRequestWithEncryptedSettings({
+        workingDir: "/workspace/project",
+        parentConversationId: "parent-1",
+      });
+
+    const skillNames = getPlannerAgentContextSkillNames(payload);
+    expect(skillNames).not.toContain("agent-memory");
+    expect(skillNames).toContain("add-javadoc");
+  });
+});
+
+describe("buildStartConversationRequest — agentProfileId path", () => {
+  it("sends agent_profile_id and omits agent_settings (mutually exclusive)", () => {
+    const settings = makeSettings({
+      agent_kind: "openhands",
+      llm: { model: "litellm_proxy/openai/gpt-5.5", api_key: "sk-test" },
+    });
+
+    const payload = buildStartConversationRequest({
+      settings,
+      agentProfileId: "profile-xyz",
+      agentProfileKind: "openhands",
+    });
+
+    expect(payload.agent_profile_id).toBe("profile-xyz");
+    expect(payload.agent_settings).toBeUndefined();
+    expect(payload.client_tools.map((tool) => tool.name)).toEqual([
+      CANVAS_UI_CLIENT_TOOL_NAME,
+      LAUNCH_CHILD_CONVERSATION_TOOL_NAME,
+    ]);
+  });
+
+  it("suppresses the ACP server tag when launching from a profile", () => {
+    const agentSettings = {
+      agent_kind: "acp",
+      acp_server: "codex",
+      acp_command: ["codex-acp"],
+      acp_model: "gpt-5.5/medium",
+    };
+
+    // Without a profile the ACP server tag is stamped from settings...
+    expect(
+      buildStartConversationRequest({ settings: makeSettings(agentSettings) })
+        .tags,
+    ).toBeDefined();
+
+    // ...but a profile launch resolves the server server-side, so the tag
+    // (which may not match the launched profile) is omitted while the client
+    // source telemetry tag is still stamped.
+    const payload = buildStartConversationRequest({
+      settings: makeSettings(agentSettings),
+      agentProfileId: "profile-xyz",
+    });
+    expect(payload.tags).toEqual({
+      [CLIENT_SOURCE_TAG_KEY]: AGENT_CANVAS_SOURCE,
+    });
+  });
+
+  it("suppresses secrets_encrypted when launching from a profile", () => {
+    const agentSettings = {
+      agent_kind: "openhands",
+      llm: {
+        model: "litellm_proxy/openai/gpt-5.5",
+        api_key: "gAAAAAencrypted-llm-api-key",
+      },
+      mcp_config: {
+        mcpServers: {
+          linear: {
+            url: "https://mcp.linear.app/mcp",
+            transport: "http",
+            headers: { Authorization: encryptedValue },
+          },
+        },
+      },
+    };
+    const settings = makeSettings(agentSettings);
+
+    // Same inputs without a profile would set secrets_encrypted (covered
+    // above); the profile path defers secret resolution to the server.
+    const payload = buildStartConversationRequest({
+      settings,
+      encryptedAgentSettings: agentSettings,
+      encryptedConversationSettings: settings.conversation_settings!,
+      secretsEncrypted: true,
+      agentProfileId: "profile-xyz",
+    });
+
+    expect(payload.secrets_encrypted).toBeUndefined();
+  });
+});

src/api/agent-server-adapter.ts

@@ -0,0 +1,1638 @@
+import { ACP_SETTINGS_KEYS } from "@openhands/typescript-client";
+import type { HookConfig } from "@openhands/typescript-client";
+import { ServerClient } from "@openhands/typescript-client/clients";
+import { SKILLS_CATALOG } from "@openhands/extensions/skills";
+import { DEFAULT_SETTINGS } from "#/services/settings";
+import { ExecutionStatus } from "#/types/agent-server/core";
+import { AgentKind, Settings, SettingsValue } from "#/types/settings";
+import {
+  getAcpPreferredDefaultModel,
+  getAcpProvider,
+  resolveEffectiveAcpModel,
+} from "#/constants/acp-providers";
+import { getAgentServerClientOptions } from "./agent-server-client-options";
+import {
+  getCachedAgentServerInfo,
+  isAgentServerToolAvailable,
+} from "./agent-server-compatibility";
+import { getAgentServerWorkingDir } from "./agent-server-config";
+import { getEffectiveLocalBackend } from "./backend-registry/active-store";
+import { buildAuthHeaders } from "./backend-registry/auth";
+import {
+  GetHooksResponse,
+  PluginSpec,
+  AppConversation,
+  AppConversationPage,
+  RuntimeConversationStats,
+  SandboxStatus,
+} from "./conversation-service/agent-server-conversation-service.types";
+import { combineUsageMetrics } from "#/utils/conversation-metrics";
+import {
+  buildSkillEnablementFilter,
+  findInvokedCatalogSkill,
+  toSkillEnablement,
+  type SkillEnablement,
+} from "#/utils/skill-enablement";
+import SettingsService from "./settings-service/settings-service.api";
+import { getStoredConversationMetadata } from "./conversation-metadata-store";
+import LLMSubscriptionService from "./llm-subscription-service";
+import {
+  LLM_AUTH_TYPE_SUBSCRIPTION,
+  OPENAI_SUBSCRIPTION_VENDOR,
+  isSubscriptionLlmConfig,
+} from "#/constants/llm-subscription";
+import {
+  CANVAS_UI_CLIENT_TOOL,
+  CANVAS_UI_CLIENT_TOOL_NAME,
+  LEGACY_CANVAS_UI_TOOL_NAME,
+  type ClientToolSpec,
+} from "./canvas-ui-client-tool";
+import {
+  LAUNCH_CHILD_CONVERSATION_CLIENT_TOOL,
+  LAUNCH_CHILD_CONVERSATION_TOOL_NAME,
+} from "./launch-child-conversation-client-tool";
+import {
+  buildPlanPath,
+  LOCAL_PLANNER_PARENT_TAG_KEY,
+  PLAN_STRUCTURE_TEXT,
+  PLANNING_AGENT_INSTRUCTION,
+  PLANNING_FILE_EDITOR_TOOL_NAME,
+  PLANNING_SYSTEM_PROMPT_FILENAME,
+} from "#/utils/plan-file";
+
+export interface DirectConversationInfo {
+  id: string;
+  title?: string | null;
+  created_at: string;
+  updated_at: string;
+  execution_status?: string | null;
+  /** Cloud-only sandbox lifecycle state. Omitted / null for local agent-server conversations. */
+  sandbox_status?: string | null;
+  metrics?: {
+    accumulated_cost?: number | null;
+    max_budget_per_task?: number | null;
+    accumulated_token_usage?: {
+      prompt_tokens?: number;
+      completion_tokens?: number;
+      cache_read_tokens?: number;
+      cache_write_tokens?: number;
+      context_window?: number;
+      per_turn_token?: number;
+    } | null;
+  } | null;
+  /**
+   * Raw per-usage-id LLM stats from the agent-server. Search/list responses
+   * often carry real usage here even when `metrics` above comes back unset;
+   * {@link toAppConversation} combines this as a fallback in that case.
+   */
+  stats?: RuntimeConversationStats | null;
+  agent?: {
+    /**
+     * Pydantic discriminator from the SDK union: ``"ACPAgent"`` for ACP CLI
+     * subprocesses (model lives on the subprocess via ``acp_model``),
+     * ``"Agent"`` for direct litellm. Read by {@link toAppConversation}.
+     */
+    kind?: string | null;
+    acp_model?: string | null;
+    /**
+     * ACP CLI identity (``claude-code`` / ``codex`` / ``gemini-cli``) from the
+     * SDK's ``ACPAgent.acp_server`` (#3692). Preferred fallback when the
+     * ``acpserver`` tag is absent — e.g. a profile launch doesn't stamp the tag
+     * client-side and the server may not repopulate it. Read by {@link toAppConversation}.
+     */
+    acp_server?: string | null;
+    llm?: {
+      model?: string | null;
+    } | null;
+  } | null;
+  current_model_id?: string | null;
+  current_model_name?: string | null;
+  workspace?: {
+    working_dir?: string | null;
+  } | null;
+  /**
+   * Arbitrary string-keyed conversation tags surfaced by the agent-server
+   * (see ``ConversationInfo.tags``). Canvas only consumes one key today —
+   * ``ACP_SERVER_TAG_KEY`` ("acpserver") — but the field is typed as a
+   * generic record so future readers don't need another wire-shape change.
+   * Keys are constrained to ``^[a-z0-9]+$`` by the agent-server validator;
+   * values are opaque strings.
+   */
+  tags?: Record<string, string> | null;
+  launched_agent_profile?: {
+    agent_profile_id: string;
+    revision: number;
+  } | null;
+  /**
+   * Server-owned, derived from the catalog's ``parent_conversation_id`` link
+   * (agent-server >= 1.37.1, SDK #4188) — a conversation started with a
+   * parent is discoverable here on any browser, which is what makes the
+   * local planner's relationship server state rather than a browser-local
+   * hint. Absent on older agent-servers and on the cloud wire shape.
+   */
+  sub_conversation_ids?: string[] | null;
+}
+
+const DEFAULT_TOOL_NAMES = ["terminal", "file_editor", "task_tracker"];
+const BROWSER_TOOL_SET_NAME = "browser_tool_set";
+const TASK_TOOL_SET_NAME = "task_tool_set";
+// Falls back to the same default the code agent uses when the user has not
+// configured `conversation_settings.max_iterations` (see buildConfiguredConversationSettings).
+const DEFAULT_MAX_ITERATIONS = 500;
+
+function resolveMaxIterations(value: unknown): number {
+  return typeof value === "number" ? value : DEFAULT_MAX_ITERATIONS;
+}
+
+function browserToolsEnabled() {
+  return import.meta.env.VITE_ENABLE_BROWSER_TOOLS !== "false";
+}
+
+/**
+ * Shape of the runtime services info served by Agent Canvas backends in
+ * `/server_info.runtime_services`. All URLs are written from the agent's point of
+ * view, not the browser's. The block is rendered into the agent's system prompt
+ * via `AgentContext.system_message_suffix` so the agent knows what's reachable
+ * from inside its sandbox without having to probe.
+ */
+export interface RuntimeServicesInfo {
+  mode?: string;
+  agent_host_alias?: string;
+  services?: {
+    agent_server?: { description?: string; url_from_agent?: string };
+    ingress?: { description?: string; url_from_agent?: string };
+    frontend?: {
+      kind?: "vite" | "static";
+      description?: string;
+      url_from_agent?: string;
+    };
+    // `vite` is the legacy key name for the frontend entry, accepted for
+    // one release while older dev-stack launchers may still emit it.
+    vite?: { description?: string; url_from_agent?: string };
+    automation?: {
+      description?: string;
+      url_from_agent?: string;
+      api_prefix?: string;
+      docs_url?: string;
+      openapi_url?: string;
+      auth_env_var?: string;
+    };
+  };
+}
+
+export function parseRuntimeServicesInfo(
+  value: unknown,
+): RuntimeServicesInfo | null {
+  if (typeof value === "string") {
+    const raw = value.trim();
+    if (!raw) return null;
+    try {
+      return parseRuntimeServicesInfo(JSON.parse(raw));
+    } catch {
+      return null;
+    }
+  }
+
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+
+  const parsed = value as RuntimeServicesInfo;
+  if (!parsed.services || typeof parsed.services !== "object") return null;
+  return parsed;
+}
+
+export async function fetchBackendRuntimeServicesInfo(): Promise<RuntimeServicesInfo | null> {
+  let clientOptions: ReturnType<typeof getAgentServerClientOptions>;
+  try {
+    clientOptions = getAgentServerClientOptions({ timeout: 3000 });
+  } catch {
+    return null;
+  }
+
+  const cached = parseRuntimeServicesInfo(
+    getCachedAgentServerInfo({ host: clientOptions.host })?.runtime_services,
+  );
+  if (cached) return cached;
+
+  try {
+    const serverInfo = await new ServerClient(clientOptions).getServerInfo();
+    return parseRuntimeServicesInfo(
+      (serverInfo as { runtime_services?: unknown }).runtime_services,
+    );
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Return the deployment mode from the runtime services info, e.g. "docker",
+ * "dev:automation", etc. Returns `null` when no runtime info is supplied.
+ */
+export function getDeploymentMode(
+  runtimeServicesInfo?: RuntimeServicesInfo | null,
+): string | null {
+  return runtimeServicesInfo?.mode ?? null;
+}
+
+/**
+ * Render the runtime services info into a markdown block suitable for
+ * appending to the system prompt via `AgentContext.system_message_suffix`.
+ *
+ * Returns `undefined` when no runtime info is available, so callers can safely
+ * omit the field when the selected backend does not advertise runtime services.
+ */
+export function buildRuntimeServicesSystemSuffix(
+  runtimeServicesInfo?: RuntimeServicesInfo | null,
+): string | undefined {
+  const info = parseRuntimeServicesInfo(runtimeServicesInfo);
+  if (!info?.services) return undefined;
+
+  const lines: string[] = [];
+  lines.push("<RUNTIME_SERVICES>");
+  if (info.mode) {
+    lines.push(
+      `You are running inside an agent-canvas dev stack started in '${info.mode}' mode.`,
+    );
+  } else {
+    lines.push("You are running inside an agent-canvas dev stack.");
+  }
+  lines.push(
+    "The following services are reachable from your sandbox. URLs are written",
+    "from your point of view (i.e., as you should curl/fetch them).",
+    "",
+  );
+
+  const { agent_server, ingress, automation } = info.services;
+  const { frontend } = info.services;
+
+  if (agent_server?.url_from_agent) {
+    lines.push(
+      `* Agent Server (you): ${agent_server.url_from_agent}`,
+      `    ${agent_server.description ?? "The agent-server hosting your tool calls."}`,
+    );
+  }
+  if (ingress?.url_from_agent) {
+    lines.push(
+      `* Ingress: ${ingress.url_from_agent}`,
+      `    ${ingress.description ?? "Unified entry point for browser-facing traffic."}`,
+    );
+  }
+  if (frontend?.url_from_agent) {
+    lines.push(
+      `* Frontend: ${frontend.url_from_agent}`,
+      `    ${frontend.description ?? "Frontend dev server."}`,
+    );
+  }
+  if (automation?.url_from_agent) {
+    lines.push(
+      `* Automation backend: ${automation.url_from_agent}`,
+      `    ${automation.description ?? "OpenHands Automations service."}`,
+    );
+    if (automation.docs_url) {
+      lines.push(`    Docs:    ${automation.docs_url}`);
+    }
+    if (automation.openapi_url) {
+      lines.push(`    OpenAPI: ${automation.openapi_url}`);
+    }
+    if (automation.auth_env_var) {
+      // X-Session-API-Key is the local convention shared by the agent-server
+      // and automation backend (see openhands-automation auth.py).
+      lines.push(
+        `    Auth:    header 'X-Session-API-Key: $${automation.auth_env_var}'`,
+      );
+    }
+  } else {
+    lines.push(
+      "* Automation backend: not running in this dev mode (skip /api/automation calls).",
+    );
+  }
+
+  // Anchor the "don't guess" warning to the actual agent-server URL for
+  // this stack instead of a hardcoded port. The agent-server listens on
+  // different ports across dev modes, and baking the wrong port into the
+  // system prompt is exactly the kind of confusion this block is meant to
+  // prevent.
+  const agentServerUrl = agent_server?.url_from_agent;
+  lines.push(
+    "",
+    "Trust this block over guessing: do not assume any other URLs are running.",
+  );
+  if (agentServerUrl) {
+    lines.push(
+      `In particular, ${agentServerUrl} inside your sandbox is the Agent Server`,
+      "you are running inside of — NOT the automation backend.",
+    );
+  }
+  lines.push("</RUNTIME_SERVICES>");
+
+  return lines.join("\n");
+}
+
+export function toConversationUrl(conversationId: string): string {
+  // Local-format conversation URL — points at whichever local agent-server
+  // is actually serving the conversation (the bundled one when the active
+  // selection is cloud).
+  const { host } = getAgentServerClientOptions();
+  return `${host}/api/conversations/${conversationId}`;
+}
+
+// TODO(i18n): extract "Conversation" once we add CONVERSATION$DEFAULT_TITLE
+// with `{{shortId}}` interpolation. Kept as a literal for now to keep the
+// fallback inside this pure adapter rather than fanning out to display sites.
+export function getDefaultConversationTitle(conversationId: string): string {
+  return `Conversation ${conversationId.slice(0, 5)}`;
+}
+
+export function toAppConversation(
+  info: DirectConversationInfo,
+): AppConversation {
+  const metadata = getStoredConversationMetadata(info.id);
+  // ACPAgent conversations carry a sentinel ``llm`` on older SDKs. Prefer the
+  // runtime model fields when available, then the configured ``acp_model`` that
+  // Canvas saves for built-in providers. ``agent_kind`` still gates model
+  // switching, so surfacing this string is display-only.
+  const isAcp = info.agent?.kind === "ACPAgent";
+  // Only surface ``acp_server`` for ACP conversations even if the wire
+  // payload accidentally carries an ``acpserver`` tag on an OpenHands
+  // conversation — the chip is identity info for the ACP CLI subprocess,
+  // and showing it on a non-ACP conversation would be a lie. Fall back to the
+  // agent's own ``acp_server`` (#3692) when the tag is missing — a profile
+  // launch doesn't stamp the tag, so tag-only reads would drop the ACP model
+  // picker and degrade the chip to a generic "ACP" (#1571).
+  const acpServer = isAcp
+    ? (info.tags?.[ACP_SERVER_TAG_KEY] ?? info.agent?.acp_server ?? null)
+    : null;
+  return {
+    id: info.id,
+    created_by_user_id: null,
+    selected_repository: metadata?.selected_repository ?? null,
+    selected_branch: metadata?.selected_branch ?? null,
+    git_provider: metadata?.git_provider ?? null,
+    selected_workspace: metadata?.selected_workspace ?? null,
+    active_profile: metadata?.active_profile ?? null,
+    title: info.title?.trim()
+      ? info.title
+      : getDefaultConversationTitle(info.id),
+    trigger: null,
+    pr_number: [],
+    agent_kind: isAcp ? "acp" : "openhands",
+    acp_server: acpServer,
+    tags: info.tags ?? null,
+    launched_agent_profile: info.launched_agent_profile ?? null,
+    // Chip path: omit ``providerDefault`` so that when no concrete model
+    // resolves, the chip falls back to the provider display name in
+    // ConversationCardFooter rather than a registry default the session may
+    // not actually be running.
+    llm_model: isAcp
+      ? resolveEffectiveAcpModel({
+          runtimeName: info.current_model_name,
+          runtimeId: info.current_model_id,
+          configured: info.agent?.acp_model,
+          sdkLlm: info.agent?.llm?.model,
+        })
+      : (info.agent?.llm?.model ?? DEFAULT_SETTINGS.llm_model),
+    metrics: info.metrics
+      ? {
+          accumulated_cost: info.metrics.accumulated_cost ?? null,
+          max_budget_per_task: info.metrics.max_budget_per_task ?? null,
+          accumulated_token_usage: info.metrics.accumulated_token_usage
+            ? {
+                prompt_tokens:
+                  info.metrics.accumulated_token_usage.prompt_tokens ?? 0,
+                completion_tokens:
+                  info.metrics.accumulated_token_usage.completion_tokens ?? 0,
+                cache_read_tokens:
+                  info.metrics.accumulated_token_usage.cache_read_tokens ?? 0,
+                cache_write_tokens:
+                  info.metrics.accumulated_token_usage.cache_write_tokens ?? 0,
+                context_window:
+                  info.metrics.accumulated_token_usage.context_window ?? 0,
+                per_turn_token:
+                  info.metrics.accumulated_token_usage.per_turn_token ?? 0,
+              }
+            : null,
+        }
+      : combineUsageMetrics(info.stats),
+    created_at: info.created_at,
+    updated_at: info.updated_at,
+    execution_status:
+      (info.execution_status as AppConversation["execution_status"]) ??
+      ExecutionStatus.IDLE,
+    sandbox_status: (info.sandbox_status as SandboxStatus | null) ?? null,
+    conversation_url: toConversationUrl(info.id),
+    session_api_key: getAgentServerClientOptions().apiKey ?? null,
+    sandbox_id: null,
+    workspace: {
+      working_dir: info.workspace?.working_dir ?? getAgentServerWorkingDir(),
+    },
+    public: false,
+    sub_conversation_ids: info.sub_conversation_ids ?? [],
+  };
+}
+
+export function toConversationPage(data: {
+  items: DirectConversationInfo[];
+  next_page_id?: string | null;
+}): AppConversationPage {
+  return {
+    items: data.items
+      .filter((item) => !item.tags?.[LOCAL_PLANNER_PARENT_TAG_KEY])
+      .map(toAppConversation),
+    next_page_id: data.next_page_id ?? null,
+  };
+}
+
+type SettingsRecord = Record<string, unknown>;
+
+interface AgentToolSpec {
+  name: string;
+  params: SettingsRecord;
+}
+
+type AgentSettingsPayload = SettingsRecord & {
+  llm?: SettingsRecord;
+  agent_context: SettingsRecord;
+  tools?: AgentToolSpec[];
+};
+
+interface LocalWorkspacePayload {
+  kind: "LocalWorkspace";
+  working_dir: string;
+}
+
+interface InitialMessagePayload {
+  role: "user";
+  content: Array<{ type: "text"; text: string }>;
+  run: true;
+}
+
+type ConversationSettingsPayload = SettingsRecord & {
+  workspace: LocalWorkspacePayload;
+  initial_message?: InitialMessagePayload;
+};
+
+export const ACP_SERVER_TAG_KEY = "acpserver";
+export const CLIENT_SOURCE_TAG_KEY = "clientsource";
+export const AGENT_CANVAS_SOURCE = "agentcanvas";
+
+export const AUTOMATION_TRIGGER_TAG_KEY = "automationtrigger";
+export const AUTOMATION_ID_TAG_KEY = "automationid";
+export const AUTOMATION_NAME_TAG_KEY = "automationname";
+export const AUTOMATION_RUN_ID_TAG_KEY = "automationrunid";
+
+/**
+ * Tag keys stamped on conversations created by automation runs (see the SDK's
+ * `RemoteWorkspace.default_conversation_tags`). The presence of any of these
+ * marks a conversation as automation-born.
+ */
+export const AUTOMATION_TAG_KEYS: readonly string[] = [
+  AUTOMATION_TRIGGER_TAG_KEY,
+  AUTOMATION_ID_TAG_KEY,
+  AUTOMATION_NAME_TAG_KEY,
+  AUTOMATION_RUN_ID_TAG_KEY,
+];
+
+/**
+ * Conversation tag keys that must not appear as generic chips / hovercard
+ * rows. Each is either already surfaced by a first-class UI source or is
+ * internal routing data:
+ * - ``acpserver`` → ACP provider chip
+ * - ``clientsource`` → telemetry attribution
+ * - ``title`` → conversation card heading
+ * - git / repo / branch / workspace stamps → repo-branch metadata + directory
+ *   footer / hovercard rows (``selected_repository``, ``selected_branch``,
+ *   ``git_provider``, ``workspace.working_dir``)
+ * - the automation family (``automationtrigger`` / ``automationid`` /
+ *   ``automationname`` / ``automationrunid``) → provenance the SDK stamps at
+ *   creation; the conversation panel's automation filter is its first-class
+ *   UI source. The tag surface is user organization data, so machine stamps
+ *   stay out of it — and users can't edit or spoof automation classification.
+ * - ``localplannerparent`` → internal routing for the local planner; already
+ *   surfaced by the hidden-from-list planner filter
+ */
+export const RESERVED_CONVERSATION_TAG_KEYS: ReadonlySet<string> = new Set([
+  ACP_SERVER_TAG_KEY,
+  CLIENT_SOURCE_TAG_KEY,
+  AUTOMATION_TRIGGER_TAG_KEY,
+  AUTOMATION_ID_TAG_KEY,
+  AUTOMATION_NAME_TAG_KEY,
+  AUTOMATION_RUN_ID_TAG_KEY,
+  "title",
+  "git_provider",
+  "repo_name",
+  "repo",
+  "repository",
+  "selected_branch",
+  "branch",
+  "archiveworkspacepath",
+  "workspace",
+  "working_dir",
+  LOCAL_PLANNER_PARENT_TAG_KEY,
+]);
+
+/**
+ * High-signal tag keys shown first in the chip row (before A–Z). Automations
+ * often stamp ``origin``; remaining free-form tags sort alphabetically.
+ */
+export const PRIORITY_CONVERSATION_TAG_KEYS: readonly string[] = ["origin"];
+
+/**
+ * User-facing subset of a conversation's server-side tags: everything except
+ * {@link RESERVED_CONVERSATION_TAG_KEYS}, as stable ``[key, value]`` entries.
+ * Priority keys come first (in {@link PRIORITY_CONVERSATION_TAG_KEYS} order);
+ * the rest sort A–Z so chip order doesn't shuffle between refetches.
+ */
+export function getDisplayConversationTags(
+  tags: Record<string, string> | null | undefined,
+): Array<[string, string]> {
+  if (!tags) {
+    return [];
+  }
+  // Both the reserved-key check and the priority lookup must see the same
+  // normalized key: a cloud backend can stamp ``Origin`` / `` origin``, and
+  // ranking those off the raw key would silently drop them out of first place.
+  const priorityRank = (key: string): number => {
+    const index = PRIORITY_CONVERSATION_TAG_KEYS.indexOf(
+      key.trim().toLowerCase(),
+    );
+    return index === -1 ? Number.POSITIVE_INFINITY : index;
+  };
+
+  return Object.entries(tags)
+    .filter(
+      ([key, value]) =>
+        !RESERVED_CONVERSATION_TAG_KEYS.has(key.trim().toLowerCase()) &&
+        typeof value === "string" &&
+        // Bare tags (empty value) are displayable — chips/tooltips render
+        // the key. Whitespace-only values stay dropped (raw-write junk).
+        (value === "" || value.trim().length > 0),
+    )
+    .sort(([a], [b]) => {
+      const aRank = priorityRank(a);
+      const bRank = priorityRank(b);
+      if (aRank !== bRank) {
+        return aRank - bRank;
+      }
+      return a.localeCompare(b);
+    });
+}
+
+const FERNET_TOKEN_PREFIX = "gAAAAA";
+
+const CONVERSATION_SETTINGS_METADATA_KEYS = new Set([
+  "schema_version",
+  "agent_settings",
+  "workspace",
+  "conversation_id",
+  "initial_message",
+  "plugins",
+]);
+
+function toRecord(value: unknown): SettingsRecord {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+
+  return structuredClone(value as SettingsRecord);
+}
+
+function normalizeSecretString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function buildNormalizedLlmSettings(value: unknown): SettingsRecord {
+  const llm = toRecord(value);
+
+  llm.model =
+    typeof llm.model === "string" && llm.model.trim().length > 0
+      ? llm.model
+      : DEFAULT_SETTINGS.llm_model;
+
+  const apiKey = normalizeSecretString(llm.api_key);
+  if (apiKey) {
+    llm.api_key = apiKey;
+  } else {
+    delete llm.api_key;
+  }
+
+  const baseUrl = normalizeSecretString(llm.base_url);
+  if (baseUrl) {
+    llm.base_url = baseUrl;
+  } else {
+    delete llm.base_url;
+  }
+
+  if (isSubscriptionLlmConfig(llm)) {
+    llm.auth_type = LLM_AUTH_TYPE_SUBSCRIPTION;
+    llm.subscription_vendor = OPENAI_SUBSCRIPTION_VENDOR;
+    delete llm.api_key;
+  } else {
+    delete llm.auth_type;
+    delete llm.subscription_vendor;
+  }
+
+  return llm;
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasEncryptedString(value: unknown): boolean {
+  if (typeof value === "string") {
+    return value.startsWith(FERNET_TOKEN_PREFIX);
+  }
+  if (Array.isArray(value)) {
+    return value.some(hasEncryptedString);
+  }
+  if (isPlainRecord(value)) {
+    return Object.values(value).some(hasEncryptedString);
+  }
+  return false;
+}
+
+function hasEncryptedMcpSecrets(mcpConfig: unknown): boolean {
+  if (!isPlainRecord(mcpConfig)) {
+    return false;
+  }
+
+  return Object.values(mcpConfig).some(hasEncryptedString);
+}
+
+function getConversationConfirmationPolicy(
+  conversationSettings: SettingsRecord,
+) {
+  if (conversationSettings.confirmation_mode !== true) {
+    return { kind: "NeverConfirm" };
+  }
+
+  if (conversationSettings.security_analyzer === "llm") {
+    return { kind: "ConfirmRisky", threshold: "HIGH", confirm_unknown: true };
+  }
+
+  return { kind: "AlwaysConfirm" };
+}
+
+function getConversationSecurityAnalyzer(conversationSettings: SettingsRecord) {
+  switch (conversationSettings.security_analyzer) {
+    case "llm":
+      return { kind: "LLMSecurityAnalyzer" };
+    case "pattern":
+      return { kind: "PatternSecurityAnalyzer" };
+    case "policy_rail":
+      return { kind: "PolicyRailSecurityAnalyzer" };
+    default:
+      return undefined;
+  }
+}
+
+function isToolRecord(
+  value: unknown,
+): value is { name: string; params?: unknown } {
+  return (
+    !!value &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    typeof (value as { name?: unknown }).name === "string"
+  );
+}
+
+function shouldIncludeTool(name: string, agentSettings: SettingsRecord) {
+  if (name === BROWSER_TOOL_SET_NAME) {
+    return browserToolsEnabled() && isAgentServerToolAvailable(name);
+  }
+
+  if (name === TASK_TOOL_SET_NAME) {
+    return (
+      agentSettings.enable_sub_agents === true &&
+      isAgentServerToolAvailable(name)
+    );
+  }
+
+  return true;
+}
+
+function getAgentTools(agentSettings: SettingsRecord): AgentToolSpec[] {
+  const tools = new Map<string, AgentToolSpec>();
+
+  for (const name of DEFAULT_TOOL_NAMES) {
+    if (shouldIncludeTool(name, agentSettings)) {
+      tools.set(name, { name, params: {} });
+    }
+  }
+
+  for (const name of [BROWSER_TOOL_SET_NAME, TASK_TOOL_SET_NAME]) {
+    if (shouldIncludeTool(name, agentSettings)) {
+      tools.set(name, { name, params: {} });
+    }
+  }
+
+  const configuredTools = agentSettings.tools;
+  if (
+    Array.isArray(configuredTools) &&
+    configuredTools.every((tool) => isToolRecord(tool))
+  ) {
+    for (const tool of configuredTools) {
+      if (shouldIncludeTool(tool.name, agentSettings)) {
+        tools.set(tool.name, {
+          name: tool.name,
+          params: toRecord(tool.params),
+        });
+      }
+    }
+  }
+
+  return Array.from(tools.values());
+}
+
+function buildInitialMessage(
+  query?: string,
+  conversationInstructions?: string,
+): InitialMessagePayload | null {
+  const parts = [query?.trim(), conversationInstructions?.trim()].filter(
+    Boolean,
+  );
+  if (parts.length === 0) {
+    return null;
+  }
+
+  return {
+    role: "user",
+    content: [{ type: "text", text: parts.join("\n\n") }],
+    run: true,
+  };
+}
+
+/**
+ * Shape of a bundled skill entry passed to the agent-server SDK via
+ * `agent_context.skills`. Mirrors the SDK's `Skill` model fields that
+ * the server uses for trigger matching, activation, and system-prompt
+ * injection.
+ */
+interface BundledSkill {
+  name: string;
+  content: string;
+  trigger: { type: "keyword"; keywords: string[] } | null;
+  source: string;
+  description: string | null;
+  is_agentskills_format: true;
+  license?: string;
+  compatibility?: string;
+}
+
+/**
+ * Convert the bundled `SKILLS_CATALOG` entries into the SDK `Skill` JSON
+ * shape so the agent-server can perform trigger matching, skill activation,
+ * and system-prompt injection without cloning the extensions repo.
+ *
+ * The SDK discriminates triggers via `{ type: "keyword", keywords: [...] }`.
+ * Skills with no triggers get `trigger: null` (always-active / on-demand).
+ */
+function buildBundledSkills(): BundledSkill[] {
+  return SKILLS_CATALOG.map((entry) => {
+    const trigger: BundledSkill["trigger"] =
+      entry.triggers?.length > 0
+        ? { type: "keyword", keywords: entry.triggers }
+        : null;
+
+    // Use the absolute path to the skill's SKILL.md so the Python
+    // agent-server can resolve bundled resources (scripts/, references/).
+    // Falls back to "public" in library builds where the path isn't known.
+    const source = __EXTENSIONS_SKILLS_DIR__
+      ? `${__EXTENSIONS_SKILLS_DIR__}/${entry.name}/SKILL.md`
+      : "public";
+
+    return {
+      name: entry.name,
+      content: entry.content,
+      trigger,
+      source,
+      description: entry.description ?? null,
+      is_agentskills_format: true as const,
+      ...(entry.license ? { license: entry.license } : {}),
+      ...(entry.compatibility ? { compatibility: entry.compatibility } : {}),
+    };
+  });
+}
+
+function buildAgentContext(
+  agentSettings: SettingsRecord,
+  runtimeServicesInfo?: RuntimeServicesInfo | null,
+  enablement: SkillEnablement = {},
+  invokedCatalogSkill?: string,
+): SettingsRecord {
+  const runtimeServicesSuffix =
+    buildRuntimeServicesSystemSuffix(runtimeServicesInfo);
+  const existingContext = toRecord(agentSettings.agent_context);
+
+  // Merge bundled public skills with any skills already present in the
+  // agent context (e.g. user-defined skills set via the settings API).
+  const existingSkills = Array.isArray(existingContext.skills)
+    ? (existingContext.skills as SettingsRecord[])
+    : [];
+  const disabledSkills = enablement.disabledSkills ?? [];
+  const disabledSkillNames = new Set(disabledSkills);
+  const isSkillEnabled = buildSkillEnablementFilter(enablement);
+
+  // The bundled catalog is allow-listed, not deny-listed: it is a build-time
+  // snapshot of ~60 skills, so a deny-list puts every future addition into
+  // every system prompt (OpenHands#16302). Skills the agent context already
+  // carries are user-authored and stay opt-out. A skill the opening message
+  // invokes by name overrides both, for this conversation only.
+  const mergedSkills = [
+    ...existingSkills.filter(
+      (skill) =>
+        typeof skill.name !== "string" || !disabledSkillNames.has(skill.name),
+    ),
+    ...buildBundledSkills().filter(
+      (skill) =>
+        skill.name === invokedCatalogSkill || isSkillEnabled(skill.name),
+    ),
+  ];
+
+  return {
+    ...existingContext,
+    // Public skills are bundled at build time from the @openhands/extensions
+    // npm package and passed directly in agent_context.skills. Setting
+    // load_public_skills to false tells the agent-server SDK to skip its own
+    // extensions-repo clone — the frontend is the sole source of public
+    // skills now.
+    //
+    // Migration: the former VITE_LOAD_PUBLIC_SKILLS env var was removed
+    // because bundled skills have no clone latency. Users who previously set
+    // VITE_LOAD_PUBLIC_SKILLS=false to avoid clone delays no longer need it.
+    skills: mergedSkills,
+    load_public_skills: false,
+    load_user_skills: true,
+    load_project_skills: true,
+    // The backend also auto-loads user/project skills; the deny-list must
+    // travel with the context so those skills are excluded from the system
+    // prompt too. The allow-list has no counterpart to send: the backend
+    // loads no catalog skills of its own (`load_public_skills` is false).
+    disabled_skills: disabledSkills,
+    ...(runtimeServicesSuffix
+      ? { system_message_suffix: runtimeServicesSuffix }
+      : {}),
+  };
+}
+
+function isAcpAgent(settings: Settings): boolean {
+  const agentSettings = toRecord(settings.agent_settings);
+  return agentSettings.agent_kind === "acp";
+}
+
+function getAcpServerTag(settings: Settings): string | undefined {
+  const agentSettings = toRecord(settings.agent_settings);
+  const value = agentSettings.acp_server;
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function resolveAcpCommand(agentSettings: SettingsRecord): unknown {
+  const cmd = agentSettings.acp_command;
+  const isEmpty = Array.isArray(cmd) && cmd.length === 0;
+  const noCommand = cmd === undefined;
+  if (!isEmpty && !noCommand) {
+    return cmd;
+  }
+
+  const serverKey =
+    typeof agentSettings.acp_server === "string"
+      ? agentSettings.acp_server
+      : undefined;
+  const provider = getAcpProvider(serverKey);
+  return provider ? [...provider.default_command] : cmd;
+}
+
+function buildConfiguredAcpAgentSettings(
+  settings: Settings,
+  runtimeServicesInfo?: RuntimeServicesInfo | null,
+  query?: string,
+): AgentSettingsPayload {
+  const agentSettings = toRecord(settings.agent_settings);
+  const payload: AgentSettingsPayload = {
+    agent_kind: "acp",
+    agent_context: buildAgentContext(
+      agentSettings,
+      runtimeServicesInfo,
+      toSkillEnablement(settings),
+      findInvokedCatalogSkill(query),
+    ),
+  };
+
+  // TODO(#1019): set ``acp_isolate_data_dir: true`` here for a containerized
+  // backend so concurrent same-provider conversations don't race on a shared
+  // HOME. The SDK supports it (software-agent-sdk#3492), but the released
+  // ``@openhands/typescript-client`` (1.24.3) doesn't surface it on
+  // ``ACPAgentSettings`` yet, so sending it risks a validation error on older
+  // servers. Cloud grouping isolation is separate (agent-canvas#1016).
+
+  for (const key of ACP_SETTINGS_KEYS) {
+    // ``acp_model`` is resolved separately below so a saved ``null`` still
+    // falls back to the provider's default rather than being dropped.
+    if (key === "acp_model") continue;
+    // ``acp_env`` is deprecated — provider creds now route via ``request.secrets``.
+    if (key === "acp_env") continue;
+    const value =
+      key === "acp_command"
+        ? resolveAcpCommand(agentSettings)
+        : agentSettings[key];
+    if (value !== undefined && value !== null) {
+      payload[key] = value;
+    }
+  }
+
+  // ``mcp_config`` is a shared field (not in ACP_SETTINGS_KEYS): forward it
+  // so the ACP subprocess connects to the configured MCP servers at session
+  // creation. Only include it when it actually carries servers — an empty or
+  // malformed value is dropped rather than sending ``mcp_config: {}``.
+  const mcpConfig = toRecord(agentSettings.mcp_config);
+  if (Object.keys(mcpConfig).length > 0) {
+    payload.mcp_config = mcpConfig;
+  }
+
+  // Saved settings may carry ``acp_model: null`` (existing users predating
+  // the default-model registry, or saved fields the agent-server stripped).
+  // Fall back to the *preferred* default (Vertex-safe for Gemini) so the
+  // conversation starts with whatever the Settings → Agent UI shows — without
+  // that, the form's displayed default would silently not take effect at
+  // runtime until the user re-saved the page.
+  const serverKey =
+    typeof agentSettings.acp_server === "string"
+      ? agentSettings.acp_server
+      : undefined;
+  const effectiveModel = resolveEffectiveAcpModel({
+    configured: agentSettings.acp_model as string | null | undefined,
+    providerDefault: getAcpPreferredDefaultModel(serverKey),
+  });
+  if (effectiveModel) {
+    payload.acp_model = effectiveModel;
+  }
+
+  return payload;
+}
+
+function buildConfiguredOpenHandsAgentSettings(
+  settings: Settings,
+  runtimeServicesInfo?: RuntimeServicesInfo | null,
+  query?: string,
+): AgentSettingsPayload {
+  const agentSettings = toRecord(settings.agent_settings);
+  const llm = buildNormalizedLlmSettings(agentSettings.llm);
+
+  // Stream assistant tokens (parity with ACP agents). The agent-server only
+  // emits StreamingDeltaEvents for SDK LLM agents when an LLM has stream=True.
+  llm.stream = true;
+
+  const mcpConfig = toRecord(agentSettings.mcp_config);
+  if (Object.keys(mcpConfig).length === 0) {
+    delete agentSettings.mcp_config;
+  }
+
+  delete agentSettings.acp_server;
+  for (const key of ACP_SETTINGS_KEYS) {
+    delete agentSettings[key];
+  }
+  // ``acp_env`` is no longer a forwarded ACP setting (provider creds ride the
+  // Secrets panel), but a legacy value may linger on persisted settings —
+  // scrub it so it never leaks onto the OpenHands payload.
+  delete agentSettings.acp_env;
+
+  return {
+    ...agentSettings,
+    llm,
+    agent_context: buildAgentContext(
+      agentSettings,
+      runtimeServicesInfo,
+      toSkillEnablement(settings),
+      findInvokedCatalogSkill(query),
+    ),
+    tools: getAgentTools(agentSettings),
+  };
+}
+
+function buildConfiguredAgentSettings(
+  settings: Settings,
+  runtimeServicesInfo?: RuntimeServicesInfo | null,
+  query?: string,
+): AgentSettingsPayload {
+  return isAcpAgent(settings)
+    ? buildConfiguredAcpAgentSettings(settings, runtimeServicesInfo, query)
+    : buildConfiguredOpenHandsAgentSettings(
+        settings,
+        runtimeServicesInfo,
+        query,
+      );
+}
+
+function buildConfiguredConversationSettings(options: {
+  settings: Settings;
+  query?: string;
+  conversationInstructions?: string;
+  plugins?: PluginSpec[];
+  workingDir?: string;
+}): ConversationSettingsPayload {
+  const { settings, query, conversationInstructions, plugins, workingDir } =
+    options;
+  const conversationSettings = toRecord(settings.conversation_settings);
+  const initialMessage = buildInitialMessage(query, conversationInstructions);
+
+  CONVERSATION_SETTINGS_METADATA_KEYS.forEach(
+    (key) => delete conversationSettings[key],
+  );
+
+  const payload: ConversationSettingsPayload = {
+    ...conversationSettings,
+    workspace: {
+      kind: "LocalWorkspace",
+      working_dir: workingDir ?? getAgentServerWorkingDir(),
+    },
+    ...(initialMessage ? { initial_message: initialMessage } : {}),
+    ...(plugins?.length
+      ? {
+          plugins: plugins.map((plugin) => ({
+            source: plugin.source,
+            ...(plugin.ref ? { ref: plugin.ref } : {}),
+            ...(plugin.repo_path ? { repo_path: plugin.repo_path } : {}),
+          })),
+        }
+      : {}),
+  };
+
+  return payload;
+}
+
+interface LookupSecret {
+  kind: "LookupSecret";
+  url: string;
+  headers?: Record<string, string>;
+  description?: string;
+}
+
+/** A custom secret's public identity — name + optional description, no value. */
+type CustomSecretInput = { name: string; description?: string };
+
+type StartConversationPayloadBase = Record<string, unknown> & {
+  workspace: LocalWorkspacePayload;
+  confirmation_policy: SettingsRecord;
+  security_analyzer?: SettingsRecord;
+  initial_message?: InitialMessagePayload;
+  max_iterations: number;
+  stuck_detection: true;
+  autotitle: boolean;
+  title_llm_profile?: string;
+  worktree: boolean;
+  secrets_encrypted?: true;
+  conversation_id?: string;
+  parent_conversation_id?: string;
+  secrets?: Record<string, LookupSecret>;
+  tags?: Record<string, string>;
+  client_tools: ClientToolSpec[];
+  tool_module_qualnames?: Record<string, string>;
+};
+
+type AgentSettingsStartConversationPayload = StartConversationPayloadBase & {
+  // Omitted when launching via ``agent_profile_id`` — the two are mutually
+  // exclusive agent sources; the server resolves the profile server-side.
+  agent_settings?: AgentSettingsPayload;
+  agent_profile_id?: string;
+  agent?: never;
+};
+
+// The local planner bypasses agent assembly entirely and sends a raw agent
+// spec, so neither of the two managed agent sources applies.
+type RawAgentStartConversationPayload = StartConversationPayloadBase & {
+  agent: SettingsRecord;
+  agent_settings?: never;
+  agent_profile_id?: never;
+  parent_conversation_id?: string;
+};
+
+export interface StartConversationOptions {
+  settings: Settings;
+  query?: string;
+  conversationInstructions?: string;
+  plugins?: PluginSpec[];
+  conversationId?: string;
+  // Links the new conversation to an existing one as its child. The
+  // agent-server requires the parent to exist and to share this
+  // conversation's requested `workspace.working_dir` (software-agent-sdk
+  // #4188, agent-server >= 1.37.1); older servers ignore the field.
+  parentConversationId?: string;
+  workingDir?: string;
+  worktree?: boolean;
+  encryptedAgentSettings?: Record<string, SettingsValue>;
+  encryptedConversationSettings?: Record<string, SettingsValue>;
+  secretsEncrypted?: boolean;
+  customSecrets?: CustomSecretInput[];
+  // When set, the conversation launches from this AgentProfile (resolved
+  // server-side) instead of an inline ``agent_settings`` dump (#3727).
+  agentProfileId?: string;
+  agentProfileKind?: AgentKind;
+  titleLlmProfile?: string;
+  runtimeServicesInfo?: RuntimeServicesInfo | null;
+  workspaceHookConfig?: HookConfig | null;
+}
+
+/**
+ * Build the `request.secrets` map shared by the standard and planning
+ * conversation builders. Every saved secret rides as a LookupSecret the
+ * agent-server resolves from its own store at spawn time — `request.secrets` is
+ * the sole channel, uniform for ACP and non-ACP (agent-canvas#1039). For ACP the
+ * resolution runs off the event loop (software-agent-sdk#3510, >=1.25.0), so the
+ * loopback fetch can't deadlock. Returns `undefined` when there are no custom
+ * secrets so callers can omit the field.
+ */
+function buildCustomSecrets(
+  customSecrets: CustomSecretInput[] | undefined,
+): Record<string, LookupSecret> | undefined {
+  if (!customSecrets?.length) return undefined;
+
+  const backend = getEffectiveLocalBackend();
+  const headers = backend ? buildAuthHeaders(backend) : {};
+
+  const secrets: Record<string, LookupSecret> = {};
+  for (const secret of customSecrets) {
+    const lookupSecret: LookupSecret = {
+      kind: "LookupSecret",
+      url: `/api/settings/secrets/${encodeURIComponent(secret.name)}`,
+      description: secret.description,
+    };
+    if (Object.keys(headers).length > 0) {
+      lookupSecret.headers = headers;
+    }
+    secrets[secret.name] = lookupSecret;
+  }
+  return secrets;
+}
+
+export function buildStartConversationRequest(
+  options: StartConversationOptions,
+): AgentSettingsStartConversationPayload {
+  const sourceAgentSettings = options.encryptedAgentSettings
+    ? { ...options.settings, agent_settings: options.encryptedAgentSettings }
+    : options.settings;
+
+  const acpMode = isAcpAgent(sourceAgentSettings);
+  const launchAgentKind = options.agentProfileId
+    ? options.agentProfileKind
+    : acpMode
+      ? "acp"
+      : "openhands";
+  const agentSettings = buildConfiguredAgentSettings(
+    sourceAgentSettings,
+    options.runtimeServicesInfo,
+    options.query,
+  );
+  const acpServerTag = acpMode
+    ? getAcpServerTag(sourceAgentSettings)
+    : undefined;
+
+  const sourceConversationOptions = options.encryptedConversationSettings
+    ? {
+        ...options,
+        settings: {
+          ...options.settings,
+          conversation_settings: options.encryptedConversationSettings,
+        },
+      }
+    : options;
+
+  const conversationSettings = buildConfiguredConversationSettings(
+    sourceConversationOptions,
+  );
+
+  const payload: AgentSettingsStartConversationPayload = {
+    // ``agent_profile_id`` and ``agent_settings`` are mutually exclusive agent
+    // sources; the profile path lets the server resolve the profile (#3727).
+    //
+    // Enrichment boundary: on the profile path the server rebuilds the agent
+    // purely from the stored profile fields, so the client-owned enrichments
+    // this adapter folds into ``agent_settings`` do NOT apply. The exec toolset
+    // (terminal/file_editor/task_tracker) and public-skill loading are the
+    // server/SDK's responsibility to restore on the profile path — tracked in
+    // software-agent-sdk#3967 (profile resolution must attach the default
+    // toolset + public skills, else a profile-launched OpenHands agent has only
+    // Finish/Think). The dev ``RUNTIME_SERVICES`` system-message suffix remains
+    // agent-settings-only; the Canvas UI tool is a top-level client tool and
+    // therefore works on both inline-agent and profile launch paths.
+    //
+    // Persistent memory is NOT on that boundary: ``load_memory`` is a global
+    // user preference, so the agent-server stamps the stored
+    // ``agent_settings.agent_context.load_memory`` onto the profile-resolved
+    // agent the same way it already applies the global ``mcp_config``. The
+    // toggle therefore applies to both launch paths, and the client must not
+    // re-send it here (``agent_profile_id`` and ``agent_settings`` are
+    // mutually exclusive).
+    ...(options.agentProfileId
+      ? { agent_profile_id: options.agentProfileId }
+      : { agent_settings: agentSettings }),
+    workspace: conversationSettings.workspace,
+    // The agent-server caches each client tool's schema per tool *name* for the
+    // life of the process and rejects a re-registration with a different schema
+    // (`ClientToolSchemaConflictError`). Editing either schema below therefore
+    // requires restarting a long-running dev agent-server before new
+    // conversations can start.
+    client_tools:
+      launchAgentKind === "openhands"
+        ? [CANVAS_UI_CLIENT_TOOL, LAUNCH_CHILD_CONVERSATION_CLIENT_TOOL]
+        : [],
+    confirmation_policy:
+      getConversationConfirmationPolicy(conversationSettings),
+    max_iterations: resolveMaxIterations(conversationSettings.max_iterations),
+    stuck_detection: true,
+    autotitle: true,
+    ...(options.titleLlmProfile
+      ? { title_llm_profile: options.titleLlmProfile }
+      : {}),
+    worktree: options.worktree ?? true,
+  };
+
+  // Stamp the client source tag so the agent-server can attribute the
+  // conversation to Canvas in telemetry (conversation_source = "canvas").
+  // A profile launch resolves the ACP server server-side, so don't stamp the
+  // tag from current settings (it may not match the launched profile).
+  if (!options.agentProfileId && acpServerTag) {
+    payload.tags = {
+      [ACP_SERVER_TAG_KEY]: acpServerTag,
+      [CLIENT_SOURCE_TAG_KEY]: AGENT_CANVAS_SOURCE,
+    };
+  } else {
+    payload.tags = { [CLIENT_SOURCE_TAG_KEY]: AGENT_CANVAS_SOURCE };
+  }
+
+  // ``secrets_encrypted`` makes the agent-server decrypt request secrets at
+  // conversation start. Non-ACP conversations need it for encrypted LLM keys.
+  // ACP normally carries provider credentials as LookupSecrets, so avoid
+  // forcing a cipher on fresh ACP-only backends. The exception is MCP:
+  // encrypted settings round-trip mcp_config secrets as Fernet tokens,
+  // and ACP forwards mcp_config directly to the subprocess.
+  if (
+    !options.agentProfileId &&
+    options.secretsEncrypted &&
+    (!acpMode || hasEncryptedMcpSecrets(agentSettings.mcp_config))
+  ) {
+    payload.secrets_encrypted = true;
+  }
+
+  if (options.conversationId) {
+    payload.conversation_id = options.conversationId;
+  }
+
+  if (options.parentConversationId) {
+    payload.parent_conversation_id = options.parentConversationId;
+  }
+
+  const securityAnalyzer =
+    getConversationSecurityAnalyzer(conversationSettings);
+  if (securityAnalyzer) {
+    payload.security_analyzer = securityAnalyzer;
+  }
+
+  if (conversationSettings.initial_message) {
+    payload.initial_message = conversationSettings.initial_message;
+  }
+
+  if (conversationSettings.plugins) {
+    payload.plugins = conversationSettings.plugins;
+  }
+
+  if (conversationSettings.hook_config) {
+    payload.hook_config = conversationSettings.hook_config;
+  } else if (options.workspaceHookConfig) {
+    payload.hook_config = options.workspaceHookConfig;
+  }
+
+  const toolModuleQualnames = {
+    ...((conversationSettings.tool_module_qualnames as
+      | Record<string, string>
+      | undefined) ?? {}),
+  };
+  delete toolModuleQualnames[LEGACY_CANVAS_UI_TOOL_NAME];
+  delete toolModuleQualnames[CANVAS_UI_CLIENT_TOOL_NAME];
+  delete toolModuleQualnames[LAUNCH_CHILD_CONVERSATION_TOOL_NAME];
+  if (Object.keys(toolModuleQualnames).length > 0) {
+    payload.tool_module_qualnames = toolModuleQualnames;
+  }
+
+  if (conversationSettings.agent_definitions) {
+    payload.agent_definitions = conversationSettings.agent_definitions;
+  }
+
+  const secrets = buildCustomSecrets(options.customSecrets);
+  if (secrets) {
+    payload.secrets = secrets;
+  }
+
+  return payload;
+}
+
+export function buildStartPlanningConversationRequest(options: {
+  encryptedAgentSettings: Record<string, SettingsValue>;
+  workingDir: string;
+  parentConversationId: string;
+  initialMessage?: string;
+  secretsEncrypted?: boolean;
+  customSecrets?: CustomSecretInput[];
+  /** Mirrors the parent's configured `conversation_settings.max_iterations` — see DEFAULT_MAX_ITERATIONS. */
+  maxIterations?: number;
+  /** Mirrors the code agent's skill filtering — see buildConfiguredOpenHandsAgentSettings. */
+  skillEnablement?: SkillEnablement;
+}): RawAgentStartConversationPayload {
+  const agentSettings = toRecord(options.encryptedAgentSettings);
+  const llm = buildNormalizedLlmSettings(agentSettings.llm);
+  // Stream assistant tokens, matching the code agent (see
+  // buildConfiguredOpenHandsAgentSettings) — otherwise the agent-server never
+  // emits StreamingDeltaEvents for the planner and its replies would appear
+  // all at once instead of token-by-token.
+  llm.stream = true;
+
+  const planPath = buildPlanPath(options.workingDir);
+
+  // Put the planner's directive + boundaries in the system prompt (matching the
+  // OpenHands app-server's PLANNING_AGENT_INSTRUCTION), preserving any suffix
+  // buildAgentContext already set (e.g. the runtime-services block).
+  const agentContext = buildAgentContext(
+    agentSettings,
+    undefined,
+    options.skillEnablement,
+  );
+  const existingSuffix = agentContext.system_message_suffix;
+  agentContext.system_message_suffix =
+    typeof existingSuffix === "string"
+      ? `${PLANNING_AGENT_INSTRUCTION}\n\n${existingSuffix}`
+      : PLANNING_AGENT_INSTRUCTION;
+
+  // Idle planner: "Create a Plan" only switches to plan mode and provisions
+  // this conversation; the user sends the first message themselves, so nothing
+  // is injected into the chat. An explicit initialMessage is still honored.
+  const initialMessage = buildInitialMessage(options.initialMessage);
+
+  const payload: RawAgentStartConversationPayload = {
+    agent: {
+      kind: "Agent",
+      llm,
+      tools: [
+        { name: "glob", params: {} },
+        { name: "grep", params: {} },
+        {
+          name: PLANNING_FILE_EDITOR_TOOL_NAME,
+          params: { plan_path: planPath },
+        },
+      ],
+      system_prompt_filename: PLANNING_SYSTEM_PROMPT_FILENAME,
+      system_prompt_kwargs: { plan_structure: PLAN_STRUCTURE_TEXT },
+      // agent_context (skills + project context) is intentionally included so
+      // the planner shares the code agent's project context. This goes beyond
+      // the bare SDK `get_planning_agent()` preset (which sets no context); it
+      // mirrors how the frontend builds every agent, so the local planner is
+      // not context-starved relative to the code agent.
+      agent_context: agentContext,
+      // Mirror the SDK planning preset's condenser (openhands-tools preset
+      // `get_planning_condenser`): a larger rolling window and more pinned
+      // initial context than the default, with its own usage_id so its
+      // summarization LLM calls are attributed separately. The planning
+      // conversation is sent as a raw agent spec (it bypasses the agent-server's
+      // default agent assembly), so without this it would never condense —
+      // diverging from the canonical planning agent on long sessions.
+      condenser: {
+        kind: "LLMSummarizingCondenser",
+        llm: { ...llm, usage_id: "planning_condenser" },
+        max_size: 100,
+        keep_first: 6,
+      },
+    },
+    workspace: {
+      kind: "LocalWorkspace",
+      working_dir: options.workingDir,
+    },
+    // No Canvas UI client tool: the planner's only output is PLAN.md, which the
+    // Planner tab surfaces on its own via PlanningFileEditorObservation. Handing
+    // it the panel-control tool would only let it navigate the right-side panel
+    // away from the plan the user is reading.
+    client_tools: [],
+    confirmation_policy: { kind: "NeverConfirm" },
+    max_iterations: options.maxIterations ?? DEFAULT_MAX_ITERATIONS,
+    stuck_detection: true,
+    autotitle: false,
+    worktree: false,
+    // Two independent links to the parent, for two different jobs:
+    //
+    // - ``parent_conversation_id`` is the server-owned relationship (SDK
+    //   #4188, agent-server >= 1.37.1). The parent's ``sub_conversation_ids``
+    //   is derived from it, so the planner is recoverable from the server on
+    //   any browser and after storage loss. Older agent-servers ignore the
+    //   field (``StartConversationRequest`` does not forbid extras), which is
+    //   why the client-side metadata hint is still written as a fallback.
+    // - The tag is what hides the helper from the conversation list; it is
+    //   also the only marker on agent-servers too old for the parent link.
+    parent_conversation_id: options.parentConversationId,
+    tags: { [LOCAL_PLANNER_PARENT_TAG_KEY]: options.parentConversationId },
+    ...(initialMessage ? { initial_message: initialMessage } : {}),
+  };
+
+  if (options.secretsEncrypted) {
+    payload.secrets_encrypted = true;
+  }
+
+  const secrets = buildCustomSecrets(options.customSecrets);
+  if (secrets) {
+    payload.secrets = secrets;
+  }
+
+  return payload;
+}
+
+/**
+ * Resolve the encrypted LLM config for a named LLM profile, so a planner can
+ * run the parent conversation's *current* model (`active_profile`, tracking
+ * `/model` and `SwitchLLMTool`) rather than a stale launch-time value.
+ * Returns `null` — caller falls back further — if unknown or lookup fails.
+ */
+async function resolveLlmProfileSettings(
+  profileName: string,
+): Promise<SettingsRecord | null> {
+  try {
+    const { default: ProfilesService } =
+      await import("./profiles-service/profiles-service.api");
+    // ``encrypted`` matches ``secrets_encrypted`` on the payload: the
+    // agent-server decrypts with the same cipher it encrypted with.
+    const detail = await ProfilesService.getProfile(profileName, "encrypted");
+    return isPlainRecord(detail.config) ? detail.config : null;
+  } catch (error) {
+    console.warn(
+      `Falling back: could not resolve LLM profile ${profileName}`,
+      error,
+    );
+    return null;
+  }
+}
+
+/**
+ * Resolve the encrypted LLM config the given AgentProfile launches with, as a
+ * fallback for `resolveLlmProfileSettings`. AgentProfiles hold a reference
+ * (`llm_profile_ref`), not credentials, so this is a two-hop lookup: profile
+ * id -> llm profile name -> encrypted LLM config. Returns `null` — caller
+ * falls back to global settings — for an unknown/ACP/dangling-ref profile or
+ * a failed lookup, none of which should block plan creation outright.
+ */
+async function resolveAgentProfileLlmSettings(
+  agentProfileId: string,
+): Promise<SettingsRecord | null> {
+  try {
+    const { default: AgentProfilesService } =
+      await import("./agent-profiles-service/agent-profiles-service.api");
+
+    const { profiles } = await AgentProfilesService.listProfiles();
+    const summary = profiles.find(
+      (profile) => profile.id === agentProfileId && profile.llm_profile_ref,
+    );
+    if (!summary?.llm_profile_ref) return null;
+
+    return await resolveLlmProfileSettings(summary.llm_profile_ref);
+  } catch (error) {
+    console.warn(
+      `Falling back to global agent settings: could not resolve the LLM for agent profile ${agentProfileId}`,
+      error,
+    );
+    return null;
+  }
+}
+
+export async function buildStartPlanningConversationRequestWithEncryptedSettings(options: {
+  workingDir: string;
+  parentConversationId: string;
+  /**
+   * The parent conversation's current LLM profile (`AppConversation.active_profile`,
+   * tracking `/model` and `SwitchLLMTool`). Takes priority over
+   * `parentAgentProfileId` so a model switch on the parent carries over to a
+   * planner created afterward, without a *different* conversation's global
+   * profile activation repointing it.
+   */
+  parentActiveProfileName?: string | null;
+  /**
+   * `launched_agent_profile.agent_profile_id` of the parent, when started
+   * from an AgentProfile. Fallback for when `parentActiveProfileName` can't
+   * be resolved (e.g. an ACP parent, whose `active_profile` is a stale
+   * launch-time snapshot rather than anything the ACP agent itself runs).
+   */
+  parentAgentProfileId?: string | null;
+  initialMessage?: string;
+}): Promise<RawAgentStartConversationPayload> {
+  const { SecretsService } = await import("./secrets-service");
+
+  const [settingsResult, customSecrets] = await Promise.all([
+    SettingsService.getSettingsForConversation(),
+    SecretsService.getSecrets(),
+  ]);
+
+  const profileLlm =
+    (options.parentActiveProfileName
+      ? await resolveLlmProfileSettings(options.parentActiveProfileName)
+      : null) ??
+    (options.parentAgentProfileId
+      ? await resolveAgentProfileLlmSettings(options.parentAgentProfileId)
+      : null);
+  const encryptedAgentSettings: Record<string, SettingsValue> = profileLlm
+    ? { ...settingsResult.agentSettings, llm: profileLlm as SettingsValue }
+    : settingsResult.agentSettings;
+
+  await assertSubscriptionAuthReady(encryptedAgentSettings);
+
+  // Mirror the code agent's configured cap (see DEFAULT_MAX_ITERATIONS) rather
+  // than hardcoding a different value the planner could silently stop against.
+  const maxIterations = resolveMaxIterations(
+    settingsResult.conversationSettings.max_iterations,
+  );
+
+  return buildStartPlanningConversationRequest({
+    ...options,
+    encryptedAgentSettings,
+    secretsEncrypted: settingsResult.secretsEncrypted,
+    customSecrets,
+    maxIterations,
+    skillEnablement: settingsResult.skillEnablement,
+  });
+}
+
+export const SUBSCRIPTION_LOGIN_REQUIRED_ERROR =
+  "Connect your ChatGPT subscription before starting a conversation with this LLM profile.";
+
+/**
+ * Throws if a ChatGPT subscription LLM profile is not connected.
+ * Called before conversation creation and LLM profile switch only — not on
+ * subsequent message sends or conversation resume. The agent-server must handle
+ * mid-conversation token expiry gracefully.
+ */
+export async function assertSubscriptionAuthReady(
+  agentSettings: Record<string, unknown>,
+): Promise<void> {
+  const llm = toRecord(agentSettings.llm);
+  if (!isSubscriptionLlmConfig(llm)) return;
+
+  const status = await LLMSubscriptionService.getOpenAIStatus();
+  if (!status.connected) {
+    throw new Error(SUBSCRIPTION_LOGIN_REQUIRED_ERROR);
+  }
+}
+
+export async function buildStartConversationRequestWithEncryptedSettings(options: {
+  settings: Settings;
+  query?: string;
+  conversationInstructions?: string;
+  plugins?: PluginSpec[];
+  conversationId?: string;
+  parentConversationId?: string;
+  workingDir?: string;
+  /** Workspace root for the hooks lookup, not the per-conversation `workingDir` (#16907). */
+  hooksProjectDir?: string;
+  worktree?: boolean;
+  agentProfileId?: string;
+  agentProfileKind?: AgentKind;
+  titleLlmProfile?: string;
+}): Promise<Record<string, unknown>> {
+  const [{ SecretsService }, { default: HooksService }] = await Promise.all([
+    import("./secrets-service"),
+    import("./hooks-service"),
+  ]);
+
+  const [
+    settingsResult,
+    customSecrets,
+    runtimeServicesInfo,
+    workspaceHookConfig,
+  ] = await Promise.all([
+    SettingsService.getSettingsForConversation(),
+    SecretsService.getSecrets(),
+    fetchBackendRuntimeServicesInfo(),
+    HooksService.loadWorkspaceHooks(options.hooksProjectDir),
+  ]);
+
+  const { agentSettings, conversationSettings, secretsEncrypted } =
+    settingsResult;
+
+  // A profile launch resolves the LLM server-side, so the current-settings
+  // subscription check doesn't apply (and can't see the profile's LLM).
+  if (!options.agentProfileId) {
+    await assertSubscriptionAuthReady(agentSettings);
+  }
+
+  return buildStartConversationRequest({
+    ...options,
+    encryptedAgentSettings: agentSettings,
+    encryptedConversationSettings: conversationSettings,
+    secretsEncrypted,
+    customSecrets,
+    runtimeServicesInfo,
+    workspaceHookConfig,
+  });
+}
+
+export function emptyHooksResponse(): GetHooksResponse {
+  return { hooks: [] };
+}

src/api/agent-server-client-options.ts

@@ -0,0 +1,80 @@
+import { buildHttpBaseUrl } from "#/utils/websocket-url";
+import { getAgentServerWorkingDir } from "./agent-server-config";
+import { getEffectiveLocalBackend } from "./backend-registry/active-store";
+import type { Backend } from "./backend-registry/types";
+
+export interface AgentServerClientOverrides {
+  host?: string;
+  apiKey?: string | null;
+  sessionApiKey?: string | null;
+  workingDir?: string;
+  conversationUrl?: string | null;
+  timeout?: number;
+}
+
+export interface AgentServerClientOptions {
+  host: string;
+  apiKey?: string;
+  workingDir: string;
+  timeout?: number;
+}
+
+export class NoBackendAvailableError extends Error {
+  constructor() {
+    super("No backend is configured.");
+    this.name = "NoBackendAvailableError";
+  }
+}
+
+export const isNoBackendAvailableError = (
+  error: unknown,
+): error is NoBackendAvailableError =>
+  error instanceof NoBackendAvailableError ||
+  (typeof error === "object" &&
+    error !== null &&
+    "name" in error &&
+    error.name === "NoBackendAvailableError");
+
+function normalizeHost(host: string): string {
+  return host.replace(/\/+$/, "");
+}
+
+function resolveHost(
+  overrides: AgentServerClientOverrides,
+  backend: Backend | null,
+): string {
+  if (overrides.host) return normalizeHost(overrides.host);
+  if (overrides.conversationUrl)
+    return normalizeHost(buildHttpBaseUrl(overrides.conversationUrl));
+  return normalizeHost(backend?.host ?? "");
+}
+
+export function getAgentServerClientOptions(
+  overrides: AgentServerClientOverrides = {},
+): AgentServerClientOptions {
+  const backend = getEffectiveLocalBackend();
+  if (!backend && !overrides.host && !overrides.conversationUrl) {
+    throw new NoBackendAvailableError();
+  }
+
+  const apiKey =
+    overrides.sessionApiKey ?? overrides.apiKey ?? backend?.apiKey ?? undefined;
+
+  return {
+    host: resolveHost(overrides, backend),
+    ...(apiKey ? { apiKey } : {}),
+    workingDir: overrides.workingDir ?? getAgentServerWorkingDir(),
+    ...(overrides.timeout !== undefined ? { timeout: overrides.timeout } : {}),
+  };
+}
+
+export function getAgentServerHttpClientOptions(
+  overrides?: AgentServerClientOverrides,
+) {
+  const { host, apiKey, timeout } = getAgentServerClientOptions(overrides);
+  return {
+    baseUrl: host,
+    ...(apiKey ? { apiKey } : {}),
+    timeout: timeout ?? 60000,
+  };
+}

src/api/agent-server-compatibility.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import {
+  AgentServerUnknownVersionError,
+  AgentServerUnsupportedVersionError,
+  assertAgentServerVersionIsSupported,
+  getDisplayAgentServerSdkVersion,
+  getDisplayAgentServerVersion,
+  type AgentServerInfo,
+} from "./agent-server-compatibility";
+
+const serverInfo = (version?: string, sdkVersion?: string): AgentServerInfo =>
+  ({ version, sdk_version: sdkVersion }) as AgentServerInfo;
+
+describe("agent-server version compatibility", () => {
+  it("classifies missing and unknown versions separately from old versions", () => {
+    for (const version of [undefined, "", "unknown", " UNKNOWN "]) {
+      expect(() =>
+        assertAgentServerVersionIsSupported(serverInfo(version)),
+      ).toThrow(AgentServerUnknownVersionError);
+    }
+  });
+
+  it("classifies malformed versions separately from old versions", () => {
+    expect(() =>
+      assertAgentServerVersionIsSupported(serverInfo("dev-build")),
+    ).toThrow(AgentServerUnknownVersionError);
+  });
+
+  it("keeps valid but too-old versions on the unsupported-version path", () => {
+    expect(() =>
+      assertAgentServerVersionIsSupported(serverInfo("0.0.1")),
+    ).toThrow(AgentServerUnsupportedVersionError);
+  });
+
+  it("does not render unknown or malformed versions as backend badges", () => {
+    expect(getDisplayAgentServerVersion(serverInfo("unknown"))).toBeNull();
+    expect(getDisplayAgentServerVersion(serverInfo("dev-build"))).toBeNull();
+    expect(getDisplayAgentServerVersion(serverInfo("1.28.0"))).toBe("1.28.0");
+  });
+
+  it("uses sdk_version as the agent-server version fallback", () => {
+    expect(getDisplayAgentServerVersion(serverInfo(undefined, "1.36.1"))).toBe(
+      "1.36.1",
+    );
+    expect(() =>
+      assertAgentServerVersionIsSupported(serverInfo(undefined, "1.36.1")),
+    ).not.toThrow();
+  });
+
+  it("reports the dedicated agent-server SDK version when present", () => {
+    expect(
+      getDisplayAgentServerSdkVersion(serverInfo("1.36.0", "1.36.1")),
+    ).toBe("1.36.1");
+    expect(getDisplayAgentServerSdkVersion(serverInfo("1.36.0"))).toBe(
+      "1.36.0",
+    );
+  });
+});

src/api/agent-server-compatibility.ts

@@ -0,0 +1,444 @@
+import {
+  ServerClient,
+  SettingsClient,
+} from "@openhands/typescript-client/clients";
+import type { ServerInfo as BaseServerInfo } from "@openhands/typescript-client";
+import { getAgentServerClientOptions } from "#/api/agent-server-client-options";
+import { isAuthRequired } from "#/api/agent-server-config";
+import {
+  getActiveBackend,
+  getEffectiveLocalBackend,
+  isNoBackend,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import defaults from "../../config/defaults.json";
+
+const AGENT_SERVER_INFO_TIMEOUT_MS = 5000;
+const UNKNOWN_AGENT_SERVER_VERSION = "unknown";
+
+export const MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION =
+  defaults.compatibility.minimumAgentServer;
+export const AGENT_SERVER_UNSUPPORTED_VERSION_ERROR_CODE =
+  "AGENT_SERVER_UNSUPPORTED_VERSION";
+export const AGENT_SERVER_UNKNOWN_VERSION_ERROR_CODE =
+  "AGENT_SERVER_UNKNOWN_VERSION";
+
+/**
+ * Sentinel string thrown (as an Error message) when a local backend
+ * rejects the configured session API key with HTTP 401.
+ * Shared between the backend health probe ({@link validateLocalBackend})
+ * and any consumer that needs to detect this specific failure.
+ */
+export const INVALID_BACKEND_API_KEY_ERROR = "Invalid API key";
+
+export interface AgentServerInfo extends BaseServerInfo {
+  sdk_version?: string;
+  usable_tools?: string[] | null;
+  runtime_services?: unknown;
+}
+
+let cachedAgentServerInfo: AgentServerInfo | null = null;
+let cachedAgentServerInfoHost: string | null = null;
+
+const getAdvertisedTools = (serverInfo: AgentServerInfo | null) => {
+  if (Array.isArray(serverInfo?.usable_tools)) {
+    return serverInfo.usable_tools;
+  }
+  return null;
+};
+
+export class AgentServerUnavailableError extends Error {
+  readonly details: string | null;
+  readonly noBackendConfigured: boolean;
+
+  constructor(
+    details?: string | null,
+    options?: { noBackendConfigured?: boolean },
+  ) {
+    const noBackendConfigured = options?.noBackendConfigured ?? false;
+    super(
+      noBackendConfigured
+        ? "No agent server backend is configured yet. Add a backend to get started."
+        : "Could not connect to the configured agent server. Make sure it is running and reachable, then reload the page.",
+    );
+    this.name = "AgentServerUnavailableError";
+    this.details = details ?? null;
+    this.noBackendConfigured = noBackendConfigured;
+  }
+}
+
+export const isAgentServerUnavailableError = (
+  error: unknown,
+): error is AgentServerUnavailableError =>
+  error instanceof AgentServerUnavailableError ||
+  (typeof error === "object" &&
+    error !== null &&
+    "name" in error &&
+    (error.name === "AgentServerUnavailableError" ||
+      error.name === "AgentServerUnsupportedVersionError" ||
+      error.name === "AgentServerUnknownVersionError"));
+
+export class AgentServerUnsupportedVersionError extends AgentServerUnavailableError {
+  readonly code = AGENT_SERVER_UNSUPPORTED_VERSION_ERROR_CODE;
+  readonly actualVersion: string;
+  readonly requiredVersion = MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION;
+
+  constructor(actualVersion: string) {
+    const message = `Agent Canvas requires agent-server ${MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION} or newer; this backend is running ${actualVersion}. Please upgrade the agent-server backend.`;
+    super(message);
+    this.name = "AgentServerUnsupportedVersionError";
+    this.message = message;
+    this.actualVersion = actualVersion;
+  }
+}
+
+export class AgentServerUnknownVersionError extends AgentServerUnavailableError {
+  readonly code = AGENT_SERVER_UNKNOWN_VERSION_ERROR_CODE;
+  readonly actualVersion: string | null;
+  readonly requiredVersion = MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION;
+
+  constructor(actualVersion: string | null) {
+    const reported = actualVersion ? ` It reported "${actualVersion}".` : "";
+    const message =
+      `Could not determine this backend's agent-server version.${reported} ` +
+      `Agent Canvas requires agent-server ${MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION} ` +
+      "or newer, but this backend did not return a valid version from " +
+      "/server_info. Restart or rebuild the agent-server backend, then try again.";
+    super(message);
+    this.name = "AgentServerUnknownVersionError";
+    this.message = message;
+    this.actualVersion = actualVersion;
+  }
+}
+
+export const isAgentServerUnsupportedVersionError = (
+  error: unknown,
+): error is AgentServerUnsupportedVersionError =>
+  error instanceof AgentServerUnsupportedVersionError ||
+  (typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === AGENT_SERVER_UNSUPPORTED_VERSION_ERROR_CODE);
+
+export const isAgentServerUnknownVersionError = (
+  error: unknown,
+): error is AgentServerUnknownVersionError =>
+  error instanceof AgentServerUnknownVersionError ||
+  (typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === AGENT_SERVER_UNKNOWN_VERSION_ERROR_CODE);
+
+/**
+ * Returns true when the agent-server probe failed with HTTP 401.
+ * In public mode this means the stored key is stale (server restarted
+ * with a different `LOCAL_BACKEND_API_KEY`). Only meaningful when
+ * auth is required — a 401 in local mode is a misconfiguration, not a
+ * key-rotation event. Uses {@link isAuthRequired} so both the build-time
+ * `VITE_AUTH_REQUIRED` flag and the runtime `window.__AGENT_CANVAS_AUTH_REQUIRED__`
+ * injection (used by pre-built static binaries) are honoured.
+ */
+export const isAgentServerAuthError = (error: unknown): boolean =>
+  isAuthRequired() && isSdkHttpStatusError(error, 401);
+
+export function clearCachedAgentServerInfo() {
+  cachedAgentServerInfo = null;
+  cachedAgentServerInfoHost = null;
+}
+
+export function getCachedAgentServerInfo(options?: {
+  host?: string | null;
+}): AgentServerInfo | null {
+  if (options?.host && options.host !== cachedAgentServerInfoHost) {
+    return null;
+  }
+  return cachedAgentServerInfo;
+}
+
+export function isAgentServerToolAvailable(toolName: string) {
+  const availableTools = getAdvertisedTools(cachedAgentServerInfo);
+  if (!Array.isArray(availableTools)) {
+    return true;
+  }
+  return availableTools.includes(toolName);
+}
+
+export function isSdkHttpError(error: unknown) {
+  return (
+    error instanceof Error &&
+    error.name === "HttpError" &&
+    "status" in error &&
+    typeof error.status === "number"
+  );
+}
+
+/**
+ * Narrows an SDK HTTP error to a specific status code.
+ * Use instead of manually casting `(err as { status: number }).status`.
+ */
+export function isSdkHttpStatusError(error: unknown, status: number): boolean {
+  return (
+    isSdkHttpError(error) && (error as { status: number }).status === status
+  );
+}
+
+function normalizeAgentServerInfoVersion(version: unknown): string | null {
+  if (typeof version !== "string") return null;
+  const trimmed = version.trim();
+  return trimmed || null;
+}
+
+function getRawAgentServerSdkVersion(
+  serverInfo: AgentServerInfo,
+): string | null {
+  return normalizeAgentServerInfoVersion(serverInfo.sdk_version);
+}
+
+function getRawAgentServerVersion(serverInfo: AgentServerInfo): string | null {
+  return (
+    normalizeAgentServerInfoVersion(serverInfo.version) ??
+    getRawAgentServerSdkVersion(serverInfo)
+  );
+}
+
+function getComparableAgentServerVersion(
+  serverInfo: AgentServerInfo,
+): string | null {
+  const version = getRawAgentServerVersion(serverInfo);
+  if (!version || version.toLowerCase() === UNKNOWN_AGENT_SERVER_VERSION) {
+    return null;
+  }
+  return version;
+}
+
+export function getDisplayAgentServerVersion(
+  serverInfo: AgentServerInfo,
+): string | null {
+  const version = getComparableAgentServerVersion(serverInfo);
+  if (!version || !parseAgentServerVersion(version)) {
+    return null;
+  }
+  return version;
+}
+
+export function getDisplayAgentServerSdkVersion(
+  serverInfo: AgentServerInfo,
+): string | null {
+  const version =
+    getRawAgentServerSdkVersion(serverInfo) ??
+    getComparableAgentServerVersion(serverInfo);
+  if (!version || version.toLowerCase() === UNKNOWN_AGENT_SERVER_VERSION) {
+    return null;
+  }
+  return version;
+}
+
+export function getCachedAgentServerSdkVersion(
+  host?: string | null,
+): string | null {
+  if (!cachedAgentServerInfo) return null;
+  if (host && getEffectiveLocalBackend()?.host !== host) return null;
+  return getDisplayAgentServerSdkVersion(cachedAgentServerInfo);
+}
+
+export function getCachedAgentServerVersion(
+  host?: string | null,
+): string | null {
+  if (!cachedAgentServerInfo) return null;
+  if (host && getEffectiveLocalBackend()?.host !== host) return null;
+  return getDisplayAgentServerVersion(cachedAgentServerInfo);
+}
+
+export function compareAgentServerVersions(actual: string, required: string) {
+  const parsedActual = parseAgentServerVersion(actual);
+  const parsedRequired = parseAgentServerVersion(required);
+
+  if (!parsedActual || !parsedRequired) {
+    return null;
+  }
+
+  for (const key of ["major", "minor", "patch"] as const) {
+    if (parsedActual[key] > parsedRequired[key]) {
+      return 1;
+    }
+    if (parsedActual[key] < parsedRequired[key]) {
+      return -1;
+    }
+  }
+
+  if (parsedActual.prerelease && !parsedRequired.prerelease) {
+    return -1;
+  }
+  if (!parsedActual.prerelease && parsedRequired.prerelease) {
+    return 1;
+  }
+  if (parsedActual.prerelease && parsedRequired.prerelease) {
+    return parsedActual.prerelease.localeCompare(parsedRequired.prerelease);
+  }
+
+  return 0;
+}
+
+function parseAgentServerVersion(version: string) {
+  const trimmed = version.trim().replace(/^v/, "");
+  const [withoutBuild] = trimmed.split("+");
+  const [core, prerelease] = withoutBuild.split("-", 2);
+  const parts = core.split(".");
+
+  if (parts.length !== 3) {
+    return null;
+  }
+
+  const [major, minor, patch] = parts.map((part) => Number(part));
+  if (
+    ![major, minor, patch].every((part) => Number.isInteger(part) && part >= 0)
+  ) {
+    return null;
+  }
+
+  return { major, minor, patch, prerelease };
+}
+
+export function assertAgentServerVersionIsSupported(
+  serverInfo: AgentServerInfo,
+) {
+  const actualVersion = getComparableAgentServerVersion(serverInfo);
+  if (!actualVersion) {
+    clearCachedAgentServerInfo();
+    throw new AgentServerUnknownVersionError(
+      getRawAgentServerVersion(serverInfo),
+    );
+  }
+
+  const comparison = compareAgentServerVersions(
+    actualVersion,
+    MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
+  );
+
+  if (comparison === null) {
+    clearCachedAgentServerInfo();
+    throw new AgentServerUnknownVersionError(actualVersion);
+  }
+
+  if (comparison < 0) {
+    clearCachedAgentServerInfo();
+    throw new AgentServerUnsupportedVersionError(actualVersion);
+  }
+}
+
+/**
+ * Validates a local agent-server backend with a two-step probe:
+ *  1. GET /api/settings — authenticates the configured session API key;
+ *     a 401 throws an Error with message {@link INVALID_BACKEND_API_KEY_ERROR}.
+ *  2. GET /server_info  — asserts the server meets the minimum version floor.
+ *
+ * Returns the display version string reported by the server, or `null` when
+ * the server does not report a parseable version. Throws on any failure.
+ *
+ * Used by both the backend health poller and the backend-form connection test
+ * so that auth-check semantics (status codes, error messages) stay in one place.
+ */
+export async function validateLocalBackend(
+  backend: Pick<Backend, "host" | "apiKey">,
+  timeout: number,
+): Promise<string | null> {
+  const clientOptions = getAgentServerClientOptions({
+    host: backend.host,
+    sessionApiKey: backend.apiKey || null,
+    timeout,
+  });
+
+  try {
+    await new SettingsClient(clientOptions).getSettings();
+    const serverInfo = await new ServerClient(clientOptions).getServerInfo();
+    assertAgentServerVersionIsSupported(serverInfo);
+    return getDisplayAgentServerVersion(serverInfo);
+  } catch (error) {
+    if (isSdkHttpStatusError(error, 401)) {
+      throw new Error(INVALID_BACKEND_API_KEY_ERROR);
+    }
+    throw error;
+  }
+}
+
+export async function loadAgentServerInfo() {
+  // The probe is a *local* agent-server concern — it verifies the runtime
+  // hosting the GUI is reachable. It must NEVER run against the active
+  // backend when that backend is cloud, because cloud hosts don't
+  // expose /api/server_info and would fail with a CORS error besides.
+  const local = getEffectiveLocalBackend();
+  if (!local) {
+    clearCachedAgentServerInfo();
+
+    // Empty registry (NO_BACKEND sentinel) — the user has no backend
+    // configured at all.  Throw so root.tsx shows the manage-backends
+    // modal instead of silently rendering a broken home page.
+    if (isNoBackend(getActiveBackend().backend)) {
+      throw new AgentServerUnavailableError("No backend configured", {
+        noBackendConfigured: true,
+      });
+    }
+
+    // Active backend is cloud — no local probe needed.
+    return null;
+  }
+
+  const clientOptions = getAgentServerClientOptions({
+    host: local.host,
+    sessionApiKey: local.apiKey || null,
+    timeout: AGENT_SERVER_INFO_TIMEOUT_MS,
+  });
+  let serverInfo: AgentServerInfo;
+
+  try {
+    serverInfo = (await new ServerClient(
+      clientOptions,
+    ).getServerInfo()) as AgentServerInfo;
+  } catch (error) {
+    clearCachedAgentServerInfo();
+    // Preserve 401 so root.tsx can show the auth screen (public mode).
+    // All other HTTP errors (502, 503, etc.) mean the server is unreachable
+    // or misconfigured — treat them as unavailable.
+    if (isSdkHttpStatusError(error, 401)) {
+      throw error;
+    }
+
+    const details = error instanceof Error ? error.message : null;
+    throw new AgentServerUnavailableError(details);
+  }
+
+  assertAgentServerVersionIsSupported(serverInfo);
+
+  // /server_info is unprotected, so a stale session key still gets 200.
+  // In public mode, validate the key against a protected endpoint so a
+  // server restart with a new LOCAL_BACKEND_API_KEY surfaces immediately
+  // instead of letting the app load and fail on every subsequent call.
+  if (isAuthRequired()) {
+    try {
+      await new SettingsClient(clientOptions).getSettings();
+    } catch (error) {
+      // Only rethrow 401 — that means the stored key is invalid /
+      // rotated.  Other HTTP errors (403, 5xx) and non-HTTP errors
+      // (network, timeout) are swallowed: the server *is* up (we just
+      // reached /server_info), so let the app proceed with an
+      // unvalidated key rather than blocking the UI.
+      // NOTE: If the connection drops between the /server_info and
+      // getSettings() probes, the app loads with an unvalidated key and
+      // subsequent 401s won't trigger the auth screen (they come from
+      // React Query hooks, not this bootstrap path). Acceptable for now
+      // since the window is narrow and a page refresh recovers.
+      if (isSdkHttpStatusError(error, 401)) {
+        throw error;
+      }
+
+      console.warn(
+        "[agent-server] getSettings() probe failed (non-401):",
+        error,
+      );
+    }
+  }
+
+  cachedAgentServerInfo = serverInfo;
+  cachedAgentServerInfoHost = clientOptions.host;
+  return serverInfo;
+}

src/api/agent-server-config.test.ts

@@ -0,0 +1,117 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  DEFAULT_WORKING_DIR,
+  buildConversationWorkingDir,
+  buildConversationWorkingDirForBackend,
+  buildRelativeConversationWorkingDir,
+  isServedOriginHost,
+} from "./agent-server-config";
+
+describe("buildRelativeConversationWorkingDir", () => {
+  afterEach(() => vi.unstubAllEnvs());
+
+  it("ignores a baked absolute VITE_WORKING_DIR and stays relative", () => {
+    vi.stubEnv("VITE_WORKING_DIR", "/Users/someone/.openhands/workspaces");
+    expect(buildRelativeConversationWorkingDir("abc-123")).toBe(
+      `${DEFAULT_WORKING_DIR}/abc123`,
+    );
+  });
+
+  it("strips dashes from the conversation id", () => {
+    expect(buildRelativeConversationWorkingDir("a-b-c")).toBe(
+      `${DEFAULT_WORKING_DIR}/abc`,
+    );
+  });
+});
+
+describe("buildConversationWorkingDir (baked default)", () => {
+  afterEach(() => vi.unstubAllEnvs());
+
+  it("uses a baked absolute dir as the base", () => {
+    vi.stubEnv("VITE_WORKING_DIR", "/Users/someone/workspaces");
+    expect(buildConversationWorkingDir("abc-123")).toBe(
+      "/Users/someone/workspaces/abc123",
+    );
+  });
+
+  it("falls back to the relative default when nothing is baked", () => {
+    vi.stubEnv("VITE_WORKING_DIR", "");
+    expect(buildConversationWorkingDir("abc-123")).toBe(
+      `${DEFAULT_WORKING_DIR}/abc123`,
+    );
+  });
+});
+
+describe("isServedOriginHost", () => {
+  afterEach(() => vi.unstubAllEnvs());
+
+  it("matches the host that served this frontend", () => {
+    vi.stubEnv("VITE_BACKEND_BASE_URL", "http://127.0.0.1:8000");
+    expect(isServedOriginHost("http://127.0.0.1:8000")).toBe(true);
+  });
+
+  it("normalizes a bare host against the served origin", () => {
+    vi.stubEnv("VITE_BACKEND_BASE_URL", "http://127.0.0.1:8000");
+    // getAgentServerBaseUrl returns the already-normalized configured URL;
+    // a bare candidate host is normalized to http:// off-window.
+    expect(isServedOriginHost("127.0.0.1:8000")).toBe(true);
+  });
+
+  it("does not match a different host", () => {
+    vi.stubEnv("VITE_BACKEND_BASE_URL", "http://127.0.0.1:8000");
+    expect(isServedOriginHost("https://cabin.liberty-labs.org")).toBe(false);
+  });
+
+  it("does not match when the backend host is empty", () => {
+    vi.stubEnv("VITE_BACKEND_BASE_URL", "http://127.0.0.1:8000");
+    expect(isServedOriginHost("")).toBe(false);
+    expect(isServedOriginHost(null)).toBe(false);
+  });
+});
+
+describe("buildConversationWorkingDirForBackend", () => {
+  afterEach(() => vi.unstubAllEnvs());
+
+  it("uses the baked absolute default for the served-origin backend", () => {
+    vi.stubEnv("VITE_BACKEND_BASE_URL", "http://127.0.0.1:8000");
+    vi.stubEnv(
+      "VITE_WORKING_DIR",
+      "/Users/me/.openhands/agent-canvas/workspaces",
+    );
+    expect(
+      buildConversationWorkingDirForBackend("abc-123", "http://127.0.0.1:8000"),
+    ).toBe("/Users/me/.openhands/agent-canvas/workspaces/abc123");
+  });
+
+  // Regression for the reviewed bug: the seeded `default-local` backend is
+  // mutable. Editing its host to a remote VM (while its id stays
+  // `default-local`) must NOT send the baked macOS path to that VM — this is
+  // the exact case that failed on our remote Linux backend (Cabin) with
+  // `mkdir: cannot create directory '/Users': Permission denied`.
+  it("uses the relative default for an edited default-local pointing at a remote host", () => {
+    vi.stubEnv("VITE_BACKEND_BASE_URL", "http://127.0.0.1:8000");
+    vi.stubEnv(
+      "VITE_WORKING_DIR",
+      "/Users/me/.openhands/agent-canvas/workspaces",
+    );
+    // The user edited the seeded `default-local` entry to a remote Linux VM
+    // (home /home/daytona); its host no longer matches the served origin.
+    expect(
+      buildConversationWorkingDirForBackend(
+        "abc-123",
+        "https://cabin.liberty-labs.org",
+      ),
+    ).toBe(`${DEFAULT_WORKING_DIR}/abc123`);
+  });
+
+  it("uses the relative default for any separately-registered remote backend", () => {
+    vi.stubEnv("VITE_BACKEND_BASE_URL", "http://127.0.0.1:8000");
+    vi.stubEnv("VITE_WORKING_DIR", "/Users/me/workspaces");
+    expect(
+      buildConversationWorkingDirForBackend(
+        "abc-123",
+        "https://sandbox.example.dev",
+      ),
+    ).toBe(`${DEFAULT_WORKING_DIR}/abc123`);
+  });
+});

src/api/agent-server-config.ts

@@ -0,0 +1,290 @@
+export const DEFAULT_WORKING_DIR = "workspace/project";
+
+export type LockedCloudAuthMode = "api-key" | "cookie";
+
+export interface AgentServerFormDefaults {
+  baseUrl: string;
+  sessionApiKey: string;
+}
+
+// Window-global key the static server injects `--lock-to-cloud` into; kept
+// module-private because only `getLockedCloudHost()` reads it. The static
+// server (`scripts/static-server.mjs`) and its tests reference the literal
+// string directly, not this constant.
+const LOCK_TO_CLOUD_WINDOW_KEY = "__AGENT_CANVAS_LOCK_TO_CLOUD__";
+const LEGACY_CLOUD_DOMAIN = "all-hands.dev";
+const CURRENT_CLOUD_DOMAIN = "openhands.dev";
+const LEGACY_PRODUCTION_APP_HOST = `app.${LEGACY_CLOUD_DOMAIN}`;
+const CURRENT_PRODUCTION_APP_HOST = CURRENT_CLOUD_DOMAIN;
+const PRODUCTION_APP_HOST_ALIAS = `app.${CURRENT_CLOUD_DOMAIN}`;
+
+function trimToNull(value?: string | null): string | null {
+  return value?.trim() || null;
+}
+
+function normalizeBaseUrl(value?: string | null): string | null {
+  if (!value) return null;
+
+  const trimmed = value.trim().replace(/\/$/, "");
+  if (!trimmed) return null;
+
+  if (/^https?:\/\//i.test(trimmed)) {
+    return trimmed;
+  }
+
+  if (typeof window !== "undefined") {
+    return `${window.location.protocol}//${trimmed}`;
+  }
+
+  return `http://${trimmed}`;
+}
+
+function normalizeCloudHost(value?: string | null): string | null {
+  if (!value) return null;
+
+  const trimmed = value.trim().replace(/\/+$/, "");
+  if (!trimmed) return null;
+
+  if (/^https?:\/\//i.test(trimmed)) {
+    return trimmed;
+  }
+
+  return `https://${trimmed}`;
+}
+
+function canonicalizeCloudHostname(hostname: string): string {
+  const lower = hostname.toLowerCase();
+  if (
+    lower === LEGACY_PRODUCTION_APP_HOST ||
+    lower === PRODUCTION_APP_HOST_ALIAS
+  ) {
+    return CURRENT_PRODUCTION_APP_HOST;
+  }
+
+  if (lower === LEGACY_CLOUD_DOMAIN) return CURRENT_CLOUD_DOMAIN;
+  if (lower.endsWith(`.${LEGACY_CLOUD_DOMAIN}`)) {
+    return `${lower.slice(0, -LEGACY_CLOUD_DOMAIN.length)}${CURRENT_CLOUD_DOMAIN}`;
+  }
+
+  return lower;
+}
+
+function getCloudHostComparisonKey(value?: string | null): string | null {
+  const normalized = normalizeCloudHost(value);
+  if (!normalized) return null;
+
+  try {
+    const url = new URL(normalized);
+    const port = url.port ? `:${url.port}` : "";
+    return `${url.protocol}//${canonicalizeCloudHostname(url.hostname)}${port}`;
+  } catch {
+    return normalized.toLowerCase();
+  }
+}
+
+export function getCookieAuthCloudHost(): string | null {
+  const lockedHost = getLockedCloudHost();
+  if (
+    !lockedHost ||
+    typeof window === "undefined" ||
+    !isSameCloudHost(window.location.origin, lockedHost)
+  ) {
+    return null;
+  }
+
+  return window.location.origin;
+}
+
+function getConfiguredBaseUrl(): string | null {
+  return normalizeBaseUrl(import.meta.env.VITE_BACKEND_BASE_URL);
+}
+
+/**
+ * Return the session API key supplied by the deployment host.
+ *
+ * Two sources are consulted, in order:
+ *   1. `VITE_SESSION_API_KEY` — baked into the bundle at build time (used by
+ *      `npm run dev` so the dev server has the key without a round-trip).
+ *   2. `window.__AGENT_CANVAS_SESSION_API_KEY__` — injected into `index.html`
+ *      at serve time by `scripts/static-server.mjs --session-api-key <key>`.
+ *      This is the path used by the published `agent-canvas` binary, where
+ *      `VITE_SESSION_API_KEY` is empty in the prebuilt bundle and the
+ *      runtime key is generated when the user launches the CLI.
+ *
+ * Without the window-global fallback, the published binary cannot construct a
+ * default local backend (`makeDefaultLocalBackend()` returns null), the
+ * registry is left empty, and the user sees the Manage Backends modal
+ * instead of the onboarding flow.
+ */
+export function getBakedSessionApiKey(): string | null {
+  const envKey = trimToNull(import.meta.env.VITE_SESSION_API_KEY);
+  if (envKey) return envKey;
+
+  if (typeof window !== "undefined") {
+    const injected = (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_SESSION_API_KEY__;
+    if (typeof injected === "string") {
+      return trimToNull(injected);
+    }
+  }
+
+  return null;
+}
+
+export function getAgentServerFormDefaults(): AgentServerFormDefaults {
+  return {
+    baseUrl: getAgentServerBaseUrl() ?? "",
+    sessionApiKey: getAgentServerSessionApiKey() ?? "",
+  };
+}
+
+export function getLockedCloudHost(): string | null {
+  const envHost = normalizeCloudHost(import.meta.env.VITE_LOCK_TO_CLOUD);
+  if (envHost) return envHost;
+
+  if (typeof window !== "undefined") {
+    const injected = (window as unknown as Record<string, unknown>)[
+      LOCK_TO_CLOUD_WINDOW_KEY
+    ];
+    if (typeof injected === "string") {
+      return normalizeCloudHost(injected);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Compare a backend host against the locked Cloud host, normalizing
+ * trailing slashes, protocol, and case so that e.g.
+ * `https://app.all-hands.dev/` matches `https://app.all-hands.dev`.
+ *
+ * Used by the locked-to-Cloud gates (`root.tsx`,
+ * `onboarding-modal.tsx`) to decide whether the active backend is the
+ * configured locked Cloud host — a Cloud backend on a *different* host
+ * (or a stale Local backend) must not be treated as the locked backend.
+ */
+export function isSameCloudHost(
+  host: string | null | undefined,
+  lockedHost: string | null | undefined,
+): boolean {
+  const a = getCloudHostComparisonKey(host);
+  const b = getCloudHostComparisonKey(lockedHost);
+  if (!a || !b) return false;
+  return a === b;
+}
+
+export function getLockedCloudAuthMode(): LockedCloudAuthMode {
+  return getCookieAuthCloudHost() ? "cookie" : "api-key";
+}
+
+export function getAgentServerBaseUrl(): string | null {
+  const configuredUrl = getConfiguredBaseUrl();
+  if (configuredUrl) return configuredUrl;
+
+  if (typeof window !== "undefined") {
+    return window.location.origin;
+  }
+
+  return null;
+}
+
+export function getAgentServerSessionApiKey(): string | null {
+  return getBakedSessionApiKey();
+}
+
+export function getAgentServerWorkingDir(): string {
+  const envDir = import.meta.env.VITE_WORKING_DIR?.trim();
+  if (envDir) return envDir;
+
+  return DEFAULT_WORKING_DIR;
+}
+
+function buildWorkingDir(base: string, conversationId: string): string {
+  const trimmed = base.replace(/\/+$/, "");
+  const hex = conversationId.replace(/-/g, "");
+  return `${trimmed}/${hex}`;
+}
+
+export function buildConversationWorkingDir(conversationId: string): string {
+  return buildWorkingDir(getAgentServerWorkingDir(), conversationId);
+}
+
+/**
+ * Conversation working dir under the backend-relative default
+ * (`workspace/project/<hex>`), deliberately ignoring any baked absolute
+ * `VITE_WORKING_DIR`. `resolveAbsoluteAgentServerPath()` anchors this to the
+ * active backend's own home via `GET /api/file/home`, so it resolves to a
+ * writable path on whichever backend actually runs the conversation.
+ */
+export function buildRelativeConversationWorkingDir(
+  conversationId: string,
+): string {
+  return buildWorkingDir(DEFAULT_WORKING_DIR, conversationId);
+}
+
+/**
+ * Whether `backendHost` is the same host that served this frontend.
+ *
+ * A launcher-baked `VITE_WORKING_DIR` is an absolute path on the serving
+ * host's filesystem, so it is only valid on that exact backend. The seeded
+ * `default-local` entry starts life pointing at the served origin, but its
+ * `host` is mutable — the user can edit it to a remote backend while its id
+ * stays `default-local`. Matching on the host (not the stable id) keeps the
+ * real invariant: the baked path is only safe for the host it was baked for.
+ */
+export function isServedOriginHost(
+  backendHost: string | null | undefined,
+): boolean {
+  const served = normalizeBaseUrl(getAgentServerBaseUrl());
+  const candidate = normalizeBaseUrl(backendHost);
+  if (!served || !candidate) return false;
+  return served === candidate;
+}
+
+/**
+ * Base working dir for a new conversation on the backend at `backendHost`.
+ * The baked (possibly absolute) default is used only for the served-origin
+ * backend; every other backend gets the relative default, anchored to its
+ * own home by `resolveAbsoluteAgentServerPath()`.
+ */
+export function buildConversationWorkingDirForBackend(
+  conversationId: string,
+  backendHost: string | null | undefined,
+): string {
+  return isServedOriginHost(backendHost)
+    ? buildConversationWorkingDir(conversationId)
+    : buildRelativeConversationWorkingDir(conversationId);
+}
+
+/**
+ * Workspace root for `backendHost` — the dir each conversation's `<root>/<hex>`
+ * working dir is created under. Same per-backend rule as
+ * `buildConversationWorkingDirForBackend()`.
+ */
+export function getWorkspaceRootForBackend(
+  backendHost: string | null | undefined,
+): string {
+  return isServedOriginHost(backendHost)
+    ? getAgentServerWorkingDir()
+    : DEFAULT_WORKING_DIR;
+}
+
+export function getAgentServerHeaders(): Record<string, string> {
+  const sessionApiKey = getAgentServerSessionApiKey();
+  return sessionApiKey ? { "X-Session-API-Key": sessionApiKey } : {};
+}
+
+export function isAuthRequired(): boolean {
+  return (
+    import.meta.env.VITE_AUTH_REQUIRED === "true" ||
+    (typeof window !== "undefined" &&
+      (window as unknown as Record<string, unknown>)
+        .__AGENT_CANVAS_AUTH_REQUIRED__ === true)
+  );
+}
+
+export function isAuthRequiredAndMissing(): boolean {
+  if (!isAuthRequired()) return false;
+  return !getAgentServerSessionApiKey();
+}

src/api/agent-server-home.ts

@@ -0,0 +1,114 @@
+// @spec WUP-001 — Resolve relative working dirs against /api/file/home
+import { FileClient } from "@openhands/typescript-client/clients";
+import {
+  getAgentServerClientOptions,
+  type AgentServerClientOverrides,
+} from "./agent-server-client-options";
+
+/**
+ * Cache the agent-server's home directory per host so we only round-trip
+ * `/api/file/home` once per backend. The home dir is effectively static for
+ * the lifetime of a running agent-server (it's `Path.home()` on the host),
+ * so caching is safe and avoids hammering the endpoint on every upload.
+ *
+ * The cache holds `Promise<string>` rather than `string` so concurrent
+ * callers share a single in-flight request.
+ */
+const homeDirCache = new Map<string, Promise<string>>();
+
+function isAbsolutePath(path: string): boolean {
+  // Treat POSIX-style and Windows-style absolute paths as absolute.
+  // The agent-server itself is POSIX on Linux/macOS and uses `\\` style
+  // on Windows; we just need to know whether `Path(path).is_absolute()`
+  // would return true on the server.
+  //
+  // Patterns covered:
+  //   POSIX absolute:      /foo/bar
+  //   Windows drive:       C:\foo  or  C:/foo
+  //   Windows UNC:         \\server\share  (starts with `\`, matches `[/\\]`)
+  return /^([/\\]|[a-zA-Z]:[/\\])/.test(path);
+}
+
+/**
+ * Join a parent directory and a relative child segment with a forward slash,
+ * collapsing any duplicate separators that result from the join.
+ */
+function joinPath(parent: string, child: string): string {
+  const left = parent.replace(/[/\\]+$/, "");
+  const right = child.replace(/^[/\\]+/, "");
+  return `${left}/${right}`;
+}
+
+/**
+ * Fetch and cache the agent-server's home directory via `GET /api/file/home`.
+ *
+ * The result is the absolute path returned by `Path.home()` on the
+ * agent-server host (e.g. `/Users/foo`, `/root`, or `C:\\Users\\Foo`). This
+ * is the most reliable absolute, writable anchor the agent-server API
+ * currently exposes — `/server_info` doesn't include the process CWD.
+ *
+ * @param overrides Same shape as `getAgentServerClientOptions` — lets cloud
+ *   sandboxes pass a `conversationUrl` + `sessionApiKey` so the lookup goes
+ *   to the per-conversation runtime rather than the bundled local backend.
+ */
+export async function getAgentServerHomeDir(
+  overrides: AgentServerClientOverrides = {},
+): Promise<string> {
+  const options = getAgentServerClientOptions(overrides);
+  const cacheKey = options.host;
+  const cached = homeDirCache.get(cacheKey);
+  if (cached) return cached;
+
+  const lookup = (async () => {
+    const { home } = await new FileClient(options).getHome();
+    if (!home || typeof home !== "string") {
+      throw new Error("Agent server returned an empty home directory");
+    }
+    return home.replace(/[/\\]+$/, "");
+  })();
+
+  homeDirCache.set(cacheKey, lookup);
+  try {
+    return await lookup;
+  } catch (error) {
+    // Don't cache failures — let the next call retry.
+    homeDirCache.delete(cacheKey);
+    throw error;
+  }
+}
+
+/** Test-only helper. */
+export function clearAgentServerHomeDirCache(): void {
+  homeDirCache.clear();
+}
+
+/**
+ * Resolve a (possibly relative) working dir to an absolute path the
+ * agent-server's file APIs will accept.
+ *
+ * - If `workingDir` is already absolute, returns it unchanged.
+ * - Otherwise prepends the agent-server's home dir (looked up via
+ *   `/api/file/home` and cached). This matches how the published binary
+ *   and Docker entrypoint expect to anchor relative working dirs: under
+ *   `~/workspace/project` rather than the filesystem root.
+ *
+ * Why this matters: the agent-server's `/api/file/upload` endpoint requires
+ * an absolute path and `mkdir -p`s the parent. Naively prepending `/` to a
+ * relative dir like `workspace/project/<hex>` produces `/workspace/...`,
+ * which on macOS lives under the SIP-protected read-only root and fails
+ * with `Errno 30: Read-only file system: '/workspace'`. Resolving against
+ * `Path.home()` instead puts the path somewhere reliably writable.
+ */
+export async function resolveAbsoluteAgentServerPath(
+  workingDir: string,
+  overrides: AgentServerClientOverrides = {},
+): Promise<string> {
+  const trimmed = workingDir.replace(/[/\\]+$/, "");
+  if (!trimmed) {
+    return getAgentServerHomeDir(overrides);
+  }
+  if (isAbsolutePath(trimmed)) return trimmed;
+
+  const home = await getAgentServerHomeDir(overrides);
+  return joinPath(home, trimmed);
+}

src/api/canvas-extensions-service.test.ts

@@ -0,0 +1,208 @@
+import { AgentServerClient } from "@openhands/typescript-client/clients";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import CanvasExtensionsService, {
+  CanvasExtensionsUnsupportedError,
+} from "#/api/canvas-extensions-service";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import type { InstalledCanvasExtensionInfo } from "#/types/canvas-extension";
+
+vi.mock("@openhands/typescript-client/clients", () => ({
+  AgentServerClient: vi.fn(),
+}));
+
+const get = vi.fn();
+const post = vi.fn();
+const patch = vi.fn();
+const remove = vi.fn();
+const request = vi.fn();
+
+const localBackend: Backend = {
+  id: "local",
+  name: "Local",
+  host: "http://127.0.0.1:8000",
+  apiKey: "session-key",
+  kind: "local",
+};
+
+const extension: InstalledCanvasExtensionInfo = {
+  name: "demo-extension",
+  version: "0.1.0",
+  description: "Demo",
+  enabled: false,
+  source: "github:example/extensions",
+  resolved_ref: "abc123",
+  repo_path: "extensions/demo",
+  installed_at: "2026-08-01T00:00:00Z",
+  install_path: "/tmp/extensions/demo-extension",
+  manifest: {
+    schema_version: 1,
+    name: "demo-extension",
+    version: "0.1.0",
+    entrypoint: "dist/extension.js",
+    contributes: {
+      pages: [{ id: "home", title: "Home", path: "home" }],
+    },
+  },
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  __resetActiveStoreForTests();
+  setRegisteredBackends([localBackend]);
+  setActiveSelection({ backendId: localBackend.id });
+  vi.mocked(AgentServerClient).mockImplementation(
+    function MockAgentServerClient() {
+      return {
+        get,
+        post,
+        patch,
+        delete: remove,
+        request,
+        close: vi.fn(),
+      } as unknown as AgentServerClient;
+    } as unknown as typeof AgentServerClient,
+  );
+});
+
+afterEach(() => {
+  setActiveSelection(null);
+  setRegisteredBackends([]);
+  __resetActiveStoreForTests();
+});
+
+describe("CanvasExtensionsService", () => {
+  it("lists extensions installed on the active Agent Server", async () => {
+    get.mockResolvedValue({ canvas_extensions: [extension] });
+
+    await expect(CanvasExtensionsService.listInstalled()).resolves.toEqual([
+      extension,
+    ]);
+    expect(get).toHaveBeenCalledWith("/api/canvas-extensions/installed");
+  });
+
+  it("preserves install coordinates without allowing an enabled flag", async () => {
+    post.mockResolvedValue(extension);
+
+    await CanvasExtensionsService.install({
+      source: "github:example/extensions",
+      ref: "main",
+      repo_path: "extensions/demo",
+    });
+
+    expect(post).toHaveBeenCalledWith("/api/canvas-extensions/install", {
+      source: "github:example/extensions",
+      ref: "main",
+      repo_path: "extensions/demo",
+    });
+  });
+
+  it.each([
+    {
+      source: "/repository-name/",
+      repoPath: "/demo-extension",
+      expectedSource: "/repository-name/demo-extension",
+    },
+    {
+      source: "/repository-name",
+      repoPath: "demo-extension",
+      expectedSource: "/repository-name/demo-extension",
+    },
+    {
+      source: "/repository-name/demo-extension",
+      repoPath: null,
+      expectedSource: "/repository-name/demo-extension",
+    },
+  ])(
+    "resolves a local extension from source $source and path $repoPath",
+    async ({ source, repoPath, expectedSource }) => {
+      post.mockResolvedValue(extension);
+
+      await CanvasExtensionsService.install({
+        source,
+        ref: null,
+        repo_path: repoPath,
+      });
+
+      expect(post).toHaveBeenCalledWith("/api/canvas-extensions/install", {
+        source: expectedSource,
+        ref: null,
+        repo_path: null,
+      });
+    },
+  );
+
+  it("maps a missing router to an explicit unsupported-backend error", async () => {
+    get.mockRejectedValue(
+      Object.assign(new Error("Not Found"), {
+        name: "HttpError",
+        status: 404,
+      }),
+    );
+
+    await expect(CanvasExtensionsService.listInstalled()).rejects.toEqual(
+      expect.objectContaining<Partial<CanvasExtensionsUnsupportedError>>({
+        name: "CanvasExtensionsUnsupportedError",
+        reason: "missing-api",
+      }),
+    );
+  });
+
+  it("does not call the Agent Server protocol for a Cloud backend", async () => {
+    const cloud: Backend = {
+      ...localBackend,
+      id: "cloud",
+      name: "Cloud",
+      kind: "cloud",
+    };
+    setRegisteredBackends([cloud]);
+    setActiveSelection({ backendId: cloud.id });
+
+    await expect(CanvasExtensionsService.listInstalled()).rejects.toEqual(
+      expect.objectContaining({ reason: "cloud-backend" }),
+    );
+    expect(AgentServerClient).not.toHaveBeenCalled();
+  });
+
+  it("fetches the bundle as authenticated text from the captured backend", async () => {
+    get.mockResolvedValue("export const activate = () => {};");
+
+    await expect(
+      CanvasExtensionsService.fetchBundle(extension.name, localBackend),
+    ).resolves.toContain("activate");
+
+    expect(AgentServerClient).toHaveBeenCalledWith({
+      host: localBackend.host,
+      apiKey: localBackend.apiKey,
+      timeout: 60000,
+    });
+    expect(get).toHaveBeenCalledWith(
+      "/api/canvas-extensions/installed/demo-extension/bundle",
+      { responseType: "text" },
+    );
+  });
+
+  it("encodes extension names in mutation paths", async () => {
+    patch.mockResolvedValue({ name: "a/b", enabled: true });
+
+    await CanvasExtensionsService.setEnabled("a/b", true);
+
+    expect(patch).toHaveBeenCalledWith(
+      "/api/canvas-extensions/installed/a%2Fb",
+      { enabled: true },
+    );
+  });
+
+  it("does not send the backend session key to an absolute request URL", async () => {
+    await expect(
+      CanvasExtensionsService.requestAgentServer({
+        path: "https://example.com/collect",
+      }),
+    ).rejects.toThrow("root-relative path");
+    expect(AgentServerClient).not.toHaveBeenCalled();
+  });
+});

src/api/canvas-extensions-service.ts

@@ -0,0 +1,192 @@
+import { AgentServerClient } from "@openhands/typescript-client/clients";
+import { getAgentServerClientOptions } from "#/api/agent-server-client-options";
+import { isSdkHttpStatusError } from "#/api/agent-server-compatibility";
+import {
+  getActiveBackend,
+  isNoBackend,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import type {
+  CanvasExtensionAgentServerRequest,
+  InstallCanvasExtensionRequest,
+  InstalledCanvasExtensionInfo,
+} from "#/types/canvas-extension";
+
+const CANVAS_EXTENSIONS_BASE_PATH = "/api/canvas-extensions";
+const REMOTE_EXTENSION_SOURCE_PATTERN =
+  /^(?:github:|https?:\/\/|git:\/\/|file:\/\/|[\w.-]+@[\w.-]+:)/i;
+
+export type CanvasExtensionsUnsupportedReason =
+  | "no-backend"
+  | "cloud-backend"
+  | "missing-api";
+
+export class CanvasExtensionsUnsupportedError extends Error {
+  readonly reason: CanvasExtensionsUnsupportedReason;
+
+  constructor(reason: CanvasExtensionsUnsupportedReason) {
+    const message =
+      reason === "no-backend"
+        ? "Add an Agent Server backend to use Apps."
+        : reason === "cloud-backend"
+          ? "Apps are not available on Cloud backends yet."
+          : "This Agent Server does not support Apps yet. Upgrade the backend and try again.";
+    super(message);
+    this.name = "CanvasExtensionsUnsupportedError";
+    this.reason = reason;
+  }
+}
+
+export function isCanvasExtensionsUnsupportedError(
+  error: unknown,
+): error is CanvasExtensionsUnsupportedError {
+  return (
+    error instanceof CanvasExtensionsUnsupportedError ||
+    (typeof error === "object" &&
+      error !== null &&
+      "name" in error &&
+      error.name === "CanvasExtensionsUnsupportedError")
+  );
+}
+
+function requireSupportedBackend(): void {
+  const { backend } = getActiveBackend();
+  if (isNoBackend(backend)) {
+    throw new CanvasExtensionsUnsupportedError("no-backend");
+  }
+  if (backend.kind === "cloud") {
+    throw new CanvasExtensionsUnsupportedError("cloud-backend");
+  }
+}
+
+function getClient(): AgentServerClient {
+  requireSupportedBackend();
+  return new AgentServerClient(getAgentServerClientOptions());
+}
+
+function getClientForBackend(backend: Backend): AgentServerClient {
+  if (isNoBackend(backend)) {
+    throw new CanvasExtensionsUnsupportedError("no-backend");
+  }
+  if (backend.kind === "cloud") {
+    throw new CanvasExtensionsUnsupportedError("cloud-backend");
+  }
+  return new AgentServerClient({
+    host: backend.host,
+    ...(backend.apiKey ? { apiKey: backend.apiKey } : {}),
+    timeout: 60000,
+  });
+}
+
+async function mapUnsupported<T>(operation: () => Promise<T>): Promise<T> {
+  try {
+    return await operation();
+  } catch (error) {
+    if (isSdkHttpStatusError(error, 404)) {
+      throw new CanvasExtensionsUnsupportedError("missing-api");
+    }
+    throw error;
+  }
+}
+
+function installedExtensionPath(name: string): string {
+  return `${CANVAS_EXTENSIONS_BASE_PATH}/installed/${encodeURIComponent(name)}`;
+}
+
+function joinLocalExtensionPath(source: string, repoPath: string): string {
+  const separator = source.includes("\\") && !source.includes("/") ? "\\" : "/";
+  const basePath = source.replace(/[\\/]+$/, "");
+  const childPath = repoPath.replace(/^[\\/]+/, "");
+
+  if (!childPath) return source;
+  if (!basePath) return `${separator}${childPath}`;
+  return `${basePath}${separator}${childPath}`;
+}
+
+function normalizeInstallRequest(
+  request: InstallCanvasExtensionRequest,
+): InstallCanvasExtensionRequest {
+  const repoPath = request.repo_path?.trim();
+  if (!repoPath || REMOTE_EXTENSION_SOURCE_PATTERN.test(request.source)) {
+    return request;
+  }
+
+  return {
+    ...request,
+    source: joinLocalExtensionPath(request.source, repoPath),
+    repo_path: null,
+  };
+}
+
+class CanvasExtensionsService {
+  static async listInstalled(): Promise<InstalledCanvasExtensionInfo[]> {
+    const client = getClient();
+    const response = await mapUnsupported(() =>
+      client.get<{ canvas_extensions: InstalledCanvasExtensionInfo[] }>(
+        `${CANVAS_EXTENSIONS_BASE_PATH}/installed`,
+      ),
+    );
+    return response.canvas_extensions ?? [];
+  }
+
+  static async install(
+    request: InstallCanvasExtensionRequest,
+  ): Promise<InstalledCanvasExtensionInfo> {
+    const client = getClient();
+    return mapUnsupported(() =>
+      client.post<InstalledCanvasExtensionInfo>(
+        `${CANVAS_EXTENSIONS_BASE_PATH}/install`,
+        normalizeInstallRequest(request),
+      ),
+    );
+  }
+
+  static async setEnabled(
+    name: string,
+    enabled: boolean,
+  ): Promise<{ name: string; enabled: boolean }> {
+    const client = getClient();
+    return mapUnsupported(() =>
+      client.patch<{ name: string; enabled: boolean }>(
+        installedExtensionPath(name),
+        { enabled },
+      ),
+    );
+  }
+
+  static async uninstall(name: string): Promise<{ message: string }> {
+    const client = getClient();
+    return mapUnsupported(() =>
+      client.delete<{ message: string }>(installedExtensionPath(name)),
+    );
+  }
+
+  static async fetchBundle(name: string, backend?: Backend): Promise<string> {
+    const client = backend ? getClientForBackend(backend) : getClient();
+    return mapUnsupported(() =>
+      client.get<string>(`${installedExtensionPath(name)}/bundle`, {
+        responseType: "text",
+      }),
+    );
+  }
+
+  static async requestAgentServer<T = unknown>(
+    request: CanvasExtensionAgentServerRequest,
+    backend?: Backend,
+  ): Promise<T> {
+    if (!request.path.startsWith("/") || request.path.startsWith("//")) {
+      throw new Error(
+        "Canvas Extension Agent Server requests must use a root-relative path.",
+      );
+    }
+    const client = backend ? getClientForBackend(backend) : getClient();
+    return client.request<T>({
+      method: request.method ?? "GET",
+      path: request.path,
+      body: request.body,
+      headers: request.headers,
+    });
+  }
+}
+
+export default CanvasExtensionsService;

src/api/canvas-ui-client-tool.ts

@@ -0,0 +1,91 @@
+import { CANVAS_UI_CLIENT_TOOL_NAME } from "#/constants/canvas-ui";
+
+export {
+  CANVAS_UI_CLIENT_ACTION_KIND,
+  CANVAS_UI_CLIENT_TOOL_NAME,
+  LEGACY_CANVAS_UI_TOOL_NAME,
+} from "#/constants/canvas-ui";
+
+export interface ClientToolSpec {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+  annotations?: {
+    title?: string | null;
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+  };
+}
+
+const CANVAS_UI_DESCRIPTION = `The user is interacting with you inside Agent Canvas — a web UI with a chat panel on the left and a tabbed right-side panel (files, terminal, browser, vscode, planner, tasklist). This tool lets you drive that right-side panel so the user sees what you just produced.
+
+They will NOT see the files you wrote, the terminal output, or the browser
+unless you call this tool to switch the right-side panel to the relevant
+tab. Call this every time you finish work that produces something the user
+should look at — don't rely on them noticing on their own.
+
+When to call (pick the most specific option that matches your last action):
+
+* You wrote or modified a single file (ANY language, ANY size — including
+  small scripts like a hello-world bash file) →
+    command="navigate_to_file", path=<workspace-relative path of that file>
+
+* You generated an HTML page, image, SVG, PDF, markdown report, or other
+  previewable artifact →
+    command="show_preview", path=<that file>
+
+* You finished editing multiple files in one logical step →
+    command="open_tab", tab="files"
+    (The Files tab automatically renders a diff view when the workspace has
+    uncommitted git changes, which covers the "highlight changes" case.)
+
+* You ran a long-running terminal command, or one whose output the user
+  should inspect →
+    command="open_tab", tab="terminal"
+
+* You browsed to a URL the user should see →
+    First call browser_get_state(include_screenshot=true) after your final
+    browser interaction so Agent Canvas has a screenshot to display, then call
+    command="open_tab", tab="browser"
+    (browser_navigate alone only updates the URL; without browser_get_state,
+    the Browser tab will open without a screenshot.)
+
+Call this BEFORE writing your chat-message summary of the change, so the
+artifact is visible while the user reads what you did. One canvas_ui_control
+call per logical step is enough — don't repeat it for the same file or tab in
+the same turn.`;
+
+export const CANVAS_UI_CLIENT_TOOL: ClientToolSpec = {
+  name: CANVAS_UI_CLIENT_TOOL_NAME,
+  description: CANVAS_UI_DESCRIPTION,
+  parameters: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      command: {
+        type: "string",
+        enum: ["navigate_to_file", "open_tab", "show_preview"],
+        description: "UI command to dispatch.",
+      },
+      path: {
+        type: "string",
+        description:
+          "Workspace-relative file path. Required for navigate_to_file and show_preview; ignored otherwise.",
+      },
+      tab: {
+        type: "string",
+        enum: ["files", "browser", "vscode", "terminal", "planner", "tasklist"],
+        description: "Tab to open. Required for open_tab; ignored otherwise.",
+      },
+    },
+    required: ["command"],
+  },
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+};

src/api/client-source.ts

@@ -0,0 +1,20 @@
+import packageJson from "../../package.json";
+
+export const AGENT_CANVAS_CLIENT_SOURCE = "agent_canvas";
+export const AGENT_CANVAS_CLIENT_VERSION = packageJson.version;
+
+/**
+ * Coarse, non-user-identifying request metadata for Cloud observability.
+ *
+ * Cloud ingress can retain these headers as facets without logging request
+ * bodies, API keys, device codes, or conversation content.
+ */
+export const OPENHANDS_CLIENT_HEADER = "X-OpenHands-Client";
+export const OPENHANDS_CLIENT_VERSION_HEADER = "X-OpenHands-Client-Version";
+export const OPENHANDS_TELEMETRY_DISTINCT_ID_HEADER =
+  "X-OpenHands-Telemetry-Distinct-Id";
+
+export const AGENT_CANVAS_CLIENT_HEADERS: Readonly<Record<string, string>> = {
+  [OPENHANDS_CLIENT_HEADER]: AGENT_CANVAS_CLIENT_SOURCE,
+  [OPENHANDS_CLIENT_VERSION_HEADER]: AGENT_CANVAS_CLIENT_VERSION,
+};

src/api/conversation-file-upload.api.ts

@@ -0,0 +1,172 @@
+import { RemoteWorkspace } from "@openhands/typescript-client/workspace/remote-workspace";
+import { getAgentServerClientOptions } from "#/api/agent-server-client-options";
+import { getActiveBackend } from "#/api/backend-registry/active-store";
+import { batchGetCloudConversations } from "#/api/cloud/conversation-service.api";
+import type { AppConversation } from "#/api/conversation-service/agent-server-conversation-service.types";
+import type { FileUploadSuccessResponse } from "#/api/open-hands.types";
+import {
+  buildWorkspaceUploadPath,
+  getSafeUploadFileName,
+  resolveConversationUploadWorkingDir,
+} from "#/api/workspace-upload-path";
+
+const FILE_UPLOAD_CONCURRENCY = 5;
+
+export interface ConversationRuntimeContext {
+  conversationUrl: string | null;
+  sessionApiKey: string | null;
+}
+
+/**
+ * Resolve the sandbox runtime URL + session key needed for file upload and
+ * send-event calls. Cloud conversations only exist on the provisioned runtime,
+ * not on the bundled local agent-server.
+ */
+export async function resolveConversationRuntime(
+  conversationId: string,
+  currentConversation?: AppConversation | null,
+): Promise<ConversationRuntimeContext> {
+  if (
+    currentConversation?.id === conversationId &&
+    currentConversation.conversation_url?.trim() &&
+    currentConversation.session_api_key?.trim()
+  ) {
+    return {
+      conversationUrl: currentConversation.conversation_url.trim(),
+      sessionApiKey: currentConversation.session_api_key.trim(),
+    };
+  }
+
+  if (getActiveBackend().backend.kind === "cloud") {
+    const [conversation] = await batchGetCloudConversations([conversationId]);
+    return {
+      conversationUrl: conversation?.conversation_url?.trim() ?? null,
+      sessionApiKey: conversation?.session_api_key?.trim() ?? null,
+    };
+  }
+
+  return { conversationUrl: null, sessionApiKey: null };
+}
+
+function requireCloudRuntime(
+  runtime: ConversationRuntimeContext,
+): ConversationRuntimeContext & {
+  conversationUrl: string;
+  sessionApiKey: string;
+} {
+  if (!runtime.conversationUrl || !runtime.sessionApiKey) {
+    throw new Error(
+      "Conversation sandbox is still starting. Wait for it to finish, then try again.",
+    );
+  }
+  return {
+    conversationUrl: runtime.conversationUrl,
+    sessionApiKey: runtime.sessionApiKey,
+  };
+}
+
+/**
+ * Upload attachments into the conversation workspace. Local conversations use
+ * the bundled agent-server; cloud conversations target the provisioned runtime.
+ */
+export async function uploadFilesToConversation(
+  conversationId: string,
+  files: File[],
+  currentConversation?: AppConversation | null,
+): Promise<FileUploadSuccessResponse> {
+  const workingDir = await resolveConversationUploadWorkingDir(
+    conversationId,
+    currentConversation,
+  );
+  const runtime = await resolveConversationRuntime(
+    conversationId,
+    currentConversation,
+  );
+  const isCloud = getActiveBackend().backend.kind === "cloud";
+
+  const sessionApiKey =
+    currentConversation?.id === conversationId
+      ? (currentConversation.session_api_key ?? runtime.sessionApiKey)
+      : runtime.sessionApiKey;
+  const conversationUrl =
+    currentConversation?.id === conversationId
+      ? (currentConversation.conversation_url ?? runtime.conversationUrl)
+      : runtime.conversationUrl;
+
+  if (isCloud) {
+    const cloudRuntime = requireCloudRuntime({
+      conversationUrl,
+      sessionApiKey,
+    });
+    return uploadFilesToRuntime({
+      files,
+      workingDir,
+      conversationUrl: cloudRuntime.conversationUrl,
+      sessionApiKey: cloudRuntime.sessionApiKey,
+    });
+  }
+
+  return uploadFilesToRuntime({
+    files,
+    workingDir,
+    conversationUrl,
+    sessionApiKey,
+  });
+}
+
+async function uploadFilesToRuntime(options: {
+  files: File[];
+  workingDir: string;
+  conversationUrl: string | null;
+  sessionApiKey: string | null;
+}): Promise<FileUploadSuccessResponse> {
+  const { files, workingDir, conversationUrl, sessionApiKey } = options;
+  const workspace = new RemoteWorkspace(
+    getAgentServerClientOptions({
+      conversationUrl,
+      sessionApiKey,
+      workingDir,
+    }),
+  );
+
+  const uploadFile = async (file: File) => {
+    try {
+      const safeName = getSafeUploadFileName(file.name);
+      // @spec WUP-001 — Build an absolute upload path that's anchored against
+      // the agent-server's home dir (when `workingDir` is relative) instead
+      // of the filesystem root. Without this, default conversations whose
+      // working_dir is `workspace/project/<hex>` (relative) land at
+      // `/workspace/project/<hex>/...` on the agent-server, which on macOS
+      // and fresh containers is a read-only mount.
+      const uploadPath = await buildWorkspaceUploadPath(file.name, workingDir, {
+        conversationUrl,
+        sessionApiKey,
+      });
+      await workspace.fileUpload(file, uploadPath);
+      return { uploadedFile: safeName, skippedFile: null };
+    } catch (error) {
+      return {
+        uploadedFile: null,
+        skippedFile: {
+          name: file.name,
+          reason: error instanceof Error ? error.message : "Upload failed",
+        },
+      };
+    }
+  };
+
+  const results: Awaited<ReturnType<typeof uploadFile>>[] = [];
+  for (let index = 0; index < files.length; index += FILE_UPLOAD_CONCURRENCY) {
+    const batch = files.slice(index, index + FILE_UPLOAD_CONCURRENCY);
+    results.push(...(await Promise.all(batch.map(uploadFile))));
+  }
+
+  return {
+    uploaded_files: results.flatMap((result) =>
+      result.uploadedFile ? [result.uploadedFile] : [],
+    ),
+    skipped_files: results.flatMap((result) =>
+      result.skippedFile ? [result.skippedFile] : [],
+    ),
+  };
+}

src/api/conversation-metadata-store.ts

@@ -0,0 +1,128 @@
+import { Provider } from "#/types/settings";
+import type { PluginSpec } from "#/api/conversation-service/agent-server-conversation-service.types";
+
+const STORAGE_KEY = "openhands-agent-server-conversation-metadata";
+
+export type WorkspaceMode = "local_repo" | "new_worktree";
+
+export interface ConversationMetadata {
+  selected_repository: string | null;
+  selected_branch: string | null;
+  git_provider: Provider | null;
+  /**
+   * The local workspace path the user explicitly attached at conversation
+   * creation time. Distinct from `selected_repository` (which is set by
+   * the repo picker on the home page). Used by the Files tab to decide
+   * whether to default to diff view: if the user attached *anything*
+   * (repo or local workspace), we lean diff-first because there's a real
+   * git baseline to compare against.
+   */
+  selected_workspace?: string | null;
+  /**
+   * How the conversation should use `selected_workspace`.
+   *
+   * `local_repo` means the runtime should operate directly in the selected
+   * folder, even when it is not a git checkout. `new_worktree` preserves the
+   * historical agent-server behavior for conversations that should start in a
+   * generated per-conversation worktree.
+   */
+  workspace_mode?: WorkspaceMode | null;
+  /**
+   * The LLM profile the conversation was created with (or last switched to).
+   * Client-side only. Lets the chat-header switcher show the exact profile
+   * name even when several profiles share the same underlying model — the
+   * agent-server only round-trips the model string, so matching on it alone
+   * is ambiguous (issue #1082).
+   */
+  active_profile?: string | null;
+  /**
+   * When `active_profile` was stamped (ISO string). Written by the live
+   * WebSocket handler (the observation's server timestamp) and the user
+   * `/model` mutation (client clock). The history seed compares the latest
+   * SwitchLLM observation's timestamp against this so a reload can repair a
+   * missed agent switch without rolling back a newer manual switch — manual
+   * `/model` switches go through REST and leave no observation in history.
+   * Absent on stamps written before this field existed; treated as older
+   * than any observation so the seed can still repair them.
+   */
+  stamped_at?: string | null;
+  /** Store plugin coordinates only; parameters may contain secrets. */
+  plugins?: PluginSpec[] | null;
+  /**
+   * Local-only client-managed planning conversation id. Cloud backends expose
+   * real sub-conversations through `sub_conversation_ids`; local agent-server
+   * backends do not, so Canvas stores the relationship here.
+   */
+  local_planning_conversation_id?: string | null;
+}
+
+export const toPluginCoordinates = (plugin: PluginSpec): PluginSpec => ({
+  source: plugin.source,
+  ref: plugin.ref ?? null,
+  repo_path: plugin.repo_path ?? null,
+});
+
+type StoredMetadata = Record<string, ConversationMetadata>;
+
+const readAll = (): StoredMetadata => {
+  if (typeof window === "undefined") return {};
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    if (!raw) return {};
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== "object") return {};
+    return parsed as StoredMetadata;
+  } catch {
+    return {};
+  }
+};
+
+const writeAll = (next: StoredMetadata): void => {
+  if (typeof window === "undefined") return;
+  if (Object.keys(next).length === 0) {
+    window.localStorage.removeItem(STORAGE_KEY);
+    return;
+  }
+  window.localStorage.setItem(STORAGE_KEY, JSON.stringify(next));
+};
+
+export const getStoredConversationMetadata = (
+  conversationId: string,
+): ConversationMetadata | null => readAll()[conversationId] ?? null;
+
+export const setStoredConversationMetadata = (
+  conversationId: string,
+  metadata: ConversationMetadata,
+): void => {
+  const all = readAll();
+  all[conversationId] = metadata;
+  writeAll(all);
+};
+
+/**
+ * Merge `patch` into a conversation's stored metadata, preserving every
+ * existing field — `setStoredConversationMetadata` does a full-object
+ * replace, which would otherwise silently drop fields the caller doesn't
+ * enumerate (e.g. `plugins`).
+ */
+export const mergeStoredConversationMetadata = (
+  conversationId: string,
+  patch: Partial<ConversationMetadata>,
+): void => {
+  setStoredConversationMetadata(conversationId, {
+    selected_repository: null,
+    selected_branch: null,
+    git_provider: null,
+    ...(getStoredConversationMetadata(conversationId) ?? {}),
+    ...patch,
+  });
+};
+
+export const removeStoredConversationMetadata = (
+  conversationId: string,
+): void => {
+  const all = readAll();
+  if (!(conversationId in all)) return;
+  delete all[conversationId];
+  writeAll(all);
+};

src/api/device-flow-client.ts

@@ -0,0 +1,38 @@
+import {
+  pollForToken as sdkPollForToken,
+  startDeviceFlow as sdkStartDeviceFlow,
+} from "@openhands/typescript-client/client/device-flow-client";
+import type {
+  DeviceAuthorizationResponse,
+  DeviceTokenResponse,
+  PollDeviceTokenOptions,
+} from "@openhands/typescript-client/client/device-flow-client";
+import { AGENT_CANVAS_CLIENT_HEADERS } from "./client-source";
+
+export {
+  DeviceFlowError,
+  isOpenHandsCloudHost,
+} from "@openhands/typescript-client/client/device-flow-client";
+
+export function startDeviceFlow(
+  host: string,
+): Promise<DeviceAuthorizationResponse> {
+  return sdkStartDeviceFlow(host, { headers: AGENT_CANVAS_CLIENT_HEADERS });
+}
+
+export function pollForToken(
+  host: string,
+  deviceCode: string,
+  options: PollDeviceTokenOptions,
+): Promise<DeviceTokenResponse> {
+  return sdkPollForToken(host, deviceCode, {
+    ...options,
+    headers: AGENT_CANVAS_CLIENT_HEADERS,
+  });
+}
+
+export type {
+  DeviceAuthorizationResponse,
+  DeviceTokenResponse,
+  PollDeviceTokenOptions as PollOptions,
+} from "@openhands/typescript-client/client/device-flow-client";

src/api/git-provider-items-service.ts

@@ -0,0 +1,290 @@
+import { SettingsClient } from "@openhands/typescript-client/clients";
+import { getAgentServerClientOptions } from "#/api/agent-server-client-options";
+import { SecretsService } from "#/api/secrets-service";
+import { getActiveBackend } from "#/api/backend-registry/active-store";
+import type { Provider } from "#/types/settings";
+import { constructPullRequestUrl, getGitProviderBaseUrl } from "#/utils/utils";
+
+export interface GitProviderItem {
+  id: number;
+  number: number;
+  title: string;
+  url: string;
+  authorLogin: string | null;
+  updatedAt: string | null;
+}
+
+const PROVIDER_TOKEN_SECRET_CANDIDATES: Partial<Record<Provider, string[]>> = {
+  github: ["GITHUB_TOKEN", "GH_TOKEN", "github"],
+  gitlab: ["GITLAB_TOKEN", "GL_TOKEN", "gitlab"],
+  bitbucket: ["BITBUCKET_TOKEN", "bitbucket"],
+  forgejo: ["FORGEJO_TOKEN", "forgejo"],
+};
+
+const LIST_LIMIT = 30;
+
+async function resolveProviderToken(
+  provider: Provider,
+): Promise<string | null> {
+  // Cloud backends keep provider tokens server-side; browser-side secret
+  // lookup is only meaningful for the local agent-server secrets store.
+  if (getActiveBackend().backend.kind !== "local") {
+    return null;
+  }
+
+  const candidates = PROVIDER_TOKEN_SECRET_CANDIDATES[provider] ?? [];
+  if (candidates.length === 0) {
+    return null;
+  }
+
+  const secrets = await SecretsService.getSecrets();
+  const available = new Set(secrets.map((secret) => secret.name));
+  const match = candidates.find((name) => available.has(name));
+  if (!match) {
+    return null;
+  }
+
+  try {
+    return await new SettingsClient(getAgentServerClientOptions()).getSecret(
+      match,
+    );
+  } catch {
+    return null;
+  }
+}
+
+function constructIssueUrl(
+  issueNumber: number,
+  provider: Provider,
+  repositoryName: string,
+): string {
+  const baseUrl = getGitProviderBaseUrl(provider);
+  switch (provider) {
+    case "gitlab":
+      return `${baseUrl}/${repositoryName}/-/issues/${issueNumber}`;
+    case "bitbucket":
+      return `${baseUrl}/${repositoryName}/issues/${issueNumber}`;
+    case "forgejo":
+      return `${baseUrl}/${repositoryName}/issues/${issueNumber}`;
+    case "github":
+    default:
+      return `${baseUrl}/${repositoryName}/issues/${issueNumber}`;
+  }
+}
+
+function constructIssuesListUrl(
+  provider: Provider,
+  repositoryName: string,
+): string {
+  const baseUrl = getGitProviderBaseUrl(provider);
+  switch (provider) {
+    case "gitlab":
+      return `${baseUrl}/${repositoryName}/-/issues`;
+    case "bitbucket":
+      return `${baseUrl}/${repositoryName}/issues`;
+    case "forgejo":
+      return `${baseUrl}/${repositoryName}/issues`;
+    case "github":
+    default:
+      return `${baseUrl}/${repositoryName}/issues`;
+  }
+}
+
+function constructPullRequestsListUrl(
+  provider: Provider,
+  repositoryName: string,
+): string {
+  const baseUrl = getGitProviderBaseUrl(provider);
+  switch (provider) {
+    case "gitlab":
+      return `${baseUrl}/${repositoryName}/-/merge_requests`;
+    case "bitbucket":
+      return `${baseUrl}/${repositoryName}/pull-requests`;
+    case "forgejo":
+      return `${baseUrl}/${repositoryName}/pulls`;
+    case "github":
+    default:
+      return `${baseUrl}/${repositoryName}/pulls`;
+  }
+}
+
+async function fetchGithubJson<T>(
+  path: string,
+  token: string | null,
+): Promise<T> {
+  const headers: Record<string, string> = {
+    Accept: "application/vnd.github+json",
+    "X-GitHub-Api-Version": "2022-11-28",
+  };
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+
+  const response = await fetch(`https://api.github.com${path}`, { headers });
+  if (!response.ok) {
+    throw new Error(`GitHub API ${response.status}`);
+  }
+  return response.json() as Promise<T>;
+}
+
+async function fetchGitlabJson<T>(
+  path: string,
+  token: string | null,
+): Promise<T> {
+  const headers: Record<string, string> = {
+    Accept: "application/json",
+  };
+  if (token) {
+    headers["PRIVATE-TOKEN"] = token;
+  }
+
+  // gitlab.com's public REST API — an external host, not the agent-server
+  // `/api` surface the rule guards (its `/api/v4` prefix just trips the
+  // substring heuristic; the companion no-direct-agent-server-calls test
+  // matches only relative `/api/...` URLs and is not affected).
+  // eslint-disable-next-line local/no-direct-agent-server-fetch
+  const response = await fetch(`https://gitlab.com/api/v4${path}`, { headers });
+  if (!response.ok) {
+    throw new Error(`GitLab API ${response.status}`);
+  }
+  return response.json() as Promise<T>;
+}
+
+type GithubIssueOrPr = {
+  id: number;
+  number: number;
+  title: string;
+  html_url: string;
+  user?: { login?: string } | null;
+  updated_at?: string | null;
+  pull_request?: unknown;
+};
+
+type GitlabMergeRequest = {
+  id: number;
+  iid: number;
+  title: string;
+  web_url: string;
+  author?: { username?: string } | null;
+  updated_at?: string | null;
+};
+
+type GitlabIssue = {
+  id: number;
+  iid: number;
+  title: string;
+  web_url: string;
+  author?: { username?: string } | null;
+  updated_at?: string | null;
+};
+
+/**
+ * Lists open pull requests / merge requests and issues for a connected
+ * repository by calling the provider's public REST API from the browser.
+ * When a matching token secret exists locally (e.g. `GITHUB_TOKEN`), it is
+ * used for auth so private repos work; otherwise public-repo unauthenticated
+ * requests are attempted.
+ */
+export class GitProviderItemsService {
+  static constructIssuesListUrl = constructIssuesListUrl;
+
+  static constructPullRequestsListUrl = constructPullRequestsListUrl;
+
+  static async listPullRequests(
+    repository: string,
+    provider: Provider,
+  ): Promise<GitProviderItem[]> {
+    const token = await resolveProviderToken(provider);
+
+    if (provider === "gitlab") {
+      const encoded = encodeURIComponent(repository);
+      const items = await fetchGitlabJson<GitlabMergeRequest[]>(
+        `/projects/${encoded}/merge_requests?state=opened&per_page=${LIST_LIMIT}`,
+        token,
+      );
+      return items.map((item) => ({
+        id: item.id,
+        number: item.iid,
+        title: item.title,
+        url: item.web_url,
+        authorLogin: item.author?.username ?? null,
+        updatedAt: item.updated_at ?? null,
+      }));
+    }
+
+    if (provider !== "github" && provider !== "forgejo") {
+      return [];
+    }
+
+    const [owner, repo] = repository.split("/");
+    if (!owner || !repo) {
+      return [];
+    }
+
+    const items = await fetchGithubJson<GithubIssueOrPr[]>(
+      `/repos/${owner}/${repo}/pulls?state=open&per_page=${LIST_LIMIT}`,
+      token,
+    );
+
+    return items.map((item) => ({
+      id: item.id,
+      number: item.number,
+      title: item.title,
+      url:
+        item.html_url ||
+        constructPullRequestUrl(item.number, provider, repository),
+      authorLogin: item.user?.login ?? null,
+      updatedAt: item.updated_at ?? null,
+    }));
+  }
+
+  static async listIssues(
+    repository: string,
+    provider: Provider,
+  ): Promise<GitProviderItem[]> {
+    const token = await resolveProviderToken(provider);
+
+    if (provider === "gitlab") {
+      const encoded = encodeURIComponent(repository);
+      const items = await fetchGitlabJson<GitlabIssue[]>(
+        `/projects/${encoded}/issues?state=opened&per_page=${LIST_LIMIT}`,
+        token,
+      );
+      return items.map((item) => ({
+        id: item.id,
+        number: item.iid,
+        title: item.title,
+        url: item.web_url,
+        authorLogin: item.author?.username ?? null,
+        updatedAt: item.updated_at ?? null,
+      }));
+    }
+
+    if (provider !== "github" && provider !== "forgejo") {
+      return [];
+    }
+
+    const [owner, repo] = repository.split("/");
+    if (!owner || !repo) {
+      return [];
+    }
+
+    const items = await fetchGithubJson<GithubIssueOrPr[]>(
+      `/repos/${owner}/${repo}/issues?state=open&per_page=${LIST_LIMIT}`,
+      token,
+    );
+
+    // GitHub's issues endpoint also returns pull requests.
+    return items
+      .filter((item) => !item.pull_request)
+      .map((item) => ({
+        id: item.id,
+        number: item.number,
+        title: item.title,
+        url:
+          item.html_url || constructIssueUrl(item.number, provider, repository),
+        authorLogin: item.user?.login ?? null,
+        updatedAt: item.updated_at ?? null,
+      }));
+  }
+}

src/api/hooks-service.ts

@@ -0,0 +1,49 @@
+import { HooksClient } from "@openhands/typescript-client/clients";
+import type { HookConfig } from "@openhands/typescript-client";
+import { getAgentServerWorkingDir } from "./agent-server-config";
+import { getEffectiveLocalBackend } from "./backend-registry/active-store";
+import { getAgentServerClientOptions } from "./agent-server-client-options";
+
+// `loadHooks()` spends this twice (version probe, then the call) on the
+// conversation-start critical path; the SDK's 60s default would stall a launch.
+const HOOKS_LOAD_TIMEOUT_MS = 5000;
+
+class HooksService {
+  /**
+   * Load workspace hooks from the agent-server by calling POST /api/hooks.
+   * Returns the HookConfig if the workspace has hooks, or null.
+   * Gracefully returns null when no usable local backend is available
+   * (cloud backend, unseeded registry, or older agent-server).
+   * `projectDir` must be the workspace root: the agent-server checks
+   * `<project_dir>/.openhands/hooks.json` literally and never walks parents.
+   */
+  static async loadWorkspaceHooks(
+    projectDir?: string,
+  ): Promise<HookConfig | null> {
+    // getEffectiveLocalBackend() returns null for cloud backends AND for the
+    // NO_BACKEND sentinel (unseeded/empty registry), avoiding the silent
+    // NoBackendAvailableError that getActiveBackend() would cause.
+    if (!getEffectiveLocalBackend()) {
+      return null;
+    }
+
+    try {
+      const response = await new HooksClient(
+        getAgentServerClientOptions({ timeout: HOOKS_LOAD_TIMEOUT_MS }),
+      ).loadHooks({
+        project_dir: projectDir ?? getAgentServerWorkingDir(),
+      });
+      return response?.hook_config ?? null;
+    } catch (error) {
+      // Agent-server may not support the hooks endpoint or may be
+      // unreachable; gracefully fall back to null.
+      console.warn(
+        "Failed to load workspace hooks, continuing without:",
+        error,
+      );
+      return null;
+    }
+  }
+}
+
+export default HooksService;

src/api/launch-child-conversation-client-tool.ts

@@ -0,0 +1,112 @@
+import {
+  CHILD_CONVERSATION_ISOLATIONS,
+  CHILD_CONVERSATION_RESULT_PREFIX,
+  CHILD_CONVERSATION_TARGETS,
+  LAUNCH_CHILD_CONVERSATION_TOOL_NAME,
+} from "#/constants/child-conversation";
+import type { ClientToolSpec } from "./canvas-ui-client-tool";
+
+export {
+  LAUNCH_CHILD_CONVERSATION_ACTION_KIND,
+  LAUNCH_CHILD_CONVERSATION_TOOL_NAME,
+} from "#/constants/child-conversation";
+
+const LAUNCH_CHILD_CONVERSATION_DESCRIPTION = `Start a NEW, independent conversation to work on a well-scoped task in parallel with this one, without the user having to run any CLI command. The new conversation is recorded as a child of this one.
+
+The child runs on its own. It does not block you, you do not see its output,
+and it cannot see this conversation's history — everything it needs must be in
+the task brief.
+
+Choosing target:
+
+* target="local" — runs on the same machine, in this conversation's workspace.
+  Fast, no repository clone, no sandbox provisioning. Use this by default when
+  the work is on code that is already checked out here.
+
+* target="cloud" — runs on OpenHands Cloud in its own isolated sandbox, from a
+  git repository. Use this when the work should not touch the user's machine or
+  when it needs a repository that is not checked out locally. Requires the user
+  to have an OpenHands Cloud backend connected in Agent Canvas; if none is
+  connected you will be told so and should fall back to target="local".
+
+Writing the task brief:
+
+* Put everything the child needs in "task": the goal, the relevant file paths,
+  the constraints, the expected deliverable, and how it should report back.
+* Keep each child's scope independent of its siblings so parallel children do
+  not fight over the same files.
+* One call per delegated task. Do NOT call this tool twice for the same task.
+
+Parameter rules (a call that breaks one of these launches nothing and comes
+back with corrective guidance):
+
+* "repository" and "branch" apply to target="cloud" only. A local child always
+  inherits this conversation's workspace, so do not pass them with
+  target="local".
+* "isolation" applies to target="local" only. Cloud sandboxes are always
+  isolated, so do not pass it with target="cloud".
+* isolation="worktree" (the default) gives the child its own git worktree and
+  branch, cut from the repository's default branch — it will NOT see this
+  conversation's uncommitted or committed work. isolation="shared" puts the
+  child in this conversation's exact directory; only choose it when the child
+  genuinely must see work in progress, and expect the two agents to conflict.
+
+What comes back: this tool is acknowledged immediately, before the conversation
+exists. The real outcome arrives moments later as a follow-up message starting
+with "${CHILD_CONVERSATION_RESULT_PREFIX.trim()}" that carries the child's
+conversation id, URL, target and initial status — or an error with guidance.
+Wait for it, then tell the user what you launched and give them the URL. If it
+reports an error, fix the parameters and call this tool again.`;
+
+export const LAUNCH_CHILD_CONVERSATION_CLIENT_TOOL: ClientToolSpec = {
+  name: LAUNCH_CHILD_CONVERSATION_TOOL_NAME,
+  description: LAUNCH_CHILD_CONVERSATION_DESCRIPTION,
+  parameters: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      target: {
+        type: "string",
+        enum: [...CHILD_CONVERSATION_TARGETS],
+        description:
+          "Where the child runs. 'local' reuses this machine and this conversation's workspace; 'cloud' runs in an isolated OpenHands Cloud sandbox.",
+      },
+      task: {
+        type: "string",
+        description:
+          "Self-contained task brief, sent as the child's first message. The child cannot see this conversation, so state the goal, constraints, expected output and handoff criteria.",
+      },
+      title: {
+        type: "string",
+        description:
+          "Optional short title for the child conversation. Omit to let it title itself from the task.",
+      },
+      repository: {
+        type: "string",
+        description:
+          "target='cloud' only. Repository to clone into the sandbox, as 'owner/repo'. Defaults to this conversation's repository when it has one.",
+      },
+      branch: {
+        type: "string",
+        description:
+          "target='cloud' only, and only together with 'repository'. Defaults to the repository's default branch.",
+      },
+      isolation: {
+        type: "string",
+        enum: [...CHILD_CONVERSATION_ISOLATIONS],
+        description:
+          "target='local' only. 'worktree' (default) gives the child its own git worktree and branch; 'shared' runs it in this conversation's exact directory.",
+      },
+    },
+    required: ["target", "task"],
+  },
+  annotations: {
+    // Launching a conversation writes real state and is not repeatable, so the
+    // agent is asked to predict a security risk before every call.
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    // The cloud target reaches OpenHands Cloud.
+    openWorldHint: true,
+  },
+};

src/api/llm-balance-service.test.ts

@@ -0,0 +1,135 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import {
+  LLM_BALANCE_PATH,
+  LLM_BALANCE_TIMEOUT_MS,
+} from "#/constants/llm-balance";
+import LLMBalanceService from "./llm-balance-service";
+import { AgentServerClient } from "@openhands/typescript-client/clients";
+
+const getMock = vi.hoisted(() => vi.fn());
+
+vi.mock("@openhands/typescript-client/clients", () => ({
+  AgentServerClient: vi.fn(function AgentServerClientMock() {
+    return { get: getMock, close: vi.fn() };
+  }),
+}));
+
+const localBackend: Backend = {
+  id: "local-test",
+  name: "Local test backend",
+  host: "http://localhost:3000",
+  apiKey: "test-session-key",
+  kind: "local",
+};
+
+const balancePayload = {
+  provider: "openrouter",
+  limit: 20,
+  limit_remaining: 14.96,
+  usage: 5.04,
+  usage_daily: 1.2,
+  usage_weekly: 3.4,
+  usage_monthly: 5.04,
+  is_free_tier: false,
+};
+
+function httpError(status: number): Error & { status: number } {
+  return Object.assign(new Error(`HTTP ${status}`), { status });
+}
+
+function mockedClient(): AgentServerClient {
+  return vi.mocked(AgentServerClient).mock.results[0]
+    ?.value as AgentServerClient;
+}
+
+describe("LLMBalanceService.getBalance", () => {
+  beforeEach(() => {
+    getMock.mockReset();
+    vi.mocked(AgentServerClient).mockClear();
+    setRegisteredBackends([localBackend]);
+    setActiveSelection({ backendId: localBackend.id });
+  });
+
+  afterEach(() => {
+    setActiveSelection(null);
+    setRegisteredBackends([]);
+  });
+
+  it("normalizes a successful balance response via the typed client", async () => {
+    getMock.mockResolvedValue(balancePayload);
+
+    const balance = await LLMBalanceService.getBalance();
+
+    expect(balance).toEqual({
+      provider: "openrouter",
+      limit: 20,
+      limitRemaining: 14.96,
+      usage: 5.04,
+      usageDaily: 1.2,
+      usageWeekly: 3.4,
+      usageMonthly: 5.04,
+      isFreeTier: false,
+    });
+
+    expect(vi.mocked(AgentServerClient)).toHaveBeenCalledWith({
+      host: "http://localhost:3000",
+      apiKey: "test-session-key",
+      timeout: LLM_BALANCE_TIMEOUT_MS,
+    });
+    expect(getMock).toHaveBeenCalledWith(LLM_BALANCE_PATH, {
+      acceptableStatusCodes: new Set([200]),
+      responseType: "json",
+      timeoutSeconds: Math.floor(LLM_BALANCE_TIMEOUT_MS / 1000),
+    });
+    expect(mockedClient().close).toHaveBeenCalled();
+  });
+
+  it("treats null caps as an uncapped key", async () => {
+    getMock.mockResolvedValue({
+      ...balancePayload,
+      limit: null,
+      limit_remaining: null,
+    });
+
+    const balance = await LLMBalanceService.getBalance();
+
+    expect(balance?.limit).toBeNull();
+    expect(balance?.limitRemaining).toBeNull();
+    expect(balance?.usage).toBe(5.04);
+  });
+
+  it("returns null when the endpoint is missing (404)", async () => {
+    getMock.mockRejectedValue(httpError(404));
+
+    await expect(LLMBalanceService.getBalance()).resolves.toBeNull();
+  });
+
+  it("returns null for a malformed response body", async () => {
+    getMock.mockResolvedValue({ unexpected: true });
+
+    await expect(LLMBalanceService.getBalance()).resolves.toBeNull();
+  });
+
+  it("throws on non-404 HTTP failures", async () => {
+    getMock.mockRejectedValue(httpError(500));
+
+    await expect(LLMBalanceService.getBalance()).rejects.toThrow(
+      "Balance request failed with 500",
+    );
+  });
+
+  it("throws a named error when the request times out", async () => {
+    getMock.mockRejectedValue(
+      new DOMException("The operation was aborted.", "TimeoutError"),
+    );
+
+    await expect(LLMBalanceService.getBalance()).rejects.toThrow(
+      "Balance request timed out",
+    );
+  });
+});

src/api/llm-balance-service.ts

@@ -0,0 +1,113 @@
+import { AgentServerClient } from "@openhands/typescript-client/clients";
+import { getAgentServerClientOptions } from "./agent-server-client-options";
+import {
+  LLM_BALANCE_PATH,
+  LLM_BALANCE_TIMEOUT_MS,
+} from "#/constants/llm-balance";
+
+/**
+ * Credit balance reported by the agent server for the active LLM provider
+ * (currently only OpenRouter). Amounts are in USD credits.
+ */
+export interface LLMBalance {
+  provider: string;
+  /** Credit cap configured for the key, or null when uncapped. */
+  limit: number | null;
+  /** Credits remaining under `limit`, or null when uncapped. */
+  limitRemaining: number | null;
+  /** Total credits consumed by the key. */
+  usage: number;
+  usageDaily: number | null;
+  usageWeekly: number | null;
+  usageMonthly: number | null;
+  isFreeTier: boolean;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function numberOrNull(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+/** `AbortSignal.timeout` rejects with a `TimeoutError`; a manual abort uses `AbortError`. */
+function isAbortLike(error: unknown): boolean {
+  return (
+    isRecord(error) &&
+    (error.name === "TimeoutError" || error.name === "AbortError")
+  );
+}
+
+function normalizeBalance(raw: unknown): LLMBalance | null {
+  if (!isRecord(raw) || typeof raw.provider !== "string") return null;
+
+  return {
+    provider: raw.provider,
+    limit: numberOrNull(raw.limit),
+    limitRemaining: numberOrNull(raw.limit_remaining),
+    usage: numberOrNull(raw.usage) ?? 0,
+    usageDaily: numberOrNull(raw.usage_daily),
+    usageWeekly: numberOrNull(raw.usage_weekly),
+    usageMonthly: numberOrNull(raw.usage_monthly),
+    isFreeTier: raw.is_free_tier === true,
+  };
+}
+
+class LLMBalanceService {
+  /**
+   * Fetch the provider balance from the agent server.
+   *
+   * Returns `null` when the server answers 404 (older servers without the
+   * endpoint, or a provider that doesn't support balance reporting) or when
+   * the response doesn't match the expected shape — callers hide the balance
+   * UI in that case. Other HTTP failures throw, as does a request that outlives
+   * `LLM_BALANCE_TIMEOUT_MS`. A timeout stays an error rather than collapsing
+   * into `null`: `null` means "this server has no balance to report" and is
+   * cached under `staleTime: Infinity`, so treating a transient stall as an
+   * absent endpoint would hide the card for the rest of the conversation.
+   */
+  static async getBalance(): Promise<LLMBalance | null> {
+    const { host, apiKey } = getAgentServerClientOptions();
+    const client = new AgentServerClient({
+      host,
+      apiKey,
+      timeout: LLM_BALANCE_TIMEOUT_MS,
+    });
+    try {
+      const data = await client.get<unknown>(LLM_BALANCE_PATH, {
+        acceptableStatusCodes: new Set([200]),
+        responseType: "json",
+        timeoutSeconds: Math.floor(LLM_BALANCE_TIMEOUT_MS / 1000),
+      });
+      return normalizeBalance(data);
+    } catch (error) {
+      // Older servers without balance support answer 404 — hide the UI.
+      if (
+        error instanceof Error &&
+        "status" in error &&
+        (error as { status: number }).status === 404
+      ) {
+        return null;
+      }
+      if (isAbortLike(error)) {
+        throw new Error(
+          `Balance request timed out after ${LLM_BALANCE_TIMEOUT_MS}ms`,
+        );
+      }
+      const status =
+        error instanceof Error &&
+        "status" in error &&
+        (error as { status: number }).status;
+      throw new Error(
+        status
+          ? `Balance request failed with ${status}`
+          : `Balance request failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    } finally {
+      client.close();
+    }
+  }
+}
+
+export default LLMBalanceService;

src/api/llm-subscription-service.ts

@@ -0,0 +1,202 @@
+import { AgentServerClient } from "@openhands/typescript-client/clients";
+import { getAgentServerClientOptions } from "./agent-server-client-options";
+import {
+  OPENAI_SUBSCRIPTION_DEVICE_POLL_PATH,
+  OPENAI_SUBSCRIPTION_DEVICE_START_PATH,
+  OPENAI_SUBSCRIPTION_LOGOUT_PATH,
+  OPENAI_SUBSCRIPTION_MODELS_PATH,
+  OPENAI_SUBSCRIPTION_STATUS_PATH,
+  OPENAI_SUBSCRIPTION_VENDOR,
+} from "#/constants/llm-subscription";
+
+type RawSubscriptionStatus = Record<string, unknown>;
+type RawDeviceStart = Record<string, unknown>;
+
+export interface LLMSubscriptionStatus {
+  vendor: typeof OPENAI_SUBSCRIPTION_VENDOR;
+  connected: boolean;
+  accountEmail: string | null;
+  expiresAt: string | number | null;
+}
+
+export interface LLMSubscriptionDeviceChallenge {
+  deviceCode: string;
+  userCode: string;
+  verificationUri: string;
+  verificationUriComplete: string | null;
+  expiresAt: string | number | null;
+  intervalSeconds: number | null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+const readString = (
+  value: Record<string, unknown>,
+  keys: string[],
+): string | null => {
+  for (const key of keys) {
+    const candidate = value[key];
+    if (typeof candidate === "string" && candidate.trim().length > 0) {
+      return candidate.trim();
+    }
+  }
+  return null;
+};
+
+const readNumber = (
+  value: Record<string, unknown>,
+  keys: string[],
+): number | null => {
+  for (const key of keys) {
+    const candidate = value[key];
+    if (typeof candidate === "number" && Number.isFinite(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+};
+
+const readBoolean = (
+  value: Record<string, unknown>,
+  keys: string[],
+): boolean => {
+  for (const key of keys) {
+    const candidate = value[key];
+    if (typeof candidate === "boolean") {
+      return candidate;
+    }
+  }
+  return false;
+};
+
+interface SubscriptionRequestOptions {
+  method?: "GET" | "POST";
+  jsonBody?: unknown;
+}
+
+async function requestSubscriptionEndpoint(
+  path: string,
+  options: SubscriptionRequestOptions = {},
+): Promise<unknown> {
+  const { host, apiKey } = getAgentServerClientOptions();
+  const client = new AgentServerClient({ host, apiKey });
+  try {
+    return await client.request<unknown>({
+      method: options.method ?? "GET",
+      path,
+      body: options.jsonBody,
+      responseType: "json",
+    });
+  } finally {
+    client.close();
+  }
+}
+
+function normalizeModels(raw: unknown): string[] {
+  if (Array.isArray(raw)) {
+    return raw.filter((item): item is string => typeof item === "string");
+  }
+  if (isRecord(raw) && Array.isArray(raw.models)) {
+    return raw.models.filter(
+      (item): item is string => typeof item === "string",
+    );
+  }
+  return [];
+}
+
+function normalizeStatus(raw: RawSubscriptionStatus): LLMSubscriptionStatus {
+  return {
+    vendor: OPENAI_SUBSCRIPTION_VENDOR,
+    connected: readBoolean(raw, ["connected", "authenticated", "is_connected"]),
+    accountEmail: readString(raw, ["account_email", "email", "account"]),
+    expiresAt:
+      readString(raw, ["expires_at", "expiresAt"]) ??
+      readNumber(raw, ["expires_at", "expiresAt"]),
+  };
+}
+
+function normalizeDeviceChallenge(
+  raw: RawDeviceStart,
+): LLMSubscriptionDeviceChallenge {
+  const deviceCode = readString(raw, ["device_code", "deviceCode"]);
+  const userCode = readString(raw, ["user_code", "userCode"]);
+  const verificationUri = readString(raw, [
+    "verification_uri",
+    "verificationUri",
+    "verification_url",
+    "verificationUrl",
+  ]);
+
+  if (!deviceCode || !userCode || !verificationUri) {
+    throw new Error("Subscription device login response is incomplete");
+  }
+
+  return {
+    deviceCode,
+    userCode,
+    verificationUri,
+    verificationUriComplete: readString(raw, [
+      "verification_uri_complete",
+      "verificationUriComplete",
+      "verification_url_complete",
+      "verificationUrlComplete",
+    ]),
+    expiresAt:
+      readString(raw, ["expires_at", "expiresAt"]) ??
+      readNumber(raw, ["expires_at", "expiresAt", "expires_in", "expiresIn"]),
+    intervalSeconds: readNumber(raw, [
+      "interval",
+      "interval_seconds",
+      "intervalSeconds",
+    ]),
+  };
+}
+
+class LLMSubscriptionService {
+  static async getOpenAIModels(): Promise<string[]> {
+    const response = await requestSubscriptionEndpoint(
+      OPENAI_SUBSCRIPTION_MODELS_PATH,
+    );
+    return normalizeModels(response);
+  }
+
+  static async getOpenAIStatus(): Promise<LLMSubscriptionStatus> {
+    const response = await requestSubscriptionEndpoint(
+      OPENAI_SUBSCRIPTION_STATUS_PATH,
+    );
+    return normalizeStatus(response as RawSubscriptionStatus);
+  }
+
+  static async startOpenAIDeviceLogin(): Promise<LLMSubscriptionDeviceChallenge> {
+    const response = await requestSubscriptionEndpoint(
+      OPENAI_SUBSCRIPTION_DEVICE_START_PATH,
+      { method: "POST" },
+    );
+    return normalizeDeviceChallenge(response as RawDeviceStart);
+  }
+
+  static async pollOpenAIDeviceLogin(
+    deviceCode: string,
+  ): Promise<LLMSubscriptionStatus> {
+    const response = await requestSubscriptionEndpoint(
+      OPENAI_SUBSCRIPTION_DEVICE_POLL_PATH,
+      {
+        method: "POST",
+        jsonBody: { device_code: deviceCode },
+      },
+    );
+    return normalizeStatus(response as RawSubscriptionStatus);
+  }
+
+  static async logoutOpenAI(): Promise<LLMSubscriptionStatus> {
+    const response = await requestSubscriptionEndpoint(
+      OPENAI_SUBSCRIPTION_LOGOUT_PATH,
+      { method: "POST" },
+    );
+    return normalizeStatus(response as RawSubscriptionStatus);
+  }
+}
+
+export default LLMSubscriptionService;

src/api/main-app-auth.ts

@@ -0,0 +1,76 @@
+import axios from "axios";
+import { AGENT_CANVAS_CLIENT_VERSION } from "./client-source";
+import { getLockedCloudAuthMode } from "./agent-server-config";
+
+export const MAIN_APP_AUTHENTICATE_PATH = "/api/authenticate";
+export const MAIN_APP_ANALYTICS_EVENTS_PATH = "/api/analytics/events";
+export const MAIN_APP_LOGIN_PATH = "/login";
+export const MAIN_APP_LOGIN_REDIRECT_PARAM = "returnTo";
+
+const LOCAL_BROWSER_HOSTNAMES = new Set(["localhost", "127.0.0.1", "::1"]);
+
+function getCurrentPathForRedirect(): string {
+  if (typeof window === "undefined") return "/";
+  return `${window.location.pathname}${window.location.search}${window.location.hash}`;
+}
+
+export function isLocalBrowserHost(): boolean {
+  if (typeof window === "undefined") return false;
+  return LOCAL_BROWSER_HOSTNAMES.has(window.location.hostname);
+}
+
+export function shouldUseMainAppCookieAuth(): boolean {
+  return getLockedCloudAuthMode() === "cookie" && !isLocalBrowserHost();
+}
+
+let canvasAuthenticatedReported = false;
+
+export function _resetCanvasAuthReported(): void {
+  canvasAuthenticatedReported = false;
+}
+
+export async function reportCanvasAuthenticated(): Promise<void> {
+  if (canvasAuthenticatedReported) return;
+  canvasAuthenticatedReported = true;
+  try {
+    await axios.post(
+      MAIN_APP_ANALYTICS_EVENTS_PATH,
+      {
+        event_type: "canvas_authenticated",
+        client_version: AGENT_CANVAS_CLIENT_VERSION,
+      },
+      { withCredentials: true },
+    );
+  } catch {
+    // Analytics must never affect authentication or application startup.
+  }
+}
+
+export async function authenticateWithMainAppCookie(): Promise<boolean> {
+  try {
+    await axios.post(MAIN_APP_AUTHENTICATE_PATH, null, {
+      withCredentials: true,
+    });
+    void reportCanvasAuthenticated();
+    return true;
+  } catch (error) {
+    if (axios.isAxiosError(error) && error.response?.status === 401) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+export function buildMainAppLoginRedirect(
+  redirectPath = getCurrentPathForRedirect(),
+): string {
+  const params = new URLSearchParams({
+    [MAIN_APP_LOGIN_REDIRECT_PARAM]: redirectPath,
+  });
+  return `${MAIN_APP_LOGIN_PATH}?${params.toString()}`;
+}
+
+export function redirectToMainAppLogin(): void {
+  if (typeof window === "undefined") return;
+  window.location.assign(buildMainAppLoginRedirect());
+}

src/api/no-direct-agent-server-calls.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const SRC_ROOT = join(process.cwd(), "src");
+const EXCLUDED_SEGMENTS = new Set(["mocks", "routeTree.gen.ts"]);
+const ALLOWED_AD_HOC_HTTP_FILES = new Set([
+  "api/automation-service/automation-service.api.ts",
+  "api/cloud/proxy.ts",
+  "api/main-app-auth.ts",
+]);
+
+function collectSourceFiles(dir: string): string[] {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const fullPath = join(dir, entry.name);
+    // Normalize to forward slashes so the path matches ALLOWED_AD_HOC_HTTP_FILES
+    // entries on Windows where path.relative() returns backslash-separated paths.
+    const relPath = relative(SRC_ROOT, fullPath).replace(/\\/g, "/");
+
+    if (entry.isDirectory()) {
+      if (EXCLUDED_SEGMENTS.has(entry.name)) return [];
+      return collectSourceFiles(fullPath);
+    }
+
+    if (EXCLUDED_SEGMENTS.has(entry.name)) return [];
+    if (!/\.(ts|tsx)$/.test(entry.name)) return [];
+    if (/\.(test|spec)\.(ts|tsx)$/.test(entry.name)) return [];
+    return [relPath];
+  });
+}
+
+describe("agent-server API access", () => {
+  it("uses typed @openhands/typescript-client access instead of ad-hoc HTTP", () => {
+    const violations = collectSourceFiles(SRC_ROOT).flatMap((relPath) => {
+      const source = readFileSync(join(SRC_ROOT, relPath), "utf8");
+      const fileViolations: string[] = [];
+
+      if (/openHands\s*\./.test(source)) {
+        fileViolations.push("uses the shared axios instance directly");
+      }
+
+      if (/\bcreateHttpClient\s*\(/.test(source)) {
+        fileViolations.push("uses createHttpClient directly");
+      }
+
+      if (
+        /from\s+["']@openhands\/typescript-client\/client\/http-client["']/.test(
+          source,
+        )
+      ) {
+        fileViolations.push("imports the low-level SDK HttpClient directly");
+      }
+
+      if (/\bnew\s+HttpClient\s*\(/.test(source)) {
+        fileViolations.push("constructs HttpClient directly");
+      }
+
+      if (
+        (/\baxios\s*\(/.test(source) ||
+          /\baxios\s*\.\s*(?:create|get|post|put|patch|delete|request)\s*\(/.test(
+            source,
+          )) &&
+        !ALLOWED_AD_HOC_HTTP_FILES.has(relPath)
+      ) {
+        fileViolations.push("uses axios directly for HTTP calls");
+      }
+
+      if (
+        /\bfetch\s*\([\s\S]{0,200}['"`]\/api\//.test(source) &&
+        !ALLOWED_AD_HOC_HTTP_FILES.has(relPath)
+      ) {
+        fileViolations.push("calls an /api path with fetch directly");
+      }
+
+      return fileViolations.map((violation) => `${relPath}: ${violation}`);
+    });
+
+    expect(violations).toEqual([]);
+  });
+});

src/api/open-hands.types.ts

@@ -0,0 +1,140 @@
+import { ConversationStatus } from "#/types/conversation-status";
+import { RuntimeStatus } from "#/types/runtime-status";
+import { Provider } from "#/types/settings";
+
+export interface ErrorResponse {
+  error: string;
+}
+
+export interface SaveFileSuccessResponse {
+  message: string;
+}
+
+export interface FileUploadSuccessResponse {
+  uploaded_files: string[];
+  skipped_files: { name: string; reason: string }[];
+}
+
+export interface FeedbackBodyResponse {
+  message: string;
+  feedback_id: string;
+  password: string;
+}
+
+export interface FeedbackResponse {
+  statusCode: number;
+  body: FeedbackBodyResponse;
+}
+
+export interface AuthenticationResponse {
+  message: string;
+  login?: string; // Only present when allow list is enabled
+}
+
+export interface Feedback {
+  version: string;
+  email: string;
+  token: string;
+  polarity: "positive" | "negative";
+  permissions: "public" | "private";
+  trajectory: unknown[];
+}
+
+export interface GetVSCodeUrlResponse {
+  vscode_url: string | null;
+  error?: string;
+}
+
+export interface GetTrajectoryResponse {
+  trajectory: unknown[] | null;
+  error?: string;
+}
+
+export interface RepositorySelection {
+  selected_repository: string | null;
+  selected_branch: string | null;
+  git_provider: Provider | null;
+}
+
+export type ConversationTrigger =
+  | "resolver"
+  | "gui"
+  | "suggested_task"
+  | "microagent_management"
+  | "automation";
+
+export interface Conversation {
+  conversation_id: string;
+  title: string;
+  selected_repository: string | null;
+  selected_branch: string | null;
+  git_provider: Provider | null;
+  last_updated_at: string;
+  created_at: string;
+  status: ConversationStatus;
+  runtime_status: RuntimeStatus | null;
+  trigger?: ConversationTrigger;
+  url: string | null;
+  session_api_key: string | null;
+  pr_number?: number[] | null;
+  conversation_version?: "V0" | "V1";
+  sub_conversation_ids?: string[];
+  public?: boolean;
+  llm_model?: string | null;
+}
+
+export interface ResultSet<T> {
+  results: T[];
+  next_page_id: string | null;
+}
+
+/**
+ * @deprecated Use AgentServerGitChangeStatus for new code. This type is maintained for backward compatibility with V0 API.
+ */
+export type GitChangeStatus = "M" | "A" | "D" | "R" | "U";
+
+export type AgentServerGitChangeStatus =
+  | "MOVED"
+  | "ADDED"
+  | "DELETED"
+  | "UPDATED";
+
+export interface GitChange {
+  status: GitChangeStatus;
+  path: string;
+}
+
+export interface GitChangeDiff {
+  modified: string;
+  original: string;
+}
+
+export interface GitCommit {
+  sha: string;
+  shortSha: string;
+  subject: string;
+  author: string;
+  // ISO 8601 author date with UTC offset (git log %aI).
+  timestamp: string;
+}
+
+export interface GitCommitsPage {
+  commits: GitCommit[];
+  hasMore: boolean;
+}
+
+export interface InputMetadata {
+  name: string;
+  description: string;
+}
+
+export interface IOption<T> {
+  label: string;
+  value: T;
+}
+
+export type GetFilesResponse = string[];
+
+export interface GetFileResponse {
+  code: string;
+}

src/api/plugins-management-service.test.ts

@@ -0,0 +1,137 @@
+import { PluginsClient } from "@openhands/typescript-client/clients";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import PluginsManagementService from "#/api/plugins-management-service";
+
+vi.mock("@openhands/typescript-client/clients", () => ({
+  PluginsClient: vi.fn(),
+}));
+
+const listInstalledPlugins = vi.fn();
+const installPlugin = vi.fn();
+const setPluginEnabled = vi.fn();
+const uninstallPlugin = vi.fn();
+const refreshPlugin = vi.fn();
+const close = vi.fn();
+
+function useBackend(kind: "local" | "cloud"): void {
+  const backend: Backend = {
+    id: kind,
+    name: kind,
+    host: "http://127.0.0.1:8001",
+    apiKey: "session-key",
+    kind,
+  };
+  setRegisteredBackends([backend]);
+  setActiveSelection({ backendId: kind, orgId: null });
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  __resetActiveStoreForTests();
+  vi.mocked(PluginsClient).mockImplementation(function MockPluginsClient() {
+    return {
+      listInstalledPlugins,
+      installPlugin,
+      setPluginEnabled,
+      uninstallPlugin,
+      refreshPlugin,
+      close,
+    } as unknown as PluginsClient;
+  } as unknown as typeof PluginsClient);
+});
+
+afterEach(() => {
+  __resetActiveStoreForTests();
+});
+
+const installedPlugin = {
+  name: "demo-plugin",
+  version: "1.0.0",
+  description: "A demo plugin",
+  enabled: true,
+  source: "github:OpenHands/extensions",
+  resolved_ref: null,
+  repo_path: "plugins/demo-plugin",
+  installed_at: "2026-06-01T00:00:00Z",
+  install_path: "/home/.openhands/plugins/installed/demo-plugin",
+};
+
+describe("PluginsManagementService", () => {
+  it("lists installed plugins from the local agent-server", async () => {
+    useBackend("local");
+    listInstalledPlugins.mockResolvedValue({ plugins: [installedPlugin] });
+
+    const result = await PluginsManagementService.listInstalledPlugins();
+
+    expect(result).toEqual([installedPlugin]);
+    expect(listInstalledPlugins).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns an empty installed list on a cloud backend without calling the client", async () => {
+    useBackend("cloud");
+
+    const result = await PluginsManagementService.listInstalledPlugins();
+
+    expect(result).toEqual([]);
+    expect(PluginsClient).not.toHaveBeenCalled();
+  });
+
+  it("returns an empty installed list when the local request fails", async () => {
+    useBackend("local");
+    listInstalledPlugins.mockRejectedValue(new Error("unreachable"));
+
+    const result = await PluginsManagementService.listInstalledPlugins();
+
+    expect(result).toEqual([]);
+  });
+
+  it("forwards source, ref, and repo_path when installing a plugin", async () => {
+    useBackend("local");
+    installPlugin.mockResolvedValue(installedPlugin);
+
+    await PluginsManagementService.installPlugin({
+      source: "github:OpenHands/extensions",
+      ref: "main",
+      repo_path: "plugins/demo-plugin",
+    });
+
+    expect(installPlugin).toHaveBeenCalledWith({
+      source: "github:OpenHands/extensions",
+      ref: "main",
+      repo_path: "plugins/demo-plugin",
+    });
+  });
+
+  it("forwards the name and enabled flag when toggling a plugin", async () => {
+    useBackend("local");
+    setPluginEnabled.mockResolvedValue({ name: "demo-plugin", enabled: false });
+
+    await PluginsManagementService.setPluginEnabled("demo-plugin", false);
+
+    expect(setPluginEnabled).toHaveBeenCalledWith("demo-plugin", false);
+  });
+
+  it("forwards the plugin name when uninstalling", async () => {
+    useBackend("local");
+    uninstallPlugin.mockResolvedValue({ message: "ok" });
+
+    await PluginsManagementService.uninstallPlugin("demo-plugin");
+
+    expect(uninstallPlugin).toHaveBeenCalledWith("demo-plugin");
+  });
+
+  it("forwards the plugin name when refreshing", async () => {
+    useBackend("local");
+    refreshPlugin.mockResolvedValue({ message: "ok", plugin: installedPlugin });
+
+    await PluginsManagementService.refreshPlugin("demo-plugin");
+
+    expect(refreshPlugin).toHaveBeenCalledWith("demo-plugin");
+  });
+});

src/api/plugins-management-service.ts

@@ -0,0 +1,136 @@
+import { PluginsClient } from "@openhands/typescript-client/clients";
+import { getActiveBackend } from "./backend-registry/active-store";
+import { getAgentServerClientOptions } from "./agent-server-client-options";
+import type { PluginBundledSkill } from "./plugins-service";
+
+/**
+ * An installed plugin, as returned by the agent-server management router
+ * (`GET /api/plugins/installed`). Matches the typescript-client
+ * `InstalledPluginInfo`. The contents fields (`skills`, `files`, relative to
+ * `install_path`) are absent on older agent-servers and null when the
+ * installed plugin directory failed to load.
+ */
+export interface InstalledPluginInfo {
+  name: string;
+  version: string;
+  description: string | null;
+  enabled: boolean;
+  source: string;
+  resolved_ref?: string | null;
+  repo_path?: string | null;
+  installed_at: string;
+  install_path: string;
+  skills?: PluginBundledSkill[] | null;
+  files?: string[] | null;
+}
+
+/** Coordinates for installing a plugin from a git source or local path. */
+export interface InstallPluginRequest {
+  source: string;
+  ref?: string | null;
+  repo_path?: string | null;
+  force?: boolean;
+}
+
+/**
+ * The slice of the typescript-client `PluginsClient` this service drives. The
+ * installed `@openhands/typescript-client` package does not yet export these
+ * management methods (they ship in typescript-client PRs #222/#223); narrowing
+ * to this local interface keeps `vitest` (types stripped) and `eslint` green
+ * until the client is republished, at which point the cast below can be dropped.
+ */
+interface PluginsManagementClient {
+  listInstalledPlugins(): Promise<{ plugins: InstalledPluginInfo[] }>;
+  installPlugin(request: InstallPluginRequest): Promise<InstalledPluginInfo>;
+  setPluginEnabled(
+    name: string,
+    enabled: boolean,
+  ): Promise<{ name: string; enabled: boolean }>;
+  uninstallPlugin(name: string): Promise<{ message: string }>;
+  refreshPlugin(
+    name: string,
+  ): Promise<{ message: string; plugin: InstalledPluginInfo }>;
+}
+
+function isCloudBackend(): boolean {
+  return getActiveBackend().backend.kind === "cloud";
+}
+
+function getManagementClient(): PluginsManagementClient {
+  return new PluginsClient(
+    getAgentServerClientOptions(),
+  ) as unknown as PluginsManagementClient;
+}
+
+/**
+ * Front-end management layer for installed plugins: list / install / enable /
+ * disable / uninstall / refresh. Kept separate from the read-only catalog
+ * service (`plugins-service.ts`), exactly as skills separate the marketplace
+ * catalog from install actions.
+ *
+ * Local backend only for now (per Appendix C Q5): installed plugins live on the
+ * local agent-server's `~/.openhands/plugins/installed/`. A cloud backend has no
+ * per-user installed store yet, so reads return an empty list and mutating
+ * actions throw (the UI also disables them on cloud).
+ */
+class PluginsManagementService {
+  static async listInstalledPlugins(): Promise<InstalledPluginInfo[]> {
+    if (isCloudBackend()) {
+      return [];
+    }
+
+    try {
+      const response = await getManagementClient().listInstalledPlugins();
+      return response.plugins ?? [];
+    } catch {
+      // Agent-server may predate the plugins router or be unreachable; surface
+      // an empty list rather than throwing (mirrors the catalog service).
+      return [];
+    }
+  }
+
+  static async installPlugin(
+    request: InstallPluginRequest,
+  ): Promise<InstalledPluginInfo> {
+    if (isCloudBackend()) {
+      throw new Error(
+        "Installing plugins is only available on a local backend.",
+      );
+    }
+    return getManagementClient().installPlugin(request);
+  }
+
+  static async setPluginEnabled(
+    name: string,
+    enabled: boolean,
+  ): Promise<{ name: string; enabled: boolean }> {
+    if (isCloudBackend()) {
+      throw new Error(
+        "Enabling and disabling plugins is only available on a local backend.",
+      );
+    }
+    return getManagementClient().setPluginEnabled(name, enabled);
+  }
+
+  static async uninstallPlugin(name: string): Promise<{ message: string }> {
+    if (isCloudBackend()) {
+      throw new Error(
+        "Uninstalling plugins is only available on a local backend.",
+      );
+    }
+    return getManagementClient().uninstallPlugin(name);
+  }
+
+  static async refreshPlugin(
+    name: string,
+  ): Promise<{ message: string; plugin: InstalledPluginInfo }> {
+    if (isCloudBackend()) {
+      throw new Error(
+        "Refreshing plugins is only available on a local backend.",
+      );
+    }
+    return getManagementClient().refreshPlugin(name);
+  }
+}
+
+export default PluginsManagementService;

src/api/plugins-service.test.ts

@@ -0,0 +1,159 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  FileClient,
+  PluginsClient,
+} from "@openhands/typescript-client/clients";
+import {
+  setActiveSelection,
+  setRegisteredBackends,
+} from "./backend-registry/active-store";
+import PluginsService from "./plugins-service";
+
+vi.mock("@openhands/typescript-client/clients", () => ({
+  PluginsClient: vi.fn(),
+  FileClient: vi.fn(),
+}));
+
+const getPluginsMarketplace = vi.fn();
+const getPlugins = vi.fn();
+const downloadFile = vi.fn();
+const close = vi.fn();
+
+function useBackend(kind: "local" | "cloud"): void {
+  setRegisteredBackends([
+    {
+      id: kind,
+      name: kind,
+      host: "http://127.0.0.1:8001",
+      apiKey: "session-key",
+      kind,
+    },
+  ]);
+  setActiveSelection({ backendId: kind, orgId: null });
+}
+
+describe("PluginsService.getPluginsMarketplace", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(PluginsClient).mockImplementation(function MockPluginsClient() {
+      return { getPluginsMarketplace, close } as unknown as PluginsClient;
+    } as unknown as typeof PluginsClient);
+  });
+
+  it("returns the catalog from the local agent-server", async () => {
+    useBackend("local");
+    const plugin = {
+      name: "city-weather",
+      description: "Weather plugin",
+      source: "github:OpenHands/extensions",
+      ref: null,
+      repo_path: "plugins/city-weather",
+      installed: false,
+    };
+    getPluginsMarketplace.mockResolvedValue({ plugins: [plugin] });
+
+    const result = await PluginsService.getPluginsMarketplace();
+
+    expect(result).toEqual([plugin]);
+    expect(getPluginsMarketplace).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns an empty catalog on a cloud backend without calling the client", async () => {
+    useBackend("cloud");
+
+    const result = await PluginsService.getPluginsMarketplace();
+
+    expect(result).toEqual([]);
+    expect(PluginsClient).not.toHaveBeenCalled();
+  });
+
+  it("returns an empty catalog when the local request fails", async () => {
+    useBackend("local");
+    getPluginsMarketplace.mockRejectedValue(new Error("unreachable"));
+
+    const result = await PluginsService.getPluginsMarketplace();
+
+    expect(result).toEqual([]);
+  });
+});
+
+describe("PluginsService.getLocalPlugins", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(PluginsClient).mockImplementation(function MockPluginsClient() {
+      return { getPlugins, close } as unknown as PluginsClient;
+    } as unknown as typeof PluginsClient);
+  });
+
+  it("requests user-level local plugins from the local agent-server", async () => {
+    useBackend("local");
+    const plugin = {
+      name: "hello-local",
+      version: "1.0.0",
+      description: "A local plugin",
+    };
+    getPlugins.mockResolvedValue({ plugins: [plugin] });
+
+    const result = await PluginsService.getLocalPlugins();
+
+    expect(result).toEqual([plugin]);
+    expect(getPlugins).toHaveBeenCalledWith({
+      load_user: true,
+      load_project: false,
+    });
+  });
+
+  it("returns an empty list on a cloud backend without calling the client", async () => {
+    useBackend("cloud");
+
+    const result = await PluginsService.getLocalPlugins();
+
+    expect(result).toEqual([]);
+    expect(PluginsClient).not.toHaveBeenCalled();
+  });
+});
+
+describe("PluginsService.getPluginFileContent", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(FileClient).mockImplementation(function MockFileClient() {
+      return { downloadFile, close } as unknown as FileClient;
+    } as unknown as typeof FileClient);
+  });
+
+  it("downloads the file under the plugin directory and decodes it as text", async () => {
+    useBackend("local");
+    downloadFile.mockResolvedValue(new TextEncoder().encode("# Hello").buffer);
+
+    const result = await PluginsService.getPluginFileContent(
+      "/plugins/demo",
+      "docs/README.md",
+    );
+
+    expect(result).toEqual({ kind: "text", text: "# Hello" });
+    expect(downloadFile).toHaveBeenCalledWith("/plugins/demo/docs/README.md");
+  });
+
+  it("flags content containing NUL bytes as binary", async () => {
+    useBackend("local");
+    downloadFile.mockResolvedValue(
+      new Uint8Array([0x89, 0x50, 0x00, 0x47]).buffer,
+    );
+
+    const result = await PluginsService.getPluginFileContent(
+      "/plugins/demo",
+      "logo.png",
+    );
+
+    expect(result).toEqual({ kind: "binary", text: null });
+  });
+
+  it("rejects on a cloud backend without calling the client", async () => {
+    useBackend("cloud");
+
+    await expect(
+      PluginsService.getPluginFileContent("/plugins/demo", "README.md"),
+    ).rejects.toThrow();
+    expect(FileClient).not.toHaveBeenCalled();
+  });
+});

src/api/plugins-service.ts

@@ -0,0 +1,150 @@
+import {
+  FileClient,
+  PluginsClient,
+} from "@openhands/typescript-client/clients";
+import { getActiveBackend } from "./backend-registry/active-store";
+import { getAgentServerClientOptions } from "./agent-server-client-options";
+
+/** Summary of a skill bundled in a plugin (agent-server `PluginSkillSummary`). */
+export interface PluginBundledSkill {
+  name: string;
+  description?: string | null;
+}
+
+/**
+ * A plugin in the dynamic marketplace catalog, with attachable coordinates and
+ * install state. Matches the agent-server `MarketplacePluginInfo` / the
+ * typescript-client `MarketplacePlugin`. The contents fields (`path`, `skills`,
+ * `files`) are populated when the entry resolves to a directory in the
+ * server's local marketplace clone, and are absent on older agent-servers.
+ */
+export interface MarketplacePlugin {
+  name: string;
+  description: string | null;
+  source: string;
+  ref?: string | null;
+  repo_path?: string | null;
+  installed: boolean;
+  path?: string | null;
+  skills?: PluginBundledSkill[] | null;
+  files?: string[] | null;
+}
+
+/**
+ * A locally-discovered ("ambient") plugin reported by the agent-server — one
+ * found in the user's local plugin directories (e.g. `~/.agents/plugins`).
+ * These auto-load into conversations and are not managed via install/uninstall,
+ * so the Plugins page renders them as a read-only "Local" group. Matches the
+ * typescript-client `PluginInfo`; the contents fields are absent on older
+ * agent-servers.
+ */
+export interface LocalPlugin {
+  name: string;
+  version: string;
+  description: string;
+  path?: string;
+  skills?: PluginBundledSkill[];
+  files?: string[];
+}
+
+/** Content of a single plugin file fetched for the detail-modal viewer. */
+export interface PluginFileContent {
+  kind: "text" | "binary";
+  text: string | null;
+}
+
+function isLikelyBinary(buffer: ArrayBuffer): boolean {
+  // Same heuristic git uses: presence of a NUL byte in the first ~8KB. Small
+  // private copy of `isLikelyBinary` in `use-workspace-file-content.ts` — that
+  // module is conversation-workspace-specific and heavy to import from here.
+  const view = new Uint8Array(buffer, 0, Math.min(buffer.byteLength, 8000));
+  for (let i = 0; i < view.length; i += 1) {
+    if (view[i] === 0) return true;
+  }
+  return false;
+}
+
+class PluginsService {
+  /**
+   * Fetch the dynamic plugins marketplace catalog.
+   *
+   * Local backend only for now: the catalog is fetched at run time from the
+   * agent-server via the typed client (no bundled catalog, so the list stays
+   * dynamic). On a cloud backend an empty catalog is returned — there is no
+   * cloud plugins-marketplace endpoint yet (tracked as a follow-up ticket).
+   */
+  static async getPluginsMarketplace(): Promise<MarketplacePlugin[]> {
+    if (getActiveBackend().backend.kind === "cloud") {
+      return [];
+    }
+
+    try {
+      const response = await new PluginsClient(
+        getAgentServerClientOptions(),
+      ).getPluginsMarketplace();
+      return (response.plugins ?? []) as MarketplacePlugin[];
+    } catch {
+      // Agent-server may not support the plugins endpoint or be unreachable;
+      // surface an empty catalog rather than throwing.
+      return [];
+    }
+  }
+
+  /**
+   * Fetch the locally-discovered ("ambient") plugins from the agent-server.
+   *
+   * Only user-level plugins are requested (`~/.agents/plugins`,
+   * `~/.openhands/plugins`, plus enabled installed plugins): the Plugins page is
+   * global, so there is no project workspace to scope project plugins to.
+   *
+   * Local backend only — a cloud backend has no local plugin directories, so an
+   * empty list is returned. Errors surface as an empty list (mirrors the
+   * catalog) rather than throwing.
+   */
+  static async getLocalPlugins(): Promise<LocalPlugin[]> {
+    if (getActiveBackend().backend.kind === "cloud") {
+      return [];
+    }
+
+    try {
+      const response = await new PluginsClient(
+        getAgentServerClientOptions(),
+      ).getPlugins({ load_user: true, load_project: false });
+      return (response.plugins ?? []) as LocalPlugin[];
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Fetch one plugin file's content for the detail-modal viewer. `basePath` is
+   * the plugin directory reported by the agent-server (`path`/`install_path`)
+   * and `relativePath` a POSIX path from the plugin's `files` listing.
+   *
+   * Local backend only — plugin files live on the local agent-server's disk.
+   * Errors propagate so the caller can render a load-error state.
+   */
+  static async getPluginFileContent(
+    basePath: string,
+    relativePath: string,
+  ): Promise<PluginFileContent> {
+    if (getActiveBackend().backend.kind === "cloud") {
+      throw new Error(
+        "Reading plugin files is only available on a local backend.",
+      );
+    }
+
+    const buffer = await new FileClient(
+      getAgentServerClientOptions(),
+    ).downloadFile(`${basePath}/${relativePath}`);
+    if (isLikelyBinary(buffer)) {
+      return { kind: "binary", text: null };
+    }
+    return {
+      kind: "text",
+      text: new TextDecoder("utf-8", { fatal: false }).decode(buffer),
+    };
+  }
+}
+
+export default PluginsService;

src/api/secrets-service.ts

@@ -0,0 +1,156 @@
+import { SettingsClient } from "@openhands/typescript-client/clients";
+import { isSdkHttpStatusError } from "./agent-server-compatibility";
+import { getActiveBackend } from "./backend-registry/active-store";
+import {
+  deleteCloudSecret,
+  fetchCloudSecrets,
+  saveCloudSecret,
+} from "./cloud/secrets-service.api";
+import { getAgentServerClientOptions } from "./agent-server-client-options";
+import { CustomSecretWithoutValue } from "./secrets-service.types";
+import { withRetry } from "./with-retry";
+
+async function fetchSecrets(): Promise<CustomSecretWithoutValue[]> {
+  if (getActiveBackend().backend.kind === "cloud") {
+    return withRetry(() => fetchCloudSecrets());
+  }
+  const response = await withRetry(() =>
+    new SettingsClient(getAgentServerClientOptions()).listSecrets(),
+  );
+  return response.secrets.map((s) => ({
+    name: s.name,
+    description: s.description,
+  }));
+}
+
+export class SecretsService {
+  /**
+   * List all custom secrets (names and descriptions only, no values).
+   * Uses the agent-server API endpoint: GET /api/settings/secrets
+   *
+   * Note: The agent-server API doesn't support pagination or search filtering.
+   * All secrets are returned in a single response.
+   */
+  static async getSecrets(): Promise<CustomSecretWithoutValue[]> {
+    try {
+      return await fetchSecrets();
+    } catch (error) {
+      console.error("Failed to fetch secrets after retries:", error);
+      return [];
+    }
+  }
+
+  /**
+   * List all custom secrets, surfacing failures to callers that must
+   * distinguish an unavailable list from an empty one.
+   */
+  static async getSecretsOrThrow(): Promise<CustomSecretWithoutValue[]> {
+    return fetchSecrets();
+  }
+
+  /**
+   * Create or update a custom secret (upsert by name).
+   * Uses the agent-server API endpoint: PUT /api/settings/secrets
+   *
+   * @param name - Secret name (must start with letter, contain only letters/numbers/underscores, 1-64 chars)
+   * @param value - Secret value
+   * @param description - Optional description
+   * @throws Error if the API call fails after retries
+   */
+  static async createSecret(
+    name: string,
+    value: string,
+    description?: string,
+  ): Promise<void> {
+    if (getActiveBackend().backend.kind === "cloud") {
+      await saveCloudSecret({ name, value, description });
+      return;
+    }
+    await withRetry(() =>
+      new SettingsClient(getAgentServerClientOptions()).upsertSecret({
+        name,
+        value,
+        description,
+      }),
+    );
+  }
+
+  /**
+   * Update a secret's name and/or description, and optionally overwrite its
+   * value. When no value is given the existing one is preserved: the
+   * agent-server only exposes an upsert endpoint, so we fetch the existing
+   * value and re-upsert it under the updated name/description.
+   *
+   * @param secretToEdit - Existing secret name
+   * @param name - New (or same) secret name
+   * @param description - Optional new description
+   * @param value - Optional new value; when omitted the stored value is kept
+   * @throws Error if the API call fails after retries
+   */
+  static async updateSecret(
+    secretToEdit: string,
+    name: string,
+    description?: string,
+    value?: string,
+  ): Promise<void> {
+    if (getActiveBackend().backend.kind === "cloud") {
+      await saveCloudSecret({
+        name,
+        value,
+        description,
+        previousName: secretToEdit,
+      });
+      return;
+    }
+
+    const client = new SettingsClient(getAgentServerClientOptions());
+    const nextValue =
+      value ?? (await withRetry(() => client.getSecret(secretToEdit)));
+
+    await withRetry(() =>
+      client.upsertSecret({
+        name,
+        value: nextValue,
+        description,
+      }),
+    );
+
+    if (name !== secretToEdit) {
+      await this.deleteSecret(secretToEdit);
+    }
+  }
+
+  /**
+   * Delete a custom secret by name.
+   * Uses the agent-server API endpoint: DELETE /api/settings/secrets/{name}
+   *
+   * @param name - Secret name to delete
+   * @throws Error if the API call fails (except 404, which is treated as success)
+   */
+  static async deleteSecret(name: string): Promise<void> {
+    try {
+      if (getActiveBackend().backend.kind === "cloud") {
+        await withRetry(() => deleteCloudSecret(name));
+        return;
+      }
+      await withRetry(() =>
+        new SettingsClient(getAgentServerClientOptions()).deleteSecret(name),
+      );
+    } catch (error) {
+      // 404 means secret doesn't exist - treat as successful deletion.
+      // Both the SDK's HttpError (status on the error itself) and
+      // axios-style errors (status under `response`) count.
+      if (
+        isSdkHttpStatusError(error, 404) ||
+        (error &&
+          typeof error === "object" &&
+          "response" in error &&
+          (error as { response?: { status?: number } }).response?.status ===
+            404)
+      ) {
+        return;
+      }
+      throw error;
+    }
+  }
+}

src/api/secrets-service.types.ts

@@ -0,0 +1,15 @@
+/**
+ * Custom secret with name, value, and optional description.
+ * Used for creating/updating secrets via PUT /api/settings/secrets.
+ */
+export type CustomSecret = {
+  name: string;
+  value: string;
+  description?: string;
+};
+
+/**
+ * Custom secret metadata without the secret value.
+ * Used for listing secrets via GET /api/settings/secrets.
+ */
+export type CustomSecretWithoutValue = Omit<CustomSecret, "value">;

src/api/skills-service.ts

@@ -0,0 +1,80 @@
+import { SkillsClient } from "@openhands/typescript-client/clients";
+import {
+  SKILLS_CATALOG,
+  type SkillCatalogEntry,
+} from "@openhands/extensions/skills";
+import { SkillInfo } from "#/types/settings";
+import { getAgentServerWorkingDir } from "./agent-server-config";
+import { getActiveBackend } from "./backend-registry/active-store";
+import {
+  fetchCloudConversationSkills,
+  fetchCloudSkills,
+} from "./cloud/skills-service.api";
+import { getAgentServerClientOptions } from "./agent-server-client-options";
+
+function catalogEntryToSkillInfo(entry: SkillCatalogEntry): SkillInfo {
+  return {
+    name: entry.name,
+    type: "knowledge",
+    source: "public",
+    description: entry.description,
+    triggers: entry.triggers,
+    category: entry.category,
+    content: entry.content,
+    license: entry.license ?? null,
+    compatibility: entry.compatibility ?? null,
+  };
+}
+
+/**
+ * Public skills loaded from the `@openhands/extensions` npm package.
+ *
+ * This is an **immutable build-time snapshot**: the catalog is baked into the
+ * bundle at `npm run build` / `vite build` time and does not change at
+ * runtime. Updating the catalog requires bumping the `@openhands/extensions`
+ * dependency and rebuilding.
+ */
+const PUBLIC_SKILLS: SkillInfo[] = SKILLS_CATALOG.map(catalogEntryToSkillInfo);
+
+class SkillsService {
+  static async getSkills(projectDir?: string): Promise<SkillInfo[]> {
+    if (getActiveBackend().backend.kind === "cloud") {
+      return fetchCloudSkills();
+    }
+
+    // Public skills come from the bundled @openhands/extensions npm package —
+    // no agent-server round-trip or GitHub fetch needed. Only ask the agent-
+    // server for user and project skills so local .agents/skills/ content is
+    // still picked up.
+    let localSkills: SkillInfo[] = [];
+    try {
+      const response = await new SkillsClient(
+        getAgentServerClientOptions(),
+      ).getSkills({
+        load_public: false,
+        load_user: true,
+        load_project: true,
+        load_org: false,
+        project_dir: projectDir ?? getAgentServerWorkingDir(),
+      });
+      localSkills = (response.skills ?? []) as SkillInfo[];
+    } catch {
+      // Agent-server may not support the skills endpoint or may be
+      // unreachable; fall back to the bundled public catalog alone.
+    }
+
+    return [...localSkills, ...PUBLIC_SKILLS];
+  }
+
+  /**
+   * Skills loaded into a running cloud conversation (see
+   * `fetchCloudConversationSkills`). Cloud-only: local conversations keep
+   * using `getSkills(projectDir)`, whose agent-server call already scopes to
+   * the conversation's workspace.
+   */
+  static getConversationSkills(conversationId: string): Promise<SkillInfo[]> {
+    return fetchCloudConversationSkills(conversationId);
+  }
+}
+
+export default SkillsService;

src/api/with-retry.ts

@@ -0,0 +1,26 @@
+/**
+ * Retry helper for API calls with exponential backoff.
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  maxRetries: number = 3,
+  baseDelayMs: number = 500,
+): Promise<T> {
+  for (let attempt = 0; attempt < maxRetries; attempt += 1) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (attempt >= maxRetries - 1) {
+        throw error;
+      }
+
+      const delay = baseDelayMs * 2 ** attempt;
+
+      await new Promise<void>((resolve) => {
+        setTimeout(resolve, delay);
+      });
+    }
+  }
+
+  throw new Error("Retry attempts exhausted");
+}

src/api/workspace-path-resolution.test.ts

@@ -0,0 +1,189 @@
+import { describe, expect, it, vi } from "vitest";
+
+const {
+  fileClientConstructorMock,
+  getAgentServerClientOptionsMock,
+  getHomeMock,
+} = vi.hoisted(() => ({
+  fileClientConstructorMock: vi.fn(),
+  getAgentServerClientOptionsMock: vi.fn(),
+  getHomeMock: vi.fn(),
+}));
+
+vi.mock("@openhands/typescript-client/clients", () => ({
+  FileClient: class {
+    constructor(options: unknown) {
+      fileClientConstructorMock(options);
+    }
+
+    getHome() {
+      return getHomeMock();
+    }
+  },
+}));
+
+vi.mock("./agent-server-client-options", () => ({
+  getAgentServerClientOptions: getAgentServerClientOptionsMock,
+}));
+
+import {
+  clearAgentServerHomeDirCache,
+  getAgentServerHomeDir,
+  resolveAbsoluteAgentServerPath,
+} from "./agent-server-home";
+
+const defaultClientOptions = {
+  host: "https://agent.example.com",
+  apiKey: "agent-key",
+  workingDir: "workspace/project",
+};
+
+function arrangeHomeLookup(): void {
+  clearAgentServerHomeDirCache();
+  vi.resetAllMocks();
+  getAgentServerClientOptionsMock.mockReturnValue(defaultClientOptions);
+}
+
+describe("agent-server workspace path resolution", () => {
+  it("looks up the server home with the resolved client options and normalizes its separator", async () => {
+    arrangeHomeLookup();
+    getHomeMock.mockResolvedValue({ home: "/Users/alice///" });
+    const overrides = {
+      conversationUrl: "wss://runtime.example.com/conversations/1",
+      sessionApiKey: "session-key",
+    };
+
+    await expect(getAgentServerHomeDir(overrides)).resolves.toBe(
+      "/Users/alice",
+    );
+
+    expect(getAgentServerClientOptionsMock).toHaveBeenCalledWith(overrides);
+    expect(fileClientConstructorMock).toHaveBeenCalledWith(
+      defaultClientOptions,
+    );
+    expect(getHomeMock).toHaveBeenCalledOnce();
+  });
+
+  it("shares one in-flight home lookup between callers for the same host", async () => {
+    arrangeHomeLookup();
+    getHomeMock.mockResolvedValue({ home: "/home/agent" });
+
+    await expect(
+      Promise.all([getAgentServerHomeDir(), getAgentServerHomeDir()]),
+    ).resolves.toEqual(["/home/agent", "/home/agent"]);
+
+    expect(getHomeMock).toHaveBeenCalledOnce();
+  });
+
+  it("caches home directories independently for each agent-server host", async () => {
+    arrangeHomeLookup();
+    getAgentServerClientOptionsMock.mockImplementation(
+      (overrides: { host?: string } = {}) => ({
+        ...defaultClientOptions,
+        host: overrides.host ?? defaultClientOptions.host,
+      }),
+    );
+    getHomeMock
+      .mockResolvedValueOnce({ home: "/home/first" })
+      .mockResolvedValueOnce({ home: "/home/second" });
+
+    await expect(
+      Promise.all([
+        getAgentServerHomeDir({ host: "https://first.example.com" }),
+        getAgentServerHomeDir({ host: "https://second.example.com" }),
+      ]),
+    ).resolves.toEqual(["/home/first", "/home/second"]);
+    await expect(
+      getAgentServerHomeDir({ host: "https://first.example.com" }),
+    ).resolves.toBe("/home/first");
+
+    expect(getHomeMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("retries a home lookup after a transient failure", async () => {
+    arrangeHomeLookup();
+    getHomeMock
+      .mockRejectedValueOnce(new Error("agent server unavailable"))
+      .mockResolvedValueOnce({ home: "/home/recovered" });
+
+    await expect(getAgentServerHomeDir()).rejects.toThrow(
+      "agent server unavailable",
+    );
+    await expect(getAgentServerHomeDir()).resolves.toBe("/home/recovered");
+
+    expect(getHomeMock).toHaveBeenCalledTimes(2);
+  });
+
+  it.each([undefined, null, "", 0, 42])(
+    "rejects an invalid home directory response (%s)",
+    async (home) => {
+      arrangeHomeLookup();
+      getHomeMock.mockResolvedValue({ home });
+
+      await expect(getAgentServerHomeDir()).rejects.toThrow(
+        "Agent server returned an empty home directory",
+      );
+    },
+  );
+
+  it("clears a successful cached lookup on request", async () => {
+    arrangeHomeLookup();
+    getHomeMock
+      .mockResolvedValueOnce({ home: "/home/first" })
+      .mockResolvedValueOnce({ home: "/home/refreshed" });
+
+    await expect(getAgentServerHomeDir()).resolves.toBe("/home/first");
+    clearAgentServerHomeDirCache();
+    await expect(getAgentServerHomeDir()).resolves.toBe("/home/refreshed");
+
+    expect(getHomeMock).toHaveBeenCalledTimes(2);
+  });
+
+  it.each([
+    ["/workspace/project///", "/workspace/project"],
+    ["C:\\workspace\\project\\", "C:\\workspace\\project"],
+    ["D:/workspace/project///", "D:/workspace/project"],
+    ["\\\\server\\share\\", "\\\\server\\share"],
+  ])(
+    "keeps the absolute path %s without a home lookup",
+    async (path, expected) => {
+      arrangeHomeLookup();
+
+      await expect(resolveAbsoluteAgentServerPath(path)).resolves.toBe(
+        expected,
+      );
+
+      expect(getAgentServerClientOptionsMock).not.toHaveBeenCalled();
+      expect(getHomeMock).not.toHaveBeenCalled();
+    },
+  );
+
+  it.each(["", "/", "\\", "///", "\\\\"])(
+    "resolves an empty path (%s) to the server home",
+    async (path) => {
+      arrangeHomeLookup();
+      getHomeMock.mockResolvedValue({ home: "/home/agent/" });
+
+      await expect(resolveAbsoluteAgentServerPath(path)).resolves.toBe(
+        "/home/agent",
+      );
+
+      expect(getHomeMock).toHaveBeenCalledOnce();
+    },
+  );
+
+  it("anchors a relative workspace below the server home", async () => {
+    arrangeHomeLookup();
+    getHomeMock.mockResolvedValue({ home: "/Users/alice///" });
+    const overrides = {
+      host: "https://runtime.example.com/",
+      sessionApiKey: "session-key",
+    };
+
+    await expect(
+      resolveAbsoluteAgentServerPath("workspace/project///", overrides),
+    ).resolves.toBe("/Users/alice/workspace/project");
+
+    expect(getAgentServerClientOptionsMock).toHaveBeenCalledWith(overrides);
+  });
+});

src/api/workspace-upload-path.ts

@@ -0,0 +1,99 @@
+// @spec WUP-001 — Resolve relative working dirs against /api/file/home
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import { getAgentServerWorkingDir } from "#/api/agent-server-config";
+import {
+  type AgentServerClientOverrides,
+  getAgentServerClientOptions,
+} from "#/api/agent-server-client-options";
+import { resolveAbsoluteAgentServerPath } from "#/api/agent-server-home";
+import { getStoredConversationMetadata } from "#/api/conversation-metadata-store";
+import type { AppConversation } from "#/api/conversation-service/agent-server-conversation-service.types";
+
+const UUID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export function getSafeUploadFileName(fileName: string): string {
+  const parts = fileName.split(/[\\/]+/).filter(Boolean);
+  const safeName = parts[parts.length - 1];
+
+  if (!safeName || safeName === "." || safeName === "..") {
+    throw new Error("Invalid file name");
+  }
+
+  return safeName;
+}
+
+/**
+ * Resolve `workingDir` to an absolute path the agent-server's file APIs
+ * accept. Relative paths are joined against `/api/file/home` (cached per
+ * backend); absolute paths pass through.
+ */
+export async function resolveAbsoluteWorkspacePath(
+  workingDir: string,
+  overrides: AgentServerClientOverrides = {},
+): Promise<string> {
+  return resolveAbsoluteAgentServerPath(workingDir, overrides);
+}
+
+/**
+ * Build the absolute destination path for a file upload, resolving the
+ * working-dir leg via {@link resolveAbsoluteWorkspacePath}.
+ */
+export async function buildWorkspaceUploadPath(
+  fileName: string,
+  workingDir: string,
+  overrides: AgentServerClientOverrides = {},
+): Promise<string> {
+  const safeName = getSafeUploadFileName(fileName);
+  const absoluteDir = await resolveAbsoluteWorkspacePath(workingDir, overrides);
+  return `${absoluteDir.replace(/[/\\]+$/, "")}/${safeName}`;
+}
+
+/**
+ * Resolve the working directory for a file upload into a conversation's
+ * workspace.
+ *
+ * **Returns the raw working dir string** — which may be relative (e.g.
+ * `workspace/project/<hex>`) when the default `DEFAULT_WORKING_DIR` is in
+ * use. Callers that need an actual filesystem-absolute path (e.g. to pass to
+ * the agent-server's `/api/file/upload` endpoint) **must** funnel this result
+ * through {@link buildWorkspaceUploadPath}, which calls
+ * {@link resolveAbsoluteWorkspacePath} to anchor any relative segment against
+ * the agent-server's home directory.
+ *
+ * Why not resolve here? Because this function is also called by cloud-runtime
+ * upload paths where the overrides (conversationUrl, sessionApiKey) aren't
+ * available until {@link uploadFilesToConversation} assembles them. Keeping
+ * the resolution step in {@link buildWorkspaceUploadPath} means both the
+ * local and cloud legs share a single resolution point with the correct
+ * override context.
+ */
+export async function resolveConversationUploadWorkingDir(
+  conversationId: string,
+  currentConversation?: AppConversation | null,
+): Promise<string> {
+  if (
+    currentConversation?.id === conversationId &&
+    currentConversation.workspace?.working_dir?.trim()
+  ) {
+    return currentConversation.workspace.working_dir.trim();
+  }
+
+  const stored = getStoredConversationMetadata(conversationId);
+  if (stored?.selected_workspace?.trim()) {
+    return stored.selected_workspace.trim();
+  }
+
+  if (UUID_PATTERN.test(conversationId)) {
+    return AgentServerConversationService.resolveConversationWorkingDir(
+      conversationId,
+    );
+  }
+
+  return getAgentServerWorkingDir();
+}
+
+// Re-export so callers can construct overrides matching what
+// {@link buildWorkspaceUploadPath} expects without importing two modules.
+export type { AgentServerClientOverrides };
+export { getAgentServerClientOptions };

src/dev/seed-pending-chat-preview.ts

@@ -0,0 +1,69 @@
+import { useOptimisticUserMessageStore } from "#/stores/optimistic-user-message-store";
+
+const PREVIEW_SENDING_TEXT = "can you review the readme";
+
+const PREVIEW_SENDING_MULTILINE_TEXT =
+  "can you review the readme and then update the contributing guide " +
+  "to match, making sure the setup steps and scripts are consistent " +
+  "across both files";
+
+const PREVIEW_ERROR_TEXT =
+  "here's a long message. here's a long message. here's a long message. " +
+  "here's a long message. here's a long message. here's a long message.";
+
+export function seedPendingChatPreview(conversationId: string): void {
+  const store = useOptimisticUserMessageStore.getState();
+  store.clearPendingMessages();
+
+  store.enqueuePendingMessage({
+    conversationId,
+    text: PREVIEW_SENDING_TEXT,
+  });
+
+  store.enqueuePendingMessage({
+    conversationId,
+    text: PREVIEW_SENDING_MULTILINE_TEXT,
+  });
+
+  const errorId = store.enqueuePendingMessage({
+    conversationId,
+    text: PREVIEW_ERROR_TEXT,
+  });
+  store.markPendingMessageError(errorId, "Failed to send message");
+}
+
+export function installPendingChatPreview(): void {
+  (
+    window as Window &
+      typeof globalThis & {
+        __OH_SEED_PENDING_PREVIEW__?: typeof seedPendingChatPreview;
+        __OH_CLEAR_PENDING_PREVIEW__?: () => void;
+      }
+  ).__OH_SEED_PENDING_PREVIEW__ = seedPendingChatPreview;
+  (
+    window as Window &
+      typeof globalThis & {
+        __OH_CLEAR_PENDING_PREVIEW__?: () => void;
+      }
+  ).__OH_CLEAR_PENDING_PREVIEW__ = () => {
+    useOptimisticUserMessageStore.getState().clearPendingMessages();
+  };
+
+  const params = new URLSearchParams(window.location.search);
+  const preview = params.get("previewPendingChat");
+  if (!preview) {
+    return;
+  }
+
+  const conversationId = preview === "true" ? "1" : preview;
+  const targetPath = `/conversations/${conversationId}`;
+
+  if (!window.location.pathname.startsWith(targetPath)) {
+    window.location.assign(
+      `${targetPath}?previewPendingChat=${encodeURIComponent(conversationId)}`,
+    );
+    return;
+  }
+
+  seedPendingChatPreview(conversationId);
+}

src/fixtures/canvas-demo-conversation.ts

@@ -0,0 +1,131 @@
+/**
+ * Generated-canvas demo fixture — models an agent creating a Markdown artifact
+ * so mock mode can demonstrate chat-to-drawer file navigation without an LLM.
+ */
+import type {
+  ActionEvent,
+  MessageEvent,
+  ObservationEvent,
+  OpenHandsEvent,
+} from "#/types/agent-server/core";
+import { SecurityRisk } from "#/types/agent-server/core";
+import type { FileEditorAction } from "#/types/agent-server/core/base/action";
+import type { FileEditorObservation } from "#/types/agent-server/core/base/observation";
+
+export const CANVAS_DEMO_CONVERSATION_ID = "canvas-demo";
+export const CANVAS_DEMO_FILE_PATH = "canvas.md";
+
+export const CANVAS_DEMO_MARKDOWN = [
+  "# Agent Canvas Demo",
+  "",
+  "This report was generated by the agent and opened from the file chip in chat.",
+  "",
+  "## Release snapshot",
+  "",
+  "| Area | Status | Next step |",
+  "| --- | --- | --- |",
+  "| Conversation UX | Ready | Validate the drawer flow |",
+  "| Markdown preview | Ready | Review rich rendering |",
+  "| Accessibility | Ready | Confirm keyboard navigation |",
+  "",
+  "## Highlights",
+  "",
+  "- The artifact stays in the conversation workspace.",
+  "- The chat chip is the compact entry point.",
+  "- The Files drawer provides the full rich Markdown view.",
+].join("\n");
+
+const BASE_TIME = Date.UTC(2026, 6, 29, 12, 0, 0);
+const timestamp = (offsetSeconds: number) =>
+  new Date(BASE_TIME + offsetSeconds * 1000).toISOString();
+
+/**
+ * Creates a minimal message event with the same SDK shape used by history.
+ */
+function createMessage(
+  id: string,
+  role: "user" | "assistant",
+  text: string,
+  offsetSeconds: number,
+): MessageEvent {
+  return {
+    id,
+    timestamp: timestamp(offsetSeconds),
+    source: role === "user" ? "user" : "agent",
+    llm_message: {
+      role,
+      content: [{ type: "text", text }],
+    },
+    activated_skills: [],
+    extended_content: [],
+  };
+}
+
+const createCanvasAction: ActionEvent<FileEditorAction> = {
+  id: "canvas-demo-action",
+  timestamp: timestamp(1),
+  source: "agent",
+  thought: [],
+  thinking_blocks: [],
+  action: {
+    kind: "FileEditorAction",
+    command: "create",
+    path: CANVAS_DEMO_FILE_PATH,
+    file_text: CANVAS_DEMO_MARKDOWN,
+    old_str: null,
+    new_str: null,
+    insert_line: null,
+    view_range: null,
+  },
+  tool_name: "file_editor",
+  tool_call_id: "canvas-demo-tool-call",
+  tool_call: {
+    id: "canvas-demo-tool-call",
+    type: "function",
+    function: {
+      name: "file_editor",
+      arguments: JSON.stringify({
+        command: "create",
+        path: CANVAS_DEMO_FILE_PATH,
+      }),
+    },
+  },
+  llm_response_id: "canvas-demo-response",
+  security_risk: SecurityRisk.LOW,
+};
+
+const createCanvasObservation: ObservationEvent<FileEditorObservation> = {
+  id: "canvas-demo-observation",
+  timestamp: timestamp(2),
+  source: "environment",
+  tool_name: "file_editor",
+  tool_call_id: "canvas-demo-tool-call",
+  action_id: createCanvasAction.id,
+  observation: {
+    kind: "FileEditorObservation",
+    command: "create",
+    output: `Created ${CANVAS_DEMO_FILE_PATH}`,
+    path: CANVAS_DEMO_FILE_PATH,
+    prev_exist: false,
+    old_content: null,
+    new_content: CANVAS_DEMO_MARKDOWN,
+    error: null,
+  },
+};
+
+export const CANVAS_DEMO_EVENTS: OpenHandsEvent[] = [
+  createMessage(
+    "canvas-demo-user",
+    "user",
+    "Create a concise project canvas as a Markdown report.",
+    0,
+  ),
+  createCanvasAction,
+  createCanvasObservation,
+  createMessage(
+    "canvas-demo-agent",
+    "assistant",
+    "I generated the project canvas. Open it from the file chip above.",
+    3,
+  ),
+];

src/fixtures/home-automations-demo.ts

@@ -0,0 +1,478 @@
+import {
+  AUTOMATION_RUN_ACTIVITY_LIMIT,
+  type LatestAutomationRunState,
+} from "#/hooks/query/use-latest-automation-runs";
+import {
+  AutomationRunStatus,
+  type Automation,
+  type AutomationRun,
+} from "#/types/automation";
+
+/** Must stay equal to `MAX_HOME_AUTOMATION_CHIPS` in use-home-automations. */
+const DEMO_LIST_LENGTH = 20;
+
+const DEMO_HISTORY_PATTERN: AutomationRunStatus[] = [
+  AutomationRunStatus.COMPLETED,
+  AutomationRunStatus.COMPLETED,
+  AutomationRunStatus.FAILED,
+  AutomationRunStatus.COMPLETED,
+  AutomationRunStatus.CANCELLED,
+  AutomationRunStatus.COMPLETED,
+  AutomationRunStatus.COMPLETED,
+  AutomationRunStatus.FAILED,
+  AutomationRunStatus.COMPLETED,
+  AutomationRunStatus.SKIPPED,
+  AutomationRunStatus.COMPLETED,
+];
+
+/**
+ * Local preview of every pinned-card + activity-list state.
+ *
+ * Enable with either:
+ * - `HOME_AUTOMATIONS_FORCE_DEMO = true` below
+ * - `VITE_HOME_AUTOMATIONS_DEMO=true`
+ */
+export const HOME_AUTOMATIONS_FORCE_DEMO = false;
+
+export const HOME_AUTOMATIONS_DEMO_KEY = "oh:home-automations-demo";
+
+export function isHomeAutomationsDemoEnabled(): boolean {
+  if (HOME_AUTOMATIONS_FORCE_DEMO) return true;
+  return import.meta.env.VITE_HOME_AUTOMATIONS_DEMO === "true";
+}
+
+const DEMO_CONVERSATION_TITLES: Record<string, string | null> = {
+  "demo-conv-titled": "Fix flaky CI on main",
+  "demo-conv-untitled": "Summarize open pull requests",
+};
+
+/** Returns a demo conversation title, or `undefined` if not a demo id. */
+export function getDemoConversationTitle(
+  conversationId: string,
+): string | null | undefined {
+  if (!(conversationId in DEMO_CONVERSATION_TITLES)) return undefined;
+  return DEMO_CONVERSATION_TITLES[conversationId];
+}
+
+function hoursAgo(hours: number): string {
+  return new Date(Date.now() - hours * 3_600_000).toISOString();
+}
+
+function makeAutomation(
+  id: string,
+  name: string,
+  trigger: Automation["trigger"],
+): Automation {
+  return {
+    id,
+    name,
+    trigger,
+    enabled: true,
+    created_at: hoursAgo(720),
+    updated_at: hoursAgo(24),
+    prompt: "demo",
+  };
+}
+
+function makeRun(
+  id: string,
+  status: AutomationRunStatus,
+  options: {
+    conversationId?: string | null;
+    errorDetail?: string | null;
+    startedHoursAgo?: number;
+    completedHoursAgo?: number | null;
+  } = {},
+): AutomationRun {
+  const startedHoursAgo = options.startedHoursAgo ?? 2;
+  const completedHoursAgo =
+    options.completedHoursAgo === undefined ? 1 : options.completedHoursAgo;
+  return {
+    id,
+    status,
+    conversation_id:
+      options.conversationId === undefined ? null : options.conversationId,
+    bash_command_id: null,
+    error_detail:
+      options.errorDetail === undefined ? null : options.errorDetail,
+    started_at: hoursAgo(startedHoursAgo),
+    completed_at:
+      completedHoursAgo === null ? null : hoursAgo(completedHoursAgo),
+  };
+}
+
+type DemoRunStateInput = Omit<LatestAutomationRunState, "recentRuns"> & {
+  recentRuns?: AutomationRun[];
+};
+
+type DemoSpec = {
+  automation: Automation;
+  runState: DemoRunStateInput;
+  /** When true, this automation is pinned in the dashboard. */
+  pin?: boolean;
+};
+
+function buildDemoRecentRuns(latestRun: AutomationRun | null): AutomationRun[] {
+  if (!latestRun) return [];
+  // Varied durations (minutes) so sparkline bar heights differ in demo mode.
+  const durationMinutes = [2, 8, 45, 3, 15, 1, 25, 90, 5, 12, 6];
+  const older = DEMO_HISTORY_PATTERN.slice(
+    0,
+    AUTOMATION_RUN_ACTIVITY_LIMIT - 1,
+  ).map((status, index) => {
+    const startedHoursAgo = 24 + index * 6;
+    const durationHours = (durationMinutes[index] ?? 5) / 60;
+    return makeRun(`${latestRun.id}-hist-${index}`, status, {
+      startedHoursAgo,
+      completedHoursAgo: startedHoursAgo - durationHours,
+      conversationId: null,
+      errorDetail:
+        status === AutomationRunStatus.FAILED ? "Prior failure" : null,
+    });
+  });
+  return [latestRun, ...older];
+}
+
+function toDemoRunState(state: DemoRunStateInput): LatestAutomationRunState {
+  return {
+    ...state,
+    recentRuns: state.recentRuns ?? buildDemoRecentRuns(state.latestRun),
+  };
+}
+
+/**
+ * Explicit card states first (pinned), then fillers to hit
+ * DEMO_LIST_LENGTH for list-length stress.
+ */
+const DEMO_SPECS: DemoSpec[] = [
+  {
+    pin: true,
+    automation: makeAutomation("demo-pin-loading", "Card: loading skeleton", {
+      type: "cron",
+      schedule: "0 * * * *",
+      schedule_human: "Every hour",
+    }),
+    runState: { latestRun: null, isLoading: true, isError: false },
+  },
+  {
+    pin: true,
+    automation: makeAutomation("demo-pin-error", "Card: status unavailable", {
+      type: "cron",
+      schedule: "0 9 * * *",
+      schedule_human: "Daily at 9am",
+    }),
+    runState: { latestRun: null, isLoading: false, isError: true },
+  },
+  {
+    pin: true,
+    automation: makeAutomation("demo-pin-no-runs", "Card: no runs yet", {
+      type: "event",
+      source: "github",
+      on: "pull_request.opened",
+    }),
+    runState: { latestRun: null, isLoading: false, isError: false },
+  },
+  {
+    pin: true,
+    automation: makeAutomation(
+      "demo-pin-failed-detail",
+      "Card: failed with error detail",
+      {
+        type: "cron",
+        schedule: "*/15 * * * *",
+        schedule_human: "Every 15 min",
+      },
+    ),
+    runState: {
+      latestRun: makeRun("run-failed-detail", AutomationRunStatus.FAILED, {
+        errorDetail:
+          "Sandbox provisioning timed out after 120s while waiting for the runtime to become ready.",
+        startedHoursAgo: 3,
+        completedHoursAgo: 2.5,
+      }),
+      isLoading: false,
+      isError: false,
+    },
+  },
+  {
+    pin: true,
+    automation: makeAutomation(
+      "demo-pin-completed-title",
+      "Card: completed + conversation title",
+      { type: "event", source: "github", on: "push" },
+    ),
+    runState: {
+      latestRun: makeRun("run-completed-title", AutomationRunStatus.COMPLETED, {
+        conversationId: "demo-conv-titled",
+        startedHoursAgo: 5,
+        completedHoursAgo: 4,
+      }),
+      isLoading: false,
+      isError: false,
+    },
+  },
+  {
+    pin: true,
+    automation: makeAutomation(
+      "demo-pin-completed-untitled",
+      "Card: completed + conversation title",
+      {
+        type: "cron",
+        schedule: "0 0 * * 1",
+        schedule_human: "Mondays at midnight",
+      },
+    ),
+    runState: {
+      latestRun: makeRun(
+        "run-completed-untitled",
+        AutomationRunStatus.COMPLETED,
+        {
+          conversationId: "demo-conv-untitled",
+          startedHoursAgo: 8,
+          completedHoursAgo: 7,
+        },
+      ),
+      isLoading: false,
+      isError: false,
+    },
+  },
+  {
+    pin: true,
+    automation: makeAutomation(
+      "demo-pin-completed-no-conv",
+      "Card: completed, no conversation",
+      { type: "cron", schedule: "0 12 * * *", schedule_human: "Daily at noon" },
+    ),
+    runState: {
+      latestRun: makeRun(
+        "run-completed-no-conv",
+        AutomationRunStatus.COMPLETED,
+        {
+          conversationId: null,
+          startedHoursAgo: 10,
+          completedHoursAgo: 9,
+        },
+      ),
+      isLoading: false,
+      isError: false,
+    },
+  },
+  {
+    pin: true,
+    automation: makeAutomation(
+      "demo-pin-failed-no-conv",
+      "Card: failed, no conversation",
+      { type: "event", source: "slack", on: "message" },
+    ),
+    runState: {
+      latestRun: makeRun("run-failed-no-conv", AutomationRunStatus.FAILED, {
+        conversationId: null,
+        errorDetail: null,
+        startedHoursAgo: 12,
+        completedHoursAgo: 11,
+      }),
+      isLoading: false,
+      isError: false,
+    },
+  },
+  {
+    pin: true,
+    automation: makeAutomation(
+      "demo-pin-pending",
+      "Card: pending (empty result panel)",
+      {
+        type: "cron",
+        schedule: "0 */6 * * *",
+        schedule_human: "Every 6 hours",
+      },
+    ),
+    runState: {
+      latestRun: makeRun("run-pending", AutomationRunStatus.PENDING, {
+        conversationId: null,
+        startedHoursAgo: 0.1,
+        completedHoursAgo: null,
+      }),
+      isLoading: false,
+      isError: false,
+    },
+  },
+  {
+    pin: true,
+    automation: makeAutomation(
+      "demo-pin-running",
+      "Card: running (empty result panel)",
+      { type: "event", source: "github", on: "issues.opened" },
+    ),
+    runState: {
+      latestRun: makeRun("run-running", AutomationRunStatus.RUNNING, {
+        // No conversation yet — status strip shows the "Running" label.
+        conversationId: null,
+        startedHoursAgo: 0.25,
+        completedHoursAgo: null,
+      }),
+      isLoading: false,
+      isError: false,
+    },
+  },
+  // Remaining rows fill the list to MAX_HOME_AUTOMATION_CHIPS.
+  {
+    automation: makeAutomation("demo-list-cancelled", "List: cancelled run", {
+      type: "cron",
+      schedule: "30 2 * * *",
+      schedule_human: "Daily at 2:30am",
+    }),
+    runState: {
+      latestRun: makeRun("run-cancelled", AutomationRunStatus.CANCELLED, {
+        startedHoursAgo: 14,
+        completedHoursAgo: 13,
+      }),
+      isLoading: false,
+      isError: false,
+    },
+  },
+  {
+    automation: makeAutomation("demo-list-skipped", "List: skipped run", {
+      type: "event",
+      source: "github",
+      on: "pull_request.synchronize",
+    }),
+    runState: {
+      latestRun: makeRun("run-skipped", AutomationRunStatus.SKIPPED, {
+        startedHoursAgo: 16,
+        completedHoursAgo: 16,
+      }),
+      isLoading: false,
+      isError: false,
+    },
+  },
+  {
+    automation: makeAutomation(
+      "demo-list-running-2",
+      "List: second in-flight run",
+      { type: "cron", schedule: "*/5 * * * *", schedule_human: "Every 5 min" },
+    ),
+    runState: {
+      latestRun: makeRun("run-running-2", AutomationRunStatus.RUNNING, {
+        conversationId: null,
+        startedHoursAgo: 0.5,
+        completedHoursAgo: null,
+      }),
+      isLoading: false,
+      isError: false,
+    },
+  },
+  {
+    automation: makeAutomation("demo-list-success-old", "List: older success", {
+      type: "cron",
+      schedule: "0 8 * * 1-5",
+      schedule_human: "Weekdays at 8am",
+    }),
+    runState: {
+      latestRun: makeRun("run-success-old", AutomationRunStatus.COMPLETED, {
+        conversationId: "demo-conv-titled",
+        startedHoursAgo: 48,
+        completedHoursAgo: 47,
+      }),
+      isLoading: false,
+      isError: false,
+    },
+  },
+  {
+    automation: makeAutomation("demo-list-failed-old", "List: older failure", {
+      type: "event",
+      source: "github",
+      on: "release.published",
+    }),
+    runState: {
+      latestRun: makeRun("run-failed-old", AutomationRunStatus.FAILED, {
+        errorDetail: "Model returned an empty completion.",
+        startedHoursAgo: 72,
+        completedHoursAgo: 71,
+      }),
+      isLoading: false,
+      isError: false,
+    },
+  },
+  {
+    automation: makeAutomation("demo-list-no-runs-2", "List: never ran", {
+      type: "cron",
+      schedule: "0 0 1 * *",
+      schedule_human: "Monthly on the 1st",
+    }),
+    runState: { latestRun: null, isLoading: false, isError: false },
+  },
+  {
+    automation: makeAutomation("demo-list-loading-2", "List: loading status", {
+      type: "event",
+      source: "linear",
+      on: "Issue.create",
+    }),
+    runState: { latestRun: null, isLoading: true, isError: false },
+  },
+  {
+    automation: makeAutomation("demo-list-error-2", "List: fetch error", {
+      type: "cron",
+      schedule: "15 * * * *",
+      schedule_human: "Hourly at :15",
+    }),
+    runState: { latestRun: null, isLoading: false, isError: true },
+  },
+  {
+    automation: makeAutomation(
+      "demo-list-pending-2",
+      "List: pending, long name that should truncate in the activity row when the viewport is narrow",
+      { type: "cron", schedule: "0 3 * * 0", schedule_human: "Sundays at 3am" },
+    ),
+    runState: {
+      latestRun: makeRun("run-pending-2", AutomationRunStatus.PENDING, {
+        startedHoursAgo: 0.05,
+        completedHoursAgo: null,
+      }),
+      isLoading: false,
+      isError: false,
+    },
+  },
+  {
+    automation: makeAutomation(
+      "demo-list-completed-fallback",
+      "List: completed with conversation",
+      { type: "event", source: "github", on: "workflow_run.completed" },
+    ),
+    runState: {
+      latestRun: makeRun(
+        "run-completed-fallback",
+        AutomationRunStatus.COMPLETED,
+        {
+          conversationId: "demo-conv-untitled",
+          startedHoursAgo: 20,
+          completedHoursAgo: 19,
+        },
+      ),
+      isLoading: false,
+      isError: false,
+    },
+  },
+];
+
+if (DEMO_SPECS.length !== DEMO_LIST_LENGTH) {
+  throw new Error(
+    `home-automations-demo: expected ${DEMO_LIST_LENGTH} specs, got ${DEMO_SPECS.length}`,
+  );
+}
+
+export const HOME_AUTOMATIONS_DEMO_PINNED_IDS: string[] = DEMO_SPECS.filter(
+  (spec) => spec.pin,
+).map((spec) => spec.automation.id);
+
+export const HOME_AUTOMATIONS_DEMO_AUTOMATIONS: Automation[] = DEMO_SPECS.map(
+  (spec) => spec.automation,
+);
+
+export const HOME_AUTOMATIONS_DEMO_RUN_STATES: Map<
+  string,
+  LatestAutomationRunState
+> = new Map(
+  DEMO_SPECS.map(
+    (spec) => [spec.automation.id, toDemoRunState(spec.runState)] as const,
+  ),
+);

src/fixtures/table-demo-conversation.ts

@@ -0,0 +1,58 @@
+import type { MessageEvent, OpenHandsEvent } from "#/types/agent-server/core";
+
+export const TABLE_DEMO_CONVERSATION_ID = "table-demo";
+
+const TABLE_DEMO_USER_MESSAGE =
+  "Can you compare several coding agents in a wide table?";
+
+/** Wide GFM table used to exercise horizontal scrolling in the chat feed. */
+export const TABLE_DEMO_AGENT_MARKDOWN = [
+  "Here is a wide comparison table. Scroll horizontally to read every column:",
+  "",
+  "| Feature | OpenHands | Claude Code | Codex | Gemini CLI | Cursor | Windsurf | Cline | Aider | Devin | Continue |",
+  "| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |",
+  "| CLI | Yes | Yes | Yes | Yes | IDE | IDE | IDE | Terminal | Cloud | IDE |",
+  "| MCP support | Yes | Yes | Partial | Partial | Yes | Yes | Yes | No | Yes | Yes |",
+  "| Local models | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | No | Yes |",
+  "| Browser tools | Yes | Yes | Yes | Limited | Yes | Yes | Yes | No | Yes | Yes |",
+  "| Git integration | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |",
+  "| Best for | General coding | Anthropic stack | OpenAI stack | Google stack | IDE users | IDE users | VS Code | Terminal | Autonomous | IDE users |",
+].join("\n");
+
+const TABLE_DEMO_BASE_TIME = Date.UTC(2026, 5, 23, 12, 0, 0);
+
+function createTableDemoMessageEvent(
+  id: string,
+  role: "user" | "assistant",
+  text: string,
+  offsetMinutes: number,
+): MessageEvent {
+  return {
+    id,
+    timestamp: new Date(
+      TABLE_DEMO_BASE_TIME + offsetMinutes * 60_000,
+    ).toISOString(),
+    source: role === "user" ? "user" : "agent",
+    llm_message: {
+      role,
+      content: [{ type: "text", text }],
+    },
+    activated_skills: [],
+    extended_content: [],
+  };
+}
+
+export const TABLE_DEMO_EVENTS: OpenHandsEvent[] = [
+  createTableDemoMessageEvent(
+    "table-demo-user-1",
+    "user",
+    TABLE_DEMO_USER_MESSAGE,
+    0,
+  ),
+  createTableDemoMessageEvent(
+    "table-demo-agent-1",
+    "assistant",
+    TABLE_DEMO_AGENT_MARKDOWN,
+    1,
+  ),
+];

src/hooks/use-acp-model-context.ts

@@ -0,0 +1,68 @@
+import { useTranslation } from "react-i18next";
+import { useActiveBackend } from "#/contexts/active-backend-context";
+import { useActiveConversation } from "#/hooks/query/use-active-conversation";
+import { useSettings } from "#/hooks/query/use-settings";
+import { useActiveAgentKind } from "#/hooks/use-active-agent-profile";
+import { I18nKey } from "#/i18n/declaration";
+
+const AGENT_SETTINGS_PATH = "/settings/agents";
+const LLM_SETTINGS_PATH = "/settings/llm";
+
+export interface AcpModelContext {
+  /** The active conversation runs an ACP agent. */
+  isActiveAcpConversation: boolean;
+  /**
+   * No active conversation (home page) but the saved agent settings already
+   * select an ACP agent — the next conversation created here inherits it, so
+   * the model UI should reflect that now.
+   */
+  isHomeAcp: boolean;
+  /** Either of the above: the model affordance should defer to the ACP picker. */
+  isAcpContext: boolean;
+  /** Where the model/settings link should navigate. */
+  destinationPath: typeof AGENT_SETTINGS_PATH | typeof LLM_SETTINGS_PATH;
+  /** Translated label for that link. */
+  destinationLabel: string;
+}
+
+/**
+ * Shared source of truth for "is this an ACP model context, and where does
+ * the model affordance link?". The chat model affordance consumes this through
+ * ``useChatInputModelState`` so inline and overflow surfaces can't drift on the
+ * home-page-ACP rule or on the destination path/label.
+ */
+export function useAcpModelContext(): AcpModelContext {
+  const { t } = useTranslation("openhands");
+  const { backend } = useActiveBackend();
+  const { data: conversation } = useActiveConversation();
+  const { data: settings } = useSettings();
+  const activeAgentKind = useActiveAgentKind();
+
+  const isActiveAcpConversation = conversation?.agent_kind === "acp";
+  // On the home page the "current agent" is the active AgentProfile, not the
+  // global agent settings (activate never writes them). Fall back to settings
+  // only while the profile list is loading.
+  const isHomeAcp =
+    !conversation &&
+    (activeAgentKind ?? settings?.agent_settings?.agent_kind) === "acp";
+  const isAcpContext = isActiveAcpConversation || isHomeAcp;
+
+  const destinationPath = isAcpContext
+    ? AGENT_SETTINGS_PATH
+    : LLM_SETTINGS_PATH;
+  const destinationLabel = t(
+    isAcpContext
+      ? I18nKey.SETTINGS$NAV_AGENT
+      : backend.kind === "cloud"
+        ? I18nKey.SETTINGS$LLM_SETTINGS
+        : I18nKey.SETTINGS$LLM_PROFILES,
+  );
+
+  return {
+    isActiveAcpConversation,
+    isHomeAcp,
+    isAcpContext,
+    destinationPath,
+    destinationLabel,
+  };
+}

src/hooks/use-agent-notification.ts

@@ -0,0 +1,49 @@
+import { useEffect, useRef } from "react";
+import { AgentState } from "#/types/agent-state";
+import { useSettings } from "#/hooks/query/use-settings";
+import notificationSound from "#/assets/notification.mp3";
+
+const NOTIFICATION_STATES: AgentState[] = [
+  AgentState.AWAITING_USER_INPUT,
+  AgentState.FINISHED,
+  AgentState.AWAITING_USER_CONFIRMATION,
+];
+
+/**
+ * Hook that plays a notification sound when the agent transitions into a
+ * state that requires user attention. The browser tab title itself is
+ * managed by `useAppTitle`, which prefixes the title with an emoji that
+ * reflects the current agent state.
+ */
+export function useAgentNotification(curAgentState: AgentState) {
+  const { data: settings } = useSettings();
+  const audioRef = useRef<HTMLAudioElement | undefined>(undefined);
+  const prevStateRef = useRef<AgentState | undefined>(undefined);
+
+  // Initialize audio only in browser environment, inside useEffect to
+  // avoid side effects during render (React 18 strict mode, SSR safety).
+  useEffect(() => {
+    if (typeof window !== "undefined" && !audioRef.current) {
+      audioRef.current = new Audio(notificationSound);
+      audioRef.current.volume = 0.5;
+    }
+  }, []);
+
+  const isSoundEnabled = settings?.enable_sound_notifications ?? false;
+
+  // Trigger notification only on actual state transitions into a
+  // notification-worthy state — not when unrelated deps (e.g. settings) change.
+  useEffect(() => {
+    if (prevStateRef.current === curAgentState) return;
+    prevStateRef.current = curAgentState;
+
+    if (!NOTIFICATION_STATES.includes(curAgentState)) return;
+
+    if (isSoundEnabled && audioRef.current) {
+      audioRef.current.currentTime = 0;
+      audioRef.current.play().catch(() => {
+        // Ignore autoplay errors (browsers may block autoplay)
+      });
+    }
+  }, [curAgentState, isSoundEnabled]);
+}

src/hooks/use-app-title.test.tsx

@@ -0,0 +1,125 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { useParams } from "react-router";
+import { useUserConversation } from "./query/use-user-conversation";
+import { useAppTitle } from "./use-app-title";
+import { useConversationStateStore } from "#/stores/conversation-state-store";
+import { ExecutionStatus } from "#/types/agent-server/core/base/common";
+
+const renderAppTitleHook = () =>
+  renderHook(() => useAppTitle(), {
+    wrapper: ({ children }) => (
+      <QueryClientProvider client={new QueryClient()}>
+        {children}
+      </QueryClientProvider>
+    ),
+  });
+
+vi.mock("./query/use-user-conversation");
+vi.mock("react-router", async () => {
+  const actual = await vi.importActual("react-router");
+  return {
+    ...actual,
+    useParams: vi.fn(),
+  };
+});
+
+describe("useAppTitle", () => {
+  const mockUseUserConversation = vi.mocked(useUserConversation);
+  const mockUseParams = vi.mocked(useParams);
+
+  beforeEach(() => {
+    // @ts-expect-error - only returning partial config for test
+    mockUseUserConversation.mockReturnValue({ data: null });
+    mockUseParams.mockReturnValue({});
+    useConversationStateStore.getState().reset();
+  });
+
+  it("returns the OSS app title outside conversations", async () => {
+    const { result } = renderAppTitleHook();
+
+    await waitFor(() => expect(result.current).toBe("OpenHands"));
+  });
+
+  it("returns the conversation title with the OSS app name", async () => {
+    mockUseParams.mockReturnValue({ conversationId: "123" });
+    mockUseUserConversation.mockReturnValue({
+      // @ts-expect-error - only returning partial config for test
+      data: { title: "My Conversation" },
+    });
+
+    const { result } = renderAppTitleHook();
+
+    await waitFor(() =>
+      expect(result.current).toBe("My Conversation | OpenHands"),
+    );
+  });
+
+  it("returns the app name while conversation data is loading", async () => {
+    mockUseParams.mockReturnValue({ conversationId: "123" });
+    // @ts-expect-error - only returning partial config for test
+    mockUseUserConversation.mockReturnValue({ data: undefined });
+
+    const { result } = renderAppTitleHook();
+
+    await waitFor(() => expect(result.current).toBe("OpenHands"));
+  });
+
+  it.each([
+    [ExecutionStatus.RUNNING, "🟢"],
+    [ExecutionStatus.FINISHED, "✅"],
+    [ExecutionStatus.IDLE, "✅"],
+    [ExecutionStatus.WAITING_FOR_CONFIRMATION, "✅"],
+    [ExecutionStatus.PAUSED, "⚪"],
+    [ExecutionStatus.ERROR, "🔴"],
+    [ExecutionStatus.STUCK, "🔴"],
+  ])(
+    "prefixes the title with %s emoji for execution status %s",
+    async (status, emoji) => {
+      mockUseParams.mockReturnValue({ conversationId: "123" });
+      mockUseUserConversation.mockReturnValue({
+        // @ts-expect-error - only returning partial config for test
+        data: { title: "My Conversation" },
+      });
+      useConversationStateStore.getState().setExecutionStatus("123", status);
+
+      const { result } = renderAppTitleHook();
+
+      await waitFor(() =>
+        expect(result.current).toBe(`${emoji} My Conversation | OpenHands`),
+      );
+    },
+  );
+
+  it("falls back to the conversation's execution_status when the live store is empty", async () => {
+    mockUseParams.mockReturnValue({ conversationId: "123" });
+    mockUseUserConversation.mockReturnValue({
+      // @ts-expect-error - only returning partial config for test
+      data: {
+        title: "My Conversation",
+        execution_status: ExecutionStatus.RUNNING,
+      },
+    });
+
+    const { result } = renderAppTitleHook();
+
+    await waitFor(() =>
+      expect(result.current).toBe("🟢 My Conversation | OpenHands"),
+    );
+  });
+
+  it("does not add an emoji when in a conversation but execution status is unknown", async () => {
+    mockUseParams.mockReturnValue({ conversationId: "123" });
+    mockUseUserConversation.mockReturnValue({
+      // @ts-expect-error - only returning partial config for test
+      data: { title: "My Conversation" },
+    });
+
+    const { result } = renderAppTitleHook();
+
+    await waitFor(() =>
+      expect(result.current).toBe("My Conversation | OpenHands"),
+    );
+  });
+});

src/hooks/use-app-title.ts

@@ -0,0 +1,32 @@
+import { useParams } from "react-router";
+import { useUserConversation } from "#/hooks/query/use-user-conversation";
+import { useConversationStateStore } from "#/stores/conversation-state-store";
+import { getAgentStateEmoji } from "#/utils/agent-state-emoji";
+
+const APP_TITLE = "OpenHands";
+
+export const useAppTitle = () => {
+  const { conversationId } = useParams<{ conversationId: string }>();
+  const { data: conversation } = useUserConversation(conversationId ?? null);
+  const liveExecutionStatus = useConversationStateStore((state) =>
+    conversationId
+      ? (state.executionStatusByConversation[conversationId] ?? null)
+      : null,
+  );
+
+  const conversationTitle = conversation?.title;
+  const baseTitle =
+    conversationId && conversationTitle
+      ? `${conversationTitle} | ${APP_TITLE}`
+      : APP_TITLE;
+
+  if (!conversationId) {
+    return baseTitle;
+  }
+
+  const executionStatus =
+    liveExecutionStatus ?? conversation?.execution_status ?? null;
+  const emoji = getAgentStateEmoji(executionStatus);
+
+  return emoji ? `${emoji} ${baseTitle}` : baseTitle;
+};

src/hooks/use-auto-resize.ts

@@ -0,0 +1,379 @@
+import { useCallback, useEffect, RefObject, useRef } from "react";
+import { IMessageToSend } from "#/stores/conversation-store";
+import { EPS } from "#/utils/constants";
+import { getStyleHeightPx, setStyleHeightPx } from "#/utils/utils";
+import { focusContentEditableAtEnd } from "#/components/features/chat/utils/chat-input.utils";
+import { useDragResize } from "./use-drag-resize";
+
+// Constants
+const DEFAULT_MIN_HEIGHT = 20;
+const DEFAULT_MAX_HEIGHT = 120;
+const HEIGHT_INCREMENT = 20;
+const MANUAL_OVERSIZE_THRESHOLD = 50;
+
+// Manual height tracking utilities
+const useManualHeight = () => {
+  const hasUserResizedRef = useRef(false);
+  const manualHeightRef = useRef<number | null>(null);
+  return { hasUserResizedRef, manualHeightRef };
+};
+
+interface UseAutoResizeOptions {
+  minHeight?: number;
+  maxHeight?: number;
+  enableManualResize?: boolean;
+  onGripDragStart?: () => void;
+  onGripDragEnd?: () => void;
+  onHeightChange?: (height: number) => void; // New callback for height changes
+  value?: IMessageToSend;
+  /** Called once `value` has been applied to the element (one-shot consume). */
+  onValueApplied?: () => void;
+}
+
+interface UseAutoResizeReturn {
+  smartResize: () => void;
+  handleGripMouseDown: (e: React.MouseEvent) => void;
+  handleGripTouchStart: (e: React.TouchEvent) => void;
+  increaseHeightForEmptyContent: () => void;
+  resetManualResize: () => void;
+}
+
+// Height management utilities
+interface HeightConstraints {
+  minHeight: number;
+  maxHeight: number;
+}
+
+interface HeightMeasurements {
+  currentHeight: number;
+  currentStyleHeight: number;
+  contentHeight: number;
+}
+
+interface ResizeStrategy {
+  finalHeight: number;
+  overflowY: "hidden" | "auto";
+}
+
+const applyHeightToElement = (
+  element: HTMLElement,
+  height: number,
+  constraints: HeightConstraints,
+): number => {
+  const { minHeight, maxHeight } = constraints;
+  const finalHeight = Math.max(minHeight, Math.min(height, maxHeight));
+
+  element.style.setProperty("height", `${finalHeight}px`);
+  element.style.setProperty(
+    "overflow-y",
+    finalHeight >= maxHeight ? "auto" : "hidden",
+  );
+
+  return finalHeight;
+};
+
+const isManuallyOversized = (
+  currentHeight: number,
+  contentHeight: number,
+  threshold = MANUAL_OVERSIZE_THRESHOLD,
+): boolean => currentHeight > contentHeight + threshold;
+
+const measureElementHeights = (
+  element: HTMLElement,
+  minHeight: number,
+): HeightMeasurements => {
+  // Use the previous explicit style height as the "current" for restore, not offsetHeight
+  const currentStyleHeight = getStyleHeightPx(element, minHeight);
+  const currentHeight = currentStyleHeight;
+
+  // Temporarily reset to measure content
+  element.style.setProperty("height", "auto");
+  const contentHeight = element.scrollHeight;
+
+  // Restore height
+  setStyleHeightPx(element, currentStyleHeight);
+
+  return {
+    currentHeight,
+    currentStyleHeight,
+    contentHeight,
+  };
+};
+
+const applyResizeStrategy = (
+  element: HTMLElement,
+  strategy: ResizeStrategy,
+): void => {
+  const { finalHeight, overflowY } = strategy;
+  const elementRef = element;
+  elementRef.style.height = `${finalHeight}px`;
+  elementRef.style.overflowY = overflowY;
+};
+
+const executeHeightCallback = (
+  height: number,
+  onHeightChange?: (height: number) => void,
+): void => {
+  if (onHeightChange) {
+    onHeightChange(height);
+  }
+};
+
+// DOM manipulation utilities
+export const useAutoResize = (
+  elementRef: RefObject<HTMLElement | null>,
+  options: UseAutoResizeOptions = {},
+): UseAutoResizeReturn => {
+  const pendingSmartRef = useRef<number | null>(null);
+
+  const {
+    minHeight = DEFAULT_MIN_HEIGHT,
+    maxHeight = DEFAULT_MAX_HEIGHT,
+    enableManualResize = false,
+    value,
+    onValueApplied,
+    onGripDragStart,
+    onGripDragEnd,
+    onHeightChange,
+  } = options;
+
+  const constraints: HeightConstraints = { minHeight, maxHeight };
+  const { hasUserResizedRef, manualHeightRef } = useManualHeight();
+
+  const resetManualResize = () => {
+    hasUserResizedRef.current = false;
+    manualHeightRef.current = null;
+  };
+
+  // Wrap onHeightChange to track manual height during drag
+  const handleExternalHeightChange = useCallback(
+    (elementHeight: number) => {
+      onHeightChange?.(elementHeight);
+      if (hasUserResizedRef.current) {
+        manualHeightRef.current = elementHeight;
+      }
+    },
+    [onHeightChange],
+  );
+
+  // Handle drag start - set manual mode flag
+  const handleDragStart = useCallback(() => {
+    hasUserResizedRef.current = true;
+    onGripDragStart?.();
+  }, [onGripDragStart]);
+
+  // Handle drag end - clear manual mode if at minimum height
+  const handleDragEnd = useCallback(() => {
+    const textareaElement = elementRef.current;
+    if (textareaElement) {
+      const currentHeight = getStyleHeightPx(textareaElement, minHeight);
+      if (Math.abs(currentHeight - minHeight) <= EPS) {
+        hasUserResizedRef.current = false;
+        manualHeightRef.current = null;
+      }
+    }
+    onGripDragEnd?.();
+  }, [minHeight, onGripDragEnd]);
+
+  // Use the drag resize hook for manual resizing functionality
+  const { handleGripMouseDown, handleGripTouchStart } = useDragResize({
+    elementRef,
+    minHeight,
+    maxHeight,
+    onGripDragStart: enableManualResize ? handleDragStart : undefined,
+    onGripDragEnd: enableManualResize ? handleDragEnd : undefined,
+    onHeightChange: handleExternalHeightChange,
+  });
+
+  // Handle content that fits within current height
+  const handleContentFitsInCurrentHeight = useCallback(
+    (
+      element: HTMLElement,
+      currentHeight: number,
+      contentHeight: number,
+    ): void => {
+      // If user manually resized and we're above min height, preserve their chosen height
+      if (hasUserResizedRef.current && currentHeight > minHeight) {
+        applyResizeStrategy(element, {
+          finalHeight: currentHeight,
+          overflowY: "hidden",
+        });
+        executeHeightCallback(currentHeight, onHeightChange);
+        return;
+      }
+
+      // Otherwise allow shrinking towards content (respect minHeight)
+      const finalHeight = Math.max(contentHeight, minHeight);
+      applyResizeStrategy(element, {
+        finalHeight,
+        overflowY: "hidden",
+      });
+      executeHeightCallback(finalHeight, onHeightChange);
+    },
+    [minHeight, onHeightChange],
+  );
+
+  // Handle content that exceeds current height but within max height
+  const handleContentExceedsCurrentHeight = useCallback(
+    (
+      element: HTMLElement,
+      currentHeight: number,
+      contentHeight: number,
+    ): void => {
+      // Grow unless the element is manually oversized beyond content significantly
+      if (!isManuallyOversized(currentHeight, contentHeight)) {
+        const finalHeight = Math.max(contentHeight, minHeight);
+        applyResizeStrategy(element, {
+          finalHeight,
+          overflowY: "hidden",
+        });
+        executeHeightCallback(finalHeight, onHeightChange);
+        return;
+      }
+
+      // Keep manual height and allow scrolling as needed
+      applyResizeStrategy(element, {
+        finalHeight: currentHeight,
+        overflowY: "auto",
+      });
+      executeHeightCallback(currentHeight, onHeightChange);
+    },
+    [minHeight, onHeightChange],
+  );
+
+  // Handle content that exceeds max height
+  const handleContentExceedsMaxHeight = useCallback(
+    (element: HTMLElement) => {
+      applyResizeStrategy(element, {
+        finalHeight: maxHeight,
+        overflowY: "auto",
+      });
+      executeHeightCallback(maxHeight, onHeightChange);
+    },
+    [maxHeight, onHeightChange],
+  );
+
+  // Debounced smartResize body
+  const smartResizeBody = useCallback(() => {
+    const element = elementRef.current;
+    if (!element) return;
+
+    const textIsEmpty = (element.textContent ?? "").trim().length === 0;
+
+    // If empty content and we have a manual height above min, preserve it
+    if (
+      textIsEmpty &&
+      hasUserResizedRef.current &&
+      manualHeightRef.current &&
+      manualHeightRef.current > minHeight + EPS
+    ) {
+      setStyleHeightPx(element, manualHeightRef.current);
+      element.style.overflowY = "hidden";
+      executeHeightCallback(manualHeightRef.current, onHeightChange);
+      return;
+    }
+
+    // Measure element heights
+    const measurements = measureElementHeights(element, minHeight);
+    const { currentHeight, contentHeight } = measurements;
+
+    // If content fits within current height
+    if (contentHeight <= currentHeight) {
+      handleContentFitsInCurrentHeight(element, currentHeight, contentHeight);
+      return;
+    }
+
+    // If content exceeds current height but within max
+    if (contentHeight <= maxHeight) {
+      handleContentExceedsCurrentHeight(element, currentHeight, contentHeight);
+      return;
+    }
+
+    // Content exceeds max height
+    handleContentExceedsMaxHeight(element);
+  }, [
+    elementRef,
+    minHeight,
+    maxHeight,
+    onHeightChange,
+    handleContentFitsInCurrentHeight,
+    handleContentExceedsCurrentHeight,
+    handleContentExceedsMaxHeight,
+  ]);
+
+  // rAF-debounced smartResize wrapper to collapse bursts
+  const smartResize = useCallback(() => {
+    if (pendingSmartRef.current) cancelAnimationFrame(pendingSmartRef.current);
+    pendingSmartRef.current = requestAnimationFrame(() => {
+      pendingSmartRef.current = null;
+      smartResizeBody();
+    });
+  }, [smartResizeBody]);
+
+  // Function to increase height when content is empty
+  const increaseHeightForEmptyContent = () => {
+    const element = elementRef.current;
+    if (!element) return;
+
+    const currentHeight = getStyleHeightPx(element, minHeight);
+    const newHeight = Math.min(currentHeight + HEIGHT_INCREMENT, maxHeight);
+
+    if (newHeight > currentHeight) {
+      const finalHeight = applyHeightToElement(element, newHeight, constraints);
+
+      // Execute height change callback
+      executeHeightCallback(finalHeight, onHeightChange);
+
+      // Set manual mode for Shift+Enter height increases
+      hasUserResizedRef.current = true;
+      manualHeightRef.current = finalHeight;
+    }
+  };
+
+  // Update content and resize when value prop changes
+  useEffect(() => {
+    if (value === undefined) {
+      return undefined;
+    }
+
+    let rafId = 0;
+
+    const applyValue = () => {
+      const element = elementRef.current;
+      if (!element) {
+        return false;
+      }
+
+      element.textContent = value.text;
+      smartResize();
+      focusContentEditableAtEnd(element);
+      onValueApplied?.(); // one-shot: let the caller clear the value
+      return true;
+    };
+
+    if (!applyValue()) {
+      rafId = requestAnimationFrame(() => {
+        applyValue();
+      });
+    }
+
+    return () => {
+      if (rafId) {
+        cancelAnimationFrame(rafId);
+      }
+    };
+  }, [value, smartResize, onValueApplied]);
+
+  // Initialize auto-resize on mount
+  useEffect(() => {
+    smartResize();
+  }, [smartResize]);
+
+  return {
+    smartResize,
+    handleGripMouseDown,
+    handleGripTouchStart,
+    increaseHeightForEmptyContent,
+    resetManualResize,
+  };
+};

src/hooks/use-automation-permissions.ts

@@ -0,0 +1,102 @@
+import { useQuery } from "@tanstack/react-query";
+import { getCloudOrganizationMe } from "#/api/cloud/organization-service.api";
+import { useActiveBackend } from "#/contexts/active-backend-context";
+import { useCloudCurrentUserId } from "./query/use-cloud-current-user-id";
+import type { Automation } from "#/types/automation";
+
+/**
+ * Server-defined permission strings (mirror the automation service's
+ * `view_automations` / `manage_automations` and the enterprise
+ * `authorization.Permission` enum). The `/me` endpoint returns whichever
+ * subset the caller's role grants.
+ */
+export const VIEW_AUTOMATIONS = "view_automations";
+export const MANAGE_AUTOMATIONS = "manage_automations";
+
+export interface AutomationPermissionsResult {
+  /** Read-only access (list, get, list runs, capabilities, git-sync status). */
+  canView: boolean;
+  /** Full write access (create, update, delete, dispatch, git-sync config). */
+  canManage: boolean;
+  /**
+   * `true` when permissions are still being resolved on cloud. Local always
+   * resolves synchronously. Mutating controls should stay hidden while this is
+   * `true` so a member never sees a flash of write controls before the
+   * server-defined permission set arrives.
+   */
+  isLoading: boolean;
+}
+
+/**
+ * Resolve the caller's automation-level permissions on the active backend.
+ *
+ * - Local agent-server (OSS): always `{ canView: true, canManage: true }`.
+ * - Cloud: reads the server-defined `permissions` array from
+ *   `GET /api/organizations/{orgId}/me` (same query `useCloudCurrentUserId`
+ *   and `useCanManageOrgProfiles` use, so no extra request is issued) and
+ *   falls back to a role check (`owner`/`admin` ⇒ both, `member` ⇒ view
+ *   only) when an older app-server doesn't return `permissions`.
+ */
+export function useAutomationPermissions(): AutomationPermissionsResult {
+  const { backend, orgId } = useActiveBackend();
+  const isCloud = backend.kind === "cloud";
+
+  // eslint-disable-next-line @tanstack/query/exhaustive-deps
+  const { data, isLoading } = useQuery({
+    queryKey: [
+      "cloud-current-user",
+      backend.id,
+      orgId,
+      backend.connectionRevision ?? 0,
+    ],
+    queryFn: () => getCloudOrganizationMe(orgId!, backend),
+    enabled: isCloud && !!orgId,
+    staleTime: 1000 * 60 * 5,
+    retry: false,
+    meta: { disableToast: true },
+  });
+
+  if (!isCloud) {
+    return { canView: true, canManage: true, isLoading: false };
+  }
+
+  if (isLoading || !data) {
+    return { canView: false, canManage: false, isLoading };
+  }
+
+  if (data.permissions) {
+    const canView = data.permissions.includes(VIEW_AUTOMATIONS);
+    const canManage = data.permissions.includes(MANAGE_AUTOMATIONS);
+    return { canView, canManage, isLoading: false };
+  }
+
+  // Fall back to role check for older app-servers without `permissions`.
+  const isOwnerOrAdmin = data.role === "owner" || data.role === "admin";
+  return {
+    canView: isOwnerOrAdmin || data.role === "member",
+    canManage: isOwnerOrAdmin,
+    isLoading: false,
+  };
+}
+
+/**
+ * Resolve whether the current user is the creator of the given automation.
+ *
+ * - Local: always `true` (the local user owns every automation; and since
+ *   local always has `manage_automations`, the distinction is moot).
+ * - Cloud: compares `automation.user_id` with the caller's `user_id` from
+ *   `GET /api/organizations/{orgId}/me`. Returns `false` while the id is
+ *   still loading so the creator escape hatch never flashes open prematurely.
+ */
+export function useIsAutomationOwner(automation: Automation): boolean {
+  const { backend } = useActiveBackend();
+  // Always call the hook so rules-of-hooks is satisfied; it's a no-op for
+  // local backends since the early return below short-circuits before use.
+  const userIds = useCloudCurrentUserId();
+
+  if (backend.kind !== "cloud") return true;
+
+  const entry = userIds[backend.id];
+  if (!entry || entry.isLoading || !entry.userId) return false;
+  return automation.user_id === entry.userId;
+}

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

@@ -0,0 +1,164 @@
+import { useEffect, useRef } from "react";
+import useMetricsStore from "#/stores/metrics-store";
+import { useEventStore } from "#/stores/use-event-store";
+import { isCondensationEvent } from "#/types/agent-server/type-guards";
+
+/** How long to wait after a Condensation event for a lower per_turn_token. */
+const METRICS_SETTLE_MS = 2_500;
+/** Give up waiting for condensation / metrics and surface whatever we have. */
+const DEFAULT_TIMEOUT_MS = 90_000;
+
+export type ContextCompactionOutcome = "compacted" | "no_change" | "timeout";
+
+export interface ContextCompactionResult {
+  beforeToken: number;
+  afterToken: number;
+  savedToken: number;
+  /**
+   * "compacted" — a Condensation event landed and per_turn_token dropped.
+   * "no_change" — a Condensation event landed but no token drop was measured.
+   * "timeout" — no Condensation event arrived in time; compaction did not
+   * happen (or was never processed), so this is a failure, not a no-op.
+   */
+  outcome: ContextCompactionOutcome;
+}
+
+export function buildContextCompactionResult(
+  beforeToken: number,
+  afterToken: number,
+  outcome: ContextCompactionOutcome,
+): ContextCompactionResult {
+  return {
+    beforeToken,
+    afterToken,
+    savedToken: Math.max(0, beforeToken - afterToken),
+    outcome,
+  };
+}
+
+interface UseAwaitContextCompactionOptions {
+  /**
+   * Snapshot of `per_turn_token` taken when compaction was requested.
+   * Pass `null` when not awaiting a result.
+   */
+  beforeToken: number | null;
+  /**
+   * Event ids that predate the compaction *request*. The condense POST can
+   * return only after the server already emitted its Condensation event, so
+   * snapshotting "known" ids when this effect starts would miss fast
+   * condensations; the baseline must be captured before the request fires.
+   * When omitted, falls back to the ids present when the effect starts.
+   */
+  baselineEventIds?: Set<string | number> | null;
+  onComplete: (result: ContextCompactionResult) => void;
+  timeoutMs?: number;
+}
+
+/**
+ * Waits for a post-request Condensation event (and ideally a lower
+ * `per_turn_token` in the live metrics store), then reports how many tokens
+ * were freed. The HTTP `/condense` ack only means work *started*.
+ */
+export function useAwaitContextCompaction({
+  beforeToken,
+  baselineEventIds,
+  onComplete,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+}: UseAwaitContextCompactionOptions) {
+  const onCompleteRef = useRef(onComplete);
+  onCompleteRef.current = onComplete;
+
+  useEffect(() => {
+    if (beforeToken === null) {
+      return undefined;
+    }
+
+    let completed = false;
+    let sawCondensation = false;
+    let settleTimer: ReturnType<typeof setTimeout> | undefined;
+    const knownEventIds = baselineEventIds
+      ? new Set(baselineEventIds)
+      : new Set(useEventStore.getState().eventIds);
+
+    const readAfterToken = () =>
+      useMetricsStore.getState().usage?.per_turn_token ?? beforeToken;
+
+    const finish = (afterToken: number, outcome: ContextCompactionOutcome) => {
+      if (completed) {
+        return;
+      }
+      completed = true;
+      onCompleteRef.current(
+        buildContextCompactionResult(beforeToken, afterToken, outcome),
+      );
+    };
+
+    const finishFromMetricsIfReady = () => {
+      const afterToken = readAfterToken();
+      if (sawCondensation && afterToken < beforeToken) {
+        finish(afterToken, "compacted");
+        return true;
+      }
+      return false;
+    };
+
+    const scheduleSettleFinish = () => {
+      clearTimeout(settleTimer);
+      settleTimer = setTimeout(() => {
+        finish(readAfterToken(), "no_change");
+      }, METRICS_SETTLE_MS);
+    };
+
+    const scanForNewCondensation = () => {
+      for (const event of useEventStore.getState().events) {
+        const eventId = "id" in event ? event.id : undefined;
+        if (eventId !== undefined) {
+          if (knownEventIds.has(eventId)) {
+            continue;
+          }
+          knownEventIds.add(eventId);
+        }
+        if (!isCondensationEvent(event)) {
+          continue;
+        }
+        sawCondensation = true;
+        if (!finishFromMetricsIfReady()) {
+          scheduleSettleFinish();
+        }
+        return;
+      }
+    };
+
+    scanForNewCondensation();
+
+    const unsubscribeEvents = useEventStore.subscribe(() => {
+      if (completed) {
+        return;
+      }
+      scanForNewCondensation();
+    });
+
+    const unsubscribeMetrics = useMetricsStore.subscribe(() => {
+      if (completed) {
+        return;
+      }
+      if (finishFromMetricsIfReady()) {
+        clearTimeout(settleTimer);
+      }
+    });
+
+    const timeoutTimer = setTimeout(() => {
+      // No Condensation event in time means the compaction never landed —
+      // a failure, not a "nothing to compact" no-op.
+      finish(readAfterToken(), sawCondensation ? "no_change" : "timeout");
+    }, timeoutMs);
+
+    return () => {
+      completed = true;
+      unsubscribeEvents();
+      unsubscribeMetrics();
+      clearTimeout(settleTimer);
+      clearTimeout(timeoutTimer);
+    };
+  }, [beforeToken, baselineEventIds, timeoutMs]);
+}

src/hooks/use-backend-scoped-path.ts

@@ -0,0 +1,27 @@
+import React from "react";
+import { isNoBackend } from "#/api/backend-registry/active-store";
+import { withBackendSelectionParams } from "#/api/backend-registry/url-selection";
+import { useActiveBackend } from "#/contexts/active-backend-context";
+
+/**
+ * Build in-app paths that carry the active backend identity.
+ *
+ * Use it for links a user can plausibly open in a *new* browsing context
+ * (cmd/ctrl-click, middle click, "Open link in new tab"). Such a tab does not
+ * reliably inherit the opener's `sessionStorage`, so without the pinned
+ * identity it can boot on whichever backend `localStorage` last recorded and
+ * fail to resolve the linked conversation.
+ */
+export function useBackendScopedPath(): (path: string) => string {
+  const active = useActiveBackend();
+
+  return React.useCallback(
+    (path: string) => {
+      // The sentinel isn't a real backend and must never be pinned onto a
+      // link — a new tab would only ignore it and fall back to storage.
+      if (isNoBackend(active.backend)) return path;
+      return withBackendSelectionParams(path, active);
+    },
+    [active],
+  );
+}

src/hooks/use-bash-command-runner.ts

@@ -0,0 +1,206 @@
+import { useCallback, useEffect, useRef } from "react";
+import type {
+  BashCommand,
+  BashError,
+  BashEvent,
+  BashOutput,
+} from "@openhands/typescript-client";
+import type { CommandResult } from "#/api/runtime-service/agent-server-runtime-service";
+import { sendWebSocketAuth } from "#/utils/websocket-auth";
+import { startHandshakeWatchdog } from "#/utils/websocket-handshake";
+import { buildBashWebSocketUrl } from "#/utils/websocket-url";
+
+interface WaitingCommand {
+  command: string;
+  cwd: string;
+  timeout: number;
+  resolve: (result: CommandResult) => void;
+  reject: (error: Error) => void;
+}
+
+interface PendingCommand {
+  resolve: (result: CommandResult) => void;
+  reject: (error: Error) => void;
+}
+
+interface ActiveCommand extends PendingCommand {
+  stdout: string[];
+  stderr: string[];
+}
+
+export type BashCommandRunner = (
+  command: string,
+  cwd: string,
+  timeout: number,
+) => Promise<CommandResult>;
+
+function isBashCommand(event: BashEvent): event is BashCommand {
+  return event.kind === "BashCommand";
+}
+
+function isBashOutput(event: BashEvent): event is BashOutput {
+  return event.kind === "BashOutput";
+}
+
+function isBashError(event: BashEvent): event is BashError {
+  return event.kind === "BashError";
+}
+
+/**
+ * Maintains a persistent WebSocket connection to the agent-server's
+ * `/sockets/bash-events` endpoint and exposes a `runCommand` function that
+ * executes a bash command and returns a Promise that resolves when the
+ * final `BashOutput` (non-null `exit_code`) arrives.
+ *
+ * Commands are correlated using a FIFO queue: each `BashCommand` echo
+ * received from the server is paired with the oldest outstanding request in
+ * the queue, and subsequent `BashOutput` events are matched by `command_id`.
+ *
+ * Commands are buffered until the socket's open handler sends authentication.
+ */
+export function useBashCommandRunner(
+  conversationUrl: string | null | undefined,
+  sessionApiKey: string | null | undefined,
+  enabled: boolean,
+): BashCommandRunner {
+  const wsRef = useRef<WebSocket | null>(null);
+  const readyWsRef = useRef<WebSocket | null>(null);
+  const waitingQueueRef = useRef<WaitingCommand[]>([]);
+  // Commands whose request was sent; waiting for the BashCommand echo to get command_id
+  const pendingQueueRef = useRef<PendingCommand[]>([]);
+  // Commands whose command_id is known; waiting for BashOutput with non-null exit_code
+  const activeCommandsRef = useRef<Map<string, ActiveCommand>>(new Map());
+
+  useEffect(() => {
+    if (!enabled) return;
+
+    const wsUrl = buildBashWebSocketUrl(conversationUrl);
+    const ws = new WebSocket(wsUrl);
+    wsRef.current = ws;
+    readyWsRef.current = null;
+
+    // Abort a handshake stuck in CONNECTING — a hung bash-events handshake
+    // would also block the conversation's events socket (the one the chat
+    // needs) until it settles.
+    const cancelHandshakeWatchdog = startHandshakeWatchdog(ws);
+
+    ws.onopen = () => {
+      cancelHandshakeWatchdog();
+      sendWebSocketAuth(ws, sessionApiKey);
+      readyWsRef.current = ws;
+      for (const {
+        command,
+        cwd,
+        timeout,
+        resolve,
+        reject,
+      } of waitingQueueRef.current) {
+        pendingQueueRef.current.push({ resolve, reject });
+        ws.send(JSON.stringify({ command, cwd, timeout }));
+      }
+      waitingQueueRef.current = [];
+    };
+
+    ws.onmessage = (event: MessageEvent) => {
+      let data: BashEvent;
+      try {
+        data = JSON.parse(event.data as string) as BashEvent;
+      } catch {
+        return; // ignore malformed frames
+      }
+
+      if (isBashCommand(data)) {
+        // Associate the next pending request with the server-assigned command_id
+        const pending = pendingQueueRef.current.shift();
+        if (pending) {
+          activeCommandsRef.current.set(data.id, {
+            ...pending,
+            stdout: [],
+            stderr: [],
+          });
+        }
+      } else if (isBashOutput(data) && data.command_id) {
+        const active = activeCommandsRef.current.get(data.command_id);
+        if (active) {
+          if (data.stdout) active.stdout.push(data.stdout);
+          if (data.stderr) active.stderr.push(data.stderr);
+          if (data.exit_code != null) {
+            activeCommandsRef.current.delete(data.command_id);
+            active.resolve({
+              exit_code: data.exit_code,
+              stdout: active.stdout.join(""),
+              stderr: active.stderr.join(""),
+            });
+          }
+        }
+      } else if (isBashError(data)) {
+        rejectAll(`Bash error: ${data.code}: ${data.detail}`);
+      }
+    };
+
+    function rejectAll(reason: string): void {
+      const err = new Error(reason);
+      for (const { reject: rej } of waitingQueueRef.current) rej(err);
+      waitingQueueRef.current = [];
+      for (const p of pendingQueueRef.current) p.reject(err);
+      pendingQueueRef.current = [];
+      for (const a of activeCommandsRef.current.values()) a.reject(err);
+      activeCommandsRef.current.clear();
+    }
+
+    ws.onclose = () => {
+      cancelHandshakeWatchdog();
+      wsRef.current = null;
+      readyWsRef.current = null;
+      rejectAll("Bash WebSocket closed");
+    };
+
+    ws.onerror = () => {
+      wsRef.current = null;
+      readyWsRef.current = null;
+      rejectAll("Bash WebSocket error");
+    };
+
+    return () => {
+      // The close handler is nulled below, so cancel the watchdog here.
+      cancelHandshakeWatchdog();
+      // Prevent the close/error handlers from double-rejecting after unmount
+      ws.onclose = null;
+      ws.onerror = null;
+      ws.close();
+      wsRef.current = null;
+      readyWsRef.current = null;
+      rejectAll("Bash WebSocket unmounted");
+    };
+  }, [enabled, conversationUrl, sessionApiKey]);
+
+  const runCommand: BashCommandRunner = useCallback(
+    (command: string, cwd: string, timeout: number) =>
+      new Promise<CommandResult>((resolve, reject) => {
+        const ws = wsRef.current;
+        if (
+          !ws ||
+          ws.readyState === WebSocket.CLOSED ||
+          ws.readyState === WebSocket.CLOSING
+        ) {
+          reject(new Error("Bash WebSocket not available"));
+          return;
+        }
+        if (ws.readyState !== WebSocket.OPEN || readyWsRef.current !== ws) {
+          waitingQueueRef.current.push({
+            command,
+            cwd,
+            timeout,
+            resolve,
+            reject,
+          });
+        } else {
+          pendingQueueRef.current.push({ resolve, reject });
+          ws.send(JSON.stringify({ command, cwd, timeout }));
+        }
+      }),
+    [],
+  );
+
+  return runCommand;
+}