nolo-cli 0.1.33 → 0.1.35

package/agentRecordCommands.ts

@@ -2,6 +2,7 @@ import { resolveCliAgentKeyInput } from "./agentAliases";
 import { getReadableCliDb, type AgentCommandDeps } from "./agentCommandSupport";
 import {
   buildUpdatedAgentRecord,
+  buildCreatedAgentRecord,
   normalizeAgentRecordForOutput,
   parseAgentUpdateArgs,
   resolveAgentRecordFromHybridStore,
@@ -21,7 +22,7 @@ export async function runAgentReadCommand(
     return agentInput ? 0 : 1;
   }
 
-  const authToken = resolveAuthToken(env);
+  const authToken = resolveAuthToken(args, env);
   if (!authToken) {
     output.write("[nolo] agent read requires an auth token. Run `nolo login` or set AUTH_TOKEN.\n");
     return 1;
@@ -35,6 +36,7 @@ export async function runAgentReadCommand(
   try {
     const result = await resolveAgentRecordFromHybridStore({
       agentInput,
+      cliArgs: args,
       env,
       db,
       fetchImpl,
@@ -79,7 +81,7 @@ export async function runAgentUpdateCommand(
     return args[0] ? 0 : 1;
   }
 
-  const authToken = resolveAuthToken(env);
+  const authToken = resolveAuthToken(args, env);
   if (!authToken) {
     output.write("[nolo] agent update requires an auth token. Run `nolo login` or set AUTH_TOKEN.\n");
     return 1;
@@ -97,6 +99,7 @@ export async function runAgentUpdateCommand(
 
   try {
     const built = await buildUpdatedAgentRecord({
+      cliArgs: args,
       parsed,
       env,
       db,
@@ -139,3 +142,85 @@ export async function runAgentUpdateCommand(
     return 1;
   }
 }
+
+export async function runAgentCreateCommand(
+  args: string[],
+  deps: AgentCommandDeps = {}
+) {
+  const env = deps.env ?? process.env;
+  const output = deps.output ?? process.stdout;
+  let parsed;
+  try {
+    parsed = parseAgentUpdateArgs(args);
+  } catch (error) {
+    output.write(`[nolo] agent create failed: ${error instanceof Error ? error.message : String(error)}\n`);
+    return 1;
+  }
+  if (!parsed) {
+    output.write(
+      "Usage: nolo agent create <agent> [--model <id>] [--cli-provider <provider>] [--api-source <source>] [--prompt <text> | --prompt-file <path> | --prompt-doc <pageKey>] [--tools <json>] [--copy-provider-from <agent>] [--name <name>] [--custom-provider-url <url>] [--provider-api-key <key>] [--field key=value]\n"
+    );
+    return args[0] ? 0 : 1;
+  }
+
+  const authToken = resolveAuthToken(args, env);
+  if (!authToken) {
+    output.write("[nolo] agent create requires an auth token. Run `nolo login` or set AUTH_TOKEN.\n");
+    return 1;
+  }
+
+  const userId = parseUserIdFromAuthToken(authToken);
+  if (!userId) {
+    output.write("[nolo] agent create could not read userId from AUTH_TOKEN.\n");
+    return 1;
+  }
+
+  const db = deps.db ?? await getReadableCliDb(output);
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const fallbackFetchImpl = deps.fallbackFetchImpl;
+
+  try {
+    const built = await buildCreatedAgentRecord({
+      cliArgs: args,
+      parsed,
+      env,
+      db,
+      fetchImpl,
+      fallbackFetchImpl,
+      authToken,
+    });
+
+    await writeAgentRecord({
+      agentKey: built.agentKey,
+      authToken,
+      fallbackFetchImpl,
+      fetchImpl,
+      serverUrl: built.serverUrl,
+      userId,
+      record: built.nextRecord,
+    });
+    await db.put(built.agentKey, {
+      ...built.nextRecord,
+      dbKey: built.agentKey,
+      key: built.nextRecord?.key || built.agentKey,
+      serverOrigin: built.serverUrl,
+    });
+
+    output.write(JSON.stringify({
+      ok: true,
+      agentKey: built.agentKey,
+      baseUrl: built.serverUrl,
+      updates: built.updates,
+      record: built.nextRecord,
+    }, null, 2));
+    output.write("\n");
+    return 0;
+  } catch (error) {
+    output.write(
+      `[nolo] agent create failed: ${
+        error instanceof Error ? error.message : String(error)
+      }\n`
+    );
+    return 1;
+  }
+}

package/agentRecordHelpers.ts

@@ -125,10 +125,12 @@ export async function readDbRecord(args: {
   authToken: string;
   fallbackFetchImpl?: typeof fetch;
   fetchImpl: typeof fetch;
+  includeDeleted?: boolean;
   serverUrl: string;
 }) {
+  const query = args.includeDeleted ? "?includeDeleted=true" : "";
   const res = await fetchWithTransportFallback(
-    `${args.serverUrl}/api/v1/db/read/${encodeURIComponent(args.dbKey)}`,
+    `${args.serverUrl}/api/v1/db/read/${encodeURIComponent(args.dbKey)}${query}`,
     {
       method: "GET",
       headers: { Authorization: `Bearer ${args.authToken}` },
@@ -146,19 +148,29 @@ export async function queryUserRecords(args: {
   authToken: string;
   fallbackFetchImpl?: typeof fetch;
   fetchImpl: typeof fetch;
+  limit?: number;
   serverUrl: string;
+  summary?: boolean;
+  includeDeleted?: boolean;
   userId: string;
-  type: "agent" | "cybot";
-}) {
+  type: string | string[];
+}): Promise<any[]> {
+  const query = typeof args.limit === "number" && args.limit > 0
+    ? `?limit=${Math.floor(args.limit)}`
+    : "";
   const res = await fetchWithTransportFallback(
-    `${args.serverUrl}/api/v1/db/query/${encodeURIComponent(args.userId)}`,
+    `${args.serverUrl}/api/v1/db/query/${encodeURIComponent(args.userId)}${query}`,
     {
       method: "POST",
       headers: {
         Authorization: `Bearer ${args.authToken}`,
         "Content-Type": "application/json",
       },
-      body: JSON.stringify({ type: args.type }),
+      body: JSON.stringify({
+        type: args.type,
+        ...(args.includeDeleted ? { includeDeleted: true } : {}),
+        ...(args.summary ? { summary: true } : {}),
+      }),
     },
     args
   );
@@ -173,6 +185,34 @@ export async function queryUserRecords(args: {
       : [];
 }
 
+export async function deleteDbRecord(args: {
+  dbKey: string;
+  deleteOptions?: { type?: "single" | "table" | "messages" };
+  authToken: string;
+  fallbackFetchImpl?: typeof fetch;
+  fetchImpl: typeof fetch;
+  serverUrl: string;
+}) {
+  const type = args.deleteOptions?.type;
+  const query =
+    type && type !== "single"
+      ? `?type=${encodeURIComponent(type)}`
+      : "";
+  const res = await fetchWithTransportFallback(
+    `${args.serverUrl}/api/v1/db/delete/${encodeURIComponent(args.dbKey)}${query}`,
+    {
+      method: "DELETE",
+      headers: { Authorization: `Bearer ${args.authToken}` },
+    },
+    args
+  );
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error(`delete failed: HTTP ${res.status} ${JSON.stringify(data)}`);
+  }
+  return data;
+}
+
 export async function writeAgentRecord(args: {
   agentKey: string;
   authToken: string;
@@ -205,14 +245,19 @@ export async function writeAgentRecord(args: {
 
 export async function resolveAgentRecordFromHybridStore(args: {
   agentInput: string;
+  cliArgs?: string[];
   env: EnvLike;
   db: CliKvDb;
   fetchImpl: typeof fetch;
   fallbackFetchImpl?: typeof fetch;
 }) {
   const agentKey = resolveCliAgentKeyInput(args.agentInput);
-  const authToken = resolveAuthToken(args.env);
-  const defaultServerUrl = resolveServerUrl(args.env);
+  const authToken = args.cliArgs
+    ? resolveAuthToken(args.cliArgs, args.env)
+    : resolveAuthToken(args.env);
+  const defaultServerUrl = args.cliArgs
+    ? resolveServerUrl(args.cliArgs, args.env)
+    : resolveServerUrl(args.env);
 
   for (const key of buildLocalAgentLookupKeys({
     agentRef: agentKey,
@@ -232,7 +277,11 @@ export async function resolveAgentRecordFromHybridStore(args: {
     }
 
     if (!shouldReadAgentKeyRemotely(key)) continue;
-    for (const serverUrl of resolveServerCandidates(args.env, defaultServerUrl)) {
+    for (const serverUrl of (
+      args.cliArgs
+        ? resolveServerCandidates(args.cliArgs, args.env, defaultServerUrl)
+        : resolveServerCandidates(args.env, defaultServerUrl)
+    )) {
       try {
         const remoteRecord = await readAgentRecord({
           agentKey: key,
@@ -290,6 +339,8 @@ export function parseAgentUpdateArgs(args: string[]) {
   const tools = readOption(args, "--tools");
   const copyProviderFrom = readOption(args, "--copy-provider-from");
   const name = readOption(args, "--name");
+  const customProviderUrl = readOption(args, "--custom-provider-url");
+  const apiKey = readOption(args, "--api-key");
 
   const promptSources = [prompt, promptFile, promptDoc].filter(Boolean);
   if (promptSources.length > 1) {
@@ -304,6 +355,8 @@ export function parseAgentUpdateArgs(args: string[]) {
   if (promptFile) updates.prompt = readFileSync(promptFile, "utf8");
   if (tools) updates.tools = parseJsonishValue(tools);
   if (name) updates.name = name;
+  if (customProviderUrl) updates.customProviderUrl = customProviderUrl;
+  if (apiKey) updates.apiKey = apiKey;
 
   for (const entry of readRepeatedOption(args, "--field")) {
     const index = entry.indexOf("=");
@@ -322,7 +375,73 @@ export function parseAgentUpdateArgs(args: string[]) {
   return { agentInput, updates, promptDoc, copyProviderFrom };
 }
 
+export async function buildCreatedAgentRecord(args: {
+  cliArgs?: string[];
+  parsed: NonNullable<ReturnType<typeof parseAgentUpdateArgs>>;
+  env: EnvLike;
+  db: CliKvDb;
+  fetchImpl: typeof fetch;
+  fallbackFetchImpl?: typeof fetch;
+  authToken: string;
+}) {
+  const agentKey = resolveCliAgentKeyInput(args.parsed.agentInput);
+  const serverUrl = args.cliArgs ? resolveServerUrl(args.cliArgs, args.env) : resolveServerUrl(args.env);
+
+  if (args.parsed.copyProviderFrom) {
+    const providerSource = await resolveAgentRecordFromHybridStore({
+      agentInput: args.parsed.copyProviderFrom,
+      cliArgs: args.cliArgs,
+      env: args.env,
+      db: args.db,
+      fetchImpl: args.fetchImpl,
+      fallbackFetchImpl: args.fallbackFetchImpl,
+    });
+    if (!providerSource) {
+      throw new Error(`provider source agent not found: ${args.parsed.copyProviderFrom}`);
+    }
+    for (const field of PROVIDER_COPY_FIELDS) {
+      if (field in providerSource.record) {
+        args.parsed.updates[field] = providerSource.record[field];
+      }
+    }
+  }
+
+  if (args.parsed.promptDoc) {
+    const promptDoc = await readDbRecord({
+      dbKey: args.parsed.promptDoc,
+      authToken: args.authToken,
+      fallbackFetchImpl: args.fallbackFetchImpl,
+      fetchImpl: args.fetchImpl,
+      serverUrl,
+    });
+    const promptBody = typeof promptDoc?.content === "string" ? promptDoc.content : "";
+    if (!promptBody.trim()) {
+      throw new Error(`prompt doc is empty or unreadable: ${args.parsed.promptDoc}`);
+    }
+    args.parsed.updates.prompt = promptBody;
+  }
+
+  const userId = parseUserIdFromAuthToken(args.authToken);
+
+  const nextRecord = {
+    ...args.parsed.updates,
+    dbKey: agentKey,
+    key: agentKey,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+    userId,
+  };
+
+  return {
+    agentKey,
+    serverUrl,
+    nextRecord,
+    updates: args.parsed.updates,
+  };
+}
+
 export async function buildUpdatedAgentRecord(args: {
+  cliArgs?: string[];
   parsed: NonNullable<ReturnType<typeof parseAgentUpdateArgs>>;
   env: EnvLike;
   db: CliKvDb;
@@ -332,13 +451,16 @@ export async function buildUpdatedAgentRecord(args: {
 }) {
   const cached = await resolveAgentRecordFromHybridStore({
     agentInput: args.parsed.agentInput,
+    cliArgs: args.cliArgs,
     env: args.env,
     db: args.db,
     fetchImpl: args.fetchImpl,
     fallbackFetchImpl: args.fallbackFetchImpl,
   });
   const agentKey = cached?.agentKey ?? resolveCliAgentKeyInput(args.parsed.agentInput);
-  const serverUrl = cached?.record?.serverOrigin ?? resolveServerUrl(args.env);
+  const serverUrl = cached?.record?.serverOrigin ?? (
+    args.cliArgs ? resolveServerUrl(args.cliArgs, args.env) : resolveServerUrl(args.env)
+  );
   const currentRecord = await readAgentRecord({
     agentKey,
     authToken: args.authToken,
@@ -350,6 +472,7 @@ export async function buildUpdatedAgentRecord(args: {
   if (args.parsed.copyProviderFrom) {
     const providerSource = await resolveAgentRecordFromHybridStore({
       agentInput: args.parsed.copyProviderFrom,
+      cliArgs: args.cliArgs,
       env: args.env,
       db: args.db,
       fetchImpl: args.fetchImpl,

package/agentRuntimeLocal.ts

@@ -19,6 +19,9 @@ export {
   resolvePlatformChatProviderConfig,
   resolveLocalToolPolicy,
   resolveOpenAiCompatibleProviderConfig,
+  resolveRequestedRuntimeToolNames,
+  evaluateShellCommandPolicy,
+  isDestructiveShellCommand,
   shouldUsePlatformChatProvider,
   shouldCacheHybridRemoteRecord,
   shouldFetchAgentRuntimeRecordRemotely,

package/ai/tools/toolNameAliases.ts

@@ -0,0 +1,70 @@
+const LEGACY_TOOL_NAME_ALIASES: Record<string, string> = {
+  createPage: "createDoc",
+  updatePage: "updateDoc",
+  update_page: "updateDoc",
+  create_page: "createDoc",
+  fetchwebpage: "fetchWebpage",
+  fetch_webpage: "fetchWebpage",
+  "fetch-page": "fetchWebpage",
+  exasearch: "exa_search",
+  "exa-search": "exa_search",
+  exa_search: "exa_search",
+  readDoc: "readDoc",
+  readpage: "readDoc",
+  read_page: "readDoc",
+  read_doc: "readDoc",
+  createdoc: "createDoc",
+  updateDocTool: "updateDoc",
+  readLocal: "readLocalFile",
+  read_local: "readLocalFile",
+  readLocalTool: "readLocalFile",
+  listLocal: "listLocalFiles",
+  list_local: "listLocalFiles",
+  terminalCommand: "execShell",
+  terminal_command: "execShell",
+  runCommand: "execShell",
+  run_command: "execShell",
+  runInBash: "execShell",
+  run_in_bash: "execShell",
+  executeCommand: "execShell",
+  execute_command: "execShell",
+};
+
+const normalizeToolName = (name: string): string =>
+  name.replace(/[-_]/g, "").toLowerCase();
+
+export const canonicalizeToolName = (rawName: string): string => {
+  const trimmedName = rawName.trim();
+  if (!trimmedName) return rawName;
+
+  if (LEGACY_TOOL_NAME_ALIASES[trimmedName]) {
+    return LEGACY_TOOL_NAME_ALIASES[trimmedName];
+  }
+
+  const normalizedRawName = normalizeToolName(trimmedName);
+  const matchedAlias = Object.entries(LEGACY_TOOL_NAME_ALIASES).find(
+    ([alias]) => normalizeToolName(alias) === normalizedRawName,
+  );
+
+  return matchedAlias?.[1] ?? trimmedName;
+};
+
+export const canonicalizeToolNames = (toolNames: string[]): string[] =>
+  Array.from(
+    new Set(
+      toolNames
+        .filter((toolName): toolName is string => typeof toolName === "string")
+        .map(canonicalizeToolName),
+    ),
+  );
+
+export const prioritizeToolNames = (
+  toolNames: string[],
+  preferredToolNames: string[],
+): string[] => {
+  const canonicalTools = canonicalizeToolNames(toolNames);
+  const preferred = new Set(canonicalizeToolNames(preferredToolNames));
+  const prioritized = canonicalTools.filter((toolName) => preferred.has(toolName));
+  const remaining = canonicalTools.filter((toolName) => !preferred.has(toolName));
+  return [...prioritized, ...remaining];
+};

package/cli/agentCommandSupport.ts

@@ -20,6 +20,10 @@ export type LocalCliExecutor = (
 export type LocalRuntimeProbeResult = {
   ok: boolean;
   dbPath: string;
+  authorityDriver?: string;
+  authorityEndpoint?: string;
+  authorityMetadataPath?: string;
+  authorityHealthPath?: string;
   agentFound: boolean;
   agentKey?: string;
   error?: string;

package/cli/agentInternalCommandEntries.ts

@@ -8,6 +8,7 @@ import { runAgentPullCommand } from "./agentPullCommand";
 import {
   runAgentReadCommand,
   runAgentUpdateCommand,
+  runAgentCreateCommand,
 } from "./agentRecordCommands";
 import { runAgentRunCommand } from "./agentRunCommand";
 import {
@@ -21,6 +22,7 @@ export function getAgentInternalCommandEntries(): CommandEntry[] {
   return [
     createEnvScriptDirCommand(["chat"], "Chat with an agent", runAgentRunCommand),
     createEnvCommand(["agent", "list"], "List owned agents", runAgentListCommand),
+    createEnvCommand(["agent", "create"], "Create a new agent", runAgentCreateCommand),
     createEnvCommand(["agent", "pull"], "Cache an agent for local runs", runAgentPullCommand),
     createEnvCommand(["agent", "read"], "Read a single agent", runAgentReadCommand),
     createEnvScriptDirCommand(["agent", "run"], "Run an agent", runAgentRunCommand),

package/cli/agentListCommands.ts

@@ -1,6 +1,8 @@
 import { getReadableCliDb, type AgentCommandDeps } from "./agentCommandSupport";
 import {
+  decorateAgentsWithPublicStatusAcrossServers,
   listLocalCachedAgents,
+  listRemoteAgentsAcrossServers,
   listRemoteAgents,
   parseAgentListArgs,
   type ListedAgent,
@@ -9,11 +11,15 @@ import {
   queryUserRecords,
   readDbRecord,
 } from "./agentRecordHelpers";
+import { buildSpaceLookup, getSpaceContentKeys } from "./cliSpaceHelpers";
 import {
   parseUserIdFromAuthToken,
+  readOption,
   resolveAuthToken,
+  resolveServerCandidates,
   resolveServerUrl,
 } from "./cliEnvHelpers";
+import { readLiveDbRecordAfterTombstoneMerge } from "./globalRecordOperations";
 
 export async function runAgentListCommand(
   args: string[],
@@ -22,8 +28,9 @@ export async function runAgentListCommand(
   const env = deps.env ?? process.env;
   const output = deps.output ?? process.stdout;
   const { wantJson, publicOnly, idsOnly, includeLegacy } = parseAgentListArgs(args);
+  const spaceInput = readOption(args, "--space") ?? readOption(args, "--space-id");
 
-  const authToken = resolveAuthToken(env);
+  const authToken = resolveAuthToken(args, env);
   if (!authToken) {
     output.write("[nolo] agent list requires an auth token. Run `nolo login` or set AUTH_TOKEN.\n");
     return 1;
@@ -35,34 +42,79 @@ export async function runAgentListCommand(
     return 1;
   }
 
-  const db = deps.db ?? await getReadableCliDb(output);
   const fetchImpl = deps.fetchImpl ?? fetch;
   const fallbackFetchImpl = deps.fallbackFetchImpl;
+  const serverUrl = resolveServerUrl(args, env);
+  const serverUrls = resolveServerCandidates(args, env, serverUrl);
 
   try {
     let agents: ListedAgent[];
-    let source: "local-cache" | "remote-cache";
+    let source: "local-cache" | "remote-cache" | "global-cache";
+    let serverFailures: Array<{ serverUrl: string; error: string }> = [];
     try {
-      agents = await listLocalCachedAgents({ db, userId });
-      source = "local-cache";
-    } catch {
-      const serverUrl = resolveServerUrl(env);
-      agents = await listRemoteAgents({
+      const remoteResult = await listRemoteAgentsAcrossServers({
         authToken,
         fallbackFetchImpl,
         fetchImpl,
         includeLegacy,
-        serverUrl,
+        serverUrls,
         userId,
-        queryUserRecords,
-        readDbRecord,
       });
-      source = "remote-cache";
+      agents = remoteResult.agents;
+      serverFailures = remoteResult.failures;
+      source = "global-cache";
+    } catch {
+      try {
+        const db = deps.db ?? await getReadableCliDb(output);
+        agents = await listLocalCachedAgents({ db, userId });
+        source = "local-cache";
+      } catch {
+        agents = await listRemoteAgents({
+          authToken,
+          fallbackFetchImpl,
+          fetchImpl,
+          includeLegacy,
+          serverUrl,
+          userId,
+          queryUserRecords,
+          readDbRecord,
+        });
+        source = "remote-cache";
+      }
     }
 
     if (!includeLegacy) {
       agents = agents.filter((agent) => !agent.privateKey.startsWith("cybot-"));
     }
+    let resolvedSpaceId: string | null = null;
+    if (spaceInput) {
+      const { spaceId, spaceKey } = buildSpaceLookup(spaceInput);
+      resolvedSpaceId = spaceId;
+      const spaceRead = await readLiveDbRecordAfterTombstoneMerge({
+        authToken,
+        dbKey: spaceKey,
+        fallbackFetchImpl,
+        fetchImpl,
+        serverUrls,
+      });
+      serverFailures = [...serverFailures, ...spaceRead.failures];
+      const spaceRecord = spaceRead.record;
+      const spaceContentKeys = getSpaceContentKeys(spaceRecord);
+      agents = agents.filter((agent) =>
+        spaceContentKeys.has(agent.privateKey) ||
+        spaceContentKeys.has(agent.publicKey) ||
+        spaceContentKeys.has(agent.id)
+      );
+    }
+    if (source === "global-cache") {
+      await decorateAgentsWithPublicStatusAcrossServers({
+        agents,
+        authToken,
+        fallbackFetchImpl,
+        fetchImpl,
+        serverUrls,
+      });
+    }
     if (publicOnly) {
       agents = agents.filter((agent) => agent.publicRecordExists);
     }
@@ -75,6 +127,9 @@ export async function runAgentListCommand(
     if (wantJson) {
       output.write(JSON.stringify({
         userId,
+        ...(resolvedSpaceId ? { spaceId: resolvedSpaceId } : {}),
+        targetServers: serverUrls,
+        ...(serverFailures.length ? { serverFailures } : {}),
         total: agents.length,
         publicCount: agents.filter((agent) => agent.publicRecordExists).length,
         source,
@@ -85,6 +140,13 @@ export async function runAgentListCommand(
     }
 
     output.write(`userId: ${userId}\n`);
+    if (resolvedSpaceId) {
+      output.write(`spaceId: ${resolvedSpaceId}\n`);
+    }
+    output.write(`targetServers: ${serverUrls.join(", ")}\n`);
+    if (serverFailures.length) {
+      output.write(`serverFailures: ${serverFailures.length}\n`);
+    }
     output.write(`total agents: ${agents.length}\n`);
     output.write(`public agents: ${agents.filter((agent) => agent.publicRecordExists).length}\n`);
     output.write(`source: ${source}\n`);

package/cli/agentListHelpers.ts

@@ -1,4 +1,8 @@
 import type { CliKvDb } from "./client/hybridRecordStore";
+import {
+  listUserRecordsFromServers,
+  readLiveDbRecordAfterTombstoneMerge,
+} from "./globalRecordOperations";
 
 export type ListedAgent = {
   id: string;
@@ -93,7 +97,7 @@ export async function listLocalCachedAgents(args: {
 }) {
   const privateRecords = new Map<string, any>();
   const publicKeys = new Set<string>();
-  for await (const [key, value] of args.db.iterator()) {
+  for await (const [key, value] of args.db.iterator({ gte: "", lte: "\uffff" })) {
     if (typeof key !== "string" || !value || typeof value !== "object") continue;
     if (key.startsWith(`agent-${args.userId}-`) || key.startsWith(`cybot-${args.userId}-`)) {
       privateRecords.set(key, { ...(value as Record<string, unknown>), dbKey: key });
@@ -185,3 +189,54 @@ export async function listRemoteAgents(args: {
   );
   return agents;
 }
+
+export async function listRemoteAgentsAcrossServers(args: {
+  authToken: string;
+  fallbackFetchImpl?: typeof fetch;
+  fetchImpl: typeof fetch;
+  includeLegacy: boolean;
+  serverUrls: string[];
+  userId: string;
+}) {
+  const remoteResult = await listUserRecordsFromServers({
+    authToken: args.authToken,
+    fallbackFetchImpl: args.fallbackFetchImpl,
+    fetchImpl: args.fetchImpl,
+    label: "agent query",
+    serverUrls: args.serverUrls,
+    type: args.includeLegacy ? ["agent", "cybot"] : "agent",
+    userId: args.userId,
+  });
+  const agents = sortListedAgents(
+    remoteResult.records
+      .map((record) => normalizeListedAgent(record))
+      .filter((agent): agent is ListedAgent => agent != null)
+  );
+  return { agents, failures: remoteResult.failures };
+}
+
+export async function decorateAgentsWithPublicStatusAcrossServers(args: {
+  agents: ListedAgent[];
+  authToken: string;
+  fallbackFetchImpl?: typeof fetch;
+  fetchImpl: typeof fetch;
+  serverUrls: string[];
+}) {
+  await Promise.all(
+    args.agents.map(async (agent) => {
+      try {
+        const result = await readLiveDbRecordAfterTombstoneMerge({
+          authToken: args.authToken,
+          dbKey: agent.publicKey,
+          fallbackFetchImpl: args.fallbackFetchImpl,
+          fetchImpl: args.fetchImpl,
+          serverUrls: args.serverUrls,
+        });
+        agent.publicRecordExists = result.record?.isPublic === true;
+      } catch {
+        agent.publicRecordExists = false;
+      }
+    })
+  );
+  return args.agents;
+}