Add files using upload-large-folder tool

src/api/acp-service/acp-service.api.ts

@@ -0,0 +1,110 @@
+import { BashClient } from "@openhands/typescript-client/clients";
+import type { BashOutput } from "@openhands/typescript-client";
+import { getAgentServerClientOptions } from "../agent-server-client-options";
+
+export type AcpAuthStatus = "authenticated" | "unauthenticated" | "unknown";
+
+// Hard cap (seconds) for a single detection command. These are fast local
+// status checks (no npx download), so 10s is ample for a healthy CLI while
+// keeping the onboarding spinner short before falling back to "unknown".
+const PROBE_TIMEOUT_SECONDS = 10;
+
+interface AcpAuthProbe {
+  /** Shell command run on the (local) agent-server host to detect login. */
+  command: string;
+  /** Classify the command's output into an auth status. */
+  classify: (out: BashOutput) => AcpAuthStatus;
+}
+
+/** Combined stdout+stderr — CLIs are inconsistent about which stream they use
+ * (e.g. ``codex login status`` writes to stderr). */
+function streams(out: BashOutput): string {
+  return `${out.stdout ?? ""}\n${out.stderr ?? ""}`;
+}
+
+// Claude Code: ``claude auth status --json`` prints {"loggedIn": bool, …}. The
+// CLI exits non-zero when logged out, so we read the JSON, not the exit code.
+// No parseable ``loggedIn`` (e.g. the CLI isn't installed → "command not
+// found", empty stdout) ⇒ unknown, so onboarding shows the API-key fields
+// rather than guessing.
+function classifyClaude(out: BashOutput): AcpAuthStatus {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse((out.stdout ?? "").trim());
+  } catch {
+    return "unknown";
+  }
+  const loggedIn = (parsed as { loggedIn?: unknown } | null)?.loggedIn;
+  if (typeof loggedIn === "boolean") {
+    return loggedIn ? "authenticated" : "unauthenticated";
+  }
+  return "unknown";
+}
+
+// Codex: ``codex login status`` prints "Logged in using …" / "Not logged in"
+// (to stderr), so check both streams. Match "not logged in" first since it
+// contains the "logged in" substring. Neither phrase (e.g. CLI missing) ⇒
+// unknown.
+function classifyCodex(out: BashOutput): AcpAuthStatus {
+  const text = streams(out).toLowerCase();
+  if (text.includes("not logged in")) return "unauthenticated";
+  if (text.includes("logged in")) return "authenticated";
+  return "unknown";
+}
+
+// Gemini CLI signs in via Google OAuth and has no status command, so we check
+// its credentials file. The command echoes present/absent and exits 0 either
+// way; anything else (a shell failure) ⇒ unknown.
+function classifyGemini(out: BashOutput): AcpAuthStatus {
+  // The command echoes exactly `present` / `absent` to stdout, so match trimmed
+  // stdout exactly. Reading only stdout (not stderr) means a stray shell
+  // warning can't turn a real result into `unknown`.
+  const text = (out.stdout ?? "").trim();
+  if (text === "present") return "authenticated";
+  if (text === "absent") return "unauthenticated";
+  return "unknown";
+}
+
+// Per-provider login detection, keyed by ``acp_server`` / OnboardingAgentId.
+// Providers absent here (OpenHands, custom, unknown) report ``unknown``.
+const ACP_AUTH_PROBES: Record<string, AcpAuthProbe> = {
+  "claude-code": {
+    command: "claude auth status --json",
+    classify: classifyClaude,
+  },
+  codex: {
+    command: "codex login status",
+    classify: classifyCodex,
+  },
+  "gemini-cli": {
+    command:
+      'test -f "$HOME/.gemini/oauth_creds.json" && echo present || echo absent',
+    classify: classifyGemini,
+  },
+};
+
+/**
+ * Detects whether the selected ACP provider is already logged in — entirely
+ * client-side, with **no dedicated agent-server endpoint**. It runs the
+ * provider's own status command (or, for Gemini, a credentials-file check)
+ * through the existing agent-server bash endpoint and classifies the output.
+ *
+ * Gated by the caller to **local backends**: the command runs wherever the
+ * agent-server runs, and on a user's own machine the provider CLIs and
+ * credential files live at their standard paths. No prompt is sent, so no model
+ * tokens are spent. A provider that can't be classified — CLI not installed,
+ * unexpected output, or the bash call failing — comes back as ``unknown`` so
+ * onboarding falls back to the API-key fields rather than a misleading banner.
+ */
+class AcpService {
+  static async getAuthStatus(server: string): Promise<AcpAuthStatus> {
+    const probe = ACP_AUTH_PROBES[server];
+    if (!probe) return "unknown";
+    const out = await new BashClient(
+      getAgentServerClientOptions(),
+    ).executeCommand(probe.command, undefined, PROBE_TIMEOUT_SECONDS);
+    return probe.classify(out);
+  }
+}
+
+export default AcpService;

src/api/agent-profiles-service/agent-profiles-service.api.ts

@@ -0,0 +1,130 @@
+/**
+ * AgentProfilesService wraps the SDK's AgentProfilesClient, creating a client
+ * per-call so it always picks up the active backend's host/apiKey (same pattern
+ * as ProfilesService / SettingsService).
+ *
+ * Backs the Settings → Agent profiles library + reused agent editor. The
+ * `AgentProfilesClient` ships in ts-client (pinned 1.28.0 here); the
+ * `/api/agent-profiles` endpoints it targets shipped in agent-server v1.29.0
+ * (local) and in the enterprise cloud app-server (OpenHands #15060, epic
+ * #3730). Cloud exposes the SAME contract but authenticates with a bearer
+ * token + `X-Org-Id`, so cloud calls route through `callCloudProxy` (see
+ * `cloud/agent-profiles-service.api.ts`) instead of the direct client.
+ */
+import {
+  AgentProfilesClient,
+  type GetAgentProfileOptions,
+} from "@openhands/typescript-client/clients";
+import type {
+  AgentProfile,
+  AgentProfileSummary,
+  AgentProfileSaveInput,
+  AgentProfileListResponse,
+  AgentProfileDetailResponse,
+  AgentProfileMutationResponse,
+  ActivateAgentProfileResponse,
+  ExposeSecretsMode,
+} from "@openhands/typescript-client";
+import { getAgentServerClientOptions } from "../agent-server-client-options";
+import { getActiveBackend } from "../backend-registry/active-store";
+import {
+  listCloudAgentProfiles,
+  getCloudAgentProfile,
+  saveCloudAgentProfile,
+  deleteCloudAgentProfile,
+  renameCloudAgentProfile,
+  activateCloudAgentProfile,
+} from "../cloud/agent-profiles-service.api";
+
+function isCloud(): boolean {
+  return getActiveBackend().backend.kind === "cloud";
+}
+
+/**
+ * The seeded, well-known baseline agent profile. The backend lazily seeds it to
+ * mirror the user's global config (#3719), and onboarding configures it from the
+ * user's choice. It stands in for global `agent_settings`, so the home-launch
+ * path treats it as the enriched baseline rather than a deliberate profile
+ * selection (see `useCreateConversation`).
+ */
+export const WELL_KNOWN_DEFAULT_AGENT_PROFILE_NAME = "default";
+
+// Re-export SDK types for consumers.
+export type {
+  AgentProfile,
+  AgentProfileSummary,
+  AgentProfileSaveInput,
+  AgentProfileListResponse,
+  AgentProfileDetailResponse,
+  AgentProfileMutationResponse,
+  ActivateAgentProfileResponse,
+};
+
+class AgentProfilesService {
+  static async listProfiles(): Promise<AgentProfileListResponse> {
+    if (isCloud()) return listCloudAgentProfiles();
+    return new AgentProfilesClient(
+      getAgentServerClientOptions(),
+    ).listAgentProfiles();
+  }
+
+  static async getProfile(
+    name: string,
+    exposeSecrets?: ExposeSecretsMode,
+  ): Promise<AgentProfileDetailResponse> {
+    // Agent profiles are secret-free at rest now (embedded skills and their
+    // `mcp_tools` were removed in #4017 — a profile carries only refs + the
+    // `disabled_skills` deny-list of names), so `exposeSecrets` is vestigial and
+    // cloud ignores it; kept for local signature parity with ProfilesService.
+    if (isCloud()) return getCloudAgentProfile(name);
+    const options: GetAgentProfileOptions = exposeSecrets
+      ? { exposeSecrets }
+      : {};
+    return new AgentProfilesClient(
+      getAgentServerClientOptions(),
+    ).getAgentProfile(name, options);
+  }
+
+  /** Create or overwrite a profile by name (upsert). */
+  static async saveProfile(
+    name: string,
+    profile: AgentProfileSaveInput,
+  ): Promise<AgentProfileMutationResponse> {
+    if (isCloud()) return saveCloudAgentProfile(name, profile);
+    return new AgentProfilesClient(
+      getAgentServerClientOptions(),
+    ).saveAgentProfile(name, profile);
+  }
+
+  static async deleteProfile(
+    name: string,
+  ): Promise<AgentProfileMutationResponse> {
+    if (isCloud()) return deleteCloudAgentProfile(name);
+    return new AgentProfilesClient(
+      getAgentServerClientOptions(),
+    ).deleteAgentProfile(name);
+  }
+
+  static async renameProfile(
+    name: string,
+    newName: string,
+  ): Promise<AgentProfileMutationResponse> {
+    if (isCloud()) return renameCloudAgentProfile(name, newName);
+    return new AgentProfilesClient(
+      getAgentServerClientOptions(),
+    ).renameAgentProfile(name, newName);
+  }
+
+  /** Activate by the profile's stable UUID `id` (pointer-only; never writes
+   * agent_settings). */
+  static async activateProfile(
+    profileId: string,
+  ): Promise<ActivateAgentProfileResponse> {
+    if (isCloud()) return activateCloudAgentProfile(profileId);
+    return new AgentProfilesClient(
+      getAgentServerClientOptions(),
+    ).activateAgentProfile(profileId);
+  }
+}
+
+export default AgentProfilesService;

src/api/agent-profiles-service/profile-field-support.ts

@@ -0,0 +1,41 @@
+import {
+  compareAgentServerVersions,
+  getCachedAgentServerVersion,
+} from "#/api/agent-server-compatibility";
+
+/**
+ * `enable_switch_llm_tool` reached `OpenHandsAgentProfile` in
+ * software-agent-sdk#3870, first released in agent-server 1.31.0. The same
+ * field reached `AgentSettingsConfig` far earlier (1.22.0), so the agent
+ * settings schema advertises it on servers whose *profile* model still
+ * rejects it.
+ *
+ * That gap sits inside the supported range rather than below it: agent
+ * profiles shipped in 1.29.0 and Canvas accepts back to
+ * `config/defaults.json`'s `compatibility.minimumAgentServer`. On 1.29.0
+ * through 1.30.x, `AgentProfileBase` is `extra="forbid"`, so a profile save
+ * carrying the key 422s and the whole save is lost. Hence the profile editor
+ * gates on the server version instead of reusing the settings schema's
+ * presence check, which answers a different question.
+ */
+export const MIN_AGENT_SERVER_VERSION_FOR_PROFILE_SWITCH_LLM_TOOL = "1.31.0";
+
+/**
+ * Whether the active backend's agent-profile model accepts
+ * `enable_switch_llm_tool`.
+ *
+ * An unreadable version counts as support, matching the other version-gated
+ * call sites: cloud backends expose no `/server_info` to probe and track the
+ * current contract, and a local backend whose version does not parse never
+ * gets past `assertAgentServerVersionIsSupported` at boot.
+ */
+export function agentProfileSupportsSwitchLlmTool(): boolean {
+  const version = getCachedAgentServerVersion();
+  if (!version) return true;
+  const comparison = compareAgentServerVersions(
+    version,
+    MIN_AGENT_SERVER_VERSION_FOR_PROFILE_SWITCH_LLM_TOOL,
+  );
+  if (comparison === null) return true;
+  return comparison >= 0;
+}

src/api/automation-service/automation-service.api.test.ts

@@ -0,0 +1,458 @@
+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 type { Automation, AutomationSpec } from "#/types/automation";
+import type { GitSyncStatus } from "#/types/git-sync";
+import AutomationService from "./automation-service.api";
+
+const {
+  localAxios,
+  callCloudProxy,
+  clearPendingLocalTelemetryRevocation,
+  getTelemetryConsent,
+  getTelemetryDistinctId,
+  getTelemetryDistinctIdForConsentSync,
+} = vi.hoisted(() => ({
+  localAxios: {
+    interceptors: { request: { use: vi.fn() } },
+    get: vi.fn(),
+    post: vi.fn(),
+    put: vi.fn(),
+    patch: vi.fn(),
+    delete: vi.fn(),
+  },
+  callCloudProxy: vi.fn(),
+  clearPendingLocalTelemetryRevocation: vi.fn(),
+  getTelemetryConsent: vi.fn(),
+  getTelemetryDistinctId: vi.fn(),
+  getTelemetryDistinctIdForConsentSync: vi.fn(),
+}));
+
+vi.mock("axios", () => ({
+  default: {
+    create: () => localAxios,
+    post: vi.fn(),
+  },
+}));
+
+vi.mock("#/api/cloud/proxy", () => ({
+  callCloudProxy,
+}));
+
+vi.mock("#/services/telemetry", () => ({
+  clearPendingLocalTelemetryRevocation,
+  getTelemetryConsent,
+  getTelemetryDistinctId,
+  getTelemetryDistinctIdForConsentSync,
+}));
+
+const localBackend: Backend = {
+  id: "local-test",
+  name: "Local test backend",
+  host: "http://localhost:3000",
+  apiKey: "test-session-key",
+  kind: "local",
+};
+
+const cloudBackend: Backend = {
+  id: "cloud-test",
+  name: "Cloud test backend",
+  host: "https://app.example.test",
+  apiKey: "cloud-api-key",
+  kind: "cloud",
+};
+
+const spec: AutomationSpec = {
+  name: "Imported review",
+  prompt: "Review open pull requests.",
+  trigger: {
+    type: "cron",
+    schedule: "0 9 * * *",
+    schedule_human: "Daily at 09:00",
+  },
+  enabled: true,
+  repository: "openhands/agent-canvas",
+  branch: "main",
+  plugins: ["github:openhands/extensions"],
+  model: "fast",
+  timezone: "America/Los_Angeles",
+};
+
+const createdAutomation: Automation = {
+  id: "created-automation",
+  name: spec.name,
+  prompt: spec.prompt,
+  trigger: { type: "cron", schedule: spec.trigger.schedule },
+  enabled: true,
+  model: spec.model,
+  created_at: "2026-07-10T00:00:00Z",
+  updated_at: "2026-07-10T00:00:00Z",
+};
+
+describe("AutomationService.getSdkVersion", () => {
+  beforeEach(() => {
+    setRegisteredBackends([localBackend]);
+    setActiveSelection({ backendId: localBackend.id });
+  });
+
+  afterEach(() => {
+    setActiveSelection(null);
+    setRegisteredBackends([]);
+    vi.clearAllMocks();
+  });
+
+  it("fetches the local automation SDK version from the automation sidecar", async () => {
+    localAxios.get.mockResolvedValueOnce({ data: { sdk_version: "1.36.1" } });
+
+    await expect(AutomationService.getSdkVersion()).resolves.toBe("1.36.1");
+
+    expect(localAxios.get).toHaveBeenCalledWith("/api/automation/sdk-version", {
+      timeout: 5000,
+    });
+  });
+
+  it("fetches the cloud automation SDK version through the cloud proxy", async () => {
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id, orgId: "org-1" });
+    callCloudProxy.mockResolvedValueOnce({ sdk_version: "1.36.2" });
+
+    await expect(AutomationService.getSdkVersion()).resolves.toBe("1.36.2");
+
+    expect(callCloudProxy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        backend: cloudBackend,
+        method: "GET",
+        path: "/api/automation/sdk-version",
+        headers: expect.objectContaining({ "X-Org-Id": "org-1" }),
+        timeoutSeconds: 5,
+      }),
+    );
+  });
+
+  it("returns null when the SDK version endpoint is unavailable", async () => {
+    localAxios.get.mockRejectedValueOnce(new Error("not running"));
+
+    await expect(AutomationService.getSdkVersion()).resolves.toBeNull();
+  });
+});
+
+describe("AutomationService.syncTelemetryConsent", () => {
+  beforeEach(() => {
+    setRegisteredBackends([localBackend]);
+    setActiveSelection({ backendId: localBackend.id });
+    getTelemetryConsent.mockReturnValue("pending");
+    getTelemetryDistinctIdForConsentSync.mockResolvedValue("ph-fe-sync");
+    localAxios.post.mockResolvedValue({ data: { consent_granted: true } });
+  });
+
+  afterEach(() => {
+    setActiveSelection(null);
+    setRegisteredBackends([]);
+    vi.clearAllMocks();
+  });
+
+  it("posts local telemetry consent with the frontend PostHog distinct ID", async () => {
+    await AutomationService.syncTelemetryConsent("granted");
+
+    expect(localAxios.post).toHaveBeenCalledWith(
+      "/api/automation/v1/telemetry/consent",
+      {
+        consent_granted: true,
+        frontend_distinct_id: "ph-fe-sync",
+      },
+      { timeout: 5000 },
+    );
+  });
+
+  it("uses the current telemetry consent when no explicit value is supplied", async () => {
+    getTelemetryConsent.mockReturnValue("denied");
+
+    await AutomationService.syncTelemetryConsent();
+
+    expect(localAxios.post).toHaveBeenCalledWith(
+      "/api/automation/v1/telemetry/consent",
+      {
+        consent_granted: false,
+        frontend_distinct_id: "ph-fe-sync",
+      },
+      { timeout: 5000 },
+    );
+    expect(clearPendingLocalTelemetryRevocation).toHaveBeenCalledWith(
+      "ph-fe-sync",
+    );
+  });
+
+  it("skips cloud backends because cloud consent is handled by auth", async () => {
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id, orgId: "org-1" });
+
+    await AutomationService.syncTelemetryConsent("granted");
+
+    expect(localAxios.post).not.toHaveBeenCalled();
+  });
+});
+
+describe("AutomationService.createAutomation", () => {
+  beforeEach(() => {
+    setRegisteredBackends([localBackend]);
+    setActiveSelection({ backendId: localBackend.id });
+    localAxios.post.mockResolvedValue({ data: createdAutomation });
+    localAxios.patch.mockImplementation(
+      async (_path: string, body: Partial<Automation>) => ({
+        data: { ...createdAutomation, ...body },
+      }),
+    );
+  });
+
+  afterEach(() => {
+    setActiveSelection(null);
+    setRegisteredBackends([]);
+    vi.clearAllMocks();
+  });
+
+  it("creates plugin automations through the preset API and disables them", async () => {
+    const created = await AutomationService.createAutomation(spec);
+
+    expect(localAxios.post).toHaveBeenCalledWith(
+      "/api/automation/v1/preset/plugin",
+      {
+        name: spec.name,
+        prompt: spec.prompt,
+        model: spec.model,
+        trigger: {
+          type: "event",
+          source: "agent-canvas-import",
+          on: expect.stringMatching(/^pending\./),
+        },
+        repos: [
+          {
+            url: spec.repository,
+            ref: spec.branch,
+            provider: "github",
+          },
+        ],
+        plugins: [{ source: spec.plugins![0] }],
+      },
+      {
+        baseURL: localBackend.host,
+        headers: expect.objectContaining({
+          "X-Session-API-Key": localBackend.apiKey,
+        }),
+      },
+    );
+    expect(localAxios.patch).toHaveBeenCalledWith(
+      "/api/automation/v1/created-automation",
+      {
+        trigger: {
+          type: "cron",
+          schedule: spec.trigger.schedule,
+          timezone: spec.timezone,
+        },
+        enabled: false,
+      },
+      {
+        baseURL: localBackend.host,
+        headers: expect.objectContaining({
+          "X-Session-API-Key": localBackend.apiKey,
+        }),
+      },
+    );
+    expect(created.enabled).toBe(false);
+  });
+
+  it("uses the prompt preset path when no plugins are configured", async () => {
+    await AutomationService.createAutomation({
+      ...spec,
+      plugins: undefined,
+    });
+
+    expect(localAxios.post).toHaveBeenCalledWith(
+      "/api/automation/v1/preset/prompt",
+      expect.not.objectContaining({ plugins: expect.anything() }),
+      expect.any(Object),
+    );
+  });
+
+  it("applies the imported event trigger while disabling the automation", async () => {
+    const eventTrigger = {
+      type: "event",
+      source: "github",
+      on: ["pull_request.opened", "pull_request.synchronize"],
+      filter: "repository.full_name == 'openhands/agent-canvas'",
+    };
+
+    await AutomationService.createAutomation({
+      ...spec,
+      trigger: eventTrigger,
+    });
+
+    expect(localAxios.patch).toHaveBeenCalledWith(
+      "/api/automation/v1/created-automation",
+      { trigger: eventTrigger, enabled: false },
+      expect.any(Object),
+    );
+  });
+
+  it("uses the selected cloud backend and organization for both requests", async () => {
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id, orgId: "org-1" });
+    callCloudProxy
+      .mockResolvedValueOnce(createdAutomation)
+      .mockResolvedValueOnce({ ...createdAutomation, enabled: false });
+
+    const created = await AutomationService.createAutomation(spec);
+
+    expect(callCloudProxy).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({
+        backend: cloudBackend,
+        method: "POST",
+        path: "/api/automation/v1/preset/plugin",
+        body: expect.objectContaining({ name: spec.name }),
+        headers: expect.objectContaining({ "X-Org-Id": "org-1" }),
+      }),
+    );
+    expect(callCloudProxy).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({
+        backend: cloudBackend,
+        method: "PATCH",
+        path: "/api/automation/v1/created-automation",
+        body: expect.objectContaining({ enabled: false }),
+        headers: expect.objectContaining({ "X-Org-Id": "org-1" }),
+      }),
+    );
+    expect(created.enabled).toBe(false);
+  });
+
+  it("removes the inert automation when disabling it fails", async () => {
+    const updateError = new Error("update failed");
+    localAxios.patch.mockRejectedValueOnce(updateError);
+
+    await expect(AutomationService.createAutomation(spec)).rejects.toBe(
+      updateError,
+    );
+
+    expect(localAxios.delete).toHaveBeenCalledWith(
+      "/api/automation/v1/created-automation",
+      {
+        baseURL: localBackend.host,
+        headers: expect.objectContaining({
+          "X-Session-API-Key": localBackend.apiKey,
+        }),
+      },
+    );
+  });
+
+  it("includes the timeout in the create request when the spec sets one", async () => {
+    await AutomationService.createAutomation({ ...spec, timeout: 1200 });
+
+    expect(localAxios.post).toHaveBeenCalledWith(
+      "/api/automation/v1/preset/plugin",
+      expect.objectContaining({ timeout: 1200 }),
+      expect.any(Object),
+    );
+  });
+});
+
+const gitSyncStatus: GitSyncStatus = {
+  enabled: true,
+  repo_url: "https://example.com/org/repo.git",
+  branch: "main",
+  path: "automations",
+  encryption_enabled: false,
+  interval_seconds: 0,
+  last_synced_commit: "abc123",
+  last_synced_at: "2026-07-10T00:00:00Z",
+  last_error: null,
+  last_error_at: null,
+  dirty_count: 0,
+};
+
+describe("AutomationService git sync", () => {
+  beforeEach(() => {
+    setRegisteredBackends([localBackend]);
+    setActiveSelection({ backendId: localBackend.id });
+  });
+
+  afterEach(() => {
+    setActiveSelection(null);
+    setRegisteredBackends([]);
+    vi.clearAllMocks();
+  });
+
+  it("fetches status from the local automation backend", async () => {
+    localAxios.get.mockResolvedValueOnce({ data: gitSyncStatus });
+
+    await expect(AutomationService.getGitSyncStatus()).resolves.toEqual(
+      gitSyncStatus,
+    );
+
+    expect(localAxios.get).toHaveBeenCalledWith(
+      "/api/automation/v1/git-sync/status",
+    );
+  });
+
+  it("fetches status through the cloud proxy", async () => {
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id, orgId: "org-1" });
+    callCloudProxy.mockResolvedValueOnce(gitSyncStatus);
+
+    await expect(AutomationService.getGitSyncStatus()).resolves.toEqual(
+      gitSyncStatus,
+    );
+
+    expect(callCloudProxy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        backend: cloudBackend,
+        method: "GET",
+        path: "/api/automation/v1/git-sync/status",
+      }),
+    );
+  });
+
+  it("sends a partial config update", async () => {
+    localAxios.put.mockResolvedValueOnce({ data: gitSyncStatus });
+
+    await expect(
+      AutomationService.updateGitSyncConfig({ branch: "develop" }),
+    ).resolves.toEqual(gitSyncStatus);
+
+    expect(localAxios.put).toHaveBeenCalledWith(
+      "/api/automation/v1/git-sync/config",
+      { branch: "develop" },
+    );
+  });
+
+  it("sends a null override through the cloud proxy", async () => {
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id, orgId: "org-1" });
+    callCloudProxy.mockResolvedValueOnce(gitSyncStatus);
+
+    await AutomationService.updateGitSyncConfig({ token: null });
+
+    expect(callCloudProxy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        backend: cloudBackend,
+        method: "PUT",
+        path: "/api/automation/v1/git-sync/config",
+        body: { token: null },
+      }),
+    );
+  });
+
+  it("triggers a sync cycle", async () => {
+    localAxios.post.mockResolvedValueOnce({ data: { triggered: true } });
+
+    await expect(AutomationService.triggerGitSync()).resolves.toEqual({
+      triggered: true,
+    });
+
+    expect(localAxios.post).toHaveBeenCalledWith(
+      "/api/automation/v1/git-sync/sync",
+    );
+  });
+});

src/api/automation-service/automation-service.api.ts

