@vellumai/assistant 0.12.1 → 0.12.2-staging.1

package/src/tools/acp/status.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Tests for the `acp_status` tool's projection of session state.
+ *
+ * The state the manager tracks feeds three surfaces with different budgets:
+ * the HTTP route, the SSE picker, and this tool, whose output is spent on
+ * LLM context. Only the fields an agent can act on belong here.
+ */
+
+import { describe, expect, mock, test } from "bun:test";
+
+import type { AcpSessionState } from "../../acp/types.js";
+import type { ToolContext } from "../types.js";
+
+const RUNNING_STATE: AcpSessionState = {
+  id: "acp-1",
+  agentId: "claude",
+  acpSessionId: "proto-1",
+  parentConversationId: "conv-1",
+  status: "running",
+  startedAt: 1234,
+  task: "refactor the parser",
+  model: "claude-opus-4-5",
+  availableModels: [
+    { value: "sonnet", label: "Sonnet" },
+    { value: "opus", label: "Opus", description: "Most capable" },
+  ],
+};
+
+let statusResult: AcpSessionState | AcpSessionState[] = RUNNING_STATE;
+
+const realAcpModule = await import("../../acp/index.js");
+mock.module("../../acp/index.js", () => ({
+  ...realAcpModule,
+  getAcpSessionManager: () => ({ getStatus: () => statusResult }),
+}));
+
+const { executeAcpStatus } = await import("./status.js");
+
+const context = {
+  conversationId: "conv-1",
+  workingDir: "/tmp",
+} as unknown as ToolContext;
+
+describe("executeAcpStatus", () => {
+  test("a single session reports its model but not the picker", async () => {
+    statusResult = RUNNING_STATE;
+
+    const result = await executeAcpStatus({ acp_session_id: "acp-1" }, context);
+
+    expect(result.isError).toBe(false);
+    const payload = JSON.parse(result.content);
+    expect(payload).toEqual({
+      id: "acp-1",
+      agentId: "claude",
+      acpSessionId: "proto-1",
+      parentConversationId: "conv-1",
+      status: "running",
+      startedAt: 1234,
+      task: "refactor the parser",
+      model: "claude-opus-4-5",
+    });
+    expect(result.content).not.toContain("Most capable");
+  });
+
+  test("the listing drops the picker from every entry", async () => {
+    statusResult = [
+      RUNNING_STATE,
+      { ...RUNNING_STATE, id: "acp-2", model: "sonnet" },
+    ];
+
+    const result = await executeAcpStatus({}, context);
+
+    const payload = JSON.parse(result.content) as Array<
+      Record<string, unknown>
+    >;
+    expect(payload).toHaveLength(2);
+    expect(payload.map((entry) => entry.model)).toEqual([
+      "claude-opus-4-5",
+      "sonnet",
+    ]);
+    for (const entry of payload) {
+      expect(entry).not.toHaveProperty("availableModels");
+    }
+  });
+
+  test("an empty listing says so rather than rendering an empty array", async () => {
+    statusResult = [];
+
+    const result = await executeAcpStatus({}, context);
+
+    expect(result.content).toBe("No ACP sessions found.");
+    expect(result.isError).toBe(false);
+  });
+});

package/src/tools/acp/status.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 
 import { getAcpSessionManager } from "../../acp/index.js";