@@ -0,0 +1,794 @@
+import axios from "axios";
+import {
+  clearPendingLocalTelemetryRevocation,
+  getTelemetryConsent,
+  getTelemetryDistinctId,
+  getTelemetryDistinctIdForConsentSync,
+  type TelemetryConsent,
+} from "#/services/telemetry";
+import type {
+  Automation,
+  AutomationRun,
+  AutomationSpec,
+  AutomationTrigger,
+  AutomationsResponse,
+  AutomationRunsResponse,
+} from "#/types/automation";
+import type {
+  GitSyncCheckResponse,
+  GitSyncConfigUpdateRequest,
+  GitSyncStatus,
+  GitSyncTriggerResponse,
+} from "#/types/git-sync";
+import {
+  automationCreateEndpoint,
+  automationUploadEndpoint,
+} from "#/manifests/automation-setup";
+import {
+  getAutomationEndpoint,
+  getAutomationIdEndpoint,
+  getImportExportSpec,
+} from "#/manifests/automation-interface";
+import type {
+  DeploymentCapabilities,
+  SetupEntry,
+  SetupRequestBody,
+  ValidateDraftResponse,
+} from "#/manifests/types";
+import type { Backend, ResolvedActiveBackend } from "../backend-registry/types";
+import {
+  getActiveBackend,
+  getEffectiveLocalBackend,
+} from "../backend-registry/active-store";
+import { NoBackendAvailableError } from "../agent-server-client-options";
+import { callCloudProxy } from "../cloud/proxy";
+import {
+  AGENT_CANVAS_CLIENT_HEADERS,
+  OPENHANDS_TELEMETRY_DISTINCT_ID_HEADER,
+} from "../client-source";
+
+const AUTOMATION_BASE_PATH = "/api/automation";
+
+export interface AutomationHealthResponse {
+  status: "ok" | "error";
+  message?: string;
+}
+
+type AutomationSdkVersionResponse =
+  | string
+  | {
+      sdk_version?: unknown;
+      version?: unknown;
+    };
+
+// Local automation calls go to the automation sidecar that
+// `scripts/dev-with-automation.mjs` mounts behind the local agent-server.
+// Both backends use the same session API key and the same `X-Session-API-Key`
+// header for consistency.
+const localAutomationAxios = axios.create();
+
+async function buildAutomationRequestHeaders(
+  extraHeaders: Record<string, string> = {},
+): Promise<Record<string, string>> {
+  const telemetryDistinctId = await getTelemetryDistinctId();
+  return {
+    ...AGENT_CANVAS_CLIENT_HEADERS,
+    ...(telemetryDistinctId
+      ? { [OPENHANDS_TELEMETRY_DISTINCT_ID_HEADER]: telemetryDistinctId }
+      : {}),
+    ...extraHeaders,
+  };
+}
+
+localAutomationAxios.interceptors.request.use(async (config) => {
+  const requestHeaders = await buildAutomationRequestHeaders();
+  Object.entries(requestHeaders).forEach(([name, value]) => {
+    config.headers.set(name, value);
+  });
+
+  // Import uses an explicit baseURL/header pair so its POST, PATCH, and
+  // cleanup stay pinned to the backend selected when the mutation started.
+  if (config.baseURL) return config;
+
+  // Resolve the local backend on every call so it tracks the
+  // currently-active local backend (and any host/key edits made via the
+  // manage-backends UI), rather than freezing whatever value the
+  // agent-server-config produced at module load time.
+  // Using the backend registry (rather than the build-time VITE_SESSION_API_KEY
+  // env var) ensures the published npm package picks up the runtime-injected
+  // session key that scripts/static-server.mjs seeds into localStorage, fixing
+  // the 401 errors reported in issue #829.
+  const backend = getEffectiveLocalBackend();
+  if (!backend) throw new NoBackendAvailableError();
+  // eslint-disable-next-line no-param-reassign
+  config.baseURL = backend.host;
+
+  const apiKey = backend.apiKey?.trim();
+  if (apiKey) {
+    config.headers.set("X-Session-API-Key", apiKey);
+  }
+  return config;
+});
+
+function normalizeAutomationSdkVersion(version: unknown): string | null {
+  if (typeof version !== "string") return null;
+  const trimmed = version.trim();
+  return trimmed || null;
+}
+
+function getAutomationSdkVersionFromResponse(
+  response: AutomationSdkVersionResponse,
+): string | null {
+  if (typeof response === "string") {
+    return normalizeAutomationSdkVersion(response);
+  }
+  return (
+    normalizeAutomationSdkVersion(response.sdk_version) ??
+    normalizeAutomationSdkVersion(response.version)
+  );
+}
+
+function buildPaginationQuery(limit: number, offset: number): string {
+  const params = new URLSearchParams();
+  params.set("limit", String(limit));
+  params.set("offset", String(offset));
+  return params.toString();
+}
+
+function buildImportedTrigger(spec: AutomationSpec): AutomationTrigger {
+  if (spec.trigger.type === "event") {
+    return {
+      type: "event",
+      source: spec.trigger.source,
+      on: spec.trigger.on,
+      ...(spec.trigger.filter && { filter: spec.trigger.filter }),
+    };
+  }
+
+  return {
+    type: "cron",
+    schedule: spec.trigger.schedule,
+    timezone: spec.timezone ?? spec.trigger.timezone ?? "UTC",
+  };
+}
+
+function generatePendingImportEvent(): string {
+  if (
+    typeof crypto !== "undefined" &&
+    typeof crypto.randomUUID === "function"
+  ) {
+    return `pending.${crypto.randomUUID()}`;
+  }
+  return `pending.${Date.now()}.${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function buildCreateAutomationRequest(spec: AutomationSpec) {
+  if (!spec.prompt) {
+    throw new Error("An automation prompt is required for import.");
+  }
+
+  const { importDefaults } = getImportExportSpec();
+  const repos = spec.repository
+    ? [
+        {
+          url: spec.repository,
+          ...(spec.branch && { ref: spec.branch }),
+          ...(!spec.repository.includes("://") &&
+            !spec.repository.startsWith("git@") && {
+              provider: importDefaults.repoProvider,
+            }),
+        },
+      ]
+    : undefined;
+
+  return {
+    path: `${AUTOMATION_BASE_PATH}${getAutomationEndpoint(
+      spec.plugins?.length ? "createPlugin" : "createPrompt",
+    )}`,
+    body: {
+      name: spec.name,
+      prompt: spec.prompt,
+      // Preset creation defaults to enabled. A unique event trigger keeps the
+      // new record inert until the real trigger and disabled state are applied
+      // together in the follow-up PATCH.
+      trigger: {
+        type: "event",
+        source: importDefaults.placeholderEventSource,
+        on: generatePendingImportEvent(),
+      },
+      ...(spec.model && { model: spec.model }),
+      ...(repos && { repos }),
+      ...(spec.plugins?.length && {
+        plugins: spec.plugins.map((source) => ({ source })),
+      }),
+      ...(spec.timeout != null && { timeout: spec.timeout }),
+    },
+  };
+}
+
+async function buildPinnedLocalConfig(backend: Backend) {
+  const apiKey = backend.apiKey.trim();
+  return {
+    baseURL: backend.host,
+    headers: await buildAutomationRequestHeaders(
+      apiKey ? { "X-Session-API-Key": apiKey } : {},
+    ),
+  };
+}
+
+async function buildPinnedCloudHeaders(active: ResolvedActiveBackend) {
+  return buildAutomationRequestHeaders(
+    active.orgId ? { "X-Org-Id": active.orgId } : {},
+  );
+}
+
+class AutomationService {
+  static async syncTelemetryConsent(
+    consent: TelemetryConsent = getTelemetryConsent(),
+  ): Promise<void> {
+    const active = getActiveBackend();
+    if (active.backend.kind !== "local") return;
+
+    const frontendDistinctId = await getTelemetryDistinctIdForConsentSync();
+    await localAutomationAxios.post(
+      `${AUTOMATION_BASE_PATH}/v1/telemetry/consent`,
+      {
+        consent_granted: consent === "granted",
+        frontend_distinct_id: frontendDistinctId,
+      },
+      { timeout: 5000 },
+    );
+    if (consent !== "granted" && frontendDistinctId) {
+      clearPendingLocalTelemetryRevocation(frontendDistinctId);
+    }
+  }
+
+  static async getSdkVersion(): Promise<string | null> {
+    const active = getActiveBackend();
+    const path = `${AUTOMATION_BASE_PATH}/sdk-version`;
+
+    try {
+      let response: AutomationSdkVersionResponse;
+      if (active.backend.kind === "cloud") {
+        response = await callCloudProxy<AutomationSdkVersionResponse>({
+          backend: active.backend,
+          method: "GET",
+          path,
+          headers: await buildPinnedCloudHeaders(active),
+          timeoutSeconds: 5,
+        });
+      } else {
+        const { data } =
+          await localAutomationAxios.get<AutomationSdkVersionResponse>(path, {
+            timeout: 5000,
+          });
+        response = data;
+      }
+
+      return getAutomationSdkVersionFromResponse(response);
+    } catch {
+      return null;
+    }
+  }
+
+  static async listAutomations(
+    params: { limit?: number; offset?: number } = {},
+  ): Promise<AutomationsResponse> {
+    const { limit = 50, offset = 0 } = params;
+    const active = getActiveBackend().backend;
+
+    if (active.kind === "cloud") {
+      return callCloudProxy<AutomationsResponse>({
+        backend: active,
+        method: "GET",
+        path: `${AUTOMATION_BASE_PATH}${getAutomationEndpoint("list")}?${buildPaginationQuery(limit, offset)}`,
+        headers: await buildAutomationRequestHeaders(),
+      });
+    }
+
+    const { data } = await localAutomationAxios.get<AutomationsResponse>(
+      `${AUTOMATION_BASE_PATH}${getAutomationEndpoint("list")}`,
+      { params: { limit, offset } },
+    );
+    return data;
+  }
+
+  static async getAutomations(
+    limit = 50,
+    offset = 0,
+  ): Promise<AutomationsResponse> {
+    return AutomationService.listAutomations({ limit, offset });
+  }
+
+  static async getAutomation(id: string): Promise<Automation> {
+    const active = getActiveBackend().backend;
+    const path = `${AUTOMATION_BASE_PATH}${getAutomationIdEndpoint("detail", id)}`;
+
+    if (active.kind === "cloud") {
+      return callCloudProxy<Automation>({
+        backend: active,
+        method: "GET",
+        path,
+        headers: await buildAutomationRequestHeaders(),
+      });
+    }
+
+    const { data } = await localAutomationAxios.get<Automation>(path);
+    return data;
+  }
+
+  static async createAutomation(spec: AutomationSpec): Promise<Automation> {
+    const active = getActiveBackend();
+    const { path, body } = buildCreateAutomationRequest(spec);
+
+    let created: Automation;
+    if (active.backend.kind === "cloud") {
+      created = await callCloudProxy<Automation>({
+        backend: active.backend,
+        method: "POST",
+        path,
+        body,
+        headers: await buildPinnedCloudHeaders(active),
+      });
+    } else {
+      const { data } = await localAutomationAxios.post<Automation>(
+        path,
+        body,
+        await buildPinnedLocalConfig(active.backend),
+      );
+      created = data;
+    }
+
+    const updatePath = `${AUTOMATION_BASE_PATH}${getAutomationIdEndpoint("detail", created.id)}`;
+    const updateBody: Partial<Automation> = {
+      trigger: buildImportedTrigger(spec),
+      enabled: false,
+    };
+
+    try {
+      if (active.backend.kind === "cloud") {
+        return await callCloudProxy<Automation>({
+          backend: active.backend,
+          method: "PATCH",
+          path: updatePath,
+          body: updateBody,
+          headers: await buildPinnedCloudHeaders(active),
+        });
+      }
+
+      const { data } = await localAutomationAxios.patch<Automation>(
+        updatePath,
+        updateBody,
+        await buildPinnedLocalConfig(active.backend),
+      );
+      return data;
+    } catch (updateError) {
+      try {
+        if (active.backend.kind === "cloud") {
+          await callCloudProxy<unknown>({
+            backend: active.backend,
+            method: "DELETE",
+            path: updatePath,
+            headers: await buildPinnedCloudHeaders(active),
+          });
+        } else {
+          await localAutomationAxios.delete(
+            updatePath,
+            await buildPinnedLocalConfig(active.backend),
+          );
+        }
+      } catch (cleanupError) {
+        throw new AggregateError(
+          [updateError, cleanupError],
+          "Failed to disable the imported automation and clean it up.",
+        );
+      }
+      throw updateError;
+    }
+  }
+
+  static async updateAutomation(
+    id: string,
+    body: Partial<Automation>,
+  ): Promise<Automation> {
+    const active = getActiveBackend().backend;
+    const path = `${AUTOMATION_BASE_PATH}${getAutomationIdEndpoint("detail", id)}`;
+
+    if (active.kind === "cloud") {
+      return callCloudProxy<Automation>({
+        backend: active,
+        method: "PATCH",
+        path,
+        body: body as Record<string, unknown>,
+        headers: await buildAutomationRequestHeaders(),
+      });
+    }
+
+    const { data } = await localAutomationAxios.patch<Automation>(path, body);
+    return data;
+  }
+
+  static async deleteAutomation(id: string): Promise<void> {
+    const active = getActiveBackend().backend;
+    const path = `${AUTOMATION_BASE_PATH}${getAutomationIdEndpoint("detail", id)}`;
+
+    if (active.kind === "cloud") {
+      await callCloudProxy<unknown>({
+        backend: active,
+        method: "DELETE",
+        path,
+        headers: await buildAutomationRequestHeaders(),
+      });
+      return;
+    }
+
+    await localAutomationAxios.delete(path);
+  }
+
+  static async dispatchAutomation(id: string): Promise<AutomationRun> {
+    const active = getActiveBackend().backend;
+    const path = `${AUTOMATION_BASE_PATH}${getAutomationIdEndpoint("dispatch", id)}`;
+
+    if (active.kind === "cloud") {
+      return callCloudProxy<AutomationRun>({
+        backend: active,
+        method: "POST",
+        path,
+        headers: await buildAutomationRequestHeaders(),
+      });
+    }
+
+    const { data } = await localAutomationAxios.post<AutomationRun>(path);
+    return data;
+  }
+
+  /**
+   * Cancel a pending or running automation run.
+   * Backend: POST /api/automation/v1/runs/{run_id}/cancel
+   */
+  static async cancelAutomationRun(runId: string): Promise<AutomationRun> {
+    const active = getActiveBackend().backend;
+    const path = `${AUTOMATION_BASE_PATH}/v1/runs/${encodeURIComponent(runId)}/cancel`;
+
+    if (active.kind === "cloud") {
+      return callCloudProxy<AutomationRun>({
+        backend: active,
+        method: "POST",
+        path,
+        headers: await buildAutomationRequestHeaders(),
+      });
+    }
+
+    const { data } = await localAutomationAxios.post<AutomationRun>(path);
+    return data;
+  }
+
+  static async listAutomationRuns(
+    id: string,
+    params: { limit?: number; offset?: number } = {},
+  ): Promise<AutomationRunsResponse> {
+    const { limit = 50, offset = 0 } = params;
+    const active = getActiveBackend().backend;
+    const basePath = `${AUTOMATION_BASE_PATH}${getAutomationIdEndpoint("runs", id)}`;
+
+    if (active.kind === "cloud") {
+      return callCloudProxy<AutomationRunsResponse>({
+        backend: active,
+        method: "GET",
+        path: `${basePath}?${buildPaginationQuery(limit, offset)}`,
+        headers: await buildAutomationRequestHeaders(),
+      });
+    }
+
+    const { data } = await localAutomationAxios.get<AutomationRunsResponse>(
+      basePath,
+      { params: { limit, offset } },
+    );
+    return data;
+  }
+
+  static async getAutomationRuns(
+    id: string,
+    limit = 50,
+    offset = 0,
+  ): Promise<AutomationRunsResponse> {
+    return AutomationService.listAutomationRuns(id, { limit, offset });
+  }
+
+  static async toggleAutomation(
+    id: string,
+    enabled: boolean,
+  ): Promise<Automation> {
+    return AutomationService.updateAutomation(id, { enabled });
+  }
+
+  static async downloadTarball(id: string, name: string): Promise<void> {
+    const active = getActiveBackend().backend;
+    const path = `${AUTOMATION_BASE_PATH}${getAutomationIdEndpoint("tarball", id)}`;
+
+    let blob: Blob;
+    if (active.kind === "cloud") {
+      blob = await callCloudProxy<Blob>({
+        backend: active,
+        method: "GET",
+        path,
+        responseType: "blob",
+        headers: await buildAutomationRequestHeaders(),
+      });
+    } else {
+      const { data } = await localAutomationAxios.get<Blob>(path, {
+        responseType: "blob",
+      });
+      blob = data;
+    }
+
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = `${name}.tar`;
+    a.click();
+    URL.revokeObjectURL(url);
+  }
+
+  /**
+   * Ask what this deployment supports, before a setup form renders.
+   *
+   * The setup endpoints answer a contract authored in `OpenHands/extensions`,
+   * so their bodies are camelCase where the rest of this service is snake_case.
+   */
+  static async getCapabilities(): Promise<DeploymentCapabilities> {
+    const active = getActiveBackend().backend;
+    const path = `${AUTOMATION_BASE_PATH}${getAutomationEndpoint("capabilities")}`;
+
+    if (active.kind === "cloud") {
+      return callCloudProxy<DeploymentCapabilities>({
+        backend: active,
+        method: "GET",
+        path,
+        headers: await buildAutomationRequestHeaders(),
+      });
+    }
+
+    const { data } =
+      await localAutomationAxios.get<DeploymentCapabilities>(path);
+    return data;
+  }
+
+  /**
+   * Validate a draft without creating it. An invalid draft is a 200 carrying
+   * field-addressed errors; only a malformed envelope is a 4xx.
+   */
+  static async validateDraft(
+    body: SetupRequestBody,
+  ): Promise<ValidateDraftResponse> {
+    const active = getActiveBackend().backend;
+    const path = `${AUTOMATION_BASE_PATH}${getAutomationEndpoint("validate")}`;
+
+    if (active.kind === "cloud") {
+      return callCloudProxy<ValidateDraftResponse>({
+        backend: active,
+        method: "POST",
+        path,
+        body,
+        headers: await buildAutomationRequestHeaders(),
+      });
+    }
+
+    const { data } = await localAutomationAxios.post<ValidateDraftResponse>(
+      path,
+      body,
+    );
+    return data;
+  }
+
+  /**
+   * Create from a draft a setup form derived. Unlike {@link
+   * AutomationService.createAutomation}, which exists for import and has to
+   * park the record on a placeholder trigger, this sends the finished record in
+   * one request.
+   */
+  static async createAutomationDraft(
+    body: SetupRequestBody,
+    /** The entry and selected action decide the create endpoint. */
+    entry?: SetupEntry,
+    selectedAction?: string | null,
+  ): Promise<Record<string, unknown>> {
+    const active = getActiveBackend().backend;
+    const path = `${AUTOMATION_BASE_PATH}${automationCreateEndpoint(
+      entry,
+      selectedAction,
+    )}`;
+
+    if (active.kind === "cloud") {
+      return callCloudProxy<Record<string, unknown>>({
+        backend: active,
+        method: "POST",
+        path,
+        body,
+        headers: await buildAutomationRequestHeaders(),
+      });
+    }
+
+    const { data } = await localAutomationAxios.post<Record<string, unknown>>(
+      path,
+      body,
+    );
+    return data;
+  }
+
+  /**
+   * Upload a packed bundle, and return the `oh-internal://` path the create
+   * call references.
+   *
+   * The body is the archive itself rather than a multipart form - the service
+   * streams it and takes its metadata from the query string, so it never has
+   * to buffer the whole file to start writing.
+   */
+  static async uploadAutomationTarball(
+    name: string,
+    archive: Uint8Array,
+  ): Promise<string> {
+    const active = getActiveBackend().backend;
+    const path =
+      `${AUTOMATION_BASE_PATH}${automationUploadEndpoint()}` +
+      `?name=${encodeURIComponent(name)}`;
+    const headers = { "Content-Type": "application/gzip" };
+
+    let upload: Record<string, unknown>;
+    if (active.kind === "cloud") {
+      // Post the archive straight to the cloud host rather than through the
+      // cloud client: that client JSON-serializes any non-FormData body, which
+      // would turn the gzip `Uint8Array` into `{"0":31,...}` even though the
+      // header says `application/gzip`. Axios preserves the raw bytes (its
+      // `transformRequest` sends the underlying buffer), so the service still
+      // receives the archive as the stream it expects, with metadata in the
+      // query string. This upload sets no host override, so a direct call
+      // matches the cloud client's own direct-to-host path -- we just add the
+      // two headers that path would (`Bearer` auth and `X-Org-Id`).
+      const { orgId } = getActiveBackend();
+      upload = (
+        await axios.post<Record<string, unknown>>(
+          `${active.host.replace(/\/+$/, "")}${path}`,
+          archive,
+          {
+            headers: {
+              ...(await buildAutomationRequestHeaders()),
+              ...headers,
+              ...(active.apiKey
+                ? { Authorization: `Bearer ${active.apiKey}` }
+                : {}),
+              ...(orgId ? { "X-Org-Id": orgId } : {}),
+            },
+          },
+        )
+      ).data;
+    } else {
+      upload = (
+        await localAutomationAxios.post<Record<string, unknown>>(
+          path,
+          archive,
+          { headers },
+        )
+      ).data;
+    }
+
+    const tarballPath = upload.tarball_path;
+    if (typeof tarballPath !== "string" || !tarballPath) {
+      throw new Error("The upload returned no tarball path.");
+    }
+    return tarballPath;
+  }
+
+  // Git sync paths are literal rather than routed through
+  // `getAutomationEndpoint`. That manifest describes the automation surface a
+  // host may remap, and `InterfaceEndpoints` requires every key it declares --
+  // adding these would break existing manifests. Git sync is a local-mode
+  // operator feature outside that surface.
+  static async getGitSyncStatus(): Promise<GitSyncStatus> {
+    const active = getActiveBackend().backend;
+    const path = `${AUTOMATION_BASE_PATH}/v1/git-sync/status`;
+
+    if (active.kind === "cloud") {
+      return callCloudProxy<GitSyncStatus>({
+        backend: active,
+        method: "GET",
+        path,
+      });
+    }
+
+    const { data } = await localAutomationAxios.get<GitSyncStatus>(path);
+    return data;
+  }
+
+  static async updateGitSyncConfig(
+    body: GitSyncConfigUpdateRequest,
+  ): Promise<GitSyncStatus> {
+    const active = getActiveBackend().backend;
+    const path = `${AUTOMATION_BASE_PATH}/v1/git-sync/config`;
+
+    if (active.kind === "cloud") {
+      return callCloudProxy<GitSyncStatus>({
+        backend: active,
+        method: "PUT",
+        path,
+        body: body as Record<string, unknown>,
+      });
+    }
+
+    const { data } = await localAutomationAxios.put<GitSyncStatus>(path, body);
+    return data;
+  }
+
+  /**
+   * Ask whether a configuration can reach its repo, without saving it. Takes
+   * the same body as `updateGitSyncConfig` and answers for the settings that
+   * body would leave in place.
+   */
+  static async checkGitSyncConfig(
+    body: GitSyncConfigUpdateRequest,
+  ): Promise<GitSyncCheckResponse> {
+    const active = getActiveBackend().backend;
+    const path = `${AUTOMATION_BASE_PATH}/v1/git-sync/check`;
+
+    if (active.kind === "cloud") {
+      return callCloudProxy<GitSyncCheckResponse>({
+        backend: active,
+        method: "POST",
+        path,
+        body: body as Record<string, unknown>,
+      });
+    }
+
+    const { data } = await localAutomationAxios.post<GitSyncCheckResponse>(
+      path,
+      body,
+    );
+    return data;
+  }
+
+  static async triggerGitSync(): Promise<GitSyncTriggerResponse> {
+    const active = getActiveBackend().backend;
+    const path = `${AUTOMATION_BASE_PATH}/v1/git-sync/sync`;
+
+    if (active.kind === "cloud") {
+      return callCloudProxy<GitSyncTriggerResponse>({
+        backend: active,
+        method: "POST",
+        path,
+      });
+    }
+
+    const { data } =
+      await localAutomationAxios.post<GitSyncTriggerResponse>(path);
+    return data;
+  }
+
+  static async checkHealth(): Promise<AutomationHealthResponse> {
+    const active = getActiveBackend().backend;
+    const path = `${AUTOMATION_BASE_PATH}${getAutomationEndpoint("health")}`;
+
+    try {
+      if (active.kind === "cloud") {
+        const response = await callCloudProxy<AutomationHealthResponse>({
+          backend: active,
+          method: "GET",
+          path,
+          // Fail fast, matching the local branch's 5s timeout below.
+          timeoutSeconds: 5,
+          headers: await buildAutomationRequestHeaders(),
+        });
+        return response;
+      }
+
+      const { data } = await localAutomationAxios.get<AutomationHealthResponse>(
+        path,
+        { timeout: 5000 },
+      );
+      return data;
+    } catch {
+      return { status: "error" };
+    }
+  }
+}
+
+export default AutomationService;

src/api/backend-registry/active-store.ts

@@ -0,0 +1,193 @@
+import { getBackendHealthEntry } from "./health-store";
+import {
+  readStoredActiveBackend,
+  readStoredBackends,
+  writeStoredActiveBackend,
+  writeStoredBackends,
+} from "./storage";
+import type { Backend, BackendSelection, ResolvedActiveBackend } from "./types";
+import {
+  currentLocationSearch,
+  readBackendSelectionFromUrl,
+} from "./url-selection";
+
+type Listener = () => void;
+
+interface Snapshot {
+  backends: Backend[];
+  selection: BackendSelection | null;
+  active: ResolvedActiveBackend;
+}
+
+export const NO_BACKEND_ID = "no-backend";
+
+/**
+ * Sentinel returned when the registry has no usable backend. It must never be
+ * persisted, and callers must check `isNoBackend()` before interpreting fields
+ * like `kind`, `host`, or `apiKey`.
+ */
+export const NO_BACKEND: Backend = {
+  id: NO_BACKEND_ID,
+  name: "No Backend Available",
+  host: "",
+  apiKey: "",
+  kind: "local",
+};
+
+export function isNoBackend(backend: Backend): boolean {
+  return backend.id === NO_BACKEND_ID;
+}
+
+/**
+ * Choose an active backend when there is no valid explicit selection (fresh
+ * start, or the selected backend was removed). Most of the GUI speaks the
+ * local agent-server protocol, so a cloud or dead-local backend at index 0
+ * would leave `getEffectiveLocalBackend()` null and make every local-protocol
+ * call throw "No backend is configured" even when a healthy local backend is
+ * registered further down the list. Consult the synchronous, persisted health
+ * store and prefer a healthy local backend; fall back to any local backend so
+ * the effective-local resolver still resolves, then to the prior deterministic
+ * `backends[0]` behavior for the registry-has-no-local case.
+ */
+function pickFallbackBackend(backends: Backend[]): Backend {
+  const healthyLocalBackend = backends.find(
+    (backend) =>
+      backend.kind === "local" &&
+      getBackendHealthEntry(backend.id)?.disabled !== true,
+  );
+  if (healthyLocalBackend) return healthyLocalBackend;
+
+  const localBackend = backends.find((backend) => backend.kind === "local");
+  return localBackend ?? backends[0] ?? NO_BACKEND;
+}
+
+function computeSnapshot(
+  backends: Backend[],
+  selection: BackendSelection | null,
+): Snapshot {
+  let activeBackend: Backend | null = null;
+  let activeOrgId: string | null = null;
+
+  if (selection) {
+    const found = backends.find((b) => b.id === selection.backendId);
+    if (found) {
+      activeBackend = found;
+      activeOrgId = selection.orgId ?? null;
+    }
+    // If the selection points at a removed backend, fall through to
+    // the unselected case below; we also drop the orgId since it only
+    // makes sense in the context of a specific cloud backend.
+  }
+
+  // @spec BM-003 — Fallback on active backend removal
+  if (!activeBackend) {
+    activeBackend = pickFallbackBackend(backends);
+    activeOrgId = null;
+  }
+
+  return {
+    backends,
+    selection,
+    active: { backend: activeBackend, orgId: activeOrgId },
+  };
+}
+
+/**
+ * Resolve the selection this tab boots with. A backend pinned in the URL wins
+ * over stored state so a link opened in a new tab (cmd/ctrl-click, middle
+ * click, "Open in new tab") lands on the backend that owns the linked
+ * conversation, even when the new tab starts with an empty `sessionStorage`
+ * and would otherwise adopt the `localStorage` fallback. The honoured
+ * selection is persisted so later in-tab navigation — which drops the query
+ * parameters — keeps the same backend.
+ */
+function readInitialSelection(backends: Backend[]): BackendSelection | null {
+  const fromUrl = readBackendSelectionFromUrl(
+    backends,
+    currentLocationSearch(),
+  );
+  if (fromUrl) {
+    writeStoredActiveBackend(fromUrl);
+    return fromUrl;
+  }
+  return readStoredActiveBackend();
+}
+
+const initialBackends = readStoredBackends();
+let snapshot: Snapshot = computeSnapshot(
+  initialBackends,
+  readInitialSelection(initialBackends),
+);
+
+const listeners = new Set<Listener>();
+
+function notify(): void {
+  listeners.forEach((listener) => listener());
+}
+
+export function getActiveBackend(): ResolvedActiveBackend {
+  return snapshot.active;
+}
+
+/**
+ * Pick the backend to use for *local agent-server protocol* calls.
+ *
+ * Most of the GUI's services (settings reads/writes, conversation CRUD,
+ * skills/MCP/secrets, etc.) speak the local agent-server's protocol —
+ * they would fail against a cloud host. Only the active backend is eligible:
+ * a cloud selection must not borrow another registered local backend.
+ */
+export function getEffectiveLocalBackend(): Backend | null {
+  const active = snapshot.active.backend;
+  if (active.kind === "local" && !isNoBackend(active)) return active;
+  return null;
+}
+
+export function getRegisteredBackends(): Backend[] {
+  return snapshot.backends;
+}
+
+export function getActiveSelection(): BackendSelection | null {
+  return snapshot.selection;
+}
+
+export function getSnapshot(): Snapshot {
+  return snapshot;
+}
+
+export function setActiveSelection(selection: BackendSelection | null): void {
+  writeStoredActiveBackend(selection);
+  snapshot = computeSnapshot(snapshot.backends, selection);
+  notify();
+}
+
+export function setRegisteredBackends(backends: Backend[]): void {
+  writeStoredBackends(backends);
+
+  let nextSelection = snapshot.selection;
+  if (
+    nextSelection &&
+    !backends.some((b) => b.id === nextSelection!.backendId)
+  ) {
+    nextSelection = null;
+    writeStoredActiveBackend(null);
+  }
+
+  snapshot = computeSnapshot(backends, nextSelection);
+  notify();
+}
+
+export function subscribeActiveBackend(listener: Listener): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** Test-only: re-read storage and clear listeners. */
+
+export function __resetActiveStoreForTests(): void {
+  const backends = readStoredBackends();
+  snapshot = computeSnapshot(backends, readInitialSelection(backends));
+  listeners.clear();
+}

src/api/backend-registry/auth.ts

@@ -0,0 +1,18 @@
+import type { Backend } from "./types";
+
+/**
+ * Build the auth headers to send to a backend.
+ *
+ * Local agent-server uses `X-Session-API-Key`. Cloud expects a bearer
+ * token in the `Authorization` header.
+ */
+export function buildAuthHeaders(backend: Backend): Record<string, string> {
+  if (backend.kind === "cloud" && backend.authMode === "cookie") return {};
+  if (!backend.apiKey) return {};
+
+  if (backend.kind === "cloud") {
+    return { Authorization: `Bearer ${backend.apiKey}` };
+  }
+
+  return { "X-Session-API-Key": backend.apiKey };
+}

src/api/backend-registry/default-backend.ts

@@ -0,0 +1,70 @@
+import {
+  getAgentServerBaseUrl,
+  getAgentServerSessionApiKey,
+  getCookieAuthCloudHost,
+  getLockedCloudHost,
+} from "../agent-server-config";
+import type { Backend } from "./types";
+
+/**
+ * Stable id for the seeded default local backend that is auto-registered in
+ * the backend registry when the launcher provides both a backend host and
+ * API key. After seeding, this backend is a normal registered entry — the
+ * user can rename it, edit its host/api key, or remove it like any other
+ * backend.
+ */
+export const SEEDED_DEFAULT_BACKEND_ID = "default-local";
+
+export const DEFAULT_LOCAL_BACKEND_NAME = "Local";
+export const LOCKED_CLOUD_BACKEND_ID = "locked-cloud";
+export const LOCKED_CLOUD_BACKEND_NAME = "OpenHands Cloud";
+
+export function makeLockedCloudBackend(): Backend | null {
+  if (!getLockedCloudHost()) return null;
+
+  const host = getCookieAuthCloudHost();
+  if (!host) return null;
+
+  return {
+    id: LOCKED_CLOUD_BACKEND_ID,
+    name: LOCKED_CLOUD_BACKEND_NAME,
+    host,
+    apiKey: "",
+    kind: "cloud",
+    authMode: "cookie",
+  };
+}
+
+/**
+ * Construct the default local backend from environment/runtime config.
+ * Returns null unless both a backend location and API key are available.
+ *
+ * Used as the seed entry written to `openhands-backends` on first load;
+ * if it returns null, onboarding is responsible for collecting backend
+ * connection details from the user.
+ *
+ * Returns null when the deployment is locked to a single OpenHands Cloud
+ * host (`VITE_LOCK_TO_CLOUD` / `--lock-to-cloud`). In locked mode the user
+ * can only authenticate against the configured Cloud URL, so seeding a
+ * Local backend from a baked/injected session key would short-circuit the
+ * first-run onboarding gate and strand the user on the Manage Backends
+ * recovery modal with a disconnected Local entry.
+ */
+export function makeDefaultLocalBackend(): Backend | null {
+  // Locked-to-Cloud deployments must never auto-seed a Local backend —
+  // see the docblock above.
+  if (getLockedCloudHost()) return null;
+
+  const host = getAgentServerBaseUrl();
+  const apiKey = getAgentServerSessionApiKey();
+
+  if (!host || !apiKey) return null;
+
+  return {
+    id: SEEDED_DEFAULT_BACKEND_ID,
+    name: DEFAULT_LOCAL_BACKEND_NAME,
+    host,
+    apiKey,
+    kind: "local",
+  };
+}

src/api/backend-registry/health-storage.ts

@@ -0,0 +1,82 @@
+import { getUserFacingConnectionErrorMessage } from "#/utils/user-facing-error";
+
+export const BACKEND_HEALTH_STORAGE_KEY = "openhands-backend-health";
+
+/**
+ * Once a backend has failed this many probes in a row, polling stops
+ * until the user edits the backend's host or apiKey (which resets the
+ * counter via the active-backend store).
+ */
+export const MAX_CONSECUTIVE_FAILURES = 5;
+
+/** Max characters of `error.message` we persist — keeps localStorage tidy. */
+const MAX_ERROR_MESSAGE_LENGTH = 500;
+
+export interface BackendHealthEntry {
+  consecutiveFailures: number;
+  lastError: string | null;
+  lastFailureAt: number | null;
+  disabled: boolean;
+}
+
+export type BackendHealthMap = Record<string, BackendHealthEntry>;
+
+function isValidEntry(value: unknown): value is BackendHealthEntry {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Partial<BackendHealthEntry>;
+  // localStorage is user-writable. Reject anything outside the range
+  // our own writer produces — a tampered `-1` would never reach the
+  // cap and would defeat the whole disable mechanism, and a giant
+  // value would clutter the UI for no reason.
+  return (
+    Number.isInteger(v.consecutiveFailures) &&
+    (v.consecutiveFailures as number) >= 0 &&
+    (v.consecutiveFailures as number) <= MAX_CONSECUTIVE_FAILURES &&
+    (v.lastError === null || typeof v.lastError === "string") &&
+    (v.lastFailureAt === null || typeof v.lastFailureAt === "number") &&
+    typeof v.disabled === "boolean"
+  );
+}
+
+export function readStoredHealth(): BackendHealthMap {
+  if (typeof window === "undefined") return {};
+  try {
+    const raw = window.localStorage.getItem(BACKEND_HEALTH_STORAGE_KEY);
+    if (!raw) return {};
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null) return {};
+
+    const out: BackendHealthMap = {};
+    for (const [id, entry] of Object.entries(parsed)) {
+      if (typeof id === "string" && id.length > 0 && isValidEntry(entry)) {
+        out[id] = entry;
+      }
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+export function writeStoredHealth(map: BackendHealthMap): void {
+  if (typeof window === "undefined") return;
+  try {
+    if (Object.keys(map).length === 0) {
+      window.localStorage.removeItem(BACKEND_HEALTH_STORAGE_KEY);
+      return;
+    }
+    window.localStorage.setItem(
+      BACKEND_HEALTH_STORAGE_KEY,
+      JSON.stringify(map),
+    );
+  } catch {
+    /* ignore quota / serialization errors */
+  }
+}
+
+export function truncateErrorMessage(error: unknown): string {
+  const message = getUserFacingConnectionErrorMessage(error) ?? "Unknown error";
+  return message.length > MAX_ERROR_MESSAGE_LENGTH
+    ? `${message.slice(0, MAX_ERROR_MESSAGE_LENGTH)}…`
+    : message;
+}

src/api/backend-registry/health-store.ts

@@ -0,0 +1,99 @@
+import {
+  MAX_CONSECUTIVE_FAILURES,
+  readStoredHealth,
+  truncateErrorMessage,
+  writeStoredHealth,
+  type BackendHealthEntry,
+  type BackendHealthMap,
+} from "./health-storage";
+
+type Listener = () => void;
+
+let healthMap: BackendHealthMap = readStoredHealth();
+const listeners = new Set<Listener>();
+
+function notify(): void {
+  listeners.forEach((listener) => listener());
+}
+
+function commit(next: BackendHealthMap): void {
+  healthMap = next;
+  writeStoredHealth(next);
+  notify();
+}
+
+export function getHealthSnapshot(): BackendHealthMap {
+  return healthMap;
+}
+
+export function getBackendHealthEntry(id: string): BackendHealthEntry | null {
+  return healthMap[id] ?? null;
+}
+
+export function subscribeBackendHealth(listener: Listener): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/**
+ * Increment the per-backend failure counter. Once the count reaches
+ * `MAX_CONSECUTIVE_FAILURES`, the entry is marked `disabled: true`
+ * which the polling hook reads to stop firing probes — including on a
+ * fresh page load, since the state lives in localStorage.
+ */
+export function recordBackendFailure(id: string, error: unknown): void {
+  const prev = healthMap[id];
+  const consecutiveFailures = Math.min(
+    (prev?.consecutiveFailures ?? 0) + 1,
+    MAX_CONSECUTIVE_FAILURES,
+  );
+  const disabled =
+    prev?.disabled === true || consecutiveFailures >= MAX_CONSECUTIVE_FAILURES;
+
+  const nextEntry: BackendHealthEntry = {
+    consecutiveFailures,
+    lastError: truncateErrorMessage(error),
+    lastFailureAt: Date.now(),
+    disabled,
+  };
+
+  commit({ ...healthMap, [id]: nextEntry });
+}
+
+/**
+ * Clear the entry so the next 10s tick can mark it healthy again.
+ * Called on a successful probe — also covers the case where a backend
+ * had a few failures but recovered before hitting the cap.
+ */
+export function recordBackendSuccess(id: string): void {
+  if (!(id in healthMap)) return;
+  const { [id]: _removed, ...rest } = healthMap;
+  commit(rest);
+}
+
+/**
+ * Re-arm polling for a backend after the user updates its config.
+ * Identical to `recordBackendSuccess` today, but kept distinct so the
+ * call sites read clearly.
+ */
+export function resetBackendHealth(id: string): void {
+  if (!(id in healthMap)) return;
+  const { [id]: _removed, ...rest } = healthMap;
+  commit(rest);
+}
+
+/** Drop the entry entirely — used when the backend is deleted. */
+export function dropBackendHealth(id: string): void {
+  if (!(id in healthMap)) return;
+  const { [id]: _removed, ...rest } = healthMap;
+  commit(rest);
+}
+
+/** Test-only: re-read storage and clear listeners. */
+
+export function __resetHealthStoreForTests(): void {
+  healthMap = readStoredHealth();
+  listeners.clear();
+}

src/api/backend-registry/last-conversation-store.ts

@@ -0,0 +1,76 @@
+// Per-(backend, org) memory of the most recently selected conversation.
+//
+// Used by `BackendSelector` so that flipping from backend A → B while a
+// conversation was active in A jumps straight to B's most recent
+// conversation (if any) instead of dropping the user on the home page.
+// Plain `localStorage` is sufficient: reads happen synchronously during
+// the dropdown's onChange and the data is purely a UX shortcut — losing
+// it just falls back to the conversations list.
+
+export const LAST_CONVERSATION_STORAGE_KEY =
+  "openhands-last-conversation-by-backend";
+
+type StoredMap = Record<string, string>;
+
+function selectionKey(backendId: string, orgId: string | null): string {
+  return orgId ? `${backendId}::${orgId}` : backendId;
+}
+
+function readMap(): StoredMap {
+  if (typeof window === "undefined") return {};
+  try {
+    const raw = window.localStorage.getItem(LAST_CONVERSATION_STORAGE_KEY);
+    if (!raw) return {};
+    const parsed = JSON.parse(raw) as unknown;
+    if (typeof parsed !== "object" || parsed === null) return {};
+    const out: StoredMap = {};
+    for (const [k, v] of Object.entries(parsed as Record<string, unknown>)) {
+      if (typeof v === "string" && v.length > 0) out[k] = v;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+function writeMap(map: StoredMap): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(
+      LAST_CONVERSATION_STORAGE_KEY,
+      JSON.stringify(map),
+    );
+  } catch {
+    /* ignore quota / serialization errors */
+  }
+}
+
+export function getLastConversationId(
+  backendId: string,
+  orgId: string | null,
+): string | null {
+  return readMap()[selectionKey(backendId, orgId)] ?? null;
+}
+
+export function setLastConversationId(
+  backendId: string,
+  orgId: string | null,
+  conversationId: string,
+): void {
+  if (!conversationId) return;
+  const map = readMap();
+  map[selectionKey(backendId, orgId)] = conversationId;
+  writeMap(map);
+}
+
+export function clearLastConversationId(
+  backendId: string,
+  orgId: string | null,
+): void {
+  const map = readMap();
+  const key = selectionKey(backendId, orgId);
+  if (key in map) {
+    delete map[key];
+    writeMap(map);
+  }
+}

src/api/backend-registry/storage.ts

@@ -0,0 +1,244 @@
+import {
+  SEEDED_DEFAULT_BACKEND_ID,
+  makeDefaultLocalBackend,
+  makeLockedCloudBackend,
+} from "./default-backend";
+import type {
+  Backend,
+  BackendAuthMode,
+  BackendKind,
+  BackendSelection,
+} from "./types";
+
+export const BACKENDS_STORAGE_KEY = "openhands-backends";
+export const ACTIVE_BACKEND_STORAGE_KEY = "openhands-active-backend";
+
+function isValidKind(value: unknown): value is BackendKind {
+  return value === "local" || value === "cloud";
+}
+
+function isValidAuthMode(value: unknown): value is BackendAuthMode {
+  return value === undefined || value === "api-key" || value === "cookie";
+}
+
+function isValidBackend(value: unknown): value is Backend {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Partial<Backend>;
+  return (
+    typeof v.id === "string" &&
+    v.id.length > 0 &&
+    typeof v.name === "string" &&
+    typeof v.host === "string" &&
+    typeof v.apiKey === "string" &&
+    isValidKind(v.kind) &&
+    isValidAuthMode(v.authMode) &&
+    (v.connectionRevision === undefined ||
+      (typeof v.connectionRevision === "number" &&
+        Number.isSafeInteger(v.connectionRevision) &&
+        v.connectionRevision >= 0))
+  );
+}
+
+function isLoopbackUrl(value: string): boolean {
+  try {
+    const { hostname } = new URL(value);
+    return (
+      hostname === "localhost" ||
+      hostname === "127.0.0.1" ||
+      hostname === "::1" ||
+      hostname === "[::1]"
+    );
+  } catch {
+    return false;
+  }
+}
+
+function shouldSyncLauncherDefaultLocalBackend(
+  backend: Backend,
+  defaultBackend: Backend,
+): boolean {
+  if (backend.id !== SEEDED_DEFAULT_BACKEND_ID || backend.kind !== "local") {
+    return false;
+  }
+
+  return (
+    backend.host === defaultBackend.host ||
+    (isLoopbackUrl(backend.host) && isLoopbackUrl(defaultBackend.host))
+  );
+}
+
+function syncLauncherDefaultLocalBackend(backends: Backend[]): Backend[] {
+  const defaultBackend = makeDefaultLocalBackend();
+  if (!defaultBackend) return backends;
+
+  let didSync = false;
+  const syncedBackends = backends.map((backend) => {
+    if (!shouldSyncLauncherDefaultLocalBackend(backend, defaultBackend)) {
+      return backend;
+    }
+
+    if (backend.apiKey === defaultBackend.apiKey) return backend;
+
+    didSync = true;
+    return {
+      ...backend,
+      apiKey: defaultBackend.apiKey,
+    };
+  });
+
+  if (!didSync) return backends;
+
+  writeStoredBackends(syncedBackends);
+  return syncedBackends;
+}
+
+export function writeStoredBackends(backends: Backend[]): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(BACKENDS_STORAGE_KEY, JSON.stringify(backends));
+  } catch {
+    /* ignore quota / serialization errors */
+  }
+}
+
+export function readStoredBackends(): Backend[] {
+  if (typeof window === "undefined") return [];
+
+  try {
+    const lockedCloudBackend = makeLockedCloudBackend();
+    if (lockedCloudBackend) {
+      writeStoredBackends([lockedCloudBackend]);
+      const activeSelection = readStoredActiveBackend();
+      if (activeSelection?.backendId !== lockedCloudBackend.id) {
+        writeStoredActiveBackend({ backendId: lockedCloudBackend.id });
+      }
+      return [lockedCloudBackend];
+    }
+
+    const raw = window.localStorage.getItem(BACKENDS_STORAGE_KEY);
+
+    // First install: seed only when the launcher supplied enough information
+    // for a usable local backend.
+    if (raw === null) {
+      const defaultBackend = makeDefaultLocalBackend();
+      if (!defaultBackend) return [];
+
+      writeStoredBackends([defaultBackend]);
+      return [defaultBackend];
+    }
+
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    const valid = parsed.filter(isValidBackend);
+
+    // If the stored array is empty (or everything in it failed validation),
+    // only re-seed when the launcher supplied both a host and API key.
+    if (valid.length === 0) {
+      const defaultBackend = makeDefaultLocalBackend();
+      if (!defaultBackend) return [];
+
+      writeStoredBackends([defaultBackend]);
+      return [defaultBackend];
+    }
+
+    const synced = syncLauncherDefaultLocalBackend(valid);
+    return synced;
+  } catch {
+    return [];
+  }
+}
+
+function parseBackendSelection(raw: string | null): BackendSelection | null {
+  if (!raw) return null;
+
+  try {
+    const parsed = JSON.parse(raw);
+    if (
+      typeof parsed !== "object" ||
+      parsed === null ||
+      typeof (parsed as BackendSelection).backendId !== "string"
+    ) {
+      return null;
+    }
+    const orgIdRaw = (parsed as BackendSelection).orgId;
+    return {
+      backendId: (parsed as BackendSelection).backendId,
+      orgId:
+        typeof orgIdRaw === "string" && orgIdRaw.length > 0 ? orgIdRaw : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function readStorageItem(
+  storage: Storage | undefined,
+  key: string,
+): string | null {
+  try {
+    return storage?.getItem(key) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function writeStorageItem(
+  storage: Storage | undefined,
+  key: string,
+  value: string,
+): void {
+  try {
+    storage?.setItem(key, value);
+  } catch {
+    /* ignore */
+  }
+}
+
+function removeStorageItem(storage: Storage | undefined, key: string): void {
+  try {
+    storage?.removeItem(key);
+  } catch {
+    /* ignore */
+  }
+}
+
+export function readStoredActiveBackend(): BackendSelection | null {
+  if (typeof window === "undefined") return null;
+
+  // Active backend is tab-scoped so reloading tab A does not adopt tab B's
+  // backend. localStorage remains a last-used fallback for fresh tabs and old
+  // persisted state.
+  const sessionSelection = parseBackendSelection(
+    readStorageItem(window.sessionStorage, ACTIVE_BACKEND_STORAGE_KEY),
+  );
+  if (sessionSelection) return sessionSelection;
+
+  return parseBackendSelection(
+    readStorageItem(window.localStorage, ACTIVE_BACKEND_STORAGE_KEY),
+  );
+}
+
+export function writeStoredActiveBackend(
+  selection: BackendSelection | null,
+): void {
+  if (typeof window === "undefined") return;
+
+  if (!selection) {
+    removeStorageItem(window.sessionStorage, ACTIVE_BACKEND_STORAGE_KEY);
+    removeStorageItem(window.localStorage, ACTIVE_BACKEND_STORAGE_KEY);
+    return;
+  }
+
+  const serialized = JSON.stringify({
+    backendId: selection.backendId,
+    orgId: selection.orgId ?? null,
+  });
+  // Mirror to localStorage only as the default for new tabs/backward
+  // compatibility; reads in existing tabs prefer sessionStorage.
+  writeStorageItem(
+    window.sessionStorage,
+    ACTIVE_BACKEND_STORAGE_KEY,
+    serialized,
+  );
+  writeStorageItem(window.localStorage, ACTIVE_BACKEND_STORAGE_KEY, serialized);
+}

src/api/backend-registry/types.ts

@@ -0,0 +1,23 @@
+export type BackendKind = "local" | "cloud";
+export type BackendAuthMode = "api-key" | "cookie";
+
+export interface Backend {
+  id: string;
+  name: string;
+  host: string;
+  apiKey: string;
+  kind: BackendKind;
+  authMode?: BackendAuthMode;
+  /** Changes whenever connection credentials change, invalidating keyed data. */
+  connectionRevision?: number;
+}
+
+export interface BackendSelection {
+  backendId: string;
+  orgId?: string | null;
+}
+
+export interface ResolvedActiveBackend {
+  backend: Backend;
+  orgId: string | null;
+}

src/api/backend-registry/url-selection.ts

@@ -0,0 +1,83 @@
+import type { Backend, BackendSelection, ResolvedActiveBackend } from "./types";
+
+/**
+ * Query parameters that pin a link to the backend (and cloud org) that owns
+ * the linked resource.
+ *
+ * The active backend is tab-scoped: `readStoredActiveBackend()` prefers
+ * `sessionStorage` and only falls back to `localStorage`. A tab opened with
+ * cmd/ctrl-click or middle-click does not reliably inherit the opener's
+ * `sessionStorage`, so it can boot from the `localStorage` fallback — which
+ * holds whichever backend was selected *last in any tab*, not the one the
+ * sidebar we were just looking at belongs to. The new tab then resolves the
+ * conversation id against the wrong backend and shows "conversation not
+ * found". Carrying the identity in the URL makes the link self-describing so
+ * the new tab pins to the right backend regardless of what storage holds.
+ */
+export const BACKEND_QUERY_PARAM = "backend";
+export const ORG_QUERY_PARAM = "org";
+
+/**
+ * Append the active backend identity to an in-app path so opening it in a new
+ * browsing context resolves against the same backend. Any fragment on the
+ * path is preserved verbatim and kept after the query string.
+ */
+export function withBackendSelectionParams(
+  path: string,
+  active: ResolvedActiveBackend,
+): string {
+  const { backend, orgId } = active;
+  if (!backend.id) return path;
+
+  const hashIndex = path.indexOf("#");
+  const fragment = hashIndex === -1 ? "" : path.slice(hashIndex);
+  const withoutFragment = hashIndex === -1 ? path : path.slice(0, hashIndex);
+
+  // Split at the *first* `?` only. A later `?` is ordinary query data (a
+  // `next=` redirect carrying its own query, say), and `split("?")` would
+  // silently drop everything past it.
+  const queryIndex = withoutFragment.indexOf("?");
+  const pathname =
+    queryIndex === -1 ? withoutFragment : withoutFragment.slice(0, queryIndex);
+  const existingSearch =
+    queryIndex === -1 ? "" : withoutFragment.slice(queryIndex + 1);
+
+  const params = new URLSearchParams(existingSearch);
+  params.set(BACKEND_QUERY_PARAM, backend.id);
+  if (orgId) params.set(ORG_QUERY_PARAM, orgId);
+
+  return `${pathname}?${params.toString()}${fragment}`;
+}
+
+/**
+ * Read a backend selection off the current URL, keeping it only when it names
+ * a registered backend. An unknown id (a link from another machine, or a
+ * backend that has since been removed) is ignored so the caller falls back to
+ * the stored selection.
+ */
+export function readBackendSelectionFromUrl(
+  backends: Backend[],
+  search: string,
+): BackendSelection | null {
+  if (!search) return null;
+
+  let params: URLSearchParams;
+  try {
+    params = new URLSearchParams(search);
+  } catch {
+    return null;
+  }
+
+  const backendId = params.get(BACKEND_QUERY_PARAM);
+  if (!backendId) return null;
+  if (!backends.some((backend) => backend.id === backendId)) return null;
+
+  const orgId = params.get(ORG_QUERY_PARAM);
+  return { backendId, orgId: orgId || null };
+}
+
+/** The current tab's query string, or "" outside a browser. */
+export function currentLocationSearch(): string {
+  if (typeof window === "undefined") return "";
+  return window.location.search;
+}

src/api/bash-service/bash-service.api.ts

@@ -0,0 +1,121 @@
+import { BashClient } from "@openhands/typescript-client/clients";
+import type {
+  BashEvent,
+  BashEventPage,
+  BashOutput,
+} from "@openhands/typescript-client";
+import { buildHttpBaseUrl } from "#/utils/websocket-url";
+import { getActiveBackend } from "../backend-registry/active-store";
+import { callCloudProxy } from "../cloud/proxy";
+import { getAgentServerClientOptions } from "../agent-server-client-options";
+
+interface SearchOptions {
+  kind__eq?: "BashCommand" | "BashOutput";
+  command_id__eq?: string;
+  sort_order?: "TIMESTAMP" | "TIMESTAMP_DESC";
+  page_id?: string;
+  limit?: number;
+}
+
+const MAX_OUTPUT_PAGES = 20; // safety cap; >2000 output events is unlikely.
+
+function isBashOutput(event: BashEvent): event is BashOutput {
+  return event.kind === "BashOutput";
+}
+
+/**
+ * Cloud-aware bash event reads.
+ *
+ * Bash events live on the agent-server runtime that owns the
+ * conversation. In **local** mode we talk to the active backend's
+ * agent-server directly with the SDK's `BashClient` (a per-conversation
+ * URL is honoured when known, otherwise we fall back to the backend
+ * host — a single local agent-server hosts all conversations). In
+ * **cloud** mode we tunnel through `callCloudProxy` with the runtime URL
+ * as `hostOverride`: direct browser calls to `*.prod-runtime.all-hands.dev`
+ * are blocked by CORS, and runtime endpoints authenticate with the
+ * conversation's `X-Session-API-Key`.
+ *
+ * Note on the search filter name: the agent-server API uses
+ * `command_id__eq` (not `bash_command_id__eq`) — that's the parameter the
+ * `BashService.search_bash_events` Python implementation declares and
+ * what the typescript-client's `BashEventSearchOptions` exposes.
+ */
+class BashService {
+  /**
+   * Fetch all `BashOutput` events for a bash command, paginated and
+   * sorted by timestamp. Returns events in command-emission order so
+   * callers can concatenate `stdout` / `stderr` values directly.
+   */
+  static async listOutputs(
+    conversationUrl: string | null,
+    sessionApiKey: string | null | undefined,
+    bashCommandId: string,
+  ): Promise<BashOutput[]> {
+    const outputs: BashOutput[] = [];
+    let pageId: string | undefined;
+    for (let i = 0; i < MAX_OUTPUT_PAGES; i += 1) {
+      const page = await BashService.searchEvents(
+        conversationUrl,
+        sessionApiKey,
+        {
+          kind__eq: "BashOutput",
+          command_id__eq: bashCommandId,
+          sort_order: "TIMESTAMP",
+          ...(pageId ? { page_id: pageId } : {}),
+        },
+      );
+      page.items.forEach((event) => {
+        if (isBashOutput(event)) outputs.push(event);
+      });
+      if (!page.next_page_id) break;
+      pageId = page.next_page_id;
+    }
+    return outputs;
+  }
+
+  private static async searchEvents(
+    conversationUrl: string | null,
+    sessionApiKey: string | null | undefined,
+    options: SearchOptions,
+  ): Promise<BashEventPage> {
+    const active = getActiveBackend().backend;
+
+    if (active.kind === "cloud") {
+      // Cloud requires the per-conversation runtime URL — there is no
+      // shared cloud host that owns bash events. Callers must wait for
+      // the conversation to be hydrated before invoking this method on
+      // a cloud backend.
+      if (!conversationUrl) {
+        throw new Error(
+          "BashService.listOutputs requires a conversation URL on cloud backends",
+        );
+      }
+      const params = new URLSearchParams();
+      Object.entries(options).forEach(([k, v]) => {
+        if (v !== undefined && v !== null) params.set(k, String(v));
+      });
+      return callCloudProxy<BashEventPage>({
+        backend: active,
+        method: "GET",
+        hostOverride: buildHttpBaseUrl(conversationUrl),
+        path: `/api/bash/bash_events/search?${params.toString()}`,
+        authMode: "session-api-key",
+        sessionApiKey,
+      });
+    }
+
+    // Local mode: the active backend's agent-server hosts the bash
+    // events. The optional `conversationUrl` is used when present (lets
+    // us target a per-conversation sub-host), otherwise we fall through
+    // to `backend.host` via `getAgentServerClientOptions`.
+    return new BashClient(
+      getAgentServerClientOptions({
+        ...(conversationUrl ? { conversationUrl } : {}),
+        sessionApiKey,
+      }),
+    ).searchEvents(options);
+  }
+}
+
+export default BashService;

src/api/cloud/agent-profiles-service.api.ts

@@ -0,0 +1,98 @@
+import type {
+  AgentProfileSaveInput,
+  AgentProfileListResponse,
+  AgentProfileDetailResponse,
+  AgentProfileMutationResponse,
+  ActivateAgentProfileResponse,
+} from "@openhands/typescript-client";
+import { getActiveBackend } from "../backend-registry/active-store";
+import type { Backend } from "../backend-registry/types";
+import { callCloudProxy } from "./proxy";
+
+/**
+ * Cloud transport for the Agent Profiles surface. The cloud enterprise
+ * app-server exposes the SAME `/api/agent-profiles` contract as the local
+ * agent-server (paths + response shapes mirror `agent_profiles_router.py`),
+ * but cloud calls authenticate with the backend's bearer token + `X-Org-Id`
+ * and must go through {@link callCloudProxy} — not the direct
+ * `AgentProfilesClient` (which speaks `X-Session-API-Key` to a local host).
+ *
+ * The org is resolved server-side from the auth session (`EFFECTIVE_ORG_ID`),
+ * so — unlike org LLM profiles — no `{org_id}` path segment is needed here.
+ *
+ * Mirrors the pattern in `cloud/settings-service.api.ts`. Consumed by
+ * `AgentProfilesService` on the cloud path.
+ */
+
+const BASE = "/api/agent-profiles";
+
+function activeCloudBackend(): Backend {
+  const active = getActiveBackend().backend;
+  if (active.kind !== "cloud") {
+    throw new Error("Cloud agent-profile call requires a cloud backend.");
+  }
+  return active;
+}
+
+export async function listCloudAgentProfiles(): Promise<AgentProfileListResponse> {
+  return callCloudProxy<AgentProfileListResponse>({
+    backend: activeCloudBackend(),
+    method: "GET",
+    path: BASE,
+  });
+}
+
+export async function getCloudAgentProfile(
+  name: string,
+): Promise<AgentProfileDetailResponse> {
+  return callCloudProxy<AgentProfileDetailResponse>({
+    backend: activeCloudBackend(),
+    method: "GET",
+    path: `${BASE}/${encodeURIComponent(name)}`,
+  });
+}
+
+export async function saveCloudAgentProfile(
+  name: string,
+  profile: AgentProfileSaveInput,
+): Promise<AgentProfileMutationResponse> {
+  return callCloudProxy<AgentProfileMutationResponse>({
+    backend: activeCloudBackend(),
+    method: "POST",
+    path: `${BASE}/${encodeURIComponent(name)}`,
+    body: profile,
+  });
+}
+
+export async function deleteCloudAgentProfile(
+  name: string,
+): Promise<AgentProfileMutationResponse> {
+  return callCloudProxy<AgentProfileMutationResponse>({
+    backend: activeCloudBackend(),
+    method: "DELETE",
+    path: `${BASE}/${encodeURIComponent(name)}`,
+  });
+}
+
+export async function renameCloudAgentProfile(
+  name: string,
+  newName: string,
+): Promise<AgentProfileMutationResponse> {
+  return callCloudProxy<AgentProfileMutationResponse>({
+    backend: activeCloudBackend(),
+    method: "POST",
+    path: `${BASE}/${encodeURIComponent(name)}/rename`,
+    body: { new_name: newName },
+  });
+}
+
+export async function activateCloudAgentProfile(
+  profileId: string,
+): Promise<ActivateAgentProfileResponse> {
+  return callCloudProxy<ActivateAgentProfileResponse>({
+    backend: activeCloudBackend(),
+    method: "POST",
+    path: `${BASE}/${encodeURIComponent(profileId)}/activate`,
+    body: {},
+  });
+}

src/api/cloud/client.ts

@@ -0,0 +1,63 @@
+import { CloudClient } from "@openhands/typescript-client/clients";
+import {
+  getAgentServerBaseUrl,
+  getAgentServerHeaders,
+} from "../agent-server-config";
+import { NoBackendAvailableError } from "../agent-server-client-options";
+import { getActiveBackend } from "../backend-registry/active-store";
+import type { Backend } from "../backend-registry/types";
+
+function requireCloudBackend(backend?: Backend): Backend {
+  if (backend) return backend;
+  const active = getActiveBackend().backend;
+  if (active.kind !== "cloud") {
+    throw new Error("Cloud calls require a cloud backend.");
+  }
+  return active;
+}
+
+/**
+ * Send `X-Org-Id` so the upstream scopes per-request to the org the user
+ * selected locally, instead of the user's globally-shared `current_org_id`
+ * on the cloud backend. Restricted to calls against the active backend: the
+ * selector also fans out per-backend bookkeeping calls (e.g.
+ * `getCloudOrganizations(b)`) that would otherwise carry the active
+ * backend's orgId across an unrelated API key, which the cloud backend
+ * rejects when api_key_org_id and X-Org-Id disagree.
+ */
+function activeOrgForBackend(backend: Backend): string | null {
+  const active = getActiveBackend();
+  return active.backend.id === backend.id ? active.orgId : null;
+}
+
+export function createCloudClient(backend?: Backend): CloudClient {
+  const target = requireCloudBackend(backend);
+  const proxyBaseUrl = getAgentServerBaseUrl();
+  const proxyHeaders = proxyBaseUrl ? getAgentServerHeaders() : {};
+
+  return new CloudClient({
+    host: target.host,
+    apiKey: target.apiKey,
+    orgId: activeOrgForBackend(target),
+    // Default request timeout in ms, matching the 30s the previous axios
+    // transport used for direct and proxied calls. Per-request
+    // `timeoutSeconds` still overrides it for direct calls.
+    timeout: 30_000,
+    ...(proxyBaseUrl
+      ? {
+          proxy: {
+            host: proxyBaseUrl,
+            headers: proxyHeaders,
+          },
+        }
+      : {}),
+  });
+}
+
+export function createCloudClientForRuntime(backend?: Backend): CloudClient {
+  const client = createCloudClient(backend);
+  if (!client.proxy) {
+    throw new NoBackendAvailableError();
+  }
+  return client;
+}

src/api/cloud/conversation-service.api.ts

@@ -0,0 +1,336 @@
+import {
+  getActiveBackend,
+  getRegisteredBackends,
+} from "../backend-registry/active-store";
+import type { Backend } from "../backend-registry/types";
+import { getStoredConversationMetadata } from "../conversation-metadata-store";
+import type {
+  AppConversation,
+  AppConversationPage,
+  AppConversationStartRequest,
+  AppConversationStartTask,
+} from "../conversation-service/agent-server-conversation-service.types";
+import { AGENT_CANVAS_CLIENT_HEADERS } from "../client-source";
+import { callCloudProxy } from "./proxy";
+
+/**
+ * The cloud backend does not always echo `selected_repository` /
+ * `selected_branch` / `git_provider` back from
+ * `GET /api/v1/app-conversations` until its own background hydration
+ * completes. We persist the selection to local storage at connect time
+ * (see `AgentServerConversationService.updateConversationRepository`)
+ * and overlay it here so the chat-page git control bar reflects the
+ * connection immediately, instead of snapping back to the empty
+ * "Connect Repo" state on every refetch.
+ *
+ * Server values take precedence whenever they're populated; the
+ * local-storage fallback only fills in fields the server returned as
+ * `null`/`undefined`.
+ */
+function overlayStoredRepoSelection(
+  conversation: AppConversation | null,
+): AppConversation | null {
+  if (!conversation?.id) return conversation;
+  const stored = getStoredConversationMetadata(conversation.id);
+  if (!stored) return conversation;
+
+  return {
+    ...conversation,
+    selected_repository:
+      conversation.selected_repository ?? stored.selected_repository ?? null,
+    selected_branch:
+      conversation.selected_branch ?? stored.selected_branch ?? null,
+    git_provider: conversation.git_provider ?? stored.git_provider ?? null,
+    selected_workspace:
+      conversation.selected_workspace ?? stored.selected_workspace ?? null,
+  };
+}
+
+function getActiveCloudBackend(): Backend {
+  const active = getActiveBackend().backend;
+  if (active.kind !== "cloud") {
+    throw new Error("Cloud conversations call requires a cloud backend.");
+  }
+  return active;
+}
+
+/**
+ * Resolve the cloud backend a Cloud conversation should be launched against
+ * when the active backend may not be a cloud one. Cloud conversations cannot
+ * register client tools, so the typed launch action always runs from a local
+ * parent and has to reach a registered-but-inactive cloud backend.
+ *
+ * Prefers the active backend when it is already cloud, then the first
+ * registered cloud backend that carries credentials. Returns `null` when the
+ * user has no cloud backend connected, so callers can give the agent
+ * corrective guidance instead of failing opaquely.
+ *
+ * Note: `createCloudClient` only sends `X-Org-Id` for the *active* backend, so
+ * a conversation launched against an inactive backend lands in the API key's
+ * own organization.
+ */
+export function pickCloudBackendForLaunch(): Backend | null {
+  const active = getActiveBackend().backend;
+  if (active.kind === "cloud") return active;
+  return (
+    getRegisteredBackends().find(
+      (backend) => backend.kind === "cloud" && !!backend.apiKey,
+    ) ?? null
+  );
+}
+
+/**
+ * Search the cloud app-conversations list. Mirrors the local
+ * `AgentServerConversationService.searchConversations` interface but calls
+ * the cloud endpoint `/api/v1/app-conversations/search`.
+ */
+export async function searchCloudConversations(
+  limit: number = 20,
+  pageId?: string,
+): Promise<AppConversationPage> {
+  const backend = getActiveCloudBackend();
+  const params = new URLSearchParams();
+  params.set("limit", String(limit));
+  if (pageId) params.set("page_id", pageId);
+  params.set("sort_order", "UPDATED_AT_DESC");
+
+  const data = await callCloudProxy<{
+    items: AppConversation[];
+    next_page_id: string | null;
+  }>({
+    backend,
+    method: "GET",
+    path: `/api/v1/app-conversations/search?${params.toString()}`,
+  });
+
+  return {
+    items: (data?.items ?? []).map(
+      (item) => overlayStoredRepoSelection(item) as AppConversation,
+    ),
+    next_page_id: data?.next_page_id ?? null,
+  };
+}
+
+/**
+ * Batch-fetch cloud app-conversations by id. Mirrors the local
+ * `AgentServerConversationService.batchGetAppConversations` interface.
+ */
+export async function batchGetCloudConversations(
+  ids: string[],
+): Promise<(AppConversation | null)[]> {
+  if (ids.length === 0) return [];
+  const backend = getActiveCloudBackend();
+  const params = new URLSearchParams();
+  for (const id of ids) params.append("ids", id);
+  const data = await callCloudProxy<(AppConversation | null)[]>({
+    backend,
+    method: "GET",
+    path: `/api/v1/app-conversations?${params.toString()}`,
+  });
+  return (data ?? []).map(overlayStoredRepoSelection);
+}
+
+/**
+ * Create a v1 app-conversation on the cloud backend.
+ *
+ * Mirrors OpenHands' cloud flow: POST /api/v1/app-conversations with the
+ * `AppConversationStartRequest` payload, returning a
+ * `AppConversationStartTask`. The task is initially WORKING; the caller
+ * polls `getCloudAppConversationStartTask` (3s cadence per OpenHands)
+ * until status is READY (then `app_conversation_id`, `agent_server_url`,
+ * and `session_api_key` are populated) or ERROR.
+ *
+ * This path does NOT use encrypted-settings round-tripping. Secrets stay
+ * server-side on the cloud backend — the only auth carried is the cloud bearer
+ * token, and the conversation runtime is
+ * provisioned with its own ephemeral session_api_key returned in the
+ * task.
+ */
+export async function createCloudAppConversation(
+  request: AppConversationStartRequest,
+  // Defaults to the active backend. The typed launch action passes an explicit
+  // backend because it always runs from a *local* parent conversation.
+  backendOverride?: Backend,
+): Promise<AppConversationStartTask> {
+  const backend = backendOverride ?? getActiveCloudBackend();
+  const data = await callCloudProxy<AppConversationStartTask>({
+    backend,
+    method: "POST",
+    path: "/api/v1/app-conversations",
+    body: request as unknown as Record<string, unknown>,
+    headers: AGENT_CANVAS_CLIENT_HEADERS,
+  });
+  return data;
+}
+
+/**
+ * Download a v1 app-conversation as a ZIP from the cloud backend. Mirrors
+ * the local `AgentServerConversationService.downloadConversation` interface but
+ * calls
+ * `GET /api/v1/app-conversations/{id}/download`, which returns
+ * `application/zip` with `Content-Disposition` set by the cloud backend.
+ */
+export async function downloadCloudConversation(
+  conversationId: string,
+): Promise<Blob> {
+  const backend = getActiveCloudBackend();
+  return callCloudProxy<Blob>({
+    backend,
+    method: "GET",
+    path: `/api/v1/app-conversations/${conversationId}/download`,
+    responseType: "blob",
+  });
+}
+
+/**
+ * Delete a v1 app-conversation on the cloud backend. Mirrors the local
+ * `AgentServerConversationService.deleteConversation` interface but calls
+ * `DELETE /api/v1/app-conversations/{id}`, which returns a JSON
+ * `Success` envelope (discarded here — the caller only needs to know
+ * the request didn't error).
+ */
+export async function deleteCloudConversation(
+  conversationId: string,
+): Promise<void> {
+  const backend = getActiveCloudBackend();
+  await callCloudProxy<unknown>({
+    backend,
+    method: "DELETE",
+    path: `/api/v1/app-conversations/${conversationId}`,
+  });
+}
+
+/**
+ * Toggle the public-sharing flag on a cloud v1 app-conversation. Mirrors
+ * OpenHands' `AgentServerConversationService.updateConversationPublicFlag`:
+ * `PATCH /api/v1/app-conversations/{id}` with `{ public }`, returning
+ * the updated conversation.
+ */
+export async function updateCloudConversationPublicFlag(
+  conversationId: string,
+  isPublic: boolean,
+): Promise<AppConversation> {
+  const backend = getActiveCloudBackend();
+  const data = await callCloudProxy<AppConversation>({
+    backend,
+    method: "PATCH",
+    path: `/api/v1/app-conversations/${conversationId}`,
+    body: { public: isPublic },
+  });
+  return data;
+}
+
+/**
+ * Rename a cloud v1 app-conversation. The title belongs to the Cloud
+ * app-conversation resource, so updating a runtime Agent Server would not
+ * persist it in the Cloud conversation list.
+ */
+export async function updateCloudConversationTitle(
+  conversationId: string,
+  title: string,
+): Promise<AppConversation> {
+  const backend = getActiveCloudBackend();
+  return callCloudProxy<AppConversation>({
+    backend,
+    method: "PATCH",
+    path: `/api/v1/app-conversations/${conversationId}`,
+    body: { title },
+  });
+}
+
+/**
+ * Pause the cloud sandbox backing a v1 app-conversation. Mirrors
+ * OpenHands' `SandboxService.pauseSandbox`:
+ * `POST /api/v1/sandboxes/{sandboxId}/pause` on the cloud backend, which stops
+ * the runtime owning the conversation.
+ */
+export async function pauseCloudSandbox(sandboxId: string): Promise<void> {
+  const backend = getActiveCloudBackend();
+  await callCloudProxy<unknown>({
+    backend,
+    method: "POST",
+    path: `/api/v1/sandboxes/${sandboxId}/pause`,
+  });
+}
+
+/**
+ * Resume a paused cloud sandbox. Mirrors OpenHands' `SandboxService.resumeSandbox`
+ * by calling `POST /api/v1/sandboxes/{sandboxId}/resume` on the SaaS.
+ *
+ * This is the correct endpoint for waking a PAUSED sandbox. It is a
+ * lightweight unpause — NOT the same as creating a new start task via
+ * `POST /api/v1/app-conversations`, which provisions a fresh conversation
+ * and is subject to the 120-second sandbox-start timeout.
+ */
+export async function resumeCloudSandbox(sandboxId: string): Promise<void> {
+  const backend = getActiveCloudBackend();
+  await callCloudProxy<unknown>({
+    backend,
+    method: "POST",
+    path: `/api/v1/sandboxes/${sandboxId}/resume`,
+  });
+}
+
+/**
+ * Read a file from a cloud conversation's sandbox workspace. Mirrors
+ * OpenHands' `AgentServerConversationService.readConversationFile` — hits
+ * `GET /api/v1/app-conversations/{id}/file?file_path=...` on the cloud backend
+ * and returns the file content as a string.
+ */
+export async function readCloudConversationFile(
+  conversationId: string,
+  filePath: string,
+): Promise<string> {
+  const backend = getActiveCloudBackend();
+  const params = new URLSearchParams();
+  params.append("file_path", filePath);
+  const data = await callCloudProxy<string>({
+    backend,
+    method: "GET",
+    path: `/api/v1/app-conversations/${conversationId}/file?${params.toString()}`,
+  });
+  return data ?? "";
+}
+
+/**
+ * List every file in a cloud conversation's sandbox workspace. Hits
+ * `GET /api/v1/app-conversations/{id}/files?path=...` on the cloud backend,
+ * which resolves the conversation's runtime and runs a bounded `find`
+ * server-side (see enterprise `list_conversation_files`). Unlike the
+ * git-changes source, this returns the full tree so the Files tab matches the
+ * local-backend experience. Paths come back relative to `path`.
+ */
+export async function listCloudConversationFiles(
+  conversationId: string,
+  path: string,
+): Promise<string[]> {
+  const backend = getActiveCloudBackend();
+  const params = new URLSearchParams();
+  params.append("path", path);
+  const data = await callCloudProxy<string[]>({
+    backend,
+    method: "GET",
+    path: `/api/v1/app-conversations/${conversationId}/files?${params.toString()}`,
+  });
+  return Array.isArray(data) ? data : [];
+}
+
+/**
+ * Fetch a single v1 app-conversation start task. Mirrors OpenHands'
+ * `AgentServerConversationService.getStartTask` — uses the batch search endpoint
+ * with a single id and unwraps the first result.
+ */
+export async function getCloudAppConversationStartTask(
+  taskId: string,
+  backendOverride?: Backend,
+): Promise<AppConversationStartTask | null> {
+  const backend = backendOverride ?? getActiveCloudBackend();
+  const params = new URLSearchParams();
+  params.set("ids", taskId);
+  const data = await callCloudProxy<(AppConversationStartTask | null)[]>({
+    backend,
+    method: "GET",
+    path: `/api/v1/app-conversations/start-tasks?${params.toString()}`,
+  });
+  return data?.[0] ?? null;
+}

src/api/cloud/git-service.api.ts

@@ -0,0 +1,104 @@
+import type {
+  BranchPage,
+  GitRepository,
+  InstallationPage,
+  RepositoryPage,
+} from "#/types/git";
+import type { Provider } from "#/types/settings";
+import { getActiveBackend } from "../backend-registry/active-store";
+import type { Backend } from "../backend-registry/types";
+import { callCloudProxy } from "./proxy";
+
+function getActiveCloudBackend(): Backend {
+  const active = getActiveBackend().backend;
+  if (active.kind !== "cloud") {
+    throw new Error("Cloud git call requires a cloud backend.");
+  }
+  return active;
+}
+
+export async function searchCloudRepositories(args: {
+  provider: Provider;
+  query?: string;
+  limit?: number;
+  pageId?: string;
+  installationId?: string;
+}): Promise<RepositoryPage> {
+  const backend = getActiveCloudBackend();
+  const params = new URLSearchParams();
+  params.set("provider", args.provider);
+  params.set("limit", String(args.limit ?? 100));
+  if (args.query) params.set("query", args.query);
+  if (args.pageId) params.set("page_id", args.pageId);
+  if (args.installationId) params.set("installation_id", args.installationId);
+
+  const data = await callCloudProxy<{
+    items: GitRepository[];
+    next_page_id: string | null;
+  }>({
+    backend,
+    method: "GET",
+    path: `/api/v1/git/repositories/search?${params.toString()}`,
+  });
+
+  return {
+    items: data?.items ?? [],
+    next_page_id: data?.next_page_id ?? null,
+  };
+}
+
+export async function getCloudInstallations(args: {
+  provider: Provider;
+  pageId?: string;
+  limit?: number;
+}): Promise<InstallationPage> {
+  const backend = getActiveCloudBackend();
+  const params = new URLSearchParams();
+  params.set("provider", args.provider);
+  params.set("limit", String(args.limit ?? 100));
+  if (args.pageId) params.set("page_id", args.pageId);
+
+  const data = await callCloudProxy<{
+    items: string[];
+    next_page_id: string | null;
+  }>({
+    backend,
+    method: "GET",
+    path: `/api/v1/git/installations/search?${params.toString()}`,
+  });
+
+  return {
+    items: data?.items ?? [],
+    next_page_id: data?.next_page_id ?? null,
+  };
+}
+
+export async function getCloudRepositoryBranches(args: {
+  provider: Provider;
+  repository: string;
+  query?: string;
+  pageId?: string;
+  limit?: number;
+}): Promise<BranchPage> {
+  const backend = getActiveCloudBackend();
+  const params = new URLSearchParams();
+  params.set("provider", args.provider);
+  params.set("repository", args.repository);
+  params.set("limit", String(args.limit ?? 30));
+  params.set("query", args.query ?? "");
+  if (args.pageId) params.set("page_id", args.pageId);
+
+  const data = await callCloudProxy<{
+    items: BranchPage["items"];
+    next_page_id: string | null;
+  }>({
+    backend,
+    method: "GET",
+    path: `/api/v1/git/branches/search?${params.toString()}`,
+  });
+
+  return {
+    items: data?.items ?? [],
+    next_page_id: data?.next_page_id ?? null,
+  };
+}

src/api/cloud/organization-service.api.ts

@@ -0,0 +1,147 @@
+import { HttpError } from "@openhands/typescript-client";
+import { getActiveBackend } from "../backend-registry/active-store";
+import type { Backend } from "../backend-registry/types";
+import { callCloudProxy } from "./proxy";
+import type {
+  CloudApiKeyMetadata,
+  CloudOrganization,
+  CloudOrganizationMember,
+  CloudOrganizationsResponse,
+} from "./types";
+
+interface OrganizationsResult {
+  items: CloudOrganization[];
+  currentOrgId: string | null;
+}
+
+function normalizeResult(
+  data: CloudOrganizationsResponse | undefined | null,
+): OrganizationsResult {
+  return {
+    items: data?.items ?? [],
+    currentOrgId: data?.current_org_id ?? null,
+  };
+}
+
+function resolveBackend(backend?: Backend): Backend {
+  if (backend) return backend;
+  const active = getActiveBackend().backend;
+  if (active.kind !== "cloud") {
+    throw new Error(
+      "Cloud organization calls require a cloud backend. Active backend is local.",
+    );
+  }
+  return active;
+}
+
+/**
+ * Fetch the org list for a cloud backend. With no argument, uses the active
+ * cloud backend; pass `backend` explicitly to fetch for an inactive cloud
+ * (used by the selector to flatten all cloud rows).
+ *
+ * Calls the cloud API directly with the backend's bearer token.
+ */
+export async function getCloudOrganizations(
+  backend?: Backend,
+): Promise<OrganizationsResult> {
+  const target = resolveBackend(backend);
+  const data = await callCloudProxy<CloudOrganizationsResponse>({
+    backend: target,
+    method: "GET",
+    path: "/api/organizations",
+  });
+  return normalizeResult(data);
+}
+
+/**
+ * Fetch metadata for the API key used to authenticate this cloud backend.
+ * The returned `orgId` is the single org the key is authorized to act on
+ * (the cloud contract: one key → one org).
+ *
+ * Legacy keys minted before per-key org binding existed cause the upstream
+ * to return HTTP 400 — we surface that as `isLegacyKey: true` with a null
+ * `orgId` so the caller can fall back to the unfiltered behavior. Other
+ * statuses (401 revoked, 5xx outage) propagate so React Query can mark
+ * the query as failed and the selector can render the no-org-known row.
+ */
+export async function getCurrentCloudApiKey(
+  backend?: Backend,
+): Promise<{ orgId: string | null; isLegacyKey: boolean }> {
+  const target = resolveBackend(backend);
+  try {
+    const data = await callCloudProxy<CloudApiKeyMetadata>({
+      backend: target,
+      method: "GET",
+      path: "/api/keys/current",
+    });
+    return { orgId: data?.org_id ?? null, isLegacyKey: false };
+  } catch (e) {
+    if (e instanceof HttpError && e.status === 400) {
+      return { orgId: null, isLegacyKey: true };
+    }
+    throw e;
+  }
+}
+
+/**
+ * Fetch `GET /api/organizations/{orgId}/me`. Identifies the calling user as
+ * a member of `orgId`. The GUI uses `me.org_id === me.user_id` to decide
+ * whether `orgId` is the user's personal workspace — that's the cloud
+ * contract (the auto-generated personal-workspace org has the same id as
+ * the user).
+ *
+ * `role` is the caller's role in the org (`owner` | `admin` | `member`, or
+ * `null` if the upstream omits it). `permissions` is the server-defined
+ * permission set for that role (e.g. `edit_org_settings`); it is `null` on
+ * older app-servers that don't return it, so callers fall back to the role.
+ * See `useCanManageOrgProfiles`.
+ */
+export async function getCloudOrganizationMe(
+  orgId: string,
+  backend?: Backend,
+): Promise<{
+  orgId: string;
+  userId: string;
+  role: string | null;
+  permissions?: string[] | null;
+}> {
+  const target = resolveBackend(backend);
+  const data = await callCloudProxy<{
+    org_id: string;
+    user_id: string;
+    role?: string;
+    permissions?: string[];
+  }>({
+    backend: target,
+    method: "GET",
+    path: `/api/organizations/${encodeURIComponent(orgId)}/me`,
+  });
+  return {
+    orgId: data?.org_id ?? orgId,
+    userId: data?.user_id ?? "",
+    role: data?.role ?? null,
+    // `null` when the field is absent (older app-server) so callers can fall
+    // back to a role check; a present array is the server's source of truth.
+    permissions: Array.isArray(data?.permissions) ? data.permissions : null,
+  };
+}
+
+/**
+ * Fetch `GET /api/organizations/{orgId}/members/{userId}`: one member of
+ * `orgId` by user id. Any org member may read it (same permission as the
+ * members list). The upstream responds 404 when `userId` is not (or no
+ * longer) a member of the org, and older app-servers that predate the route
+ * 404 as well, so callers should treat a failure as "identity unresolved".
+ */
+export async function getCloudOrganizationMember(
+  orgId: string,
+  userId: string,
+  backend?: Backend,
+): Promise<CloudOrganizationMember> {
+  const target = resolveBackend(backend);
+  return callCloudProxy<CloudOrganizationMember>({
+    backend: target,
+    method: "GET",
+    path: `/api/organizations/${encodeURIComponent(orgId)}/members/${encodeURIComponent(userId)}`,
+  });
+}

src/api/cloud/profiles-service.api.ts

@@ -0,0 +1,140 @@
+import type {
+  ActivateProfileResponse,
+  ProfileDetailResponse,
+  ProfileListResponse,
+  ProfileMutationResponse,
+  SaveProfileRequest,
+} from "@openhands/typescript-client";
+import { getActiveBackend } from "../backend-registry/active-store";
+import type { Backend } from "../backend-registry/types";
+import { callCloudProxy } from "./proxy";
+
+/**
+ * Cloud LLM-profile service.
+ *
+ * Profile CRUD is routed to the org-scoped endpoints
+ * `/api/organizations/{orgId}/profiles`, which enforce `EDIT_ORG_SETTINGS`
+ * server-side — so a member's mutation is rejected with 403 even on a direct
+ * API call, not just hidden in the UI. When the active cloud backend has no org
+ * bound (legacy API keys), we fall back to the ungated per-user settings route
+ * `/api/v1/settings/profiles`, where there is no org role to enforce against.
+ *
+ * The two routes share shapes except `get` (org returns `llm`, settings returns
+ * `config`) and `activate` (org returns `llm`, settings returns `model`); both
+ * are normalized to the SDK profile types below. Neither route exposes secrets.
+ */
+
+const SETTINGS_PROFILES_PATH = "/api/v1/settings/profiles";
+
+/**
+ * Resolve the backend + base path for the active cloud backend's profiles:
+ * the org-gated route when an org is bound, else the per-user settings route.
+ */
+function cloudProfilesTarget(): { backend: Backend; base: string } {
+  const { backend, orgId } = getActiveBackend();
+  if (backend.kind !== "cloud") {
+    throw new Error("Cloud profiles call requires a cloud backend.");
+  }
+  return {
+    backend,
+    base: orgId
+      ? `/api/organizations/${encodeURIComponent(orgId)}/profiles`
+      : SETTINGS_PROFILES_PATH,
+  };
+}
+
+export async function fetchCloudProfiles(): Promise<ProfileListResponse> {
+  const { backend, base } = cloudProfilesTarget();
+  return callCloudProxy<ProfileListResponse>({
+    backend,
+    method: "GET",
+    path: base,
+  });
+}
+
+export async function fetchCloudProfile(
+  name: string,
+): Promise<ProfileDetailResponse> {
+  const { backend, base } = cloudProfilesTarget();
+  // Org returns `{ name, llm }`; settings returns `{ name, config, api_key_set }`.
+  // Normalize to the SDK detail shape. Neither route exposes the key, and the
+  // GUI never reads the detail's `api_key_set` (only list-item `api_key_set`).
+  const result = await callCloudProxy<{
+    name: string;
+    config?: Record<string, unknown>;
+    llm?: Record<string, unknown>;
+    api_key_set?: boolean;
+  }>({
+    backend,
+    method: "GET",
+    path: `${base}/${encodeURIComponent(name)}`,
+  });
+  return {
+    name: result.name,
+    config: result.config ?? result.llm ?? {},
+    api_key_set: result.api_key_set ?? false,
+  };
+}
+
+export async function saveCloudProfile(
+  name: string,
+  request: SaveProfileRequest,
+): Promise<ProfileMutationResponse> {
+  const { backend, base } = cloudProfilesTarget();
+  return callCloudProxy<ProfileMutationResponse>({
+    backend,
+    method: "POST",
+    path: `${base}/${encodeURIComponent(name)}`,
+    body: request,
+  });
+}
+
+export async function deleteCloudProfile(
+  name: string,
+): Promise<ProfileMutationResponse> {
+  const { backend, base } = cloudProfilesTarget();
+  return callCloudProxy<ProfileMutationResponse>({
+    backend,
+    method: "DELETE",
+    path: `${base}/${encodeURIComponent(name)}`,
+  });
+}
+
+export async function renameCloudProfile(
+  name: string,
+  newName: string,
+): Promise<ProfileMutationResponse> {
+  const { backend, base } = cloudProfilesTarget();
+  return callCloudProxy<ProfileMutationResponse>({
+    backend,
+    method: "POST",
+    path: `${base}/${encodeURIComponent(name)}/rename`,
+    body: { new_name: newName },
+  });
+}
+
+export async function activateCloudProfile(
+  name: string,
+): Promise<ActivateProfileResponse> {
+  const { backend, base } = cloudProfilesTarget();
+  // Org returns `{ name, message, llm }`; settings returns `{ name, message,
+  // model }`. The SDK type carries `llm_applied`; derive it from whichever the
+  // route provided (consumers only read name/message — the hook just
+  // invalidates caches).
+  const result = await callCloudProxy<{
+    name: string;
+    message: string;
+    model?: string | null;
+    llm?: Record<string, unknown> | null;
+  }>({
+    backend,
+    method: "POST",
+    path: `${base}/${encodeURIComponent(name)}/activate`,
+    body: {},
+  });
+  return {
+    name: result.name,
+    message: result.message,
+    llm_applied: result.model != null || result.llm != null,
+  };
+}

src/api/cloud/provider-connections-service.api.ts

@@ -0,0 +1,99 @@
+import type {
+  ProviderConnection,
+  CreateProviderConnectionRequest,
+  UpdateProviderConnectionRequest,
+} from "../provider-connections-service/provider-connections-service.api";
+import { getActiveBackend } from "../backend-registry/active-store";
+import type { Backend } from "../backend-registry/types";
+import { callCloudProxy } from "./proxy";
+
+/**
+ * Cloud provider-connections service.
+ *
+ * Provider-connection CRUD is routed to the org-scoped endpoints
+ * `/api/organizations/{orgId}/provider-connections`, which enforce
+ * `EDIT_ORG_SETTINGS` server-side (listing requires `VIEW_ORG_SETTINGS`) — so a
+ * member's mutation is rejected with 403 even on a direct API call, not just
+ * hidden in the UI. This mirrors the cloud LLM-profile service.
+ *
+ * Unlike the local agent-server (which returns a bare array), the org list
+ * route wraps results as `{ connections: [...] }`; this service unwraps that so
+ * callers see the same `ProviderConnection[]` shape on both backends. Individual
+ * mutations return a bare `ProviderConnection` on both backends. Neither route
+ * exposes the stored key; each item carries `api_key_set` instead.
+ *
+ * Cloud has no unbound-org fallback here: provider connections are inherently
+ * org-scoped, so an org must be bound. A cloud backend without an org id is a
+ * programming error rather than a legacy-key case.
+ */
+
+interface CloudProviderConnectionListResponse {
+  connections: ProviderConnection[];
+}
+
+/** Resolve the backend + org-scoped base path for the active cloud backend. */
+function cloudProviderConnectionsTarget(): { backend: Backend; base: string } {
+  const { backend, orgId } = getActiveBackend();
+  if (backend.kind !== "cloud") {
+    throw new Error(
+      "Cloud provider-connections call requires a cloud backend.",
+    );
+  }
+  if (!orgId) {
+    throw new Error(
+      "Cloud provider connections require an organization-bound backend.",
+    );
+  }
+  return {
+    backend,
+    base: `/api/organizations/${encodeURIComponent(orgId)}/provider-connections`,
+  };
+}
+
+export async function fetchCloudProviderConnections(): Promise<
+  ProviderConnection[]
+> {
+  const { backend, base } = cloudProviderConnectionsTarget();
+  const result = await callCloudProxy<CloudProviderConnectionListResponse>({
+    backend,
+    method: "GET",
+    path: base,
+  });
+  return result.connections ?? [];
+}
+
+export async function createCloudProviderConnection(
+  request: CreateProviderConnectionRequest,
+): Promise<ProviderConnection> {
+  const { backend, base } = cloudProviderConnectionsTarget();
+  return callCloudProxy<ProviderConnection>({
+    backend,
+    method: "POST",
+    path: base,
+    body: request,
+  });
+}
+
+export async function updateCloudProviderConnection(
+  id: string,
+  request: UpdateProviderConnectionRequest,
+): Promise<ProviderConnection> {
+  const { backend, base } = cloudProviderConnectionsTarget();
+  return callCloudProxy<ProviderConnection>({
+    backend,
+    method: "PATCH",
+    path: `${base}/${encodeURIComponent(id)}`,
+    body: request,
+  });
+}
+
+export async function deleteCloudProviderConnection(
+  id: string,
+): Promise<ProviderConnection> {
+  const { backend, base } = cloudProviderConnectionsTarget();
+  return callCloudProxy<ProviderConnection>({
+    backend,
+    method: "DELETE",
+    path: `${base}/${encodeURIComponent(id)}`,
+  });
+}

src/api/cloud/proxy.ts

@@ -0,0 +1,39 @@
+import type { CloudRequestOptions } from "@openhands/typescript-client/clients";
+import type { Backend } from "../backend-registry/types";
+import { createCloudClientForRuntime, createCloudClient } from "./client";
+
+export interface CloudProxyRequest {
+  backend: Backend;
+  method: CloudRequestOptions["method"];
+  path: string;
+  body?: unknown;
+  headers?: Record<string, string>;
+  timeoutSeconds?: number;
+  hostOverride?: string;
+  authMode?: "bearer" | "session-api-key" | "none";
+  sessionApiKey?: string | null;
+  responseType?: "blob";
+}
+
+export async function callCloudProxy<TResponse = unknown>(
+  req: CloudProxyRequest,
+): Promise<TResponse> {
+  const client = req.hostOverride
+    ? createCloudClientForRuntime(req.backend)
+    : createCloudClient(req.backend);
+
+  return client.request<TResponse>({
+    method: req.method,
+    path: req.path,
+    body: req.body,
+    headers: req.headers,
+    timeoutSeconds: req.timeoutSeconds,
+    hostOverride: req.hostOverride,
+    authMode:
+      req.authMode === undefined || req.authMode === "bearer"
+        ? "bearer"
+        : req.authMode,
+    sessionApiKey: req.sessionApiKey,
+    responseType: req.responseType,
+  });
+}

src/api/cloud/sandbox-service.api.ts

@@ -0,0 +1,39 @@
+import { getActiveBackend } from "../backend-registry/active-store";
+import type { Backend } from "../backend-registry/types";
+import { callCloudProxy } from "./proxy";
+import type { V1SandboxInfo } from "./sandbox-service.types";
+
+function getActiveCloudBackend(): Backend {
+  const active = getActiveBackend().backend;
+  if (active.kind !== "cloud") {
+    throw new Error("Cloud sandboxes call requires a cloud backend.");
+  }
+  return active;
+}
+
+/**
+ * Batch-fetch cloud sandboxes by id. Mirrors OpenHands'
+ * `SandboxService.batchGetSandboxes` by calling
+ * `GET /api/v1/sandboxes?id=...` on the cloud backend, returning each
+ * `SandboxInfo` (or null if not found).
+ *
+ * The returned `SandboxInfo.exposed_urls` carry the cloud-computed,
+ * publicly-reachable URLs for the sandbox's services (VSCODE,
+ * AGENT_SERVER, WORKER_*) — the GUI reads them directly instead of
+ * asking the runtime for `/api/vscode/url`, which only knows its
+ * internal localhost address.
+ */
+export async function batchGetCloudSandboxes(
+  ids: string[],
+): Promise<(V1SandboxInfo | null)[]> {
+  if (ids.length === 0) return [];
+  const backend = getActiveCloudBackend();
+  const params = new URLSearchParams();
+  for (const id of ids) params.append("id", id);
+  const data = await callCloudProxy<(V1SandboxInfo | null)[]>({
+    backend,
+    method: "GET",
+    path: `/api/v1/sandboxes?${params.toString()}`,
+  });
+  return data ?? [];
+}

src/api/cloud/sandbox-service.types.ts

@@ -0,0 +1,21 @@
+export type V1SandboxStatus =
+  | "STARTING"
+  | "RUNNING"
+  | "PAUSED"
+  | "ERROR"
+  | "MISSING";
+
+export interface V1ExposedUrl {
+  name: string;
+  url: string;
+}
+
+export interface V1SandboxInfo {
+  id: string;
+  created_by_user_id: string | null;
+  sandbox_spec_id: string;
+  status: V1SandboxStatus;
+  session_api_key: string | null;
+  exposed_urls: V1ExposedUrl[] | null;
+  created_at: string;
+}

src/api/cloud/secrets-service.api.ts

@@ -0,0 +1,118 @@
+import { getActiveBackend } from "../backend-registry/active-store";
+import type { Backend } from "../backend-registry/types";
+import type { CustomSecretWithoutValue } from "../secrets-service.types";
+import { withRetry } from "../with-retry";
+import { callCloudProxy } from "./proxy";
+
+interface CloudSecretsPage {
+  items: CustomSecretWithoutValue[];
+  next_page_id: string | null;
+}
+
+const PAGE_LIMIT = 100;
+
+function getActiveCloudBackend(): Backend {
+  const active = getActiveBackend().backend;
+  if (active.kind !== "cloud") {
+    throw new Error("Cloud secrets call requires a cloud backend.");
+  }
+  return active;
+}
+
+/**
+ * Walk every page of the cloud `/api/v1/secrets/search` endpoint and return
+ * the merged list. The cloud shape (name + description) matches
+ * `CustomSecretWithoutValue`, so items pass through unchanged.
+ */
+export async function fetchCloudSecrets(): Promise<CustomSecretWithoutValue[]> {
+  const backend = getActiveCloudBackend();
+
+  const secrets: CustomSecretWithoutValue[] = [];
+  let pageId: string | null = null;
+
+  do {
+    const query = new URLSearchParams({ limit: String(PAGE_LIMIT) });
+    if (pageId) query.set("page_id", pageId);
+
+    const page = await callCloudProxy<CloudSecretsPage>({
+      backend,
+      method: "GET",
+      path: `/api/v1/secrets/search?${query.toString()}`,
+    });
+
+    secrets.push(...(page.items ?? []));
+    pageId = page.next_page_id;
+  } while (pageId);
+
+  return secrets;
+}
+
+export interface SaveCloudSecretOptions {
+  /** Name the secret should have after saving. */
+  name: string;
+  /** New value. Omit to leave the stored value untouched. */
+  value?: string;
+  description?: string;
+  /** Name the secret is currently stored under, when editing an existing one. */
+  previousName?: string;
+}
+
+/**
+ * Create a cloud secret, or save changes to an existing one.
+ *
+ * The cloud splits a save across two endpoints, so this issues up to two
+ * requests to cover the whole operation:
+ *
+ * - `PUT /api/v1/secrets/{previousName}` applies the name and description. It
+ *   is the only endpoint that can rename, and the only one that rejects a
+ *   collision with `400`. It never touches the value.
+ * - `POST /api/v1/secrets` writes the value. It is a documented upsert
+ *   ("creates a new custom secret, or overwrites it if it already exists") but
+ *   it is keyed by the name in its body, so it cannot rename, and its `value`
+ *   field is required, so it cannot express a metadata-only edit.
+ *
+ * The `PUT` runs first so a rejected rename fails before the value is
+ * overwritten — the cloud exposes no way to read a value back, so a value lost
+ * to a half-applied save is unrecoverable. Each request is retried on its own:
+ * re-running the `PUT` after a failed `POST` would `404` once the rename has
+ * landed.
+ */
+export async function saveCloudSecret({
+  name,
+  value,
+  description,
+  previousName,
+}: SaveCloudSecretOptions): Promise<void> {
+  const backend = getActiveCloudBackend();
+
+  if (previousName !== undefined) {
+    await withRetry(() =>
+      callCloudProxy<unknown>({
+        backend,
+        method: "PUT",
+        path: `/api/v1/secrets/${encodeURIComponent(previousName)}`,
+        body: { name, description },
+      }),
+    );
+  }
+
+  if (value !== undefined) {
+    await withRetry(() =>
+      callCloudProxy<unknown>({
+        backend,
+        method: "POST",
+        path: "/api/v1/secrets",
+        body: { name, value, description },
+      }),
+    );
+  }
+}
+
+export async function deleteCloudSecret(name: string): Promise<void> {
+  const backend = getActiveCloudBackend();
+  await callCloudProxy<unknown>({
+    backend,
+    method: "DELETE",
+    path: `/api/v1/secrets/${encodeURIComponent(name)}`,
+  });
+}

src/api/cloud/settings-service.api.ts

@@ -0,0 +1,230 @@
+import {
+  type Provider,
+  type Settings,
+  type SettingsValue,
+} from "#/types/settings";
+import { type AppPreferences } from "../settings-service/settings-service.api";
+import { getActiveBackend } from "../backend-registry/active-store";
+import type { Backend } from "../backend-registry/types";
+import { callCloudProxy } from "./proxy";
+
+/**
+ * The cloud Settings response is mostly flat — top-level fields like
+ * `llm_model`, `provider_tokens_set`, etc., rather than the nested
+ * `{ agent_settings, conversation_settings }` shape the local agent-server
+ * uses. We deliberately do NOT remap cloud fields into the local shape:
+ * the GUI's `Settings` type already supports both layouts (it has flat
+ * fields AND nested `agent_settings`/`conversation_settings`), and
+ * cloud-aware hooks like `useUserProviders` read directly from the flat
+ * `provider_tokens_set` field. So the cloud response is passed through as
+ * a `Partial<Settings>`, with a small derivation step to also populate
+ * the nested fields the local-mode settings UI consumes.
+ */
+type CloudSettingsResponse = {
+  llm_model?: string;
+  llm_base_url?: string;
+  llm_api_key?: string | null;
+  llm_api_key_set?: boolean;
+  search_api_key_set?: boolean;
+  agent?: string;
+  confirmation_mode?: boolean;
+  security_analyzer?: string | null;
+  max_iterations?: number | null;
+  enable_default_condenser?: boolean;
+  condenser_max_size?: number | null;
+  enable_proactive_conversation_starters?: boolean;
+  enable_solvability_analysis?: boolean;
+  enable_sound_notifications?: boolean;
+  language?: string;
+  email?: string;
+  email_verified?: boolean;
+  git_user_name?: string;
+  git_user_email?: string;
+  title_llm_profile?: string | null;
+  user_consents_to_analytics?: boolean | null;
+  is_new_user?: boolean;
+  remote_runtime_resource_factor?: number | null;
+  max_budget_per_task?: number | null;
+  provider_tokens_set?: Partial<Record<Provider, string | null>>;
+  mcp_config?: Record<string, SettingsValue>;
+  disabled_skills?: string[];
+  agent_settings?: Record<string, SettingsValue> | null;
+  conversation_settings?: Record<string, SettingsValue> | null;
+  agent_settings_schema?: unknown;
+  conversation_settings_schema?: unknown;
+  [key: string]: unknown;
+};
+
+function getActiveCloudBackend(): Backend {
+  const active = getActiveBackend().backend;
+  if (active.kind !== "cloud") {
+    throw new Error("Cloud settings call requires a cloud backend.");
+  }
+  return active;
+}
+
+/**
+ * Build the nested `agent_settings` block from the cloud's flat fields.
+ * Used so the local-mode settings page (which renders against the nested
+ * shape) shows the right values when the active backend is cloud.
+ */
+function deriveAgentSettings(
+  flat: CloudSettingsResponse,
+): Record<string, SettingsValue> {
+  if (flat.agent_settings && Object.keys(flat.agent_settings).length > 0) {
+    return flat.agent_settings;
+  }
+  const agent: Record<string, SettingsValue> = {};
+  const llm: Record<string, SettingsValue> = {};
+  if (typeof flat.llm_model === "string") llm.model = flat.llm_model;
+  if (typeof flat.llm_base_url === "string") llm.base_url = flat.llm_base_url;
+  if (typeof flat.llm_api_key === "string") llm.api_key = flat.llm_api_key;
+  if (Object.keys(llm).length > 0) agent.llm = llm;
+
+  const condenser: Record<string, SettingsValue> = {};
+  if (typeof flat.enable_default_condenser === "boolean") {
+    condenser.enabled = flat.enable_default_condenser;
+  }
+  if (typeof flat.condenser_max_size === "number") {
+    condenser.max_size = flat.condenser_max_size;
+  }
+  if (Object.keys(condenser).length > 0) agent.condenser = condenser;
+
+  if (typeof flat.agent === "string") agent.agent = flat.agent;
+  if (flat.mcp_config && Object.keys(flat.mcp_config).length > 0) {
+    agent.mcp_config = flat.mcp_config;
+  }
+  return agent;
+}
+
+function deriveConversationSettings(
+  flat: CloudSettingsResponse,
+): Record<string, SettingsValue> {
+  if (
+    flat.conversation_settings &&
+    Object.keys(flat.conversation_settings).length > 0
+  ) {
+    return flat.conversation_settings;
+  }
+  const out: Record<string, SettingsValue> = {};
+  if (typeof flat.confirmation_mode === "boolean") {
+    out.confirmation_mode = flat.confirmation_mode;
+  }
+  if (
+    typeof flat.security_analyzer === "string" ||
+    flat.security_analyzer === null
+  ) {
+    out.security_analyzer = flat.security_analyzer;
+  }
+  if (typeof flat.max_iterations === "number") {
+    out.max_iterations = flat.max_iterations;
+  }
+  return out;
+}
+
+/**
+ * Fetch the cloud settings and return them as a `Partial<Settings>`.
+ *
+ * Top-level fields like `provider_tokens_set` are preserved unchanged so
+ * the existing `useUserProviders` → `useAppInstallations` →
+ * `useGitRepositories` chain (which reads `settings.provider_tokens_set`)
+ * fires correctly in cloud mode. Nested `agent_settings` /
+ * `conversation_settings` are derived for the settings page.
+ */
+export async function fetchCloudSettings(): Promise<Partial<Settings>> {
+  const backend = getActiveCloudBackend();
+  const flat = await callCloudProxy<CloudSettingsResponse>({
+    backend,
+    method: "GET",
+    path: "/api/v1/settings",
+  });
+
+  return {
+    ...flat,
+    agent_settings: deriveAgentSettings(flat),
+    conversation_settings: deriveConversationSettings(flat),
+    llm_api_key_set: !!flat.llm_api_key_set,
+    search_api_key_set: !!flat.search_api_key_set,
+    provider_tokens_set: flat.provider_tokens_set,
+  } as Partial<Settings>;
+}
+
+export async function saveCloudSettings(diff: {
+  agent_settings_diff?: Record<string, SettingsValue>;
+  conversation_settings_diff?: Record<string, SettingsValue>;
+  /**
+   * App-level user preferences (language, sound notifications, disabled
+   * skills, …). The cloud `POST /api/v1/settings` consumes these as flat
+   * top-level fields, so this helper iterates the object and assigns each
+   * key onto the request body.
+   *
+   * Note: `app_preferences.disabled_skills` is the canonical source for the
+   * skill list since `AppPreferences` was unified in agent-server 1.27.
+   * Callers that still pass `disabled_skills` separately should migrate to
+   * setting it under `app_preferences` instead.
+   */
+  app_preferences?: AppPreferences;
+}): Promise<void> {
+  const backend = getActiveCloudBackend();
+  const body: Record<string, unknown> = {};
+  if (diff.agent_settings_diff) {
+    const agentDiff: Record<string, SettingsValue> = {
+      ...diff.agent_settings_diff,
+    };
+    // The cloud validates agent settings against the SDK's
+    // OpenHandsAgentSettings, whose `agent_context` is a required
+    // AgentContext (not Optional). A literal `agent_context: null` fails
+    // backend validation, so drop it and let the backend keep/default it.
+    // See OpenHands/agent-canvas#981.
+    if (agentDiff.agent_context === null) {
+      delete agentDiff.agent_context;
+    }
+    if (Object.keys(agentDiff).length > 0) {
+      body.agent_settings_diff = agentDiff;
+    }
+  }
+  if (
+    diff.conversation_settings_diff &&
+    Object.keys(diff.conversation_settings_diff).length > 0
+  ) {
+    body.conversation_settings_diff = diff.conversation_settings_diff;
+  }
+  // Flat top-level app-preference fields (language, git_user_name,
+  // disabled_skills, …). The cloud POST /api/v1/settings stores these
+  // directly; see `CloudSettingsResponse` and the MSW handler in
+  // `src/mocks/settings-handlers.ts` for the accepted shape. `undefined`
+  // values are skipped so the cloud server keeps the prior value; `null`
+  // and empty arrays (e.g. re-enabling every skill) round-trip as
+  // explicit clears.
+  if (diff.app_preferences) {
+    for (const [key, value] of Object.entries(diff.app_preferences)) {
+      if (value !== undefined) {
+        body[key] = value;
+      }
+    }
+  }
+  await callCloudProxy<unknown>({
+    backend,
+    method: "POST",
+    path: "/api/v1/settings",
+    body,
+  });
+}
+
+export async function fetchCloudSettingsSchema(): Promise<unknown> {
+  const backend = getActiveCloudBackend();
+  return callCloudProxy<unknown>({
+    backend,
+    method: "GET",
+    path: "/api/v1/settings/agent-schema",
+  });
+}
+
+export async function fetchCloudConversationSettingsSchema(): Promise<unknown> {
+  const backend = getActiveCloudBackend();
+  return callCloudProxy<unknown>({
+    backend,
+    method: "GET",
+    path: "/api/v1/settings/conversation-schema",
+  });
+}

src/api/cloud/skills-service.api.ts

@@ -0,0 +1,83 @@
+import type { SkillInfo } from "#/types/settings";
+import { getActiveBackend } from "../backend-registry/active-store";
+import type { Backend } from "../backend-registry/types";
+import { callCloudProxy } from "./proxy";
+
+interface CloudSkillsPage {
+  items: SkillInfo[];
+  next_page_id: string | null;
+}
+
+const PAGE_LIMIT = 100;
+
+function getActiveCloudBackend(): Backend {
+  const active = getActiveBackend().backend;
+  if (active.kind !== "cloud") {
+    throw new Error("Cloud skills call requires a cloud backend.");
+  }
+  return active;
+}
+
+/**
+ * Fetch the full list of skills from the cloud backend. The cloud endpoint is
+ * paginated (page_id cursor); we walk all pages so the settings UI gets a
+ * complete list in one call. The cloud SkillInfo shape
+ * (name/type/source/triggers) matches the GUI's SkillInfo type, so items are
+ * passed through unchanged.
+ */
+export async function fetchCloudSkills(): Promise<SkillInfo[]> {
+  const backend = getActiveCloudBackend();
+
+  const skills: SkillInfo[] = [];
+  let pageId: string | null = null;
+
+  do {
+    const query = new URLSearchParams({ limit: String(PAGE_LIMIT) });
+    if (pageId) query.set("page_id", pageId);
+
+    const page = await callCloudProxy<CloudSkillsPage>({
+      backend,
+      method: "GET",
+      path: `/api/v1/skills/search?${query.toString()}`,
+    });
+
+    skills.push(...(page.items ?? []));
+    pageId = page.next_page_id;
+  } while (pageId);
+
+  return skills;
+}
+
+interface CloudConversationSkill {
+  name: string;
+  type: SkillInfo["type"];
+  content: string;
+  triggers: string[];
+}
+
+interface CloudConversationSkillsResponse {
+  skills: CloudConversationSkill[];
+}
+
+/**
+ * Fetch the skills loaded into a running cloud conversation from the
+ * per-conversation route (the one the OpenHands web UI's own "Show Available
+ * Skills" modal uses). Unlike `/api/v1/skills/search`, which only scans the
+ * API host's built-in skills directory, this resolves the conversation's
+ * sandbox and asks its agent-server for the merged set: public catalog,
+ * user/org repos, project skills and auto-loaded marketplace plugins. The
+ * route reports no `source`, so it is `null`.
+ */
+export async function fetchCloudConversationSkills(
+  conversationId: string,
+): Promise<SkillInfo[]> {
+  const backend = getActiveCloudBackend();
+
+  const data = await callCloudProxy<CloudConversationSkillsResponse>({
+    backend,
+    method: "GET",
+    path: `/api/v1/app-conversations/${conversationId}/skills`,
+  });
+
+  return (data?.skills ?? []).map((skill) => ({ ...skill, source: null }));
+}

src/api/cloud/types.ts

@@ -0,0 +1,56 @@
+/**
+ * Minimal slice of the OpenHands cloud organization shape that the GUI needs
+ * to render the backend selector. Full shape lives in the OpenHands repo;
+ * we keep only the fields actually read by this codebase.
+ */
+export interface CloudOrganization {
+  id: string;
+  name: string;
+  is_personal?: boolean;
+}
+
+export interface CloudOrganizationsResponse {
+  items: CloudOrganization[];
+  current_org_id: string | null;
+}
+
+/**
+ * Subset of OpenHands' OrganizationMember that the GUI reads. Returned by
+ * `GET /api/organizations/{orgId}/me`. The relationship between the org and
+ * the current user is the source of truth for "is this a personal
+ * workspace?" — namely `org_id === user_id`.
+ */
+export interface CloudOrganizationMember {
+  org_id: string;
+  user_id: string;
+  email?: string | null;
+  role?: string;
+  status?: string;
+}
+
+/**
+ * Response from `GET /api/keys/current`. Identifies the org the calling
+ * API key is scoped to. Legacy keys without an org binding cause the
+ * upstream to return HTTP 400 instead of producing this shape — the
+ * caller catches that case rather than expecting a partial response.
+ */
+export interface CloudApiKeyMetadata {
+  id: string;
+  name: string;
+  org_id: string | null;
+  user_id: string;
+  auth_type: string;
+}
+
+/**
+ * Response from `GET /api/v1/users/git-info`. Identifies the currently
+ * authenticated user across the connected git providers.
+ */
+export interface CloudGitUser {
+  id: string;
+  login: string;
+  avatar_url: string;
+  company: string | null;
+  name: string | null;
+  email: string | null;
+}

src/api/config-service/config-service.api.ts

@@ -0,0 +1,195 @@
+import { LLMMetadataClient } from "@openhands/typescript-client/clients";
+import { getAgentServerClientOptions } from "../agent-server-client-options";
+import { getActiveBackend } from "../backend-registry/active-store";
+import { callCloudProxy } from "../cloud/proxy";
+import type {
+  LLMModel,
+  LLMModelPage,
+  LLMProvider,
+  ProviderPage,
+  SearchModelsParams,
+  SearchProvidersParams,
+} from "./config-service.types";
+
+function filterByQuery<T extends { name: string }>(
+  items: T[],
+  query?: string,
+): T[] {
+  if (!query) {
+    return items;
+  }
+
+  const normalizedQuery = query.toLowerCase();
+  return items.filter((item) =>
+    item.name.toLowerCase().includes(normalizedQuery),
+  );
+}
+
+function filterByVerified<T extends { verified: boolean }>(
+  items: T[],
+  verified?: boolean,
+): T[] {
+  if (verified === undefined) {
+    return items;
+  }
+
+  return items.filter((item) => item.verified === verified);
+}
+
+function limitItems<T>(items: T[], limit?: number): T[] {
+  if (!limit || limit <= 0) {
+    return items;
+  }
+
+  return items.slice(0, limit);
+}
+
+function buildCloudQueryString(
+  params: Record<string, string | number | boolean | undefined>,
+): string {
+  const qs = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined) qs.set(key, String(value));
+  }
+  const str = qs.toString();
+  return str ? `?${str}` : "";
+}
+
+class ConfigService {
+  /**
+   * @param verifiedByProvider - Pre-fetched verified-models map used by the
+   *   local reconstruction path. Ignored for cloud backends, which call
+   *   `/api/v1/config/models/search` directly (verified status is embedded in
+   *   each returned item).
+   */
+  static async searchModels(
+    params: SearchModelsParams = {},
+    verifiedByProvider?: Record<string, string[]>,
+  ): Promise<LLMModelPage> {
+    const active = getActiveBackend();
+
+    if (active.backend.kind === "cloud") {
+      // Cloud exposes /api/v1/config/models/search which returns LLMModelPage directly.
+      // verifiedByProvider is not needed — the cloud API embeds verified status natively.
+      const qs = buildCloudQueryString({
+        page_id: params.page_id,
+        limit: params.limit,
+        query: params.query,
+        verified__eq: params.verified__eq,
+        provider__eq: params.provider__eq,
+      });
+      return callCloudProxy<LLMModelPage>({
+        backend: active.backend,
+        method: "GET",
+        path: `/api/v1/config/models/search${qs}`,
+      });
+    }
+
+    const llmClient = new LLMMetadataClient(getAgentServerClientOptions());
+    const verifiedFetch =
+      verifiedByProvider !== undefined
+        ? Promise.resolve(verifiedByProvider)
+        : llmClient.getVerifiedModels();
+    const [models, verifiedMap] = await Promise.all([
+      llmClient.getModels(),
+      verifiedFetch,
+    ]);
+
+    const provider = params.provider__eq ?? null;
+    const verifiedNames = new Set(
+      provider ? (verifiedMap?.[provider] ?? []) : [],
+    );
+    // The local agent-server has no model database, so it exposes no free /
+    // default metadata; both are always false here. Cloud backends embed the
+    // DB-driven flags natively on each item (handled above).
+    const verifiedItems: LLMModel[] = [...verifiedNames].map((name) => ({
+      provider,
+      name,
+      verified: true,
+      free: false,
+      default: false,
+    }));
+
+    const prefixedItems: LLMModel[] = provider
+      ? (models ?? [])
+          .filter((model) => model.startsWith(`${provider}/`))
+          .map((model) => model.slice(provider.length + 1))
+          .filter((name) => name.length > 0 && !verifiedNames.has(name))
+          .map((name) => ({
+            provider,
+            name,
+            verified: false,
+            free: false,
+            default: false,
+          }))
+      : [];
+
+    const items = limitItems(
+      filterByVerified(
+        filterByQuery([...verifiedItems, ...prefixedItems], params.query),
+        params.verified__eq,
+      ),
+      params.limit,
+    );
+
+    return { items, next_page_id: null };
+  }
+
+  /**
+   * @param verifiedByProvider - Pre-fetched verified-models map used by the
+   *   local reconstruction path. Ignored for cloud backends, which call
+   *   `/api/v1/config/providers/search` directly (verified status is embedded in
+   *   each returned item).
+   */
+  static async searchProviders(
+    params: SearchProvidersParams = {},
+    verifiedByProvider?: Record<string, string[]>,
+  ): Promise<ProviderPage> {
+    const active = getActiveBackend();
+
+    if (active.backend.kind === "cloud") {
+      // Cloud exposes /api/v1/config/providers/search which returns ProviderPage directly.
+      // verifiedByProvider is not needed — the cloud API embeds verified status natively.
+      const qs = buildCloudQueryString({
+        page_id: params.page_id,
+        limit: params.limit,
+        query: params.query,
+        verified__eq: params.verified__eq,
+      });
+      return callCloudProxy<ProviderPage>({
+        backend: active.backend,
+        method: "GET",
+        path: `/api/v1/config/providers/search${qs}`,
+      });
+    }
+
+    const llmClient = new LLMMetadataClient(getAgentServerClientOptions());
+    const verifiedFetch =
+      verifiedByProvider !== undefined
+        ? Promise.resolve(verifiedByProvider)
+        : llmClient.getVerifiedModels();
+    const [providers, verifiedMap] = await Promise.all([
+      llmClient.getProviders(),
+      verifiedFetch,
+    ]);
+
+    const verifiedProviders = new Set(Object.keys(verifiedMap ?? {}));
+    const names = new Set<string>([...verifiedProviders, ...(providers ?? [])]);
+    const providerItems: LLMProvider[] = [...names].map((name) => ({
+      name,
+      verified: verifiedProviders.has(name),
+    }));
+
+    const items = limitItems(
+      filterByVerified(
+        filterByQuery(providerItems, params.query),
+        params.verified__eq,
+      ),
+      params.limit,
+    );
+
+    return { items, next_page_id: null };
+  }
+}
+
+export default ConfigService;

src/api/config-service/config-service.types.ts

@@ -0,0 +1,50 @@
+/** V1 Config API types for models and providers */
+
+export interface LLMModel {
+  provider: string | null;
+  name: string;
+  verified: boolean;
+  /**
+   * Whether the model is free to use on the OpenHands provider. Mirrors
+   * `verified`: it is populated by the backend model list (DB-driven on
+   * cloud) and defaults to `false` where no free metadata exists (e.g. the
+   * local agent-server reconstruction path, which has no model database).
+   */
+  free: boolean;
+  /**
+   * Whether this is the provider's default model. Mirrors `free`: DB-driven on
+   * cloud, `false` where no default metadata exists. Used to preselect the
+   * model on onboarding and when creating a new model for the provider.
+   */
+  default: boolean;
+}
+
+export interface LLMModelPage {
+  items: LLMModel[];
+  next_page_id: string | null;
+}
+
+export interface SearchModelsParams {
+  page_id?: string;
+  limit?: number;
+  query?: string;
+  verified__eq?: boolean;
+  provider__eq?: string;
+}
+
+export interface LLMProvider {
+  name: string;
+  verified: boolean;
+}
+
+export interface ProviderPage {
+  items: LLMProvider[];
+  next_page_id: string | null;
+}
+
+export interface SearchProvidersParams {
+  page_id?: string;
+  limit?: number;
+  query?: string;
+  verified__eq?: boolean;
+}

src/api/conversation-service/agent-server-conversation-service.api.ts

@@ -0,0 +1,1145 @@
+import {
+  ConversationSortOrder,
+  type ForkConversationRequest,
+  type LLMConfig,
+  type VSCodeStatusResponse,
+} from "@openhands/typescript-client";
+import {
+  ConversationClient,
+  FileClient,
+  ProfilesClient,
+  VSCodeClient,
+} from "@openhands/typescript-client/clients";
+import { v4 as uuidv4 } from "uuid";
+import { AgentKind, Provider } from "#/types/settings";
+import type { ConversationRuntimeContext } from "#/api/conversation-file-upload.api";
+import { buildHttpBaseUrl } from "#/utils/websocket-url";
+import {
+  buildConversationWorkingDirForBackend,
+  getAgentServerWorkingDir,
+  getWorkspaceRootForBackend,
+} from "../agent-server-config";
+import { resolveAbsoluteAgentServerPath } from "../agent-server-home";
+import {
+  getActiveBackend,
+  getEffectiveLocalBackend,
+} from "../backend-registry/active-store";
+import { callCloudProxy } from "../cloud/proxy";
+import ProfilesService from "../profiles-service/profiles-service.api";
+import {
+  batchGetCloudConversations,
+  createCloudAppConversation,
+  deleteCloudConversation,
+  downloadCloudConversation,
+  getCloudAppConversationStartTask,
+  readCloudConversationFile,
+  searchCloudConversations,
+  updateCloudConversationPublicFlag,
+  updateCloudConversationTitle,
+} from "../cloud/conversation-service.api";
+import {
+  DirectConversationInfo,
+  assertSubscriptionAuthReady,
+  buildStartConversationRequestWithEncryptedSettings,
+  buildStartPlanningConversationRequestWithEncryptedSettings,
+  emptyHooksResponse,
+  getDefaultConversationTitle,
+  toAppConversation,
+  toConversationPage,
+} from "../agent-server-adapter";
+import { GetVSCodeUrlResponse } from "../open-hands.types";
+import {
+  getAgentServerClientOptions,
+  NoBackendAvailableError,
+} from "../agent-server-client-options";
+import SettingsService from "../settings-service/settings-service.api";
+import { getTelemetryDistinctId } from "../../services/telemetry";
+import {
+  ConversationMetadata,
+  getStoredConversationMetadata,
+  mergeStoredConversationMetadata,
+  removeStoredConversationMetadata,
+  setStoredConversationMetadata,
+  type WorkspaceMode,
+} from "../conversation-metadata-store";
+import { resolveTitleLlmProfile } from "#/utils/title-llm-profile";
+import { isPlannerConversationOf } from "#/utils/plan-file";
+import type {
+  GetHooksResponse,
+  PluginSpec,
+  AppConversation,
+  AppConversationPage,
+  AppConversationStartRequest,
+  AppConversationStartTask,
+  MetricsSnapshot,
+  RuntimeConversationInfo,
+  RuntimeConversationStats,
+  SendMessageRequest,
+  SendMessageResponse,
+} from "./agent-server-conversation-service.types";
+
+const DEFAULT_CONVERSATION_TIMESTAMP = "1970-01-01T00:00:00.000Z";
+// Creating the first conversation right after a cold agent-server boot (fresh
+// machine or the packaged desktop app, where uvx may still be warming caches)
+// can exceed the client's 60s default timeout.
+const CREATE_CONVERSATION_TIMEOUT_MS = 5 * 60 * 1000;
+const INVALID_CONVERSATION_RESPONSE_MESSAGE =
+  "Unable to load conversations because the selected agent server returned " +
+  "data this UI does not understand. Check the backend URL/session key and " +
+  "update the agent server if needed.";
+function invalidConversationResponse(): Error {
+  return new Error(INVALID_CONVERSATION_RESPONSE_MESSAGE);
+}
+
+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" ? value : null;
+}
+
+function numberOrZero(value: unknown): number {
+  return typeof value === "number" ? value : 0;
+}
+
+function stringOrNull(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+
+function readTimestamp(
+  item: Record<string, unknown>,
+  snakeKey: "created_at" | "updated_at",
+  camelKey: "createdAt" | "updatedAt",
+): string {
+  const value = item[snakeKey] ?? item[camelKey];
+  return typeof value === "string" && value.trim()
+    ? value
+    : DEFAULT_CONVERSATION_TIMESTAMP;
+}
+
+function normalizeTokenUsage(
+  value: unknown,
+): NonNullable<MetricsSnapshot["accumulated_token_usage"]> | null {
+  if (!isRecord(value)) return null;
+
+  return {
+    prompt_tokens: numberOrZero(value.prompt_tokens),
+    completion_tokens: numberOrZero(value.completion_tokens),
+    cache_read_tokens: numberOrZero(value.cache_read_tokens),
+    cache_write_tokens: numberOrZero(value.cache_write_tokens),
+    context_window: numberOrZero(value.context_window),
+    per_turn_token: numberOrZero(value.per_turn_token),
+  };
+}
+
+function normalizeMetrics(value: unknown): MetricsSnapshot | null {
+  if (!isRecord(value)) return null;
+
+  return {
+    accumulated_cost: numberOrNull(value.accumulated_cost),
+    max_budget_per_task: numberOrNull(value.max_budget_per_task),
+    accumulated_token_usage: normalizeTokenUsage(value.accumulated_token_usage),
+  };
+}
+
+// Shallow check only (matches the trust level `getRuntimeConversation` used
+// before this field was threaded through `DirectConversationInfo`): the
+// per-usage-id entries are consumed via `combineUsageMetrics`, which already
+// tolerates missing/malformed fields, so there's no need to validate them here.
+function normalizeStats(value: unknown): RuntimeConversationStats | null {
+  return isRecord(value)
+    ? (value as unknown as RuntimeConversationStats)
+    : null;
+}
+
+function normalizeAgent(value: unknown): DirectConversationInfo["agent"] {
+  if (!isRecord(value)) return null;
+  const llm = isRecord(value.llm)
+    ? { model: stringOrNull(value.llm.model) }
+    : null;
+  // ``kind`` is the SDK's pydantic discriminator (``"Agent"`` vs ``"ACPAgent"``);
+  // ``toAppConversation`` reads it to derive ``agent_kind``. ``acp_server`` is
+  // the ACP provider identity (``ACPAgent.acp_server``, SDK #3692) — required so
+  // the adapter can source the chip + in-conversation model list from the agent
+  // when the ``acpserver`` tag is absent (a profile launch doesn't stamp it,
+  // #1571). ``acp_model`` is the Canvas-configured model — preserved so the chip
+  // can fall back to it when the SDK runtime model fields aren't populated.
+  // Preserving these makes the wire path agree with the unit-test path that
+  // builds ``DirectConversationInfo`` directly
+  // (e.g. ``__tests__/api/agent-server-adapter.test.ts``).
+  return {
+    kind: stringOrNull(value.kind),
+    acp_server: stringOrNull(value.acp_server),
+    acp_model: stringOrNull(value.acp_model),
+    llm,
+  };
+}
+
+function normalizeWorkspace(
+  value: unknown,
+): DirectConversationInfo["workspace"] {
+  if (!isRecord(value)) return null;
+  return { working_dir: stringOrNull(value.working_dir) };
+}
+
+/**
+ * Accept the agent-server's ``tags: Record[str, str]`` payload defensively:
+ * the wire shape is guaranteed by the server-side validator (keys
+ * ``^[a-z0-9]+$``, string values), but a non-conforming response (older
+ * server, raw API write, future schema drift) must never crash the parser
+ * — Canvas only consumes ``acpserver`` and falls back to a generic chip
+ * for anything it doesn't recognize. Drop entries whose value isn't a
+ * plain string; return ``null`` when the wire field is absent or not an
+ * object so consumers can use ``info.tags?.[KEY] ?? null`` uniformly.
+ */
+function normalizeTags(value: unknown): Record<string, string> | null {
+  if (!isRecord(value)) return null;
+  const tags: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (typeof entry === "string") {
+      tags[key] = entry;
+    }
+  }
+  return tags;
+}
+
+/**
+ * ``ConversationInfo.sub_conversation_ids`` — the agent-server derives it from
+ * its own catalog of conversations that name this one as parent (SDK #4188),
+ * which is what lets Canvas find a conversation's local planner without any
+ * browser-local state. Absent on agent-servers older than 1.37.1; parsed
+ * defensively so a non-conforming payload degrades to "no children" instead of
+ * crashing the list.
+ */
+function normalizeSubConversationIds(value: unknown): string[] | null {
+  if (!Array.isArray(value)) return null;
+  return value.filter((entry): entry is string => typeof entry === "string");
+}
+
+function normalizeLaunchedAgentProfile(
+  value: unknown,
+): DirectConversationInfo["launched_agent_profile"] {
+  if (!isRecord(value)) return null;
+  const { agent_profile_id: agentProfileId, revision } = value;
+  if (typeof agentProfileId !== "string" || typeof revision !== "number") {
+    return null;
+  }
+  return { agent_profile_id: agentProfileId, revision };
+}
+
+function normalizeAbsolutePath(path: string): string | null {
+  if (!path.startsWith("/")) return null;
+
+  const segments: string[] = [];
+  for (const segment of path.split("/")) {
+    if (segment && segment !== ".") {
+      if (segment === "..") {
+        if (!segments.length) return null;
+        segments.pop();
+      } else {
+        segments.push(segment);
+      }
+    }
+  }
+
+  return `/${segments.join("/")}`;
+}
+
+function requirePathInsideDirectory(path: string, directory: string): string {
+  const normalizedPath = normalizeAbsolutePath(path);
+  const normalizedDirectory = normalizeAbsolutePath(directory);
+
+  if (
+    !normalizedPath ||
+    !normalizedDirectory ||
+    (normalizedPath !== normalizedDirectory &&
+      !normalizedPath.startsWith(`${normalizedDirectory}/`))
+  ) {
+    throw new Error("Conversation file path must stay inside the workspace");
+  }
+
+  return normalizedPath;
+}
+
+function requireDirectConversationInfo(item: unknown): DirectConversationInfo {
+  if (!isRecord(item) || typeof item.id !== "string" || !item.id.trim()) {
+    throw invalidConversationResponse();
+  }
+
+  return {
+    id: item.id.trim(),
+    title: stringOrNull(item.title),
+    created_at: readTimestamp(item, "created_at", "createdAt"),
+    updated_at: readTimestamp(item, "updated_at", "updatedAt"),
+    execution_status: stringOrNull(item.execution_status),
+    sandbox_status: stringOrNull(item.sandbox_status),
+    metrics: normalizeMetrics(item.metrics),
+    stats: normalizeStats(item.stats),
+    agent: normalizeAgent(item.agent),
+    workspace: normalizeWorkspace(item.workspace),
+    tags: normalizeTags(item.tags),
+    launched_agent_profile: normalizeLaunchedAgentProfile(
+      item.launched_agent_profile,
+    ),
+    sub_conversation_ids: normalizeSubConversationIds(
+      item.sub_conversation_ids,
+    ),
+    // SDK-runtime ACP model fields (populated when the agent-server supports
+    // ``ConversationInfo.current_model_*``). Consumed by the conversation
+    // adapter to drive the per-card chip's model text. Older agent-servers
+    // omit these — adapter handles ``undefined`` / ``null`` gracefully.
+    current_model_id: stringOrNull(item.current_model_id),
+    current_model_name: stringOrNull(item.current_model_name),
+  };
+}
+
+function requireDirectConversationItems(
+  items: unknown,
+): DirectConversationInfo[] {
+  if (!Array.isArray(items)) {
+    throw invalidConversationResponse();
+  }
+  return items.map(requireDirectConversationInfo);
+}
+
+function requireConversationSearchPage(page: unknown): {
+  items: DirectConversationInfo[];
+  next_page_id: string | null;
+} {
+  if (Array.isArray(page)) {
+    return {
+      items: requireDirectConversationItems(page),
+      next_page_id: null,
+    };
+  }
+
+  if (!isRecord(page)) {
+    throw invalidConversationResponse();
+  }
+
+  return {
+    items: requireDirectConversationItems(page.items),
+    next_page_id:
+      typeof page.next_page_id === "string" ? page.next_page_id : null,
+  };
+}
+
+const RUNTIME_STATUSES = new Set<string>([
+  "idle",
+  "running",
+  "paused",
+  "waiting_for_confirmation",
+  "finished",
+  "error",
+  "stuck",
+]);
+
+function toRuntimeStatus(
+  status: DirectConversationInfo["execution_status"],
+): RuntimeConversationInfo["status"] {
+  const nextStatus = status ?? "idle";
+  return (
+    RUNTIME_STATUSES.has(nextStatus) ? nextStatus : "idle"
+  ) as RuntimeConversationInfo["status"];
+}
+
+function requireAppConversation(
+  conversation: AppConversation | null | undefined,
+  conversationId: string,
+): AppConversation {
+  if (!conversation) {
+    throw new Error(`Conversation ${conversationId} was not found`);
+  }
+  return conversation;
+}
+
+/**
+ * Options for {@link AgentServerConversationService.createConversation}.
+ */
+export interface CreateConversationOptions {
+  initialUserMsg?: string;
+  conversationInstructions?: string;
+  plugins?: PluginSpec[];
+  metadata?: ConversationMetadata | null;
+  workingDirOverride?: string;
+  workspaceMode?: WorkspaceMode;
+  parentConversationId?: string;
+  agentType?: "default" | "plan";
+  sandboxId?: string;
+  // Launch from a saved AgentProfile (resolved server-side) instead of the
+  // current encrypted agent_settings (#3727). Supported on both local and the
+  // cloud app-server (OpenHands #15060): local threads it through the
+  // encrypted-settings builder; cloud sends it as a flat request field.
+  agentProfileId?: string;
+  agentProfileKind?: AgentKind;
+}
+
+class AgentServerConversationService {
+  static async sendMessage(
+    conversationId: string,
+    message: SendMessageRequest,
+    runtime?: ConversationRuntimeContext | null,
+  ): Promise<SendMessageResponse> {
+    const active = getActiveBackend().backend;
+    let conversationUrl = runtime?.conversationUrl ?? null;
+    let sessionApiKey = runtime?.sessionApiKey ?? null;
+
+    if (active.kind === "cloud") {
+      if (!conversationUrl || !sessionApiKey) {
+        const [conversation] = await batchGetCloudConversations([
+          conversationId,
+        ]);
+        conversationUrl = conversation?.conversation_url?.trim() ?? null;
+        sessionApiKey = conversation?.session_api_key?.trim() ?? null;
+      }
+
+      if (!conversationUrl || !sessionApiKey) {
+        throw new Error(
+          "Conversation sandbox is still starting. Wait for it to finish, then try again.",
+        );
+      }
+
+      await callCloudProxy({
+        backend: active,
+        method: "POST",
+        hostOverride: buildHttpBaseUrl(conversationUrl),
+        path: `/api/conversations/${conversationId}/events`,
+        body: { ...message, run: true },
+        authMode: "session-api-key",
+        sessionApiKey,
+      });
+
+      return message;
+    }
+
+    await new ConversationClient(
+      getAgentServerClientOptions({ conversationUrl, sessionApiKey }),
+    ).sendEvent(conversationId, message, {
+      run: true,
+    });
+
+    return message;
+  }
+
+  static async createConversation(
+    options: CreateConversationOptions = {},
+  ): Promise<AppConversationStartTask> {
+    const {
+      initialUserMsg,
+      conversationInstructions,
+      plugins,
+      metadata,
+      workingDirOverride,
+      workspaceMode,
+      parentConversationId,
+      agentType,
+      sandboxId,
+      agentProfileId,
+      agentProfileKind,
+    } = options;
+
+    if (getActiveBackend().backend.kind === "cloud") {
+      // Cloud path mirrors OpenHands' frontend: build a flat
+      // AppConversationStartRequest, POST /api/v1/app-conversations
+      // (returns a WORKING task), and let the conversation route's
+      // useTaskPolling drive it to READY. NO encrypted-settings
+      // round-trip — the cloud backend holds secrets server-side.
+      // When launching from a profile, send `agent_profile_id`; the backend
+      // resolves it to agent_settings server-side.
+      const request: AppConversationStartRequest = {
+        initial_message: initialUserMsg
+          ? {
+              role: "user",
+              content: [{ type: "text", text: initialUserMsg }],
+            }
+          : null,
+        title: conversationInstructions ?? null,
+        selected_repository: metadata?.selected_repository ?? null,
+        selected_branch: metadata?.selected_branch ?? null,
+        git_provider: metadata?.git_provider ?? null,
+        plugins: plugins ?? null,
+        parent_conversation_id: parentConversationId ?? null,
+        agent_type: agentType,
+        sandbox_id: sandboxId ?? null,
+        agent_profile_id: agentProfileId ?? null,
+        trigger: "gui",
+      };
+      return createCloudAppConversation(request);
+    }
+
+    const [settings, profiles] = await Promise.all([
+      SettingsService.getSettings(),
+      ProfilesService.listProfiles().catch(() => undefined),
+    ]);
+    const titleLlmProfile = resolveTitleLlmProfile(
+      settings.title_llm_profile,
+      profiles,
+    );
+    const conversationId = uuidv4();
+    // @spec WUP-001 — Send an absolute working_dir to the agent-server.
+    // The default is `workspace/project/<hex>` (relative); without
+    // resolving it here, `/api/file/upload` later prepends `/` and writes
+    // to `/workspace/...` (read-only on macOS and fresh containers). When
+    // the user picks an explicit workspace, `workingDirOverride` is
+    // already absolute (it comes from `search_subdirs`).
+    //
+    // Pick the base working dir per-backend:
+    //   1. explicit user workspace pick → use it as-is;
+    //   2. no pick, backend that served this frontend → the baked default
+    //      (honors a launcher-baked absolute `VITE_WORKING_DIR`);
+    //   3. no pick, any other backend → the backend-relative default.
+    // A baked absolute dir is a path on the host that served this frontend,
+    // so it is only valid on that backend. Using it for a different backend
+    // (e.g. a remote sandbox) makes the agent-server mkdir an unwritable path
+    // and the conversation fails at the first prompt (e.g. `Permission
+    // denied: '/Users'`). The relative default is anchored per-backend by
+    // `resolveAbsoluteAgentServerPath()` via `/api/file/home`. The gate keys
+    // on the active backend's host (not its id): the seeded `default-local`
+    // entry is mutable, so a user can edit it to point at a remote host while
+    // its id stays `default-local`.
+    const backendHost = getActiveBackend().backend.host;
+    const baseWorkingDir =
+      workingDirOverride ??
+      buildConversationWorkingDirForBackend(conversationId, backendHost);
+    const workingDir = await resolveAbsoluteAgentServerPath(baseWorkingDir);
+    // The agent-server checks `<project_dir>/.openhands/hooks.json` literally,
+    // so hooks need the workspace root: the per-conversation subdir below it is
+    // created only after this request (#16907). An explicit pick is the root.
+    const hooksProjectDir = workingDirOverride
+      ? workingDir
+      : await resolveAbsoluteAgentServerPath(
+          getWorkspaceRootForBackend(backendHost),
+        );
+    const resolvedWorkspaceMode =
+      workspaceMode ?? (workingDirOverride ? "local_repo" : "new_worktree");
+
+    // Use encrypted settings to avoid exposing secrets in the browser
+    const payload = await buildStartConversationRequestWithEncryptedSettings({
+      settings,
+      query: initialUserMsg,
+      conversationInstructions,
+      plugins,
+      conversationId,
+      // The agent-server rejects a parent in a different workspace, so callers
+      // launching a child must pass the parent's own `working_dir` as
+      // `workingDirOverride` (see `resolveConversationWorkingDir`). Servers
+      // older than 1.37.1 ignore the field and create an unlinked conversation.
+      parentConversationId,
+      workingDir,
+      hooksProjectDir,
+      worktree: resolvedWorkspaceMode === "new_worktree",
+      agentProfileId,
+      agentProfileKind,
+      titleLlmProfile,
+    });
+
+    const telemetryDistinctId = await getTelemetryDistinctId();
+    const data = await new ConversationClient(
+      getAgentServerClientOptions({ timeout: CREATE_CONVERSATION_TIMEOUT_MS }),
+    ).createConversation<DirectConversationInfo>({
+      ...payload,
+      ...(telemetryDistinctId ? { user_id: telemetryDistinctId } : {}),
+    });
+    const localBackend = getEffectiveLocalBackend();
+    if (!localBackend) throw new NoBackendAvailableError();
+
+    if (metadata?.selected_repository || workingDirOverride) {
+      // The agent-server runtime has no concept of selected repo/branch/
+      // workspace, so persist the home-page selection client-side.
+      // `toAppConversation` reads the repo/branch fields back to hydrate
+      // the chat-page badges; `useHasAttachedSource` reads
+      // `selected_workspace` to default the Files tab to Diff mode when
+      // the user explicitly attached a local workspace.
+      setStoredConversationMetadata(data.id, {
+        selected_repository: metadata?.selected_repository ?? null,
+        selected_branch: metadata?.selected_branch ?? null,
+        git_provider: metadata?.git_provider ?? null,
+        selected_workspace: workingDirOverride ?? null,
+        workspace_mode: resolvedWorkspaceMode,
+      });
+    }
+
+    return {
+      id: data.id,
+      created_by_user_id: null,
+      status: "READY",
+      detail: null,
+      app_conversation_id: data.id,
+      agent_server_url: localBackend.host,
+      request: {
+        initial_message: payload.initial_message as
+          | AppConversationStartRequest["initial_message"]
+          | undefined,
+        plugins: plugins ?? null,
+      },
+      created_at: data.created_at,
+      updated_at: data.updated_at,
+    };
+  }
+
+  static async createLocalPlanningConversation(
+    parentConversationId: string,
+    initialMessage?: string,
+  ): Promise<AppConversation> {
+    if (getActiveBackend().backend.kind === "cloud") {
+      throw new Error("Local planning conversations require a local backend.");
+    }
+
+    const [parent] = await this.batchGetAppConversations([
+      parentConversationId,
+    ]);
+    const workingDir =
+      parent?.workspace?.working_dir ?? getAgentServerWorkingDir();
+
+    const payload =
+      await buildStartPlanningConversationRequestWithEncryptedSettings({
+        workingDir,
+        parentConversationId,
+        // Pin the planner to the parent's own current model. Only meaningful
+        // for "openhands"-kind parents: an ACP parent's active_profile is a
+        // stale launch-time snapshot (/model is a no-op for ACP), not a live
+        // value, so treating it as authoritative would pin the planner to
+        // the wrong model instead of falling through to global settings.
+        parentActiveProfileName:
+          parent?.agent_kind === "openhands"
+            ? (parent?.active_profile ?? null)
+            : null,
+        // Fallback when active_profile can't be resolved (e.g. an ACP parent).
+        parentAgentProfileId:
+          parent?.launched_agent_profile?.agent_profile_id ?? null,
+        initialMessage,
+      });
+
+    const data = await new ConversationClient(
+      getAgentServerClientOptions(),
+    ).createConversation<DirectConversationInfo>(payload);
+
+    // Client-side fallback only: agent-servers >= 1.37.1 persist the link via
+    // `parent_conversation_id` and hand it back on the parent's
+    // `sub_conversation_ids`, which is the source of truth. This hint covers
+    // older backends that ignore the field.
+    mergeStoredConversationMetadata(parentConversationId, {
+      local_planning_conversation_id: data.id,
+    });
+
+    return toAppConversation(data);
+  }
+
+  /**
+   * Ids of the conversations owned by `parentConversationId` on a local
+   * backend — today that means its planner helper, the only child Canvas
+   * creates locally.
+   *
+   * `sub_conversation_ids` is the generic server-derived child list, so each
+   * child is kept only if it's tagged `plannerparent` for this parent —
+   * otherwise deleting the parent would also delete an unrelated non-planner
+   * child (e.g. a delegated sub-agent). The stored metadata hint is merged in
+   * for agent-servers older than 1.37.1, which report no children at all.
+   */
+  static async getLocalPlanningConversationIds(
+    parentConversationId: string,
+  ): Promise<string[]> {
+    if (getActiveBackend().backend.kind === "cloud") return [];
+
+    const ids = new Set<string>();
+
+    try {
+      const [parent] = await this.batchGetAppConversations([
+        parentConversationId,
+      ]);
+      const childIds = parent?.sub_conversation_ids ?? [];
+      if (childIds.length > 0) {
+        const children = await this.batchGetAppConversations(childIds);
+        for (const child of children) {
+          if (child && isPlannerConversationOf(child, parentConversationId)) {
+            ids.add(child.id);
+          }
+        }
+      }
+    } catch (error) {
+      // The stored hint below still covers the common case, and callers
+      // (delete) must not be blocked by a failed lookup.
+      console.warn(
+        `Failed to read sub-conversations of ${parentConversationId}`,
+        error,
+      );
+    }
+
+    const stored =
+      getStoredConversationMetadata(
+        parentConversationId,
+      )?.local_planning_conversation_id;
+    if (stored) ids.add(stored);
+
+    return [...ids];
+  }
+
+  static async getStartTask(
+    taskId: string,
+  ): Promise<AppConversationStartTask | null> {
+    if (getActiveBackend().backend.kind === "cloud") {
+      return getCloudAppConversationStartTask(taskId);
+    }
+    // Local agent-server creates conversations synchronously — every
+    // local "task" is already READY when createConversation returns, so
+    // there's nothing to poll for.
+    return null;
+  }
+
+  static async getVSCodeUrl(
+    conversationId: string,
+    conversationUrl: string | null | undefined,
+    sessionApiKey?: string | null,
+  ): Promise<GetVSCodeUrlResponse> {
+    // Local-only path. Cloud conversations read the VSCode URL straight
+    // from the cloud-computed `sandbox.exposed_urls` (see
+    // `useUnifiedVSCodeUrl` + `useCloudSandbox`); the runtime's own
+    // `/api/vscode/url` only knows its internal `localhost:8001`, which
+    // the user's browser can't reach.
+    const workspaceDir =
+      await this.resolveConversationWorkingDir(conversationId);
+    // Local mode: the typescript-client targets the local agent-server
+    // directly via the conversationUrl override.
+    const vscodeUrl = await new VSCodeClient(
+      getAgentServerClientOptions({
+        conversationUrl,
+        sessionApiKey,
+      }),
+    ).getUrl({
+      baseUrl:
+        typeof window !== "undefined" ? window.location.origin : undefined,
+      workspaceDir,
+    });
+
+    return { vscode_url: vscodeUrl };
+  }
+
+  /**
+   * Read the editor's capability state from the agent-server.
+   *
+   * `/api/vscode/status` answers 200 with `enabled: false` when the
+   * deployment set `enable_vscode: false`, which distinguishes "this
+   * deployment offers no editor" from a transport, auth, or server
+   * failure — `/api/vscode/url` answers 503 for the former and so
+   * cannot be told apart from the latter.
+   */
+  static async getVSCodeStatus(
+    conversationUrl: string | null | undefined,
+    sessionApiKey?: string | null,
+  ): Promise<VSCodeStatusResponse> {
+    return new VSCodeClient(
+      getAgentServerClientOptions({
+        conversationUrl,
+        sessionApiKey,
+      }),
+    ).getStatus();
+  }
+
+  static async resolveConversationWorkingDir(
+    conversationId: string,
+  ): Promise<string> {
+    const [conversation] = await this.batchGetAppConversations([
+      conversationId,
+    ]);
+    return conversation?.workspace?.working_dir ?? getAgentServerWorkingDir();
+  }
+
+  static async batchGetAppConversations(
+    ids: string[],
+  ): Promise<(AppConversation | null)[]> {
+    if (ids.length === 0) return [];
+
+    if (getActiveBackend().backend.kind === "cloud") {
+      return batchGetCloudConversations(ids);
+    }
+
+    const data = await new ConversationClient(
+      getAgentServerClientOptions(),
+    ).getConversations<DirectConversationInfo>(ids);
+
+    return requireDirectConversationItems(data).map((item) =>
+      toAppConversation(item),
+    );
+  }
+
+  static async updateConversationPublicFlag(
+    conversationId: string,
+    isPublic: boolean,
+  ): Promise<AppConversation> {
+    if (getActiveBackend().backend.kind !== "cloud") {
+      throw new Error("Public sharing requires a cloud backend.");
+    }
+    return updateCloudConversationPublicFlag(conversationId, isPublic);
+  }
+
+  static async updateConversationRepository(
+    conversationId: string,
+    repository: string | null,
+    branch?: string | null,
+    gitProvider?: string | null,
+  ): Promise<AppConversation> {
+    if (repository) {
+      const existing = getStoredConversationMetadata(conversationId);
+      setStoredConversationMetadata(conversationId, {
+        ...(existing ?? {}),
+        selected_repository: repository,
+        selected_branch: branch ?? null,
+        git_provider: (gitProvider as Provider | null | undefined) ?? null,
+      });
+    } else {
+      removeStoredConversationMetadata(conversationId);
+    }
+    const [conversation] = await this.batchGetAppConversations([
+      conversationId,
+    ]);
+    return requireAppConversation(conversation, conversationId);
+  }
+
+  static async readConversationFile(
+    conversationId: string,
+    filePath?: string,
+  ): Promise<string> {
+    if (getActiveBackend().backend.kind === "cloud") {
+      // Cloud exposes a per-conversation file endpoint; the sandbox
+      // working dir is fixed (`/workspace/project`), so PLAN.md lives at
+      // a known absolute path. Mirrors OpenHands' readConversationFile.
+      const path = requirePathInsideDirectory(
+        filePath ?? "/workspace/project/.agents_tmp/PLAN.md",
+        "/workspace/project",
+      );
+      return readCloudConversationFile(conversationId, path);
+    }
+
+    const workingDir = await this.resolveConversationWorkingDir(conversationId);
+    const path = requirePathInsideDirectory(
+      filePath ?? `${workingDir}/.agents_tmp/PLAN.md`,
+      workingDir,
+    );
+    return new FileClient(getAgentServerClientOptions()).downloadTextFile(path);
+  }
+
+  static async downloadConversation(conversationId: string): Promise<Blob> {
+    if (getActiveBackend().backend.kind === "cloud") {
+      return downloadCloudConversation(conversationId);
+    }
+
+    return new FileClient(getAgentServerClientOptions()).downloadTrajectory(
+      conversationId,
+    );
+  }
+
+  static async getHooks(conversationId: string): Promise<GetHooksResponse> {
+    if (!conversationId) {
+      return emptyHooksResponse();
+    }
+    return emptyHooksResponse();
+  }
+
+  static async getRuntimeConversation(
+    conversationId: string,
+    conversationUrl: string | null | undefined,
+    sessionApiKey?: string | null,
+  ): Promise<RuntimeConversationInfo> {
+    // Fetch directly from the per-conversation runtime agent-server at conversationUrl.
+    const response = await new ConversationClient(
+      getAgentServerClientOptions({
+        conversationUrl,
+        sessionApiKey,
+      }),
+    ).getConversation<DirectConversationInfo>(conversationId);
+    const data = requireDirectConversationInfo(response);
+
+    return {
+      id: data.id,
+      title: data.title?.trim()
+        ? data.title
+        : getDefaultConversationTitle(data.id),
+      metrics: normalizeMetrics(data.metrics),
+      created_at: data.created_at,
+      updated_at: data.updated_at,
+      status: toRuntimeStatus(data.execution_status),
+      stats: data.stats ?? { usage_to_metrics: {} },
+    };
+  }
+
+  /**
+   * Force condensation ("compact") of the conversation history via
+   * `POST /api/conversations/{id}/condense`. Routed the same way as
+   * {@link sendMessage}: through the cloud proxy at the conversation's own
+   * runtime host for cloud backends, directly against that runtime otherwise.
+   */
+  static async condenseConversation(
+    conversationId: string,
+    conversationUrl: string | null | undefined,
+    sessionApiKey?: string | null,
+  ): Promise<void> {
+    const active = getActiveBackend().backend;
+
+    if (active.kind === "cloud" && conversationUrl) {
+      await callCloudProxy({
+        backend: active,
+        method: "POST",
+        hostOverride: buildHttpBaseUrl(conversationUrl),
+        path: `/api/conversations/${conversationId}/condense`,
+        authMode: "session-api-key",
+        sessionApiKey,
+      });
+      return;
+    }
+
+    await new ConversationClient(
+      getAgentServerClientOptions({ conversationUrl, sessionApiKey }),
+    ).condenseConversation(conversationId);
+  }
+
+  static async searchConversations(
+    limit: number = 20,
+    pageId?: string,
+  ): Promise<AppConversationPage> {
+    if (getActiveBackend().backend.kind === "cloud") {
+      return searchCloudConversations(limit, pageId);
+    }
+
+    const data = await new ConversationClient(
+      getAgentServerClientOptions(),
+    ).searchConversations({
+      limit,
+      page_id: pageId,
+      sort_order: ConversationSortOrder.UPDATED_AT_DESC,
+    });
+
+    return toConversationPage(requireConversationSearchPage(data));
+  }
+
+  static async deleteConversation(conversationId: string): Promise<void> {
+    if (getActiveBackend().backend.kind === "cloud") {
+      await deleteCloudConversation(conversationId);
+      removeStoredConversationMetadata(conversationId);
+      return;
+    }
+
+    // The agent-server orphans children rather than cascading, and the local
+    // planner helper is hidden from the conversation list by its
+    // `plannerparent` tag — so without this it would survive its parent as an
+    // invisible, unreachable conversation (plus its events and state).
+    const planningConversationIds =
+      await this.getLocalPlanningConversationIds(conversationId);
+
+    const client = new ConversationClient(getAgentServerClientOptions());
+    await Promise.all(
+      planningConversationIds.map(async (planningConversationId) => {
+        try {
+          await client.deleteConversation(planningConversationId);
+        } catch (error) {
+          // Already gone (or unreachable): never block deleting the parent the
+          // user actually asked to remove.
+          console.warn(
+            `Failed to delete planning conversation ${planningConversationId}`,
+            error,
+          );
+        }
+        removeStoredConversationMetadata(planningConversationId);
+      }),
+    );
+
+    await client.deleteConversation(conversationId);
+    removeStoredConversationMetadata(conversationId);
+  }
+
+  static async updateConversationTitle(
+    conversationId: string,
+    title: string,
+  ): Promise<AppConversation> {
+    if (getActiveBackend().backend.kind === "cloud") {
+      return updateCloudConversationTitle(conversationId, title);
+    }
+
+    await new ConversationClient(
+      getAgentServerClientOptions(),
+    ).updateConversation(conversationId, {
+      title,
+    });
+    const [conversation] = await this.batchGetAppConversations([
+      conversationId,
+    ]);
+    return requireAppConversation(conversation, conversationId);
+  }
+
+  /**
+   * Replaces the conversation's complete server-side tag map (the PATCH is
+   * replace-all, so callers must merge user edits with any reserved/internal
+   * keys before calling). Mirrors `updateConversationTitle`; local
+   * agent-server conversations only — Cloud conversations don't carry tags.
+   */
+  static async updateConversationTags(
+    conversationId: string,
+    tags: Record<string, string>,
+  ): Promise<AppConversation> {
+    await new ConversationClient(
+      getAgentServerClientOptions(),
+    ).updateConversation(conversationId, {
+      tags,
+    });
+    const [conversation] = await this.batchGetAppConversations([
+      conversationId,
+    ]);
+    return requireAppConversation(conversation, conversationId);
+  }
+
+  /**
+   * Forks a conversation, copying event history up to and including
+   * `fromEventId`. Local agent-server only; needs agent-server >= 1.31.0 for
+   * `from_event_id` (older backends copy the whole conversation).
+   */
+  static async forkConversation(
+    sourceConversationId: string,
+    fromEventId: string,
+    title?: string,
+  ): Promise<DirectConversationInfo> {
+    if (getActiveBackend().backend.kind === "cloud") {
+      throw new Error(
+        "Branching a conversation isn't supported on the cloud backend yet.",
+      );
+    }
+
+    // `from_event_id` is accepted by `/fork` but not yet typed in
+    // ForkConversationRequest (through client 1.32.0); the client forwards the
+    // body verbatim, so cast to carry it. A title also suppresses the backend
+    // auto-title, so the "(branch)" marker sticks.
+    const data = await new ConversationClient(
+      getAgentServerClientOptions(),
+    ).forkConversation<DirectConversationInfo>(sourceConversationId, {
+      from_event_id: fromEventId,
+      ...(title ? { title } : {}),
+    } as ForkConversationRequest & { from_event_id: string });
+
+    // Carry over the source's client-side metadata (repo/branch/workspace/
+    // profile/plugins) so the fork hydrates its chat-page badges the same way.
+    const sourceMetadata = getStoredConversationMetadata(sourceConversationId);
+    if (sourceMetadata) {
+      setStoredConversationMetadata(data.id, sourceMetadata);
+    }
+
+    return data;
+  }
+
+  /**
+   * Returns an event's `parent_id` (the fork point for branching *before* it),
+   * or undefined at the root. Uses the single-event endpoint because the events
+   * *search* API omits `parent_id`.
+   */
+  static async getEventParentId(
+    conversationId: string,
+    eventId: string,
+  ): Promise<string | undefined> {
+    const event = (await new ConversationClient(
+      getAgentServerClientOptions(),
+    ).getEvent(conversationId, eventId)) as { parent_id?: string | null };
+    return event.parent_id ?? undefined;
+  }
+
+  /**
+   * Switches the LLM profile for the running conversation when one is open
+   * (POST /switch_profile — per-conversation swap, doesn't change the user's
+   * default profile). When called without a conversationId (home page),
+   * falls back to POST /activate so the next conversation created picks up
+   * the chosen profile.
+   *
+   * The per-conversation endpoint accepts only the profile name, so the UI does
+   * not need to fetch or forward profile secrets. That keeps switching working
+   * even when the agent server has no OH_SECRET_KEY for encrypted secret export.
+   *
+   * Cloud backends route to the app-server's per-conversation
+   * `/switch_profile`, which owns the profiles and resolves the swap
+   * server-side (base_url/api_key fixups, usage_id derivation, then the
+   * agent-server's switch_llm) — so the client only forwards the profile name,
+   * mirroring {@link switchAcpModel}.
+   */
+  static async switchProfile(
+    conversationId: string | null,
+    profileName: string,
+  ): Promise<void> {
+    const { backend } = getActiveBackend();
+
+    if (backend.kind === "cloud") {
+      // No conversation (home page): activate globally so the next
+      // conversation starts with it. ProfilesService routes to the cloud
+      // activate endpoint.
+      if (!conversationId) {
+        await ProfilesService.activateProfile(profileName);
+        return;
+      }
+      await callCloudProxy({
+        backend,
+        method: "POST",
+        path: `/api/v1/app-conversations/${conversationId}/switch_profile`,
+        body: { profile_name: profileName },
+      });
+      return;
+    }
+
+    if (!conversationId) {
+      await new ProfilesClient(getAgentServerClientOptions()).activateProfile(
+        profileName,
+      );
+      return;
+    }
+
+    const clientOptions = getAgentServerClientOptions();
+    const conversationClient = new ConversationClient(clientOptions);
+    const profile = await new ProfilesClient(clientOptions).getProfile(
+      profileName,
+      { exposeSecrets: "encrypted" },
+    );
+    const model =
+      typeof profile.config.model === "string" ? profile.config.model : "";
+    if (!model) throw new Error(`Profile '${profileName}' has no model.`);
+    await assertSubscriptionAuthReady({ llm: profile.config });
+    await conversationClient.switchLLM(conversationId, {
+      ...profile.config,
+      model,
+      // Keep streaming on after a switch (parity with conversation start);
+      // the profile config would otherwise default it to stream=False.
+      stream: true,
+      // Avoid stale first-write-wins entries in the backend LLM registry.
+      usage_id: `profile:${profileName}:${uuidv4()}`,
+    } as LLMConfig);
+  }
+
+  /**
+   * Switches the model of a running ACP conversation in place (POST
+   * /switch_acp_model — the ACP analog of {@link switchProfile}'s /switch_profile).
+   * The agent-server calls the ACP wrapper's ``session/set_model`` on the live
+   * session, preserving context. Mirrors {@link switchProfile}'s
+   * local-backend-only guard and per-conversation ConversationClient call.
+   *
+   * Works on a created-but-not-yet-run conversation too: the agent-server
+   * treats a pre-first-run switch as a persist-only deferral (the model is
+   * mirrored into the conversation's stored agent and applied when the session
+   * starts). The home/no-conversation default is persisted via the active ACP
+   * profile / Settings instead (see ``use-switch-acp-model``).
+   */
+  static async switchAcpModel(
+    conversationId: string,
+    model: string,
+  ): Promise<void> {
+    const { backend } = getActiveBackend();
+    if (backend.kind === "cloud") {
+      await callCloudProxy({
+        backend,
+        method: "POST",
+        path: `/api/v1/app-conversations/${conversationId}/switch_acp_model`,
+        body: { model },
+      });
+      return;
+    }
+
+    await new ConversationClient(getAgentServerClientOptions()).switchAcpModel(
+      conversationId,
+      model,
+    );
+  }
+}
+
+export default AgentServerConversationService;

src/api/conversation-service/agent-server-conversation-service.types.ts

@@ -0,0 +1,298 @@
+import { ConversationTrigger } from "../open-hands.types";
+import { Provider } from "#/types/settings";
+import { SuggestedTask } from "#/utils/types";
+import { ExecutionStatus } from "#/types/agent-server/core";
+
+/**
+ * Lifecycle state of a cloud sandbox. Mirrors OpenHands' V1SandboxStatus.
+ * Local agent-server conversations do not carry this field (null).
+ */
+export type SandboxStatus =
+  | "PAUSED"
+  | "RUNNING"
+  | "STARTING"
+  | "MISSING"
+  | "ERROR";
+
+// Plugin specification for starting conversations with plugins
+export interface PluginSpec {
+  source: string; // Plugin source: 'github:owner/repo', git URL, or local path
+  ref?: string | null; // Optional branch, tag, or commit
+  repo_path?: string | null; // Subdirectory path within the git repository
+  parameters?: Record<string, unknown> | null; // User-provided configuration values
+  // Client-side display label (e.g. an installed plugin's `name`). Not a
+  // coordinate and not required by the agent-server; used only for rendering.
+  name?: string | null;
+}
+
+// V1 Metrics Types
+export interface TokenUsage {
+  prompt_tokens: number;
+  completion_tokens: number;
+  cache_read_tokens: number;
+  cache_write_tokens: number;
+  context_window: number;
+  per_turn_token: number;
+}
+
+export interface MetricsSnapshot {
+  accumulated_cost: number | null;
+  max_budget_per_task: number | null;
+  accumulated_token_usage: TokenUsage | null;
+}
+
+// V1 API Types for requests
+// These types match the SDK's TextContent and ImageContent formats
+export interface MessageTextContent {
+  type: "text";
+  text: string;
+}
+
+export interface MessageImageContent {
+  type: "image";
+  image_urls: string[];
+}
+
+export type MessageContent = MessageTextContent | MessageImageContent;
+
+type MessageRole = "user" | "system" | "assistant" | "tool";
+
+export interface SendMessageRequest {
+  role: MessageRole;
+  content: MessageContent[];
+}
+
+export interface AppConversationStartRequest {
+  // Re-provision an EXISTING conversation (waking a recycled sandbox) instead
+  // of minting a new one. The backend keys the rebuilt conversation on this id
+  // and, for ACP, resumes it from the durable event store with a bootstrap
+  // prompt (OpenHands#14640). Omit/null to create a fresh conversation.
+  conversation_id?: string | null;
+  initial_message?: SendMessageRequest | null;
+  processors?: unknown[]; // EventCallbackProcessor - keeping as unknown for now
+  llm_model?: string | null;
+  selected_repository?: string | null;
+  selected_branch?: string | null;
+  git_provider?: Provider | null;
+  suggested_task?: SuggestedTask | null;
+  title?: string | null;
+  trigger?: ConversationTrigger | null;
+  pr_number?: number[];
+  parent_conversation_id?: string | null;
+  agent_type?: "default" | "plan";
+  sandbox_id?: string | null;
+  plugins?: PluginSpec[] | null; // Plugins to load when starting the conversation
+  // One-off launch from a saved AgentProfile, resolved server-side (#3727).
+  // Accepted by the cloud app-server (OpenHands #15060) on
+  // POST /api/v1/app-conversations; the local path uses the encrypted
+  // agent_settings builder instead, which threads its own agentProfileId.
+  agent_profile_id?: string | null;
+}
+
+export type AppConversationStartTaskStatus =
+  | "WORKING"
+  | "WAITING_FOR_SANDBOX"
+  | "PREPARING_REPOSITORY"
+  | "RUNNING_SETUP_SCRIPT"
+  | "SETTING_UP_GIT_HOOKS"
+  | "SETTING_UP_SKILLS"
+  | "STARTING_CONVERSATION"
+  | "READY"
+  | "ERROR";
+
+export interface AppConversationStartTask {
+  id: string;
+  created_by_user_id: string | null;
+  status: AppConversationStartTaskStatus;
+  detail: string | null;
+  app_conversation_id: string | null;
+  agent_server_url: string | null;
+  request: AppConversationStartRequest;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface SendMessageResponse {
+  role: "user" | "system" | "assistant" | "tool";
+  content: MessageContent[];
+}
+
+export interface AppConversationStartTaskPage {
+  items: AppConversationStartTask[];
+  next_page_id: string | null;
+}
+
+export interface ConversationWorkspace {
+  working_dir: string | null;
+}
+
+export interface LaunchedAgentProfile {
+  agent_profile_id: string;
+  revision: number;
+}
+
+export interface AppConversation {
+  id: string;
+  created_by_user_id: string | null;
+  selected_repository: string | null;
+  selected_branch: string | null;
+  git_provider: Provider | null;
+  title: string | null;
+  trigger: ConversationTrigger | null;
+  pr_number: number[];
+  /**
+   * High-level kind of the conversation's agent — ``"openhands"`` for an LLM-
+   * driven Agent, ``"acp"`` for an ACPAgent that delegates to an external
+   * ACP CLI subprocess. Consumers can use this to gate UI affordances that
+   * only make sense for one kind (e.g. the LLM-profile switcher in the chat
+   * header is a no-op for ACP conversations even though ``llm_model`` may
+   * carry the ACP subprocess model for display).
+   */
+  agent_kind?: "openhands" | "acp" | null;
+  launched_agent_profile?: LaunchedAgentProfile | null;
+  /**
+   * For ACP conversations, the registry key of the ACP CLI server the
+   * conversation was launched against (e.g. ``"claude-code"``, ``"codex"``,
+   * ``"gemini-cli"``). Populated from ``info.tags.acpserver`` — see
+   * ``ACP_SERVER_TAG_KEY`` in ``agent-server-adapter.ts`` for the wire
+   * format and the rationale behind the snake_case-incompatible
+   * ``acpserver`` form. ``null`` for OpenHands conversations and for ACP
+   * conversations whose tag wasn't stamped (e.g. created via an older
+   * client or via the raw API). Consumers resolve the display name via
+   * ``getAcpProviderDisplayName(acp_server)`` and fall back to a generic
+   * "ACP" chip when the key is unknown or null.
+   */
+  acp_server?: string | null;
+  /**
+   * Server-side key-value tags from the agent-server's
+   * ``ConversationInfo.tags`` (settable at creation and via
+   * ``PATCH /api/conversations/{id}``). Automations and API clients use these
+   * for attribution (e.g. ``origin=slack``, ``owner=alice``). Includes
+   * reserved/internal keys such as ``acpserver`` — display consumers should
+   * go through ``getDisplayConversationTags`` in ``agent-server-adapter.ts``
+   * rather than reading this raw. ``null``/absent for Cloud conversations
+   * and agent-servers that don't return tags.
+   *
+   * PATCH semantics: the agent-server replaces the **complete** ``tags`` map
+   * on every PATCH — it does not merge individual keys. A writer adding one
+   * tag must read the current map, merge, and send the full desired result,
+   * or it will silently drop every other tag (including ``acpserver``).
+   */
+  tags?: Record<string, string> | null;
+  llm_model: string | null;
+  metrics: MetricsSnapshot | null;
+  created_at: string;
+  updated_at: string;
+  execution_status: ExecutionStatus | null;
+  /**
+   * Cloud-only sandbox lifecycle status. Mirrors OpenHands' V1SandboxStatus.
+   * Absent / null for local agent-server conversations.
+   */
+  sandbox_status?: SandboxStatus | null;
+  conversation_url: string | null;
+  session_api_key: string | null;
+  sandbox_id: string | null;
+  workspace?: ConversationWorkspace | null;
+  /**
+   * The local workspace the user explicitly attached when creating this
+   * conversation. Client-side only — never round-tripped to the agent-server
+   * or cloud. Null/undefined for conversations created via "No workspace".
+   * Distinct from `workspace.working_dir`, which is the runtime path and may
+   * either match this folder directly or point at a per-conversation worktree.
+   */
+  selected_workspace?: string | null;
+  /**
+   * The LLM profile this conversation was created with / last switched to.
+   * Hydrated from client-side metadata (see
+   * `ConversationMetadata.active_profile`). Preferred over matching
+   * `llm_model` against the profile list, which is ambiguous when several
+   * profiles share a model (#1082). Null when unknown (e.g. created by an
+   * older client) — consumers fall back to model-matching.
+   */
+  active_profile?: string | null;
+  public?: boolean;
+  sub_conversation_ids: string[];
+}
+
+export interface AppConversationPage {
+  items: AppConversation[];
+  next_page_id: string | null;
+}
+
+export interface Skill {
+  name: string;
+  type: "repo" | "knowledge" | "agentskills";
+  content: string;
+  triggers: string[];
+  source?: string | null;
+  description?: string | null;
+  version?: string;
+  license?: string | null;
+  compatibility?: string | null;
+  metadata?: Record<string, string> | null;
+  allowed_tools?: string[] | null;
+  is_agentskills_format?: boolean;
+  disable_model_invocation?: boolean;
+}
+
+export interface GetSkillsResponse {
+  skills: Skill[];
+}
+
+export interface HookDefinition {
+  type: string; // 'command' or 'prompt'
+  command: string;
+  timeout: number;
+  async?: boolean;
+}
+
+export interface HookMatcher {
+  matcher: string; // Pattern: '*', exact match, or regex
+  hooks?: HookDefinition[]; // May be undefined while hooks are still executing on the server
+}
+
+export interface HookEvent {
+  event_type: string; // e.g., 'stop', 'pre_tool_use', 'post_tool_use'
+  matchers: HookMatcher[];
+}
+
+export interface GetHooksResponse {
+  hooks: HookEvent[];
+}
+
+// Runtime conversation types (from agent server)
+export interface RuntimeConversationStats {
+  usage_to_metrics: Record<string, RuntimeMetrics>;
+}
+
+export interface RuntimeMetrics {
+  model_name: string;
+  accumulated_cost: number;
+  max_budget_per_task: number | null;
+  accumulated_token_usage: TokenUsage | null;
+  costs: Cost[];
+  response_latencies: ResponseLatency[];
+  token_usages: TokenUsage[];
+}
+
+export interface Cost {
+  model: string;
+  cost: number;
+  timestamp: number;
+}
+
+export interface ResponseLatency {
+  model: string;
+  latency: number;
+  response_id: string;
+}
+
+export interface RuntimeConversationInfo {
+  id: string;
+  title: string | null;
+  metrics: MetricsSnapshot | null;
+  created_at: string;
+  updated_at: string;
+  status: ExecutionStatus;
+  stats: RuntimeConversationStats;
+}

src/api/conversation-service/conversation-service.api.ts

@@ -0,0 +1,77 @@
+import { VSCodeClient } from "@openhands/typescript-client/clients";
+import { RemoteEventsList } from "@openhands/typescript-client/events/remote-events-list";
+import { uploadFilesToConversation } from "#/api/conversation-file-upload.api";
+import {
+  GetVSCodeUrlResponse,
+  GetTrajectoryResponse,
+  FileUploadSuccessResponse,
+} from "../open-hands.types";
+import { getAgentServerWorkingDir } from "../agent-server-config";
+import {
+  getAgentServerClientOptions,
+  getAgentServerHttpClientOptions,
+} from "../agent-server-client-options";
+import { AppConversation } from "./agent-server-conversation-service.types";
+
+class ConversationService {
+  private static currentConversation: AppConversation | null = null;
+
+  static setCurrentConversation(
+    currentConversation: AppConversation | null,
+  ): void {
+    this.currentConversation = currentConversation;
+  }
+
+  static getCurrentConversation(): AppConversation | null {
+    return this.currentConversation;
+  }
+
+  private static getClientOverrides() {
+    return {
+      sessionApiKey: this.currentConversation?.session_api_key,
+    };
+  }
+
+  static async getVSCodeUrl(
+    conversationId: string,
+  ): Promise<GetVSCodeUrlResponse> {
+    const workspaceDir =
+      this.currentConversation?.id === conversationId
+        ? (this.currentConversation?.workspace?.working_dir ??
+          getAgentServerWorkingDir())
+        : getAgentServerWorkingDir();
+    const vscodeUrl = await new VSCodeClient(
+      getAgentServerClientOptions(this.getClientOverrides()),
+    ).getUrl({
+      baseUrl:
+        typeof window !== "undefined" ? window.location.origin : undefined,
+      workspaceDir,
+    });
+
+    return { vscode_url: vscodeUrl };
+  }
+
+  static async getTrajectory(
+    conversationId: string,
+  ): Promise<GetTrajectoryResponse> {
+    const page = await new RemoteEventsList(
+      getAgentServerHttpClientOptions(this.getClientOverrides()),
+      conversationId,
+    ).search({ limit: 10000 });
+
+    return { trajectory: page.items ?? [] };
+  }
+
+  static async uploadFiles(
+    conversationId: string,
+    files: File[],
+  ): Promise<FileUploadSuccessResponse> {
+    return uploadFilesToConversation(
+      conversationId,
+      files,
+      this.currentConversation,
+    );
+  }
+}
+
+export default ConversationService;

src/api/event-service/event-service.api.test.ts

@@ -0,0 +1,409 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const {
+  buildHttpBaseUrlMock,
+  callCloudProxyMock,
+  conversationClientConstructorMock,
+  getActiveBackendMock,
+  getAgentServerClientOptionsMock,
+  getAgentServerHttpClientOptionsMock,
+  getEventCountMock,
+  remoteEventsListConstructorMock,
+  remoteSearchMock,
+  respondToConfirmationMock,
+} = vi.hoisted(() => ({
+  buildHttpBaseUrlMock: vi.fn(),
+  callCloudProxyMock: vi.fn(),
+  conversationClientConstructorMock: vi.fn(),
+  getActiveBackendMock: vi.fn(),
+  getAgentServerClientOptionsMock: vi.fn(),
+  getAgentServerHttpClientOptionsMock: vi.fn(),
+  getEventCountMock: vi.fn(),
+  remoteEventsListConstructorMock: vi.fn(),
+  remoteSearchMock: vi.fn(),
+  respondToConfirmationMock: vi.fn(),
+}));
+
+vi.mock("@openhands/typescript-client/clients", () => ({
+  ConversationClient: class {
+    constructor(options: unknown) {
+      conversationClientConstructorMock(options);
+    }
+
+    respondToConfirmation = respondToConfirmationMock;
+    getEventCount = getEventCountMock;
+  },
+}));
+vi.mock("@openhands/typescript-client/events/remote-events-list", () => ({
+  RemoteEventsList: class {
+    constructor(options: unknown, conversationId: string) {
+      remoteEventsListConstructorMock(options, conversationId);
+    }
+
+    search = remoteSearchMock;
+  },
+}));
+vi.mock("#/utils/websocket-url", () => ({
+  buildHttpBaseUrl: buildHttpBaseUrlMock,
+}));
+vi.mock("../backend-registry/active-store", () => ({
+  getActiveBackend: getActiveBackendMock,
+}));
+vi.mock("../cloud/proxy", () => ({ callCloudProxy: callCloudProxyMock }));
+vi.mock("../agent-server-client-options", () => ({
+  getAgentServerClientOptions: getAgentServerClientOptionsMock,
+  getAgentServerHttpClientOptions: getAgentServerHttpClientOptionsMock,
+}));
+
+import EventService from "./event-service.api";
+
+const cloudBackend = {
+  id: "cloud-backend",
+  name: "Cloud",
+  host: "https://app.example.com",
+  apiKey: "cloud-api-key",
+  kind: "cloud",
+};
+
+const localBackend = {
+  id: "local-backend",
+  name: "Local",
+  host: "http://localhost:3000",
+  apiKey: "local-api-key",
+  kind: "local",
+};
+
+function useBackend(backend: typeof cloudBackend | typeof localBackend): void {
+  getActiveBackendMock.mockReturnValue({ backend, orgId: null });
+}
+
+describe("EventService", () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    useBackend(cloudBackend);
+    buildHttpBaseUrlMock.mockReturnValue("https://runtime.example.com/base");
+    getAgentServerClientOptionsMock.mockReturnValue({
+      host: "http://local-client.example.com",
+      apiKey: "client-key",
+      workingDir: "workspace/project",
+    });
+    getAgentServerHttpClientOptionsMock.mockReturnValue({
+      baseUrl: "http://local-http.example.com",
+      apiKey: "http-key",
+      timeout: 60_000,
+    });
+  });
+
+  describe("respondToConfirmation", () => {
+    it("routes cloud confirmations through the runtime proxy with session authentication", async () => {
+      const request = { accept: false, reason: "Needs human review" };
+      callCloudProxyMock.mockResolvedValue({ success: true });
+
+      await expect(
+        EventService.respondToConfirmation(
+          "conversation-cloud",
+          "wss://runtime.example.com/base/api/conversations/conversation-cloud",
+          request,
+          "session-key",
+        ),
+      ).resolves.toEqual({ success: true });
+
+      expect(buildHttpBaseUrlMock).toHaveBeenCalledWith(
+        "wss://runtime.example.com/base/api/conversations/conversation-cloud",
+      );
+      expect(callCloudProxyMock).toHaveBeenCalledWith({
+        backend: cloudBackend,
+        method: "POST",
+        hostOverride: "https://runtime.example.com/base",
+        path: "/api/conversations/conversation-cloud/events/respond_to_confirmation",
+        body: request,
+        authMode: "session-api-key",
+        sessionApiKey: "session-key",
+      });
+      expect(conversationClientConstructorMock).not.toHaveBeenCalled();
+    });
+
+    it("uses the typed conversation client for local confirmations", async () => {
+      useBackend(localBackend);
+      respondToConfirmationMock.mockResolvedValue({ success: false });
+
+      await expect(
+        EventService.respondToConfirmation(
+          "conversation-local",
+          "http://localhost:3000/api/conversations/conversation-local",
+          { accept: true },
+        ),
+      ).resolves.toEqual({ success: false });
+
+      expect(getAgentServerClientOptionsMock).toHaveBeenCalledWith({
+        conversationUrl:
+          "http://localhost:3000/api/conversations/conversation-local",
+        sessionApiKey: undefined,
+      });
+      expect(conversationClientConstructorMock).toHaveBeenCalledWith({
+        host: "http://local-client.example.com",
+        apiKey: "client-key",
+        workingDir: "workspace/project",
+      });
+      expect(respondToConfirmationMock).toHaveBeenCalledWith(
+        "conversation-local",
+        { accept: true },
+      );
+      expect(callCloudProxyMock).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("getEventCount", () => {
+    it("gets the cloud count from the runtime proxy", async () => {
+      callCloudProxyMock.mockResolvedValue(17);
+
+      await expect(
+        EventService.getEventCount(
+          "conversation-cloud",
+          "https://runtime.example.com/api/conversations/conversation-cloud",
+          null,
+        ),
+      ).resolves.toBe(17);
+
+      expect(buildHttpBaseUrlMock).toHaveBeenCalledWith(
+        "https://runtime.example.com/api/conversations/conversation-cloud",
+      );
+      expect(callCloudProxyMock).toHaveBeenCalledWith({
+        backend: cloudBackend,
+        method: "GET",
+        hostOverride: "https://runtime.example.com/base",
+        path: "/api/conversations/conversation-cloud/events/count",
+        authMode: "session-api-key",
+        sessionApiKey: null,
+      });
+      expect(conversationClientConstructorMock).not.toHaveBeenCalled();
+    });
+
+    it("gets the local count from the typed conversation client", async () => {
+      useBackend(localBackend);
+      getEventCountMock.mockResolvedValue(8);
+
+      await expect(
+        EventService.getEventCount(
+          "conversation-local",
+          "http://localhost:3000/api/conversations/conversation-local",
+          "session-key",
+        ),
+      ).resolves.toBe(8);
+
+      expect(getAgentServerClientOptionsMock).toHaveBeenCalledWith({
+        conversationUrl:
+          "http://localhost:3000/api/conversations/conversation-local",
+        sessionApiKey: "session-key",
+      });
+      expect(conversationClientConstructorMock).toHaveBeenCalledWith({
+        host: "http://local-client.example.com",
+        apiKey: "client-key",
+        workingDir: "workspace/project",
+      });
+      expect(getEventCountMock).toHaveBeenCalledWith("conversation-local");
+      expect(callCloudProxyMock).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("searchEvents", () => {
+    it("caps cloud limits and forwards every supported history filter", async () => {
+      const event = { id: "event-1" };
+      callCloudProxyMock.mockResolvedValue({
+        items: [event],
+        next_page_id: "page-2",
+      });
+
+      await expect(
+        EventService.searchEvents("conversation-cloud", null, null, {
+          limit: 250,
+          pageId: "page-1",
+          sortOrder: "TIMESTAMP_DESC",
+          timestampGte: "2026-07-12T00:00:00.000Z",
+          timestampLt: "2026-07-13T00:00:00.000Z",
+        }),
+      ).resolves.toEqual({ items: [event], next_page_id: "page-2" });
+
+      expect(callCloudProxyMock).toHaveBeenCalledWith({
+        backend: cloudBackend,
+        method: "GET",
+        path: "/api/v1/conversation/conversation-cloud/events/search?limit=100&sort_order=TIMESTAMP_DESC&page_id=page-1&timestamp__gte=2026-07-12T00%3A00%3A00.000Z&timestamp__lt=2026-07-13T00%3A00%3A00.000Z",
+      });
+    });
+
+    it("uses default cloud options and normalizes a missing response", async () => {
+      callCloudProxyMock.mockResolvedValue(undefined);
+
+      await expect(
+        EventService.searchEvents("conversation-cloud"),
+      ).resolves.toEqual({ items: [], next_page_id: null });
+
+      expect(callCloudProxyMock).toHaveBeenCalledWith({
+        backend: cloudBackend,
+        method: "GET",
+        path: "/api/v1/conversation/conversation-cloud/events/search?limit=100",
+      });
+    });
+
+    it("preserves zero as an explicit cloud limit", async () => {
+      callCloudProxyMock.mockResolvedValue({});
+
+      await expect(
+        EventService.searchEvents("conversation-cloud", null, null, {
+          limit: 0,
+        }),
+      ).resolves.toEqual({ items: [], next_page_id: null });
+
+      expect(callCloudProxyMock).toHaveBeenCalledWith({
+        backend: cloudBackend,
+        method: "GET",
+        path: "/api/v1/conversation/conversation-cloud/events/search?limit=0",
+      });
+    });
+
+    it("rethrows cloud failures when no pagination filter was requested", async () => {
+      const searchError = new Error("cloud unavailable");
+      callCloudProxyMock.mockRejectedValue(searchError);
+
+      await expect(
+        EventService.searchEvents("conversation-cloud", null, null, {
+          limit: 25,
+        }),
+      ).rejects.toBe(searchError);
+    });
+
+    it("rethrows filtered cloud failures for completeness-sensitive callers", async () => {
+      const paginationError = new Error("pagination unsupported");
+      callCloudProxyMock.mockRejectedValue(paginationError);
+
+      await expect(
+        EventService.searchEvents("conversation-cloud", null, null, {
+          pageId: "page-2",
+          strictPagination: true,
+        }),
+      ).rejects.toBe(paginationError);
+    });
+
+    it("retains the empty-page fallback for ordinary cloud pagination", async () => {
+      callCloudProxyMock.mockRejectedValue(new Error("pagination unsupported"));
+      const warn = vi
+        .spyOn(console, "warn")
+        .mockImplementation(() => undefined);
+
+      await expect(
+        EventService.searchEvents("conversation-cloud", null, null, {
+          timestampLt: "2026-07-10T12:34:56.000Z",
+        }),
+      ).resolves.toEqual({ items: [], next_page_id: null });
+
+      expect(warn).toHaveBeenCalledWith(
+        "[EventService] Cloud backend doesn't support pagination filters. " +
+          "Falling back to initial load only. " +
+          "Server needs OpenHands/OpenHands#14399.",
+      );
+      warn.mockRestore();
+    });
+
+    it("treats a sort-only cloud failure as unsupported filtered pagination", async () => {
+      callCloudProxyMock.mockRejectedValue(new Error("pagination unsupported"));
+      const warn = vi
+        .spyOn(console, "warn")
+        .mockImplementation(() => undefined);
+
+      await expect(
+        EventService.searchEvents("conversation-cloud", null, null, {
+          sortOrder: "TIMESTAMP_DESC",
+        }),
+      ).resolves.toEqual({ items: [], next_page_id: null });
+
+      expect(callCloudProxyMock).toHaveBeenCalledWith({
+        backend: cloudBackend,
+        method: "GET",
+        path: "/api/v1/conversation/conversation-cloud/events/search?limit=100&sort_order=TIMESTAMP_DESC",
+      });
+      expect(warn).toHaveBeenCalledOnce();
+      warn.mockRestore();
+    });
+
+    it("recognizes a lower timestamp bound as a cloud pagination filter", async () => {
+      callCloudProxyMock.mockResolvedValue({
+        items: [],
+        next_page_id: null,
+      });
+
+      await EventService.searchEvents("conversation-cloud", null, null, {
+        timestampGte: "2026-07-10T12:34:56.000Z",
+      });
+
+      expect(callCloudProxyMock).toHaveBeenCalledWith({
+        backend: cloudBackend,
+        method: "GET",
+        path: "/api/v1/conversation/conversation-cloud/events/search?limit=100&timestamp__gte=2026-07-10T12%3A34%3A56.000Z",
+      });
+    });
+
+    it("passes all local filters to the remote events list", async () => {
+      useBackend(localBackend);
+      const event = { id: "event-local" };
+      remoteSearchMock.mockResolvedValue({
+        items: [event],
+        next_page_id: "local-page-2",
+      });
+
+      await expect(
+        EventService.searchEvents(
+          "conversation-local",
+          "http://localhost:3000/api/conversations/conversation-local",
+          "session-key",
+          {
+            limit: 40,
+            pageId: "local-page-1",
+            sortOrder: "TIMESTAMP",
+            timestampGte: "2026-07-11T00:00:00.000Z",
+            timestampLt: "2026-07-12T00:00:00.000Z",
+          },
+        ),
+      ).resolves.toEqual({
+        items: [event],
+        next_page_id: "local-page-2",
+      });
+
+      expect(getAgentServerHttpClientOptionsMock).toHaveBeenCalledWith({
+        conversationUrl:
+          "http://localhost:3000/api/conversations/conversation-local",
+        sessionApiKey: "session-key",
+      });
+      expect(remoteEventsListConstructorMock).toHaveBeenCalledWith(
+        {
+          baseUrl: "http://local-http.example.com",
+          apiKey: "http-key",
+          timeout: 60_000,
+        },
+        "conversation-local",
+      );
+      expect(remoteSearchMock).toHaveBeenCalledWith({
+        limit: 40,
+        page_id: "local-page-1",
+        sort_order: "TIMESTAMP",
+        timestamp__gte: "2026-07-11T00:00:00.000Z",
+        timestamp__lt: "2026-07-12T00:00:00.000Z",
+      });
+      expect(callCloudProxyMock).not.toHaveBeenCalled();
+    });
+
+    it("uses default local options and normalizes a missing page", async () => {
+      useBackend(localBackend);
+      remoteSearchMock.mockResolvedValue(undefined);
+
+      await expect(
+        EventService.searchEvents("conversation-local"),
+      ).resolves.toEqual({ items: [], next_page_id: null });
+
+      expect(getAgentServerHttpClientOptionsMock).toHaveBeenCalledWith({
+        conversationUrl: undefined,
+        sessionApiKey: undefined,
+      });
+      expect(remoteSearchMock).toHaveBeenCalledWith({ limit: 100 });
+    });
+  });
+});

src/api/event-service/event-service.api.ts

@@ -0,0 +1,184 @@
+import { ConversationClient } from "@openhands/typescript-client/clients";
+import { RemoteEventsList } from "@openhands/typescript-client/events/remote-events-list";
+import { OpenHandsEvent } from "#/types/agent-server/core";
+import { buildHttpBaseUrl } from "#/utils/websocket-url";
+import { getActiveBackend } from "../backend-registry/active-store";
+import { callCloudProxy } from "../cloud/proxy";
+import {
+  getAgentServerClientOptions,
+  getAgentServerHttpClientOptions,
+} from "../agent-server-client-options";
+import type {
+  ConfirmationResponseRequest,
+  ConfirmationResponseResponse,
+  EventSearchOptions,
+  EventSearchPage,
+} from "./event-service.types";
+
+/**
+ * Cloud-mode REST calls are split between two upstream hosts (matching
+ * OpenHands' cloud frontend):
+ *
+ *   - **App API** (`backend.host`, default in `callCloudProxy`):
+ *     event *history* (`/api/v1/conversation/{id}/events/search`).
+ *     Persisted by the cloud backend — survives the runtime sandbox.
+ *
+ *   - **Runtime sandbox** (extracted from `conversation.conversation_url`
+ *     and passed as `hostOverride`): live runtime endpoints like
+ *     `/api/conversations/{id}/events/count` and
+ *     `/api/conversations/{id}/events/respond_to_confirmation`. Auth on
+ *     these endpoints is `X-Session-API-Key`, not `Authorization: Bearer`.
+ *
+ * App API calls go directly to the cloud backend with bearer auth. Runtime
+ * sandbox calls go through `/api/cloud-proxy`, which avoids depending on CORS
+ * for per-conversation runtime hosts.
+ *
+ * Local mode keeps the existing typescript-client path: it targets the
+ * conversation's host directly via typed client classes.
+ */
+class EventService {
+  static async respondToConfirmation(
+    conversationId: string,
+    conversationUrl: string,
+    request: ConfirmationResponseRequest,
+    sessionApiKey?: string | null,
+  ): Promise<ConfirmationResponseResponse> {
+    const active = getActiveBackend().backend;
+
+    if (active.kind === "cloud") {
+      return callCloudProxy<ConfirmationResponseResponse>({
+        backend: active,
+        method: "POST",
+        hostOverride: buildHttpBaseUrl(conversationUrl),
+        path: `/api/conversations/${conversationId}/events/respond_to_confirmation`,
+        body: request,
+        authMode: "session-api-key",
+        sessionApiKey,
+      });
+    }
+
+    return new ConversationClient(
+      getAgentServerClientOptions({
+        conversationUrl,
+        sessionApiKey,
+      }),
+    ).respondToConfirmation<ConfirmationResponseResponse>(
+      conversationId,
+      request,
+    );
+  }
+
+  static async getEventCount(
+    conversationId: string,
+    conversationUrl: string,
+    sessionApiKey?: string | null,
+  ): Promise<number> {
+    const active = getActiveBackend().backend;
+
+    if (active.kind === "cloud") {
+      return callCloudProxy<number>({
+        backend: active,
+        method: "GET",
+        hostOverride: buildHttpBaseUrl(conversationUrl),
+        path: `/api/conversations/${conversationId}/events/count`,
+        authMode: "session-api-key",
+        sessionApiKey,
+      });
+    }
+
+    return new ConversationClient(
+      getAgentServerClientOptions({
+        conversationUrl,
+        sessionApiKey,
+      }),
+    ).getEventCount(conversationId);
+  }
+
+  /**
+   * Search events for a conversation. Returns the raw page so callers can
+   * paginate (via `next_page_id`) and so REST-driven history loading can
+   * tell when there are no more older events to load.
+   */
+  static async searchEvents(
+    conversationId: string,
+    conversationUrl?: string | null,
+    sessionApiKey?: string | null,
+    options: EventSearchOptions = {},
+  ): Promise<EventSearchPage<OpenHandsEvent>> {
+    const active = getActiveBackend().backend;
+    const limit = options.limit ?? 100;
+
+    if (active.kind === "cloud") {
+      // Event *history* lives on the cloud App API, not the runtime
+      // sandbox. Path is singular `conversation` and v1-prefixed.
+      //
+      // Full pagination params (sort_order, page_id, timestamp filters)
+      // require the server-side fix from OpenHands/OpenHands#14399. If
+      // the cloud backend hasn't been updated yet, the timestamp filters
+      // trigger a 500 (str-vs-datetime comparison). We attempt the full
+      // request first and fall back to a limit-only request on failure.
+      const cloudLimit = Math.min(limit, 100);
+      const hasFilterParams = !!(
+        options.sortOrder ||
+        options.pageId ||
+        options.timestampGte ||
+        options.timestampLt
+      );
+
+      const params = new URLSearchParams();
+      params.set("limit", String(cloudLimit));
+      if (options.sortOrder) params.set("sort_order", options.sortOrder);
+      if (options.pageId) params.set("page_id", options.pageId);
+      if (options.timestampGte)
+        params.set("timestamp__gte", options.timestampGte);
+      if (options.timestampLt) params.set("timestamp__lt", options.timestampLt);
+
+      const doCloudSearch = (searchParams: URLSearchParams) =>
+        callCloudProxy<EventSearchPage<OpenHandsEvent>>({
+          backend: active,
+          method: "GET",
+          path: `/api/v1/conversation/${conversationId}/events/search?${searchParams.toString()}`,
+        });
+
+      try {
+        const data = await doCloudSearch(params);
+        return {
+          items: data?.items ?? [],
+          next_page_id: data?.next_page_id ?? null,
+        };
+      } catch (err) {
+        if (!hasFilterParams) throw err;
+        if (options.strictPagination) throw err;
+
+        // Server doesn't support timestamp filters yet — stop pagination
+        // by returning an empty page so the UI doesn't retry indefinitely.
+        // A limit-only fallback would return the same most-recent events
+        // already in the store, which get deduped but keep hasMore=true.
+        console.warn(
+          "[EventService] Cloud backend doesn't support pagination filters. " +
+            "Falling back to initial load only. " +
+            "Server needs OpenHands/OpenHands#14399.",
+        );
+        return { items: [], next_page_id: null };
+      }
+    }
+
+    const page = await new RemoteEventsList(
+      getAgentServerHttpClientOptions({ conversationUrl, sessionApiKey }),
+      conversationId,
+    ).search({
+      limit,
+      ...(options.pageId ? { page_id: options.pageId } : {}),
+      ...(options.sortOrder ? { sort_order: options.sortOrder } : {}),
+      ...(options.timestampGte ? { timestamp__gte: options.timestampGte } : {}),
+      ...(options.timestampLt ? { timestamp__lt: options.timestampLt } : {}),
+    });
+
+    return {
+      items: (page?.items ?? []) as OpenHandsEvent[],
+      next_page_id: page?.next_page_id ?? null,
+    };
+  }
+}
+
+export default EventService;

src/api/event-service/event-service.types.ts

@@ -0,0 +1,34 @@
+export interface ConfirmationResponseRequest {
+  accept: boolean;
+  reason?: string;
+}
+
+export interface ConfirmationResponseResponse {
+  success: boolean;
+}
+
+export type EventSortOrder = "TIMESTAMP" | "TIMESTAMP_DESC";
+
+export interface EventSearchOptions {
+  /** Maximum number of events to return per page (server caps at 100). */
+  limit?: number;
+  /** Page ID for pagination. */
+  pageId?: string;
+  /** Sort order for the underlying server query. */
+  sortOrder?: EventSortOrder;
+  /** Filter: event timestamp >= this value (ISO 8601). */
+  timestampGte?: string;
+  /** Filter: event timestamp < this value (ISO 8601). */
+  timestampLt?: string;
+  /**
+   * Surface unsupported cloud pagination instead of degrading to an empty
+   * page. Callers that require a complete result (such as transcript export)
+   * must set this so a partial history is never mistaken for exhaustion.
+   */
+  strictPagination?: boolean;
+}
+
+export interface EventSearchPage<TEvent> {
+  items: TEvent[];
+  next_page_id?: string | null;
+}

src/api/git-service/agent-server-git-service.api.ts

@@ -0,0 +1,282 @@
+import { isAxiosError } from "axios";
+import { RemoteWorkspace } from "@openhands/typescript-client/workspace/remote-workspace";
+import { mapAnyGitStatusToClientStatus } from "#/utils/git-status-mapper";
+import { buildHttpBaseUrl } from "#/utils/websocket-url";
+import type {
+  GitChange,
+  GitChangeDiff,
+  GitCommitsPage,
+} from "../open-hands.types";
+import { getActiveBackend } from "../backend-registry/active-store";
+import { callCloudProxy } from "../cloud/proxy";
+import { getAgentServerClientOptions } from "../agent-server-client-options";
+import { isSdkHttpStatusError } from "../agent-server-compatibility";
+
+interface AgentServerGitChange {
+  status: string;
+  path: string;
+}
+
+interface AgentServerGitCommit {
+  sha: string;
+  short_sha: string;
+  subject: string;
+  author: string;
+  timestamp: string;
+}
+
+interface AgentServerGitCommitsPage {
+  commits: AgentServerGitCommit[];
+  has_more: boolean;
+}
+
+/**
+ * Git operations for agent-server conversations.
+ *
+ * In **local** mode the runtime is reachable directly from the browser
+ * (it's `127.0.0.1:18000`); the SDK's `RemoteWorkspace` calls land
+ * fine. In **cloud** mode the runtime is at
+ * `*.prod-runtime.all-hands.dev`, which doesn't allow CORS from
+ * `localhost`. So cloud-mode calls hit the cloud API's
+ * `GET /api/v1/app-conversations/{id}/git/{changes,diff}` proxy
+ * endpoints instead — the server resolves the conversation's runtime
+ * and makes the hop itself with the sandbox's session API key, and the
+ * cloud API's CORS is permissive for bearer-token requests.
+ */
+
+/**
+ * The cloud runtime's `/api/git/{changes,diff}` endpoints prepend
+ * `/workspace/` to relative paths (so a relative arg like
+ * `workspace/project` becomes `/workspace/workspace/project` and 404s).
+ * `getGitPath` returns the local agent-server's relative convention by
+ * default; normalize to an absolute path before sending to the cloud
+ * runtime.
+ */
+function toAbsoluteRuntimePath(path: string): string {
+  return path.startsWith("/") ? path : `/${path}`;
+}
+
+/**
+ * GET an arbitrary runtime git endpoint in both backend modes. Local mode
+ * uses the SDK's public `HttpClient` (the typed `gitChanges`/`gitDiff`
+ * wrappers don't know the newer endpoints/params, and they re-wrap errors,
+ * dropping the `.status` needed for 404 feature-detection). Cloud mode goes
+ * through the generic cloud-proxy envelope with the sandbox's session API
+ * key — the same hop `executeCommand`/`downloadFile` use — so no dedicated
+ * cloud API endpoints are required.
+ */
+async function getFromRuntime<T>(
+  conversationUrl: string | null | undefined,
+  sessionApiKey: string | null | undefined,
+  apiPath: string,
+  params: { path: string } & Record<string, string>,
+): Promise<T> {
+  const active = getActiveBackend().backend;
+
+  if (active.kind === "cloud" && conversationUrl) {
+    const search = new URLSearchParams({
+      ...params,
+      path: toAbsoluteRuntimePath(params.path),
+    });
+    return callCloudProxy<T>({
+      backend: active,
+      method: "GET",
+      hostOverride: buildHttpBaseUrl(conversationUrl),
+      path: `${apiPath}?${search.toString()}`,
+      authMode: "session-api-key",
+      sessionApiKey: sessionApiKey ?? undefined,
+    });
+  }
+
+  const response = await new RemoteWorkspace(
+    getAgentServerClientOptions({ conversationUrl, sessionApiKey }),
+  ).client.get<T>(apiPath, { params });
+  return response.data;
+}
+
+/**
+ * The commit endpoints are newer than some deployed agent servers. A 404
+ * (route absent) means "server too old" — callers hide the commits section
+ * instead of surfacing an error. Local calls and cloud-proxy calls (via the
+ * shared TypeScript client) both throw the SDK's `HttpError`; the axios
+ * check is kept as a safety net for axios-shaped errors.
+ */
+function isEndpointMissingError(error: unknown): boolean {
+  return (
+    isSdkHttpStatusError(error, 404) ||
+    (isAxiosError(error) && error.response?.status === 404)
+  );
+}
+
+class AgentServerGitService {
+  static async getGitChanges(
+    conversationId: string,
+    conversationUrl: string | null | undefined,
+    sessionApiKey: string | null | undefined,
+    path: string,
+  ): Promise<GitChange[]> {
+    const active = getActiveBackend().backend;
+
+    if (active.kind === "cloud" && conversationId) {
+      const params = new URLSearchParams();
+      params.set("path", toAbsoluteRuntimePath(path));
+      const data = await callCloudProxy<AgentServerGitChange[]>({
+        backend: active,
+        method: "GET",
+        path: `/api/v1/app-conversations/${conversationId}/git/changes?${params.toString()}`,
+      });
+      if (!Array.isArray(data)) {
+        throw new Error(
+          "Invalid response from runtime - runtime may be unavailable",
+        );
+      }
+      return data.map((change) => ({
+        status: mapAnyGitStatusToClientStatus(
+          String(change.status) as Parameters<
+            typeof mapAnyGitStatusToClientStatus
+          >[0],
+        ),
+        path: change.path,
+      }));
+    }
+
+    // No `ref`: let the server auto-detect the base (origin branch /
+    // merge-base), so changes the agent has already committed still show
+    // up. `ref: "HEAD"` would go blank after every `git commit` — and the
+    // cloud-proxy branch above already omits `ref`.
+    const changes = await new RemoteWorkspace(
+      getAgentServerClientOptions({ conversationUrl, sessionApiKey }),
+    ).gitChanges(path);
+
+    if (!Array.isArray(changes)) {
+      throw new Error(
+        "Invalid response from runtime - runtime may be unavailable",
+      );
+    }
+
+    return changes.map((change) => ({
+      status: mapAnyGitStatusToClientStatus(
+        String(change.status) as Parameters<
+          typeof mapAnyGitStatusToClientStatus
+        >[0],
+      ),
+      path: change.path,
+    }));
+  }
+
+  /**
+   * List the conversation's commits (display-base..HEAD, newest first).
+   * Resolves to `null` when the agent server predates the endpoint (404),
+   * so callers can hide the commits section instead of erroring.
+   */
+  static async getGitCommits(
+    conversationUrl: string | null | undefined,
+    sessionApiKey: string | null | undefined,
+    path: string,
+    limit = 50,
+  ): Promise<GitCommitsPage | null> {
+    try {
+      const page = await getFromRuntime<AgentServerGitCommitsPage>(
+        conversationUrl,
+        sessionApiKey,
+        "/api/git/commits",
+        { path, limit: String(limit) },
+      );
+      return {
+        commits: (page?.commits ?? []).map((commit) => ({
+          sha: commit.sha,
+          shortSha: commit.short_sha,
+          subject: commit.subject,
+          author: commit.author,
+          timestamp: commit.timestamp,
+        })),
+        hasMore: Boolean(page?.has_more),
+      };
+    } catch (error) {
+      if (isEndpointMissingError(error)) return null;
+      throw error;
+    }
+  }
+
+  /** Files changed by a single commit (vs its first parent). */
+  static async getCommitChanges(
+    conversationUrl: string | null | undefined,
+    sessionApiKey: string | null | undefined,
+    path: string,
+    sha: string,
+  ): Promise<GitChange[]> {
+    const changes = await getFromRuntime<AgentServerGitChange[]>(
+      conversationUrl,
+      sessionApiKey,
+      `/api/git/commits/${encodeURIComponent(sha)}/changes`,
+      { path },
+    );
+
+    if (!Array.isArray(changes)) {
+      throw new Error(
+        "Invalid response from runtime - runtime may be unavailable",
+      );
+    }
+
+    return changes.map((change) => ({
+      status: mapAnyGitStatusToClientStatus(
+        String(change.status) as Parameters<
+          typeof mapAnyGitStatusToClientStatus
+        >[0],
+      ),
+      path: change.path,
+    }));
+  }
+
+  static async getGitChangeDiff(
+    conversationId: string,
+    conversationUrl: string | null | undefined,
+    sessionApiKey: string | null | undefined,
+    path: string,
+    commit?: string,
+  ): Promise<GitChangeDiff> {
+    if (commit) {
+      // Per-commit diff: both sides come from git objects on the server,
+      // so files the commit deleted still render.
+      const commitDiff = await getFromRuntime<
+        GitChangeDiff & { diff?: string }
+      >(conversationUrl, sessionApiKey, "/api/git/diff", { path, commit });
+      return {
+        modified: commitDiff?.modified ?? "",
+        original: commitDiff?.original ?? "",
+        ...(commitDiff?.diff ? { diff: commitDiff.diff } : {}),
+      } as GitChangeDiff;
+    }
+
+    const active = getActiveBackend().backend;
+
+    if (active.kind === "cloud" && conversationId) {
+      const params = new URLSearchParams();
+      params.set("path", toAbsoluteRuntimePath(path));
+      const diff = await callCloudProxy<GitChangeDiff & { diff?: string }>({
+        backend: active,
+        method: "GET",
+        path: `/api/v1/app-conversations/${conversationId}/git/diff?${params.toString()}`,
+      });
+      return {
+        modified: diff?.modified ?? "",
+        original: diff?.original ?? "",
+        ...(diff?.diff ? { diff: diff.diff } : {}),
+      } as GitChangeDiff;
+    }
+
+    // No `ref` for the same reason as getGitChanges: the base must match
+    // the one the change list was computed against.
+    const diff = (await new RemoteWorkspace(
+      getAgentServerClientOptions({ conversationUrl, sessionApiKey }),
+    ).gitDiff(path)) as GitChangeDiff & { diff?: string };
+
+    return {
+      modified: diff.modified ?? "",
+      original: diff.original ?? "",
+      ...(diff.diff ? { diff: diff.diff } : {}),
+    } as GitChangeDiff;
+  }
+}
+
+export default AgentServerGitService;

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

@@ -0,0 +1,178 @@
+import { RemoteWorkspace } from "@openhands/typescript-client/workspace/remote-workspace";
+import { RepositoryPage, BranchPage, InstallationPage } from "#/types/git";
+import { Provider } from "#/types/settings";
+import { GitChange, GitChangeDiff } from "../open-hands.types";
+import AgentServerConversationService from "../conversation-service/agent-server-conversation-service.api";
+import { getAgentServerClientOptions } from "../agent-server-client-options";
+import { mapAnyGitStatusToClientStatus } from "#/utils/git-status-mapper";
+import { getActiveBackend } from "../backend-registry/active-store";
+import {
+  getCloudInstallations,
+  getCloudRepositoryBranches,
+  searchCloudRepositories,
+} from "../cloud/git-service.api";
+
+const safeProvider = (value: string): Provider => value as Provider;
+
+const isCloudActive = () => getActiveBackend().backend.kind === "cloud";
+
+/**
+ * Guard against null/undefined provider values that would result in
+ * invalid API requests (e.g., "?provider=undefined"). Returns true
+ * if the provider is falsy and the request should be skipped.
+ */
+const isInvalidProvider = (provider: string | null | undefined): boolean =>
+  !provider || provider === "undefined" || provider === "null";
+
+const EMPTY_REPOSITORY_PAGE: RepositoryPage = { items: [], next_page_id: null };
+const EMPTY_BRANCH_PAGE: BranchPage = { items: [], next_page_id: null };
+const EMPTY_INSTALLATION_PAGE: InstallationPage = {
+  items: [],
+  next_page_id: null,
+};
+
+class GitService {
+  static async searchGitRepositories(
+    query: string,
+    provider: string,
+    limit = 100,
+    pageId?: string,
+    installationId?: string,
+  ): Promise<RepositoryPage> {
+    if (isInvalidProvider(provider) || !isCloudActive()) {
+      return EMPTY_REPOSITORY_PAGE;
+    }
+    return searchCloudRepositories({
+      provider: safeProvider(provider),
+      query: query || undefined,
+      limit,
+      pageId,
+      installationId,
+    });
+  }
+
+  static async retrieveUserGitRepositories(
+    provider: string,
+    pageId?: string,
+    limit = 30,
+    installationId?: string,
+  ): Promise<RepositoryPage> {
+    if (isInvalidProvider(provider) || !isCloudActive()) {
+      return EMPTY_REPOSITORY_PAGE;
+    }
+    return searchCloudRepositories({
+      provider: safeProvider(provider),
+      limit,
+      pageId,
+      installationId,
+    });
+  }
+
+  static async retrieveInstallationRepositories(
+    provider: string,
+    installationIndex: number,
+    installations: string[],
+    pageId?: string,
+    limit = 30,
+  ): Promise<RepositoryPage> {
+    if (isInvalidProvider(provider) || !isCloudActive()) {
+      return EMPTY_REPOSITORY_PAGE;
+    }
+    const installationId = installations[installationIndex];
+    if (!installationId) return EMPTY_REPOSITORY_PAGE;
+    return searchCloudRepositories({
+      provider: safeProvider(provider),
+      installationId,
+      limit,
+      pageId,
+    });
+  }
+
+  static async getRepositoryBranches(
+    repository: string,
+    provider: string,
+    query: string = "",
+    pageId?: string,
+    limit = 30,
+  ): Promise<BranchPage> {
+    if (isInvalidProvider(provider) || !isCloudActive()) {
+      return EMPTY_BRANCH_PAGE;
+    }
+    return getCloudRepositoryBranches({
+      provider: safeProvider(provider),
+      repository,
+      query: query || undefined,
+      pageId,
+      limit,
+    });
+  }
+
+  static async searchRepositoryBranches(
+    repository: string,
+    provider: string,
+    query: string,
+    pageId?: string,
+    limit = 30,
+  ): Promise<BranchPage> {
+    if (isInvalidProvider(provider) || !isCloudActive()) {
+      return EMPTY_BRANCH_PAGE;
+    }
+    return getCloudRepositoryBranches({
+      provider: safeProvider(provider),
+      repository,
+      query,
+      pageId,
+      limit,
+    });
+  }
+
+  static async getUserInstallations(
+    provider: string,
+    pageId?: string,
+    limit = 100,
+  ): Promise<InstallationPage> {
+    if (isInvalidProvider(provider) || !isCloudActive()) {
+      return EMPTY_INSTALLATION_PAGE;
+    }
+    return getCloudInstallations({
+      provider: safeProvider(provider),
+      pageId,
+      limit,
+    });
+  }
+
+  static async getGitChanges(conversationId: string): Promise<GitChange[]> {
+    const workingDir =
+      await AgentServerConversationService.resolveConversationWorkingDir(
+        conversationId,
+      );
+    const changes = await new RemoteWorkspace(
+      getAgentServerClientOptions({ workingDir }),
+    ).gitChanges(workingDir);
+
+    return changes.map((change) => ({
+      path: change.path,
+      status: mapAnyGitStatusToClientStatus(
+        String(change.status) as Parameters<
+          typeof mapAnyGitStatusToClientStatus
+        >[0],
+      ),
+    }));
+  }
+
+  static async getGitChangeDiff(
+    _conversationId: string,
+    path: string,
+  ): Promise<GitChangeDiff> {
+    const diff = await new RemoteWorkspace(
+      getAgentServerClientOptions(),
+    ).gitDiff(path);
+
+    return {
+      modified: diff.modified ?? "",
+      original: diff.original ?? "",
+    };
+  }
+}
+
+export default GitService;

src/api/mcp-health/mcp-health-store.ts

@@ -0,0 +1,79 @@
+import type { McpServerHealth } from "#/types/mcp-health";
+
+type Listener = () => void;
+
+export type McpHealthMap = Record<string, McpServerHealth>;
+
+/**
+ * In-memory MCP connection-health store, keyed by
+ * `getMcpServerHealthKey(server)`. Mirrors the module-store shape of
+ * `#/api/backend-registry/health-store` but is deliberately NOT persisted:
+ * a health verdict is only as fresh as its probe, so a page reload resets
+ * every server to "unchecked" instead of resurrecting a possibly-stale
+ * "healthy".
+ */
+let healthMap: McpHealthMap = {};
+const listeners = new Set<Listener>();
+let nextCheckId = 1;
+
+function commit(next: McpHealthMap): void {
+  healthMap = next;
+  listeners.forEach((listener) => listener());
+}
+
+export function getMcpHealthSnapshot(): McpHealthMap {
+  return healthMap;
+}
+
+export function subscribeMcpHealth(listener: Listener): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** Mark a probe as in flight and return its id for `resolveMcpHealthCheck`. */
+export function beginMcpHealthCheck(key: string): number {
+  const checkId = nextCheckId;
+  nextCheckId += 1;
+  commit({ ...healthMap, [key]: { status: "checking", checkId } });
+  return checkId;
+}
+
+/**
+ * Commit a probe result, but only while the entry is still the `checking`
+ * state that probe created. A slow older probe can never overwrite a newer
+ * probe's result, and a probe whose server was edited, deleted, or reseeded
+ * mid-flight (entry cleared or replaced) is silently dropped — a stale
+ * check can never land a false verdict.
+ */
+export function resolveMcpHealthCheck(
+  key: string,
+  checkId: number,
+  health: McpServerHealth,
+): void {
+  const current = healthMap[key];
+  if (current?.status !== "checking" || current.checkId !== checkId) {
+    return;
+  }
+  commit({ ...healthMap, [key]: health });
+}
+
+/** Unconditional write — used to seed health from a pre-save test result. */
+export function setMcpServerHealth(key: string, health: McpServerHealth): void {
+  commit({ ...healthMap, [key]: health });
+}
+
+/** Drop the entry (back to "unchecked") — used when a server changes or is deleted. */
+export function clearMcpServerHealth(key: string): void {
+  if (!(key in healthMap)) return;
+  const { [key]: _removed, ...rest } = healthMap;
+  commit(rest);
+}
+
+/** Test-only: reset state and listeners. */
+export function __resetMcpHealthStoreForTests(): void {
+  healthMap = {};
+  listeners.clear();
+  nextCheckId = 1;
+}

src/api/mcp-health/probe-mcp-server-health.ts

@@ -0,0 +1,135 @@
+import McpService from "#/api/mcp-service/mcp-service.api";
+import type { McpServerHealth } from "#/types/mcp-health";
+import type {
+  ExtendedMCPTestResponse,
+  MCPServerConfig,
+} from "#/types/mcp-server";
+import { getCredentialValidationForServer } from "#/utils/mcp-credential-validation";
+import { getMcpServerHealthKey } from "#/utils/mcp-server-health-key";
+import { redactMcpSecrets } from "#/utils/redact-mcp-secrets";
+import {
+  beginMcpHealthCheck,
+  resolveMcpHealthCheck,
+  setMcpServerHealth,
+} from "./mcp-health-store";
+
+/**
+ * Conservative auth-failure sniffing for hosted servers that reject a bad
+ * token at the HTTP handshake: the backend can only classify those as
+ * `connection`/`unknown` (the MCP connection itself failed), but the
+ * guidance the user needs is the credentials one.
+ */
+const AUTH_FAILURE_TEXT =
+  /\b(401|403)\b|unauthorized|forbidden|invalid[ _-]?(token|credentials?|api[ _-]?key)/i;
+
+function failedHealth(
+  server: MCPServerConfig,
+  error: unknown,
+): McpServerHealth {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    status: "failed",
+    kind: "unknown",
+    error: redactMcpSecrets(message, server),
+    checkedAt: Date.now(),
+  };
+}
+
+/**
+ * Map a test/OAuth probe response (already secret-redacted and
+ * credential-interpreted by `McpService`) to a card health state.
+ *
+ * `verified` requires the catalog entry's read-only probe tool to have been
+ * advertised AND invoked without error; everything else that connected is
+ * `connectivity-only` — truthfully labeled, never silently upgraded.
+ */
+export function interpretMcpTestResponse(
+  server: MCPServerConfig,
+  response: ExtendedMCPTestResponse,
+): McpServerHealth {
+  const checkedAt = Date.now();
+  if (!response.ok) {
+    const kind =
+      (response.error_kind === "connection" ||
+        response.error_kind === "unknown") &&
+      AUTH_FAILURE_TEXT.test(response.error)
+        ? "credentials"
+        : response.error_kind;
+    return { status: "failed", kind, error: response.error, checkedAt };
+  }
+  const validation = getCredentialValidationForServer(server);
+  const verified =
+    !!validation &&
+    response.tools.includes(validation.toolCall.name) &&
+    !!response.tool_result &&
+    !response.tool_result.is_error;
+  return {
+    status: "healthy",
+    verification: verified ? "verified" : "connectivity-only",
+    toolCount: response.tools.length,
+    checkedAt,
+  };
+}
+
+/** Run the non-mutating connection probe and publish the result. */
+export async function probeMcpServerHealth(
+  server: MCPServerConfig,
+): Promise<void> {
+  const key = getMcpServerHealthKey(server);
+  const checkId = beginMcpHealthCheck(key);
+  let health: McpServerHealth;
+  try {
+    const response = await McpService.testServer(server);
+    health = interpretMcpTestResponse(server, response);
+  } catch (error) {
+    health = failedHealth(server, error);
+  }
+  resolveMcpHealthCheck(key, checkId, health);
+}
+
+/**
+ * Run the interactive OAuth authorization probe and publish the result.
+ * Returns the raw response (null on transport error) so the caller can
+ * persist a refreshed `oauth_state`.
+ */
+export async function reauthorizeMcpServerHealth(
+  server: MCPServerConfig,
+): Promise<ExtendedMCPTestResponse | null> {
+  const key = getMcpServerHealthKey(server);
+  const checkId = beginMcpHealthCheck(key);
+  try {
+    const response = await McpService.authorizeOAuth(server);
+    resolveMcpHealthCheck(
+      key,
+      checkId,
+      interpretMcpTestResponse(server, response),
+    );
+    return response;
+  } catch (error) {
+    resolveMcpHealthCheck(key, checkId, failedHealth(server, error));
+    return null;
+  }
+}
+
+/**
+ * Publish a just-saved server's health from the pre-save test result the
+ * install/edit flow already produced (same config, moments earlier), so its
+ * card shows a verdict immediately without a second probe.
+ *
+ * `otherServers` are the servers whose health must NOT be overwritten —
+ * callers pass the pre-save list, excluding the server being saved. When a
+ * same-shape duplicate exists (health keys exclude secret values, so two
+ * installs of one catalog entry can collide until the save suffixes the
+ * name), the seed is skipped and the new card simply starts "unchecked".
+ */
+export function seedMcpServerHealth(
+  server: MCPServerConfig,
+  response: ExtendedMCPTestResponse,
+  otherServers: MCPServerConfig[],
+): void {
+  const key = getMcpServerHealthKey(server);
+  if (otherServers.some((other) => getMcpServerHealthKey(other) === key)) {
+    return;
+  }
+  setMcpServerHealth(key, interpretMcpTestResponse(server, response));
+}

src/api/mcp-service/mcp-redacted-credentials.test.ts

@@ -0,0 +1,308 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import SettingsService, {
+  type SettingsApiResponse,
+} from "#/api/settings-service/settings-service.api";
+import { substituteRedactedMcpCredentials } from "./mcp-redacted-credentials";
+import { REDACTED_MCP_SECRET_VALUE } from "#/utils/mcp-config";
+
+describe("substituteRedactedMcpCredentials", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("preserves encrypted stdio env when the server is renamed", async () => {
+    // Regression: renaming a stdio server left a redacted env value unchanged,
+    // so the lookup by the new display name missed the stored entry and the
+    // literal redaction placeholder overwrote the stored encrypted secret.
+    vi.spyOn(SettingsService, "fetchSettingsFromApi").mockResolvedValue({
+      agent_settings: {
+        mcp_config: {
+          "old-name": {
+            command: "npx",
+            env: { API_KEY: "gAAAAA-encrypted-api-key" },
+          },
+        },
+      },
+    } as unknown as SettingsApiResponse);
+
+    const result = await substituteRedactedMcpCredentials({
+      id: "old-name",
+      type: "stdio",
+      name: "new-name",
+      command: "npx",
+      env: { API_KEY: REDACTED_MCP_SECRET_VALUE },
+    });
+
+    expect(result.env).toEqual({ API_KEY: "gAAAAA-encrypted-api-key" });
+    expect(result.name).toBe("new-name");
+  });
+
+  it("does not restore another server's secret when renamed onto an existing name", async () => {
+    // Renaming "alpha" onto "beta"'s name must still resolve alpha's stored
+    // entry by stable key, not beta's entry.
+    vi.spyOn(SettingsService, "fetchSettingsFromApi").mockResolvedValue({
+      agent_settings: {
+        mcp_config: {
+          alpha: { command: "npx", env: { TOKEN: "gAAAAA-alpha-token" } },
+          beta: { command: "npx", env: { TOKEN: "gAAAAA-beta-token" } },
+        },
+      },
+    } as unknown as SettingsApiResponse);
+
+    const result = await substituteRedactedMcpCredentials({
+      id: "alpha",
+      type: "stdio",
+      name: "beta",
+      command: "npx",
+      env: { TOKEN: REDACTED_MCP_SECRET_VALUE },
+    });
+
+    expect(result.env).toEqual({ TOKEN: "gAAAAA-alpha-token" });
+  });
+
+  it("leaves typed (non-redacted) env values untouched", async () => {
+    vi.spyOn(SettingsService, "fetchSettingsFromApi").mockResolvedValue({
+      agent_settings: {
+        mcp_config: {
+          "my-server": {
+            command: "npx",
+            env: { API_KEY: "gAAAAA-encrypted", REGION: "us-east-1" },
+          },
+        },
+      },
+    } as unknown as SettingsApiResponse);
+
+    const result = await substituteRedactedMcpCredentials({
+      id: "my-server",
+      type: "stdio",
+      name: "my-server",
+      command: "npx",
+      env: {
+        API_KEY: REDACTED_MCP_SECRET_VALUE,
+        REGION: "eu-west-1",
+      },
+    });
+
+    expect(result.env).toEqual({
+      API_KEY: "gAAAAA-encrypted",
+      REGION: "eu-west-1",
+    });
+  });
+
+  it("returns the server unchanged when no env value is redacted", async () => {
+    const server = {
+      id: "stdio-0",
+      type: "stdio" as const,
+      name: "my-server",
+      command: "npx",
+      env: { API_KEY: "plaintext" },
+    };
+
+    const result = await substituteRedactedMcpCredentials(server);
+
+    expect(result).toBe(server);
+    expect(SettingsService.fetchSettingsFromApi).not.toHaveBeenCalled();
+  });
+
+  it("keeps the placeholder when the stored stdio entry is missing", async () => {
+    vi.spyOn(SettingsService, "fetchSettingsFromApi").mockResolvedValue({
+      agent_settings: { mcp_config: {} },
+    } as unknown as SettingsApiResponse);
+
+    const result = await substituteRedactedMcpCredentials({
+      id: "stdio-0",
+      type: "stdio",
+      name: "new-name",
+      command: "npx",
+      env: { API_KEY: REDACTED_MCP_SECRET_VALUE },
+    });
+
+    expect(result.env).toEqual({ API_KEY: REDACTED_MCP_SECRET_VALUE });
+  });
+
+  it("replaces redacted OAuth state with the encrypted stored subtree", async () => {
+    vi.spyOn(SettingsService, "fetchSettingsFromApi").mockResolvedValue({
+      agent_settings: {
+        mcp_config: {
+          "superhuman-mail": {
+            url: "https://mcp.mail.superhuman.com/mcp",
+            auth: {
+              strategy: "oauth2",
+              state: {
+                tokens: {
+                  access_token: "gAAAAA-encrypted-access-token",
+                  refresh_token: "gAAAAA-encrypted-refresh-token",
+                },
+                client_info: {
+                  client_id: "superhuman-client",
+                  client_secret: "gAAAAA-encrypted-client-secret",
+                },
+              },
+            },
+          },
+        },
+      },
+    } as unknown as SettingsApiResponse);
+
+    const result = await substituteRedactedMcpCredentials({
+      id: "superhuman-mail",
+      type: "shttp",
+      name: "superhuman-mail",
+      url: "https://mcp.mail.superhuman.com/mcp",
+      auth: {
+        strategy: "oauth2",
+        state: {
+          tokens: {
+            access_token: REDACTED_MCP_SECRET_VALUE,
+            refresh_token: REDACTED_MCP_SECRET_VALUE,
+          },
+          client_info: {
+            client_id: "superhuman-client",
+            client_secret: REDACTED_MCP_SECRET_VALUE,
+          },
+        },
+      },
+    });
+
+    expect(result.auth).toEqual({
+      strategy: "oauth2",
+      state: {
+        tokens: {
+          access_token: "gAAAAA-encrypted-access-token",
+          refresh_token: "gAAAAA-encrypted-refresh-token",
+        },
+        client_info: {
+          client_id: "superhuman-client",
+          client_secret: "gAAAAA-encrypted-client-secret",
+        },
+      },
+    });
+  });
+
+  it("preserves fresh OAuth edits while substituting only redacted leaves", async () => {
+    vi.spyOn(SettingsService, "fetchSettingsFromApi").mockResolvedValue({
+      agent_settings: {
+        mcp_config: {
+          "superhuman-mail": {
+            url: "https://mcp.mail.superhuman.com/mcp",
+            auth: {
+              strategy: "oauth2",
+              state: {
+                tokens: {
+                  access_token: "gAAAAA-encrypted-access-token",
+                  refresh_token: "gAAAAA-encrypted-refresh-token",
+                },
+                client_info: {
+                  client_id: "old-client-id",
+                  client_secret: "gAAAAA-encrypted-client-secret",
+                },
+              },
+            },
+          },
+        },
+      },
+    } as unknown as SettingsApiResponse);
+
+    const result = await substituteRedactedMcpCredentials({
+      id: "superhuman-mail",
+      type: "shttp",
+      name: "superhuman-mail",
+      url: "https://mcp.mail.superhuman.com/mcp",
+      auth: {
+        strategy: "oauth2",
+        state: {
+          tokens: {
+            access_token: REDACTED_MCP_SECRET_VALUE,
+            refresh_token: REDACTED_MCP_SECRET_VALUE,
+          },
+          client_info: {
+            client_id: "new-client-id",
+            client_secret: REDACTED_MCP_SECRET_VALUE,
+          },
+        },
+      },
+    });
+
+    expect(result.auth).toEqual({
+      strategy: "oauth2",
+      state: {
+        tokens: {
+          access_token: "gAAAAA-encrypted-access-token",
+          refresh_token: "gAAAAA-encrypted-refresh-token",
+        },
+        client_info: {
+          client_id: "new-client-id",
+          client_secret: "gAAAAA-encrypted-client-secret",
+        },
+      },
+    });
+  });
+
+  it("preserves fresh header-auth edits while substituting only redacted leaves", async () => {
+    vi.spyOn(SettingsService, "fetchSettingsFromApi").mockResolvedValue({
+      agent_settings: {
+        mcp_config: {
+          mail: {
+            url: "https://mail.example/mcp",
+            auth: {
+              strategy: "header",
+              headers: {
+                "X-API-Key": "gAAAAA-encrypted-api-key",
+                "X-Region": "us-east-1",
+              },
+            },
+          },
+        },
+      },
+    } as unknown as SettingsApiResponse);
+
+    const result = await substituteRedactedMcpCredentials({
+      id: "mail",
+      type: "shttp",
+      name: "mail",
+      url: "https://mail.example/mcp",
+      auth: {
+        strategy: "header",
+        headers: {
+          "X-API-Key": REDACTED_MCP_SECRET_VALUE,
+          "X-Region": "eu-west-1",
+        },
+      },
+    });
+
+    expect(result.auth).toEqual({
+      strategy: "header",
+      headers: {
+        "X-API-Key": "gAAAAA-encrypted-api-key",
+        "X-Region": "eu-west-1",
+      },
+    });
+  });
+
+  it("replaces redacted raw remote headers with encrypted stored values", async () => {
+    vi.spyOn(SettingsService, "fetchSettingsFromApi").mockResolvedValue({
+      agent_settings: {
+        mcp_config: {
+          github: {
+            url: "https://github.example/mcp",
+            headers: {
+              Authorization: "Bearer gAAAAA-encrypted-github-token",
+            },
+          },
+        },
+      },
+    } as unknown as SettingsApiResponse);
+
+    const result = await substituteRedactedMcpCredentials({
+      id: "github",
+      type: "shttp",
+      name: "github",
+      url: "https://github.example/mcp",
+      headers: { Authorization: REDACTED_MCP_SECRET_VALUE },
+    });
+
+    expect(result.headers).toEqual({
+      Authorization: "Bearer gAAAAA-encrypted-github-token",
+    });
+  });
+});

src/api/mcp-service/mcp-redacted-credentials.ts

@@ -0,0 +1,138 @@
+import SettingsService from "#/api/settings-service/settings-service.api";
+import { isMcpAuthCredential } from "#/types/mcp-auth";
+import type { MCPServerConfig } from "#/types/mcp-server";
+import {
+  hasRedactedMcpSecretLeaf,
+  REDACTED_MCP_SECRET_VALUE,
+} from "#/utils/mcp-config";
+
+type StoredMcpServer = {
+  url?: unknown;
+  transport?: unknown;
+  env?: unknown;
+  auth?: unknown;
+  headers?: unknown;
+};
+
+type StoredMcpConfig = Record<string, StoredMcpServer>;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  !!value && typeof value === "object" && !Array.isArray(value);
+
+const stringRecord = (value: unknown): Record<string, string> | undefined => {
+  if (!isRecord(value)) return undefined;
+  const entries = Object.entries(value).filter(
+    (entry): entry is [string, string] => typeof entry[1] === "string",
+  );
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+};
+
+const hasRedactedValue = (values: Record<string, string> | undefined) =>
+  !!values &&
+  Object.values(values).some((value) => value === REDACTED_MCP_SECRET_VALUE);
+
+/**
+ * Recursively replace only the redacted display placeholders inside
+ * ``submitted`` with the corresponding stored (encrypted) leaf. Fresh
+ * non-redacted edits and untouched structure are preserved verbatim, so a
+ * probe request exercises the server exactly as it will be persisted.
+ */
+function substituteRedactedLeaves<T>(submitted: T, stored: unknown): T {
+  if (!isRecord(submitted)) return submitted;
+
+  const storedRecord = isRecord(stored) ? stored : {};
+  const merged: Record<string, unknown> = { ...submitted };
+  for (const [key, value] of Object.entries(submitted)) {
+    if (value === REDACTED_MCP_SECRET_VALUE) {
+      const storedValue = storedRecord[key];
+      if (
+        typeof storedValue === "string" &&
+        storedValue !== REDACTED_MCP_SECRET_VALUE
+      ) {
+        merged[key] = storedValue;
+      }
+    } else if (isRecord(value)) {
+      merged[key] = substituteRedactedLeaves(value, storedRecord[key]);
+    }
+  }
+  return merged as T;
+}
+
+const findStoredServer = (
+  server: MCPServerConfig,
+  storedServers: StoredMcpConfig,
+): StoredMcpServer | undefined => storedServers[server.id];
+
+async function fetchEncryptedStoredServer(
+  server: MCPServerConfig,
+): Promise<StoredMcpServer | undefined> {
+  const response = await SettingsService.fetchSettingsFromApi("encrypted");
+  const mcpConfig = response.agent_settings?.mcp_config;
+  if (!isRecord(mcpConfig)) {
+    return undefined;
+  }
+  return findStoredServer(server, mcpConfig as StoredMcpConfig);
+}
+
+/**
+ * The MCP editor sees redacted settings (`**********`). When the user leaves
+ * a secret unchanged, replace that placeholder with the stored encrypted
+ * env/header/OAuth state value so a connectivity test can exercise the real
+ * credential without exposing plaintext in the browser. Persistence never
+ * calls this helper; sparse settings patches omit unchanged secrets.
+ */
+export async function substituteRedactedMcpCredentials(
+  server: MCPServerConfig,
+): Promise<MCPServerConfig> {
+  const redactedStdioEnv =
+    server.type === "stdio" && hasRedactedValue(server.env);
+  const redactedRemoteAuth =
+    (server.type === "sse" || server.type === "shttp") &&
+    hasRedactedMcpSecretLeaf(server.auth);
+  const redactedRemoteHeaders =
+    (server.type === "sse" || server.type === "shttp") &&
+    hasRedactedValue(server.headers);
+
+  if (!redactedStdioEnv && !redactedRemoteAuth && !redactedRemoteHeaders) {
+    return server;
+  }
+
+  try {
+    const stored = await fetchEncryptedStoredServer(server);
+    if (!stored) return server;
+
+    if (redactedStdioEnv) {
+      const storedEnv = stringRecord(stored.env) ?? {};
+      const env = Object.fromEntries(
+        Object.entries(server.env ?? {}).map(([key, value]) => [
+          key,
+          value === REDACTED_MCP_SECRET_VALUE &&
+          typeof storedEnv[key] === "string"
+            ? storedEnv[key]
+            : value,
+        ]),
+      );
+      return { ...server, env };
+    }
+
+    const nextServer = { ...server };
+    if (redactedRemoteAuth && isMcpAuthCredential(stored.auth)) {
+      nextServer.auth = substituteRedactedLeaves(server.auth, stored.auth);
+    }
+    if (redactedRemoteHeaders) {
+      const storedHeaders = stringRecord(stored.headers) ?? {};
+      nextServer.headers = Object.fromEntries(
+        Object.entries(server.headers ?? {}).map(([key, value]) => [
+          key,
+          value === REDACTED_MCP_SECRET_VALUE &&
+          typeof storedHeaders[key] === "string"
+            ? storedHeaders[key]
+            : value,
+        ]),
+      );
+    }
+    return nextServer;
+  } catch {
+    return server;
+  }
+}

src/api/mcp-service/mcp-service.api.test.ts

@@ -0,0 +1,238 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { MCPClient } from "@openhands/typescript-client/clients";
+import {
+  setActiveSelection,
+  setRegisteredBackends,
+} from "../backend-registry/active-store";
+import SettingsService from "../settings-service/settings-service.api";
+import McpService from "./mcp-service.api";
+import { REDACTED_MCP_SECRET_VALUE } from "#/utils/mcp-config";
+
+vi.mock("@openhands/typescript-client/clients", () => ({
+  MCPClient: vi.fn(),
+}));
+
+const testServer = vi.fn();
+const startOAuth = vi.fn();
+const getOAuthStatus = vi.fn();
+const submitOAuthCallback = vi.fn();
+const close = vi.fn();
+
+const encryptedAuth = "gAAAAAencrypted-auth";
+
+describe("McpService.testServer", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    setRegisteredBackends([
+      {
+        id: "local",
+        name: "Local",
+        host: "http://127.0.0.1:8001",
+        apiKey: "session-key",
+        kind: "local",
+      },
+    ]);
+    setActiveSelection({ backendId: "local", orgId: null });
+    vi.mocked(MCPClient).mockImplementation(function MockMCPClient() {
+      return {
+        testServer,
+        startOAuth,
+        getOAuthStatus,
+        submitOAuthCallback,
+        close,
+      } as unknown as MCPClient;
+    } as unknown as typeof MCPClient);
+    testServer.mockResolvedValue({ ok: true, tools: [] });
+    startOAuth.mockResolvedValue({
+      ok: true,
+      job_id: "job-1",
+      authorization_url: "https://auth.example/authorize",
+    });
+    getOAuthStatus.mockResolvedValue({
+      ok: true,
+      status: "succeeded",
+      job_id: "job-1",
+      tools: ["search_mail"],
+    });
+    submitOAuthCallback.mockResolvedValue({
+      ok: true,
+      status: "succeeded",
+      job_id: "job-1",
+      tools: ["search_mail"],
+    });
+  });
+
+  it("tests stored remote MCP credentials as encrypted auth, not redacted text", async () => {
+    vi.spyOn(SettingsService, "fetchSettingsFromApi").mockResolvedValue({
+      llm_api_key_is_set: false,
+      conversation_settings: {},
+      agent_settings: {
+        mcp_config: {
+          linear: {
+            url: "https://mcp.linear.app/mcp",
+            transport: "http",
+            auth: { strategy: "bearer", value: encryptedAuth },
+          },
+        },
+      },
+    });
+
+    await McpService.testServer({
+      id: "linear",
+      type: "shttp",
+      name: "linear",
+      url: "https://mcp.linear.app/mcp",
+      auth: { strategy: "bearer", value: REDACTED_MCP_SECRET_VALUE },
+    });
+
+    expect(SettingsService.fetchSettingsFromApi).toHaveBeenCalledWith(
+      "encrypted",
+    );
+    expect(testServer).toHaveBeenCalledTimes(1);
+    expect(testServer.mock.calls[0][0]).toMatchObject({
+      name: "linear",
+      server: {
+        type: "http",
+        url: "https://mcp.linear.app/mcp",
+        auth: { strategy: "bearer", value: encryptedAuth },
+      },
+    });
+    expect(testServer.mock.calls[0][0].server).not.toHaveProperty("api_key");
+    expect(testServer.mock.calls[0][0].server).not.toHaveProperty("headers");
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+
+  it("forwards explicit OAuth authentication metadata to the MCP test endpoint", async () => {
+    await McpService.testServer({
+      id: "shttp-0",
+      type: "shttp",
+      name: "superhuman-mail",
+      url: "https://mcp.mail.superhuman.com/mcp",
+      auth: {
+        strategy: "oauth2",
+        authentication: {
+          type: "oauth",
+          client_auth_method: "none",
+        },
+        state: {
+          tokens: {
+            access_token: "gAAAAexisting-access-token",
+          },
+        },
+      },
+    });
+
+    expect(testServer).toHaveBeenCalledTimes(1);
+    expect(testServer.mock.calls[0][0]).toMatchObject({
+      name: "superhuman-mail",
+      server: {
+        type: "http",
+        url: "https://mcp.mail.superhuman.com/mcp",
+        auth: {
+          strategy: "oauth2",
+          authentication: {
+            type: "oauth",
+            client_auth_method: "none",
+          },
+          state: {
+            tokens: {
+              access_token: "gAAAAexisting-access-token",
+            },
+          },
+        },
+      },
+      timeout: 120,
+    });
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns OAuth state captured by the MCP test endpoint", async () => {
+    testServer.mockResolvedValueOnce({
+      ok: true,
+      tools: ["search_mail"],
+      oauth_state: {
+        tokens: {
+          access_token: "gAAAAencrypted-access-token",
+        },
+        token_expires_at: 12345,
+      },
+    });
+
+    const result = await McpService.testServer({
+      id: "shttp-0",
+      type: "shttp",
+      name: "superhuman-mail",
+      url: "https://mcp.mail.superhuman.com/mcp",
+      auth: {
+        strategy: "oauth2",
+        authentication: {
+          type: "oauth",
+          client_auth_method: "none",
+        },
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("expected successful MCP test");
+    expect(result.oauth_state).toMatchObject({
+      tokens: {
+        access_token: "gAAAAencrypted-access-token",
+      },
+      token_expires_at: 12345,
+    });
+  });
+
+  it("starts OAuth through the TypeScript MCP client", async () => {
+    const result = await McpService.startOAuth({
+      id: "shttp-0",
+      type: "shttp",
+      name: "superhuman-mail",
+      url: "https://mcp.mail.superhuman.com/mcp",
+      auth: {
+        strategy: "oauth2",
+        authentication: {
+          type: "oauth",
+          client_auth_method: "none",
+        },
+      },
+    });
+
+    expect(result.job_id).toBe("job-1");
+    expect(startOAuth).toHaveBeenCalledTimes(1);
+    expect(startOAuth.mock.calls[0][0]).toMatchObject({
+      name: "superhuman-mail",
+      server: {
+        type: "http",
+        url: "https://mcp.mail.superhuman.com/mcp",
+        auth: {
+          strategy: "oauth2",
+          authentication: {
+            type: "oauth",
+            client_auth_method: "none",
+          },
+        },
+      },
+      timeout: 120,
+    });
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+
+  it("submits OAuth callback through the TypeScript MCP client", async () => {
+    await McpService.submitOAuthCallback(
+      "job/1",
+      "http://localhost:1234/callback?code=abc",
+    );
+
+    expect(submitOAuthCallback).toHaveBeenCalledWith("job/1", {
+      callback_url: "http://localhost:1234/callback?code=abc",
+    });
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+
+  it("gets OAuth status through the TypeScript MCP client", async () => {
+    await McpService.getOAuthStatus("job/1");
+
+    expect(getOAuthStatus).toHaveBeenCalledWith("job/1");
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+});

src/api/mcp-service/mcp-service.api.ts

@@ -0,0 +1,344 @@
+import { MCPClient } from "@openhands/typescript-client/clients";
+import type { AgentServerMCPTestRequest } from "@openhands/typescript-client";
+import { getAgentServerClientOptions } from "../agent-server-client-options";
+import {
+  getActiveBackend,
+  getRegisteredBackends,
+} from "../backend-registry/active-store";
+import {
+  getCredentialValidationForServer,
+  type CredentialValidation,
+} from "#/utils/mcp-credential-validation";
+import type {
+  ExtendedMCPTestResponse,
+  MCPOAuthStartResponse,
+  MCPOAuthStatusResponse,
+  MCPServerConfig,
+} from "#/types/mcp-server";
+import { redactMcpSecrets } from "#/utils/redact-mcp-secrets";
+import { substituteRedactedMcpCredentials } from "./mcp-redacted-credentials";
+
+const OAUTH_MCP_TEST_TIMEOUT_SECONDS = 120;
+
+function toMcpServer(
+  server: MCPServerConfig,
+): AgentServerMCPTestRequest["server"] {
+  if (server.type === "stdio") {
+    return {
+      type: "stdio",
+      command: server.command!,
+      ...(server.args?.length && { args: server.args }),
+      ...(server.env &&
+        Object.keys(server.env).length > 0 && { env: server.env }),
+    };
+  }
+  return {
+    type: server.type === "sse" ? "sse" : "http",
+    url: server.url!,
+    ...(server.headers &&
+      Object.keys(server.headers).length > 0 && { headers: server.headers }),
+    ...(server.auth ? { auth: server.auth } : {}),
+  };
+}
+
+function getMcpTestTimeout(server: MCPServerConfig): number | undefined {
+  if (server.auth?.strategy !== "oauth2") return server.timeout;
+  return OAUTH_MCP_TEST_TIMEOUT_SECONDS;
+}
+
+async function buildMcpTestRequest(server: MCPServerConfig): Promise<{
+  request: AgentServerMCPTestRequest;
+  substituted: MCPServerConfig;
+}> {
+  const validation = getCredentialValidationForServer(server);
+  const substituted = await substituteRedactedMcpCredentials(server);
+  const serverSpec = toMcpServer(substituted);
+  const timeout = getMcpTestTimeout(server);
+  return {
+    request: {
+      server: serverSpec,
+      ...(server.name ? { name: server.name } : {}),
+      ...(timeout !== undefined ? { timeout } : {}),
+      ...(validation ? { tool_call: validation.toolCall } : {}),
+    },
+    substituted,
+  };
+}
+
+function redactMcpTestResponse(
+  result: ExtendedMCPTestResponse,
+  redactionSources: (MCPServerConfig | undefined)[],
+): ExtendedMCPTestResponse {
+  if (!result.ok) {
+    return {
+      ...result,
+      error: redactMcpSecrets(result.error, ...redactionSources),
+    };
+  }
+  if (result.tool_result) {
+    return {
+      ...result,
+      tool_result: {
+        ...result.tool_result,
+        text: redactMcpSecrets(result.tool_result.text, ...redactionSources),
+      },
+    };
+  }
+  return result;
+}
+
+/**
+ * Display-boundary post-processing shared by the test and OAuth probes:
+ * scrub secrets from error/tool-result text, then let the catalog entry's
+ * credential validation turn a failed read-only tool call into a
+ * `credentials` failure. The interpretation only runs when the probe tool
+ * is actually advertised in `tools` — a server variant that doesn't expose
+ * the tool (e.g. a hosted alternative to the stdio server the spec was
+ * written for) must degrade to a connectivity-only success, not be
+ * misreported as bad credentials.
+ */
+function finalizeMcpTestResponse(
+  result: ExtendedMCPTestResponse,
+  validation: CredentialValidation | undefined,
+  redactionSources: (MCPServerConfig | undefined)[],
+): ExtendedMCPTestResponse {
+  const redacted = redactMcpTestResponse(result, redactionSources);
+  if (
+    redacted.ok &&
+    validation &&
+    redacted.tool_result &&
+    redacted.tools.includes(validation.toolCall.name)
+  ) {
+    const credentialError = validation.interpret(redacted.tool_result);
+    if (credentialError) {
+      return {
+        ok: false,
+        error: credentialError,
+        error_kind: "credentials",
+      };
+    }
+  }
+  return redacted;
+}
+
+function getMcpProbeOptions(): { host: string; apiKey?: string } {
+  const active = getActiveBackend().backend;
+  if (active.kind === "local") {
+    const { host, apiKey } = getAgentServerClientOptions();
+    return { host, ...(apiKey ? { apiKey } : {}) };
+  }
+
+  const localBackend = getRegisteredBackends().find(
+    (backend) => backend.kind === "local" && backend.host,
+  );
+  if (localBackend) {
+    return {
+      host: localBackend.host.replace(/\/+$/, ""),
+      ...(localBackend.apiKey ? { apiKey: localBackend.apiKey } : {}),
+    };
+  }
+  throw new Error("OAuth authorization requires a reachable local backend.");
+}
+
+function createMcpProbeClient(): MCPClient {
+  const { host, apiKey } = getMcpProbeOptions();
+  return new MCPClient({
+    host,
+    ...(apiKey ? { apiKey } : {}),
+    timeout: OAUTH_MCP_TEST_TIMEOUT_SECONDS * 1000 + 5000,
+  });
+}
+
+function oauthStatusToTestResponse(
+  status: MCPOAuthStatusResponse,
+): ExtendedMCPTestResponse {
+  if (status.status === "succeeded") {
+    return {
+      ok: true,
+      tools: status.tools ?? [],
+      ...(status.tool_result !== undefined && {
+        tool_result: status.tool_result,
+      }),
+      ...(status.oauth_state !== undefined && {
+        oauth_state: status.oauth_state,
+      }),
+    };
+  }
+  return {
+    ok: false,
+    error: status.error || "OAuth authorization did not complete",
+    error_kind: status.error_kind || "unknown",
+  };
+}
+
+const sleep = (ms: number) =>
+  new Promise<void>((resolve) => {
+    window.setTimeout(resolve, ms);
+  });
+
+class McpService {
+  static async testServer(
+    server: MCPServerConfig,
+  ): Promise<ExtendedMCPTestResponse> {
+    // The MCP connectivity-test endpoint lives on the local agent-server. It
+    // spawns the configured stdio command / opens an SSE-or-SHTTP connection
+    // from that process's environment. Cloud backends don't expose this
+    // endpoint to the frontend — the MCP server would actually run inside the
+    // cloud sandbox, which isn't reachable from the browser before the user
+    // starts a conversation. Calling `getAgentServerClientOptions()` here for
+    // a cloud-active session would throw `NoBackendAvailableError("No backend
+    // is configured.")` and block the install flow entirely. Short-circuit
+    // with a synthetic success so saving proceeds; any real connection
+    // failure surfaces inside the conversation runtime instead.
+    if (getActiveBackend().backend.kind === "cloud") {
+      return { ok: true, tools: [] };
+    }
+    const validation = getCredentialValidationForServer(server);
+    const { host, apiKey } = getAgentServerClientOptions();
+    const client = new MCPClient({ host, ...(apiKey ? { apiKey } : {}) });
+    try {
+      const { request, substituted } = await buildMcpTestRequest(server);
+      const result = (await client.testServer(
+        request,
+      )) as ExtendedMCPTestResponse;
+      // Redact against both config forms: `server` may hold fresh plaintext
+      // input, `substituted` the stored (encrypted) round-trip values.
+      return finalizeMcpTestResponse(result, validation, [substituted, server]);
+    } finally {
+      client.close();
+    }
+  }
+
+  static async startOAuth(
+    server: MCPServerConfig,
+  ): Promise<MCPOAuthStartResponse> {
+    const client = createMcpProbeClient();
+    try {
+      return await McpService.startOAuthWithClient(client, server);
+    } finally {
+      client.close();
+    }
+  }
+
+  static async getOAuthStatus(jobId: string): Promise<MCPOAuthStatusResponse> {
+    const client = createMcpProbeClient();
+    try {
+      return await McpService.getOAuthStatusWithClient(client, jobId);
+    } finally {
+      client.close();
+    }
+  }
+
+  static async submitOAuthCallback(
+    jobId: string,
+    callbackUrl: string,
+  ): Promise<MCPOAuthStatusResponse> {
+    const client = createMcpProbeClient();
+    try {
+      return await McpService.submitOAuthCallbackWithClient(
+        client,
+        jobId,
+        callbackUrl,
+      );
+    } finally {
+      client.close();
+    }
+  }
+
+  static async authorizeOAuth(
+    server: MCPServerConfig,
+  ): Promise<ExtendedMCPTestResponse> {
+    const validation = getCredentialValidationForServer(server);
+    const finalize = (result: ExtendedMCPTestResponse) =>
+      finalizeMcpTestResponse(result, validation, [server]);
+    const popup = window.open("about:blank", "_blank");
+    const client = createMcpProbeClient();
+    try {
+      const start = await McpService.startOAuthWithClient(client, server);
+      if (!start.ok || !start.job_id || !start.authorization_url) {
+        popup?.close();
+        return finalize({
+          ok: false,
+          error: start.error || "Could not start OAuth authorization",
+          error_kind: start.error_kind || "unknown",
+        });
+      }
+
+      let status = await McpService.getOAuthStatusWithClient(
+        client,
+        start.job_id,
+      );
+      for (let attempt = 0; attempt < 20; attempt += 1) {
+        if (status.status === "succeeded" || status.status === "failed") {
+          popup?.close();
+          return finalize(oauthStatusToTestResponse(status));
+        }
+        if (status.callback_ready) break;
+        await sleep(250);
+        status = await McpService.getOAuthStatusWithClient(
+          client,
+          start.job_id,
+        );
+      }
+
+      if (popup) {
+        popup.location.href = start.authorization_url;
+      }
+
+      for (
+        let attempt = 0;
+        attempt < OAUTH_MCP_TEST_TIMEOUT_SECONDS;
+        attempt += 1
+      ) {
+        await sleep(1000);
+        status = await McpService.getOAuthStatusWithClient(
+          client,
+          start.job_id,
+        );
+        if (status.status === "succeeded" || status.status === "failed") {
+          popup?.close();
+          return finalize(oauthStatusToTestResponse(status));
+        }
+      }
+
+      return {
+        ok: false,
+        error: "OAuth authorization timed out",
+        error_kind: "timeout",
+      };
+    } finally {
+      client.close();
+    }
+  }
+
+  private static async startOAuthWithClient(
+    client: MCPClient,
+    server: MCPServerConfig,
+  ): Promise<MCPOAuthStartResponse> {
+    const { request } = await buildMcpTestRequest(server);
+    return client.startOAuth(request);
+  }
+
+  // typescript-client 1.36 types the OAuth probes with the generated
+  // agent-server models, which describe the opaque `oauth_state` JSON blobs as
+  // `unknown` rather than the recursive `MCPJsonValue` the local types use. The
+  // wire shape is unchanged, so narrow back to the app's boundary type.
+  private static async getOAuthStatusWithClient(
+    client: MCPClient,
+    jobId: string,
+  ): Promise<MCPOAuthStatusResponse> {
+    return (await client.getOAuthStatus(jobId)) as MCPOAuthStatusResponse;
+  }
+
+  private static async submitOAuthCallbackWithClient(
+    client: MCPClient,
+    jobId: string,
+    callbackUrl: string,
+  ): Promise<MCPOAuthStatusResponse> {
+    return (await client.submitOAuthCallback(jobId, {
+      callback_url: callbackUrl,
+    })) as MCPOAuthStatusResponse;
+  }
+}
+
+export default McpService;

src/api/option-service/option-service.api.ts

@@ -0,0 +1,48 @@
+import { LLMMetadataClient } from "@openhands/typescript-client/clients";
+import { loadAgentServerInfo } from "../agent-server-compatibility";
+import { getAgentServerClientOptions } from "../agent-server-client-options";
+import { ModelsResponse, WebClientConfig } from "./option.types";
+
+class OptionService {
+  static async getModels(): Promise<ModelsResponse> {
+    const llmClient = new LLMMetadataClient(getAgentServerClientOptions());
+    const [models, verifiedByProvider, providers] = await Promise.all([
+      llmClient.getModels(),
+      llmClient.getVerifiedModels(),
+      llmClient.getProviders(),
+    ]);
+
+    const verifiedProviders = Object.keys(verifiedByProvider ?? {}).sort();
+    const verifiedModels = verifiedProviders.flatMap(
+      (provider) => verifiedByProvider[provider] ?? [],
+    );
+
+    return {
+      models: models ?? [],
+      verified_models: verifiedModels,
+      verified_providers:
+        providers?.filter((provider) => verifiedProviders.includes(provider)) ??
+        verifiedProviders,
+      default_model: verifiedModels[0] ?? models?.[0] ?? "",
+    };
+  }
+
+  static async getConfig(): Promise<WebClientConfig> {
+    await loadAgentServerInfo();
+
+    return {
+      feature_flags: {
+        hide_llm_settings: false,
+        hide_users_page: true,
+      },
+      providers_configured: [],
+      maintenance_start_time: null,
+      recaptcha_site_key: null,
+      faulty_models: [],
+      error_message: null,
+      updated_at: new Date().toISOString(),
+    };
+  }
+}
+
+export default OptionService;

src/api/option-service/option.types.ts

@@ -0,0 +1,33 @@
+import { Provider } from "#/types/settings";
+
+/**
+ * Structured response from ``GET /api/options/models``.
+ *
+ * The backend is the single source of truth — the frontend no longer carries
+ * its own hardcoded verified-model lists.
+ */
+export interface ModelsResponse {
+  /** Flat list of ``provider/model`` strings (bare names already prefixed). */
+  models: string[];
+  /** Model names (without provider) that OpenHands has verified to work well. */
+  verified_models: string[];
+  /** Provider names shown in the "Verified" section of the model selector. */
+  verified_providers: string[];
+  /** Recommended default model id (e.g. ``openhands/claude-opus-4-5-20251101``). */
+  default_model: string;
+}
+
+export interface WebClientFeatureFlags {
+  hide_llm_settings: boolean;
+  hide_users_page: boolean;
+}
+
+export interface WebClientConfig {
+  feature_flags: WebClientFeatureFlags;
+  providers_configured: Provider[];
+  maintenance_start_time: string | null;
+  recaptcha_site_key: string | null;
+  faulty_models: string[];
+  error_message: string | null;
+  updated_at: string;
+}

src/api/profiles-service/profiles-service.api.ts

@@ -0,0 +1,191 @@
+/**
+ * ProfilesService is the single entry point for LLM-profile CRUD, routing per
+ * active backend so callers (hooks, the settings manager) stay backend-agnostic:
+ * - local agent-server: the SDK's ProfilesClient (`/api/profiles`), created
+ *   per-call to pick up current backend configuration;
+ * - cloud app-server: `src/api/cloud/profiles-service.api.ts` (the org-gated
+ *   `/api/organizations/{orgId}/profiles` routes, or the per-user settings
+ *   route as a fallback) via the org-scoped cloud proxy.
+ * This mirrors how SettingsService branches to fetchCloudSettings().
+ *
+ * Uses ProfilesClient from @openhands/typescript-client v0.2.0+.
+ * All types are re-exported from the SDK for consumer convenience.
+ *
+ * Note: Unlike some SDK clients, we don't call client.close() here for
+ * consistency with other services (SettingsService, SecretsService) that
+ * also create SDK clients without explicit cleanup. The SDK clients use
+ * fetch-based HTTP which doesn't require connection cleanup.
+ */
+import {
+  ProfilesClient,
+  type GetProfileOptions,
+} from "@openhands/typescript-client/clients";
+import type {
+  ProfileInfo as ClientProfileInfo,
+  ProfileListResponse as ClientProfileListResponse,
+  ProfileDetailResponse,
+  ProfileMutationResponse,
+  ActivateProfileResponse,
+  SaveProfileRequest,
+  ExposeSecretsMode,
+  ValidateProfileResponse,
+} from "@openhands/typescript-client";
+import { getAgentServerClientOptions } from "../agent-server-client-options";
+import { getActiveBackend } from "../backend-registry/active-store";
+import {
+  activateCloudProfile,
+  deleteCloudProfile,
+  fetchCloudProfile,
+  fetchCloudProfiles,
+  renameCloudProfile,
+  saveCloudProfile,
+} from "../cloud/profiles-service.api";
+
+/**
+ * Profile summaries carry an optional `provider_connection_id` (the shared
+ * provider connection a profile links to), but `@openhands/typescript-client`
+ * predates that field. Widen the client types here so consumers can read it; it
+ * stays optional, so a client response without the field is still assignable.
+ */
+export interface ProfileInfo extends ClientProfileInfo {
+  provider_connection_id?: string | null;
+  /** True when provider_connection_id is set but the referenced connection no longer exists. */
+  provider_connection_broken?: boolean;
+}
+
+export interface ProfileListResponse extends Omit<
+  ClientProfileListResponse,
+  "profiles"
+> {
+  profiles: ProfileInfo[];
+}
+
+// Re-export SDK types for consumers
+export type {
+  ProfileDetailResponse,
+  ProfileMutationResponse,
+  ActivateProfileResponse,
+  SaveProfileRequest,
+  ExposeSecretsMode,
+  ValidateProfileResponse,
+};
+
+function isCloudBackend(): boolean {
+  return getActiveBackend().backend.kind === "cloud";
+}
+
+function isAbortLike(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  const name = "name" in error ? error.name : undefined;
+  if (name === "AbortError" || name === "TimeoutError") return true;
+  const cause = "cause" in error ? error.cause : undefined;
+  return (
+    !!cause &&
+    typeof cause === "object" &&
+    "name" in cause &&
+    (cause.name === "AbortError" || cause.name === "TimeoutError")
+  );
+}
+
+class ProfilesService {
+  static async listProfiles(): Promise<ProfileListResponse> {
+    if (isCloudBackend()) return fetchCloudProfiles();
+    return new ProfilesClient(getAgentServerClientOptions()).listProfiles();
+  }
+
+  static async getProfile(
+    name: string,
+    exposeSecrets?: ExposeSecretsMode,
+  ): Promise<ProfileDetailResponse> {
+    // Cloud never exposes profile secrets (api_key is always nulled with an
+    // api_key_set flag), so `exposeSecrets` is local-only.
+    if (isCloudBackend()) return fetchCloudProfile(name);
+    const options: GetProfileOptions = exposeSecrets ? { exposeSecrets } : {};
+    return new ProfilesClient(getAgentServerClientOptions()).getProfile(
+      name,
+      options,
+    );
+  }
+
+  static async saveProfile(
+    name: string,
+    request: SaveProfileRequest,
+  ): Promise<ProfileMutationResponse> {
+    if (isCloudBackend()) return saveCloudProfile(name, request);
+    return new ProfilesClient(getAgentServerClientOptions()).saveProfile(
+      name,
+      request,
+    );
+  }
+
+  static async deleteProfile(name: string): Promise<ProfileMutationResponse> {
+    if (isCloudBackend()) return deleteCloudProfile(name);
+    return new ProfilesClient(getAgentServerClientOptions()).deleteProfile(
+      name,
+    );
+  }
+
+  static async renameProfile(
+    name: string,
+    newName: string,
+  ): Promise<ProfileMutationResponse> {
+    if (isCloudBackend()) return renameCloudProfile(name, newName);
+    return new ProfilesClient(getAgentServerClientOptions()).renameProfile(
+      name,
+      newName,
+    );
+  }
+
+  static async activateProfile(name: string): Promise<ActivateProfileResponse> {
+    if (isCloudBackend()) return activateCloudProfile(name);
+    return new ProfilesClient(getAgentServerClientOptions()).activateProfile(
+      name,
+    );
+  }
+
+  /**
+   * Pre-flight check: fire a minimal LLM completion to catch misconfigurations
+   * (invalid model names, missing provider prefixes, bad base URLs, invalid
+   * API keys) before a profile is saved.
+   *
+   * Returns `{ valid: true }` when the LLM responds, or
+   * `{ valid: false, error: { type, message } }` on a blocking error.
+   * Transient errors (rate limits, timeouts) are non-blocking.
+   *
+   * Cloud backends do not implement this endpoint; `null` signals
+   * "no verdict" so callers fall through to the normal save path.
+   */
+  static async validateProfile(
+    name: string,
+    request: SaveProfileRequest,
+  ): Promise<ValidateProfileResponse | null> {
+    if (isCloudBackend()) return null;
+    const client = new ProfilesClient({
+      ...getAgentServerClientOptions(),
+      timeout: 30000,
+    });
+    try {
+      return await client.validateProfile(name, request);
+    } catch (error) {
+      // Older agent-server versions don't have the endpoint → 404
+      // Treat as "no verdict" rather than blocking the save.
+      const status =
+        error && typeof error === "object" && "status" in error
+          ? (error as { status?: unknown }).status
+          : undefined;
+      if (
+        status === 404 ||
+        status === 429 ||
+        (typeof status === "number" && status >= 500) ||
+        isAbortLike(error)
+      ) {
+        return null;
+      }
+      throw error;
+    } finally {
+      client.close();
+    }
+  }
+}
+
+export default ProfilesService;

src/api/provider-connections-service/provider-connections-service.api.test.ts

@@ -0,0 +1,130 @@
+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 { AgentServerClient } from "@openhands/typescript-client/clients";
+import ProviderConnectionsService from "./provider-connections-service.api";
+
+const getMock = vi.hoisted(() => vi.fn());
+const postMock = vi.hoisted(() => vi.fn());
+const patchMock = vi.hoisted(() => vi.fn());
+const deleteMock = vi.hoisted(() => vi.fn());
+const closeMock = vi.hoisted(() => vi.fn());
+
+vi.mock("@openhands/typescript-client/clients", () => ({
+  AgentServerClient: vi.fn(function AgentServerClientMock() {
+    return {
+      get: getMock,
+      post: postMock,
+      patch: patchMock,
+      delete: deleteMock,
+      close: closeMock,
+    };
+  }),
+}));
+
+const localBackend: Backend = {
+  id: "local-test",
+  name: "Local test backend",
+  host: "http://localhost:3000",
+  apiKey: "test-session-key",
+  kind: "local",
+};
+
+const connection = {
+  id: "conn-1",
+  display_name: "My OpenAI",
+  provider: "openai",
+  base_url: null,
+  created_at: 1,
+  updated_at: 2,
+  api_key_set: true,
+};
+
+const PATH = "/api/llm/provider-connections";
+
+describe("ProviderConnectionsService", () => {
+  beforeEach(() => {
+    getMock.mockReset();
+    postMock.mockReset();
+    patchMock.mockReset();
+    deleteMock.mockReset();
+    closeMock.mockReset();
+    vi.mocked(AgentServerClient).mockClear();
+    setRegisteredBackends([localBackend]);
+    setActiveSelection({ backendId: localBackend.id });
+  });
+
+  afterEach(() => {
+    setActiveSelection(null);
+    setRegisteredBackends([]);
+  });
+
+  it("lists connections via the typed client and closes it", async () => {
+    getMock.mockResolvedValue([connection]);
+
+    const result = await ProviderConnectionsService.list();
+
+    expect(result).toEqual([connection]);
+    expect(vi.mocked(AgentServerClient)).toHaveBeenCalledWith({
+      host: "http://localhost:3000",
+      apiKey: "test-session-key",
+    });
+    expect(getMock).toHaveBeenCalledWith(PATH, { responseType: "json" });
+    expect(closeMock).toHaveBeenCalled();
+  });
+
+  it("creates a connection with the request body", async () => {
+    postMock.mockResolvedValue(connection);
+
+    const request = {
+      display_name: "My OpenAI",
+      provider: "openai",
+      api_key: "sk-123",
+      base_url: null,
+    };
+    const result = await ProviderConnectionsService.create(request);
+
+    expect(result).toEqual(connection);
+    expect(postMock).toHaveBeenCalledWith(PATH, request, {
+      responseType: "json",
+    });
+    expect(closeMock).toHaveBeenCalled();
+  });
+
+  it("updates a connection at the id-scoped path", async () => {
+    patchMock.mockResolvedValue(connection);
+
+    const result = await ProviderConnectionsService.update("conn-1", {
+      display_name: "Renamed",
+    });
+
+    expect(result).toEqual(connection);
+    expect(patchMock).toHaveBeenCalledWith(
+      `${PATH}/conn-1`,
+      { display_name: "Renamed" },
+      { responseType: "json" },
+    );
+    expect(closeMock).toHaveBeenCalled();
+  });
+
+  it("url-encodes the id when deleting", async () => {
+    deleteMock.mockResolvedValue(connection);
+
+    await ProviderConnectionsService.delete("a b/c");
+
+    expect(deleteMock).toHaveBeenCalledWith(`${PATH}/a%20b%2Fc`, {
+      responseType: "json",
+    });
+    expect(closeMock).toHaveBeenCalled();
+  });
+
+  it("closes the client even when the request throws", async () => {
+    getMock.mockRejectedValue(new Error("boom"));
+
+    await expect(ProviderConnectionsService.list()).rejects.toThrow("boom");
+    expect(closeMock).toHaveBeenCalled();
+  });
+});

src/api/provider-connections-service/provider-connections-service.api.ts

@@ -0,0 +1,130 @@
+/**
+ * ProviderConnectionsService is the single entry point for provider-connection
+ * CRUD, routing per active backend so callers (hooks, the settings manager)
+ * stay backend-agnostic. A provider connection is a shared `api_key` + optional
+ * `base_url` that one or more LLM profiles reference by id; the backend resolves
+ * the credential into a runnable LLM at profile-load time, so this service only
+ * manages the stored connections.
+ *
+ * - local agent-server: the `/api/llm/provider-connections` CRUD endpoints via
+ *   the generic `AgentServerClient` verb helpers (the same approach
+ *   `LLMBalanceService` uses; there is no generated client for these routes in
+ *   `@openhands/typescript-client` yet);
+ * - cloud app-server: `src/api/cloud/provider-connections-service.api.ts` (the
+ *   org-gated `/api/organizations/{orgId}/provider-connections` routes) via the
+ *   org-scoped cloud proxy.
+ *
+ * This mirrors how `ProfilesService` branches to the cloud profile service.
+ */
+import { AgentServerClient } from "@openhands/typescript-client/clients";
+import { getAgentServerClientOptions } from "../agent-server-client-options";
+import { getActiveBackend } from "../backend-registry/active-store";
+import {
+  fetchCloudProviderConnections,
+  createCloudProviderConnection,
+  updateCloudProviderConnection,
+  deleteCloudProviderConnection,
+} from "../cloud/provider-connections-service.api";
+
+const PROVIDER_CONNECTIONS_PATH = "/api/llm/provider-connections";
+
+function isCloudBackend(): boolean {
+  return getActiveBackend().backend.kind === "cloud";
+}
+
+export interface ProviderConnection {
+  id: string;
+  display_name: string;
+  provider: string;
+  base_url: string | null;
+  created_at: number;
+  updated_at: number;
+  /** Whether the stored connection currently holds a usable key. */
+  api_key_set: boolean;
+}
+
+export interface CreateProviderConnectionRequest {
+  display_name: string;
+  provider: string;
+  api_key: string;
+  base_url?: string | null;
+}
+
+/**
+ * Partial update. Only the provided fields change. `api_key` may be sent to
+ * rotate the key; the agent-server rejects `api_key: null` (a connection must
+ * always keep a key), so callers omit it to leave the key unchanged.
+ */
+export interface UpdateProviderConnectionRequest {
+  display_name?: string;
+  provider?: string;
+  api_key?: string;
+  base_url?: string | null;
+}
+
+function createClient(): AgentServerClient {
+  const { host, apiKey } = getAgentServerClientOptions();
+  return new AgentServerClient({ host, ...(apiKey ? { apiKey } : {}) });
+}
+
+class ProviderConnectionsService {
+  static async list(): Promise<ProviderConnection[]> {
+    if (isCloudBackend()) return fetchCloudProviderConnections();
+    const client = createClient();
+    try {
+      return await client.get<ProviderConnection[]>(PROVIDER_CONNECTIONS_PATH, {
+        responseType: "json",
+      });
+    } finally {
+      client.close();
+    }
+  }
+
+  static async create(
+    request: CreateProviderConnectionRequest,
+  ): Promise<ProviderConnection> {
+    if (isCloudBackend()) return createCloudProviderConnection(request);
+    const client = createClient();
+    try {
+      return await client.post<ProviderConnection>(
+        PROVIDER_CONNECTIONS_PATH,
+        request,
+        { responseType: "json" },
+      );
+    } finally {
+      client.close();
+    }
+  }
+
+  static async update(
+    id: string,
+    request: UpdateProviderConnectionRequest,
+  ): Promise<ProviderConnection> {
+    if (isCloudBackend()) return updateCloudProviderConnection(id, request);
+    const client = createClient();
+    try {
+      return await client.patch<ProviderConnection>(
+        `${PROVIDER_CONNECTIONS_PATH}/${encodeURIComponent(id)}`,
+        request,
+        { responseType: "json" },
+      );
+    } finally {
+      client.close();
+    }
+  }
+
+  static async delete(id: string): Promise<ProviderConnection> {
+    if (isCloudBackend()) return deleteCloudProviderConnection(id);
+    const client = createClient();
+    try {
+      return await client.delete<ProviderConnection>(
+        `${PROVIDER_CONNECTIONS_PATH}/${encodeURIComponent(id)}`,
+        { responseType: "json" },
+      );
+    } finally {
+      client.close();
+    }
+  }
+}
+
+export default ProviderConnectionsService;