+import type { AcpSessionState } from "../../acp/types.js";
 import {
   invalidToolInputResult,
   nullAsOmitted,
@@ -16,6 +17,40 @@ export const acpStatusInputSchema = z.looseObject({
   acp_session_id: nullAsOmitted(z.string()),
 });
 
+/**
+ * The session fields worth spending LLM context on. An allowlist rather than
+ * an omission: `availableModels` is a picker for the human surfaces (HTTP and
+ * SSE) that says nothing the agent can act on, and a field added to
+ * `AcpSessionState` for those surfaces should not reach this one by default.
+ * `model` stays: which model a session is running on is answerable.
+ */
+function projectSession(state: AcpSessionState) {
+  return {
+    id: state.id,
+    agentId: state.agentId,
+    acpSessionId: state.acpSessionId,
+    parentConversationId: state.parentConversationId,
+    status: state.status,
+    startedAt: state.startedAt,
+    completedAt: state.completedAt,
+    error: state.error,
+    stopReason: state.stopReason,
+    task: state.task,
+    parentToolUseId: state.parentToolUseId,
+    authErrorCode: state.authErrorCode,
+    authErrorCredential: state.authErrorCredential,
+    latestUsage: state.latestUsage,
+    model: state.model,
+  };
+}
+
+/** Projects either shape `getStatus` answers with. */
+function projectStatus(status: AcpSessionState | AcpSessionState[]): unknown {
+  return Array.isArray(status)
+    ? status.map(projectSession)
+    : projectSession(status);
+}
+
 export async function executeAcpStatus(
   input: Record<string, unknown>,
   _context: ToolContext,
@@ -29,9 +64,8 @@ export async function executeAcpStatus(
 
   try {
     if (acpSessionId) {
-      const state = manager.getStatus(acpSessionId);
       return {
-        content: JSON.stringify(state),
+        content: JSON.stringify(projectStatus(manager.getStatus(acpSessionId))),
         isError: false,
       };
     }
@@ -42,7 +76,10 @@ export async function executeAcpStatus(
       return { content: "No ACP sessions found.", isError: false };
     }
 
-    return { content: JSON.stringify(allStates), isError: false };
+    return {
+      content: JSON.stringify(projectStatus(allStates)),
+      isError: false,
+    };
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     return { content: msg, isError: true };

package/src/tools/app-control/skill-proxy-bridge.ts

@@ -5,6 +5,7 @@
  * the proxy resolver, which forwards the call to the connected client.
  */
 
+import { formatDesktopAppRequired } from "../capability-offer.js";
 import { throwIfCancelled } from "../shared/abort.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
@@ -32,7 +33,7 @@ export function forwardAppControlProxyTool(
   }
   if (!context.proxyToolResolver) {
     return Promise.resolve({
-      content: `Cannot execute ${toolName}: no proxy resolver available. This tool requires a connected client.`,
+      content: formatDesktopAppRequired("apps"),
       isError: true,
     });
   }

package/src/tools/browser/browser-execution.ts

@@ -262,7 +262,7 @@ export const EXTRACT_LINKS_EXPRESSION = `
 (() => {
   const anchors = Array.from(document.querySelectorAll('a[href]'));
   return anchors.slice(0, 200).map(a => ({
-    text: (a.textContent || '').trim().slice(0, 80),
+    text: Array.from((a.textContent || '').trim()).slice(0, 80).join(''),
     href: a.href,
   }));
 })()

package/src/tools/browser/cdp-client/accessibility-snapshot.ts

@@ -14,6 +14,8 @@
  * a later PR is a direct drop-in replacement.
  */
 
+import { safeStringSlice } from "../../../util/unicode.js";
+
 // ── Types ─────────────────────────────────────────────────────────────
 
 /**
@@ -288,7 +290,11 @@ function extractAttrs(node: RawAxNode): Record<string, string> {
     if (!PROPERTY_ALLOWLIST.has(name)) {
       continue;
     }
-    attrs[name] = stringifyAxValue(prop.value?.value).slice(0, MAX_VALUE_CHARS);
+    attrs[name] = safeStringSlice(
+      stringifyAxValue(prop.value?.value),
+      0,
+      MAX_VALUE_CHARS,
+    );
   }
   return attrs;
 }
@@ -346,12 +352,12 @@ export function transformAxTree(
     }
 
     const rawName = typeof node.name?.value === "string" ? node.name.value : "";
-    const name = rawName.trim().slice(0, MAX_NAME_CHARS);
+    const name = safeStringSlice(rawName.trim(), 0, MAX_NAME_CHARS);
 
     const rawValue = node.value?.value;
     const value =
       typeof rawValue === "string" && rawValue.length > 0
-        ? rawValue.slice(0, MAX_VALUE_CHARS)
+        ? safeStringSlice(rawValue, 0, MAX_VALUE_CHARS)
         : undefined;
 
     const attrs = extractAttrs(node);

package/src/tools/browser/cdp-client/cdp-inspect/discovery.ts

@@ -25,6 +25,7 @@
  * value.
  */
 
+import { safeStringSlice } from "../../../../util/unicode.js";
 import type { CdpWsTransport } from "./ws-transport.js";
 
 /**
@@ -336,7 +337,7 @@ function parseJsonText(text: string, endpoint: string): unknown {
   } catch (err) {
     throw new DevToolsDiscoveryError(
       "invalid_response",
-      `Expected JSON from ${endpoint} but got: ${text.slice(0, 200)}`,
+      `Expected JSON from ${endpoint} but got: ${safeStringSlice(text, 0, 200)}`,
       err,
     );
   }

package/src/tools/browser/cdp-client/extension-cdp-client.ts

@@ -1,5 +1,6 @@
 import type { HostBrowserProxy } from "../../../daemon/host-browser-proxy.js";
 import { getLogger } from "../../../util/logger.js";
+import { safeStringSlice } from "../../../util/unicode.js";
 import type { CdpErrorCode } from "./errors.js";
 import { CdpError } from "./errors.js";
 import type { CdpClientKind, ScopedCdpClient, TabInfo } from "./types.js";
@@ -121,7 +122,7 @@ export class ExtensionCdpClient implements ScopedCdpClient {
         // and mask the extension path as the true failing hop.
         throw new CdpError(
           "cdp_error",
-          result.content.slice(0, 200) || `CDP error for ${method}`,
+          safeStringSlice(result.content, 0, 200) || `CDP error for ${method}`,
           {
             cdpMethod: method,
             cdpParams: params,
@@ -164,7 +165,7 @@ export class ExtensionCdpClient implements ScopedCdpClient {
     } catch (err) {
       throw new CdpError(
         "transport_error",
-        `Non-JSON content from host_browser_result: ${result.content.slice(0, 200)}`,
+        `Non-JSON content from host_browser_result: ${safeStringSlice(result.content, 0, 200)}`,
         {
           cdpMethod: method,
           cdpParams: params,

package/src/tools/browser/network-recorder.ts

@@ -7,6 +7,7 @@
 
 import { getLogger } from "../../util/logger.js";
 import { truncate } from "../../util/truncate.js";
+import { safeStringSlice } from "../../util/unicode.js";
 import type {
   ExtractedCredential,
   NetworkRecordedEntry,
@@ -457,7 +458,7 @@ export class NetworkRecorder {
 
         entry.response.body =
           body.length > MAX_BODY_SIZE
-            ? body.slice(0, MAX_BODY_SIZE) + "...[truncated]"
+            ? safeStringSlice(body, 0, MAX_BODY_SIZE) + "...[truncated]"
             : body;
       }
     } catch {

package/src/tools/capability-offer.test.ts

@@ -4,11 +4,26 @@ import {
   appendLoggedInBrowserOffer,
   CHROME_WEB_STORE_INSTALL_URL,
   DESKTOP_APP_DOWNLOAD_URL,
+  formatDesktopAppRequired,
   formatLoggedInBrowserOffer,
   isPhoneSurface,
   shouldOfferLoggedInBrowser,
 } from "./capability-offer.js";
 
+describe("formatDesktopAppRequired", () => {
+  test("offers a direct desktop-app download and retry step", () => {
+    const message = formatDesktopAppRequired("shell");
+
+    expect(message).toContain(
+      "The Vellum desktop app is needed to run commands on your computer",
+    );
+    expect(message).toContain(DESKTOP_APP_DOWNLOAD_URL);
+    expect(message).toContain("Open it, then retry.");
+    expect(message).not.toContain("client");
+    expect(message).not.toContain("daemon");
+  });
+});
+
 describe("isPhoneSurface", () => {
   test("is true for iOS transport and mobile client OS", () => {
     expect(isPhoneSurface({ transportInterface: "ios" })).toBe(true);
@@ -49,7 +64,9 @@ describe("shouldOfferLoggedInBrowser", () => {
     expect(shouldOfferLoggedInBrowser('Invalid browser_mode "bogus"')).toBe(
       false,
     );
-    expect(shouldOfferLoggedInBrowser("url must use http or https")).toBe(false);
+    expect(shouldOfferLoggedInBrowser("url must use http or https")).toBe(
+      false,
+    );
   });
 });
 
@@ -71,6 +88,7 @@ describe("formatLoggedInBrowserOffer", () => {
     });
     expect(offer).toContain("no in-app browser");
     expect(offer).toContain("Do not describe a browser panel");
+    expect(offer).toContain("Mac or Windows PC");
     expect(offer).toContain(DESKTOP_APP_DOWNLOAD_URL);
     expect(offer).toContain(CHROME_WEB_STORE_INSTALL_URL);
   });
@@ -78,7 +96,9 @@ describe("formatLoggedInBrowserOffer", () => {
 
 describe("appendLoggedInBrowserOffer", () => {
   test("appends the offer once", () => {
-    const once = appendLoggedInBrowserOffer("Error: Navigation failed: timeout");
+    const once = appendLoggedInBrowserOffer(
+      "Error: Navigation failed: timeout",
+    );
     expect(once).toContain("Error: Navigation failed: timeout");
     expect(once).toContain(DESKTOP_APP_DOWNLOAD_URL);
     const twice = appendLoggedInBrowserOffer(once);

package/src/tools/capability-offer.ts

@@ -7,7 +7,22 @@ export const DESKTOP_APP_DOWNLOAD_URL = "https://www.vellum.ai/downloads";
 export const CHROME_WEB_STORE_INSTALL_URL =
   "https://chromewebstore.google.com/detail/vellum-assistant-browser/hphbdmpffeigpcdjkckleobjmhhokpne";
 
-export const DESKTOP_APP_INSTALL_HINT = `Install the Vellum desktop app: ${DESKTOP_APP_DOWNLOAD_URL}`;
+export const DESKTOP_APP_INSTALL_HINT = `Download the Vellum desktop app: ${DESKTOP_APP_DOWNLOAD_URL}. Open it, then retry.`;
+
+export type DesktopAppCapability = "files" | "screen" | "shell" | "apps";
+
+const DESKTOP_APP_CAPABILITY_ACTION: Record<DesktopAppCapability, string> = {
+  files: "access files on your computer",
+  screen: "view or control your screen",
+  shell: "run commands on your computer",
+  apps: "control apps on your computer",
+};
+
+export function formatDesktopAppRequired(
+  capability: DesktopAppCapability,
+): string {
+  return `Error: The Vellum desktop app is needed to ${DESKTOP_APP_CAPABILITY_ACTION[capability]}. ${DESKTOP_APP_INSTALL_HINT}`;
+}
 
 /** User-facing install step for status userActions and command-failure hints. */
 export const CHROME_EXTENSION_INSTALL_HINT = `Install the Vellum Assistant Chrome extension from the Chrome Web Store: ${CHROME_WEB_STORE_INSTALL_URL}`;

package/src/tools/computer-use/definitions.ts

@@ -8,6 +8,7 @@
  */
 
 import { RiskLevel } from "../../permissions/types.js";
+import { formatDesktopAppRequired } from "../capability-offer.js";
 import type {
   ToolContext,
   ToolDefinition,
@@ -31,7 +32,7 @@ function proxyExecute(toolName: string) {
   ): Promise<ToolExecutionResult> => {
     if (!context.proxyToolResolver) {
       return {
-        content: `No proxy resolver configured for proxy tool "${toolName}". This tool requires a connected desktop client.`,
+        content: formatDesktopAppRequired("screen"),
         isError: true,
       };
     }
@@ -381,6 +382,112 @@ export const computerUseRunAppleScriptTool = {
   execute: proxyExecute("computer_use_run_applescript"),
 } satisfies ToolDefinition;
 
+// ---------------------------------------------------------------------------
+// sequence
+// ---------------------------------------------------------------------------
+
+export const computerUseSequenceTool = {
+  name: "computer_use_sequence",
+  description:
+    "Run several computer-use actions you already know, in order, in one step, for example open an app, press cmd+n, type a URL and press enter. Use it when no action depends on seeing the result of the one before; otherwise act one step at a time. Element IDs refer to the latest observation, so use them only for actions that act before the screen changes. Stops at the first action that is refused or fails and reports which one. Returns one observation after the last action.",
+  category: "computer-use",
+  defaultRiskLevel: RiskLevel.Low,
+  executionTarget: "host",
+  supportedClientOs: ["macos"],
+
+  input_schema: {
+    type: "object",
+    properties: {
+      actions: {
+        type: "array",
+        minItems: 1,
+        maxItems: 10,
+        description: "The actions to run, in order",
+        items: {
+          type: "object",
+          properties: {
+            action: {
+              type: "string",
+              enum: [
+                "key",
+                "type_text",
+                "type",
+                "click",
+                "double_click",
+                "right_click",
+                "scroll",
+                "wait",
+                "open_app",
+              ],
+              description: "The action to run",
+            },
+            key: {
+              type: "string",
+              description:
+                "key: key or shortcut to press (e.g. enter, tab, cmd+n)",
+            },
+            text: {
+              type: "string",
+              description: "type_text (or type): the text to type",
+            },
+            element_id: {
+              type: "integer",
+              description:
+                "click, double_click, right_click, scroll: the [ID] of the element from the latest accessibility tree (preferred)",
+            },
+            x: {
+              type: "integer",
+              description:
+                "click, double_click, right_click, scroll: X coordinate on screen (fallback when no element_id)",
+            },
+            y: {
+              type: "integer",
+              description:
+                "click, double_click, right_click, scroll: Y coordinate on screen (fallback when no element_id)",
+            },
+            direction: {
+              type: "string",
+              enum: ["up", "down", "left", "right"],
+              description: "scroll: scroll direction",
+            },
+            amount: {
+              type: "integer",
+              description: "scroll: scroll amount (1-10)",
+            },
+            duration_ms: {
+              type: "integer",
+              description: "wait: milliseconds to wait",
+            },
+            app_name: {
+              type: "string",
+              description:
+                'open_app: the name of the application to open (e.g. "Google Chrome")',
+            },
+            reasoning: {
+              type: "string",
+              description: "Optional: why this action",
+            },
+          },
+          required: ["action"],
+        },
+      },
+      reasoning: {
+        type: "string",
+        description:
+          "Optional: what these actions do together. Reasoning on each action works too",
+      },
+      target_client_id: {
+        type: "string",
+        description:
+          "ID of the specific client to target. Required when multiple clients support host_cu; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_cu`.",
+      },
+    },
+    required: ["actions"],
+  },
+
+  execute: proxyExecute("computer_use_sequence"),
+} satisfies ToolDefinition;
+
 // ---------------------------------------------------------------------------
 // done
 // ---------------------------------------------------------------------------
@@ -456,7 +563,18 @@ export const computerUseObserveTool = {
         type: "integer",
         minimum: 1,
         maximum: 4294967295,
-        description: "macOS only: capture this native CGWindowID instead of the desktop, including only its accessibility tree. Obtain a current native window ID first; do not guess or use a browser tab ID. Applies to this observation only, not subsequent actions. Requires a desktop helper with window-capture support. Screenshot coordinates are window-relative; use accessibility element IDs for later actions, not desktop scaling.",
+        description:
+          "macOS only: capture this native CGWindowID instead of the desktop, including only its accessibility tree. Obtain a current native window ID first; do not guess or use a browser tab ID. Applies to this observation only, not subsequent actions. Requires a desktop helper with window-capture support. Screenshot coordinates are window-relative; use accessibility element IDs for later actions, not desktop scaling.",
+      },
+      include_screenshot: {
+        type: "boolean",
+        description:
+          "Force a screenshot with this observation. The accessibility tree is returned every step; ask for pixels whenever the tree is not enough to act on, such as a canvas, a game, a custom-drawn view, a window with few or unlabeled controls, or a question about layout.",
+      },
+      full_tree: {
+        type: "boolean",
+        description:
+          "Walk the accessibility tree to full depth. Observations list the tree to a limited depth and say when it was cut off; pass this when the element you need is not in the tree.",
       },
       target_client_id: {
         type: "string",
@@ -484,6 +602,7 @@ export const allComputerUseTools: ToolDefinition[] = [
   computerUseWaitTool,
   computerUseOpenAppTool,
   computerUseRunAppleScriptTool,
+  computerUseSequenceTool,
   computerUseDoneTool,
   computerUseRespondTool,
 ];

package/src/tools/computer-use/skill-proxy-bridge.ts

@@ -5,6 +5,7 @@
  * the proxy resolver, which forwards the call to the connected desktop client.
  */
 
+import { formatDesktopAppRequired } from "../capability-offer.js";
 import { throwIfCancelled } from "../shared/abort.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
@@ -45,7 +46,7 @@ export function forwardComputerUseProxyTool(
   }
   if (!context.proxyToolResolver) {
     return Promise.resolve({
-      content: `Cannot execute ${toolName}: no proxy resolver available. This tool requires a connected desktop client.`,
+      content: formatDesktopAppRequired("screen"),
       isError: true,
     });
   }

package/src/tools/credentials/metadata-store.ts

@@ -20,6 +20,7 @@ import {
 } from "@vellumai/credential-storage";
 import type { CredentialRecord } from "@vellumai/service-contracts/credential-rpc";
 
+import { createCesHttpRecordBackendIfConfigured } from "../../security/ces-http-record-backend.js";
 import type { CredentialRecordBackend } from "../../security/ces-rpc-record-backend.js";
 import { getLogger } from "../../util/logger.js";
 import type { CredentialInjectionTemplate } from "./policy-types.js";
@@ -55,6 +56,11 @@ const CES_MEMORY_PATH = "ces-in-memory-credential-metadata";
 let _store: StaticCredentialMetadataStore | undefined;
 let _overridePath: string | null = null;
 let _recordBackend: CredentialRecordBackend | undefined;
+/**
+ * Test override for the CES HTTP listing fallback. `undefined` uses the
+ * production factory. `null` disables HTTP fallback.
+ */
+let _httpRecordBackendOverride: CredentialRecordBackend | null | undefined;
 let _cesRecordsLoaded = false;
 let _cesLoad: Promise<void> | undefined;
 let _cesLoadGeneration = 0;
@@ -255,6 +261,93 @@ export function listCredentialMetadata(): CredentialMetadata[] {
   return getStore().list() as CredentialMetadata[];
 }
 
+export type CredentialRecordListResult = {
+  records: CredentialMetadata[];
+  unreachable: boolean;
+};
+
+type ListedCredentialRecords = Array<{
+  account: string;
+  record: CredentialRecord;
+}>;
+
+function backendIsAvailable(backend: CredentialRecordBackend): boolean {
+  try {
+    return backend.isAvailable();
+  } catch {
+    return false;
+  }
+}
+
+async function listFromRecordBackend(
+  backend: CredentialRecordBackend,
+): Promise<ListedCredentialRecords | null> {
+  if (!backendIsAvailable(backend)) {
+    return null;
+  }
+  return backend.list();
+}
+
+function resolveHttpRecordBackend(): CredentialRecordBackend | null {
+  if (_httpRecordBackendOverride !== undefined) {
+    return _httpRecordBackendOverride;
+  }
+  return createCesHttpRecordBackendIfConfigured();
+}
+
+async function listFromHttpFallback(): Promise<ListedCredentialRecords | null> {
+  const httpBackend = resolveHttpRecordBackend();
+  if (!httpBackend) {
+    return null;
+  }
+  return listFromRecordBackend(httpBackend);
+}
+
+/**
+ * Live catalog from the credential record backend. Does not read the
+ * daemon in-process cache, so an outage cannot be mistaken for an empty
+ * vault. `unreachable` is true when the backend is missing, down, or
+ * the list RPC fails, and CES HTTP failover is also unavailable.
+ *
+ * When the attached backend is CES RPC (or none is attached), listing
+ * fails over to CES HTTP in containerized deployments so a down RPC
+ * socket does not hide a healthy vault sidecar. A successful empty
+ * catalog (`[]`) does not fall through to HTTP.
+ *
+ * The file-backed test store is the catalog when a test override path is set.
+ */
+export async function listCredentialRecordsLive(): Promise<CredentialRecordListResult> {
+  if (_overridePath) {
+    return {
+      records: getStore().list() as CredentialMetadata[],
+      unreachable: false,
+    };
+  }
+  if (_recordBackend) {
+    const remote = await listFromRecordBackend(_recordBackend);
+    if (remote !== null) {
+      return {
+        records: remote.map((entry) => entry.record as CredentialMetadata),
+        unreachable: false,
+      };
+    }
+    if (_recordBackend.name !== "ces-rpc") {
+      return { records: [], unreachable: true };
+    }
+  }
+  const httpRemote = await listFromHttpFallback();
+  if (httpRemote !== null) {
+    log.warn(
+      "CES RPC credential record list unavailable. Failing over to CES HTTP.",
+    );
+    return {
+      records: httpRemote.map((entry) => entry.record as CredentialMetadata),
+      unreachable: false,
+    };
+  }
+  return { records: [], unreachable: true };
+}
+
 /**
  * Delete metadata for a credential.
  */
@@ -287,3 +380,10 @@ export function _setMetadataPath(path: string | null): void {
     }
   }
 }
+
+/** @internal Test-only: override the CES HTTP listing fallback. */
+export function _setHttpRecordBackendForTests(
+  backend: CredentialRecordBackend | null | undefined,
+): void {
+  _httpRecordBackendOverride = backend;
+}