@desplega.ai/agent-swarm 1.90.0 → 1.91.0

package/src/hooks/hook.ts

@@ -11,6 +11,7 @@ import {
 } from "../be/memory/raters/llm";
 import type { Agent } from "../types";
 import { getApiKey } from "../utils/api-key";
+import { getMcpBaseUrl } from "../utils/constants";
 import { summarizeSession as runSummarize } from "../utils/internal-ai";
 import { checkToolLoop, clearToolHistory } from "./tool-loop-detection";
 
@@ -82,6 +83,27 @@ interface CancelledTasksResponse {
   cancelled: CancelledTask[];
 }
 
+/**
+ * Decide whether to show the "not registered — use join-swarm" nudge.
+ *
+ * Rules:
+ *  1. Only nudge on SessionStart — other events should not prompt re-registration.
+ *  2. If X-Agent-ID header is present the agent is pre-assigned; a null lookup
+ *     is transient, not a real "unregistered" state → suppress the nudge.
+ *  3. Only genuinely-unregistered agents (no X-Agent-ID, null lookup, SessionStart)
+ *     see the nudge.
+ */
+export function shouldShowRegistrationNudge(opts: {
+  agentInfoPresent: boolean;
+  eventType: string;
+  hasAgentIdHeader: boolean;
+}): boolean {
+  if (opts.agentInfoPresent) return false;
+  if (opts.eventType !== "SessionStart") return false;
+  if (opts.hasAgentIdHeader) return false;
+  return true;
+}
+
 /**
  * Check if a path is under the agent's own subdirectory on the shared disk.
  * Shared disk categories: thoughts, memory, downloads, misc.
@@ -150,7 +172,7 @@ async function readTaskFile(): Promise<TaskFileData | null> {
 async function fetchTaskDetails(
   taskId: string,
 ): Promise<{ id: string; task: string; progress?: string } | null> {
-  const apiUrl = process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
+  const apiUrl = getMcpBaseUrl();
   const apiKey = getApiKey();
   const headers: Record<string, string> = {};
   if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
@@ -889,13 +911,15 @@ export async function handleHook(): Promise<void> {
         console.log(tray);
       }
     }
-  } else {
+  } else if (
+    shouldShowRegistrationNudge({
+      agentInfoPresent: false,
+      eventType: msg.hook_event_name,
+      hasAgentIdHeader: hasAgentIdHeader(),
+    })
+  ) {
     console.log(
-      `You are not registered in the agent swarm yet. Use the join-swarm tool to register yourself, then check your status with my-agent-info.
-
-If the ${SERVER_NAME} server is not running or disabled, disregard this message.
-
-${hasAgentIdHeader() ? `You have a pre-defined agent ID via header: ${mcpConfig?.headers["X-Agent-ID"]}, it will be used automatically on join-swarm.` : "You do not have a pre-defined agent ID, you will receive one when you join the swarm, or optionally you can request one when calling join-swarm."}`,
+      `You are not registered in the agent swarm yet. Use the join-swarm tool to register yourself, then check your status with my-agent-info.\n\nIf the ${SERVER_NAME} server is not running or disabled, disregard this message.\n\nYou do not have a pre-defined agent ID, you will receive one when you join the swarm, or optionally you can request one when calling join-swarm.`,
     );
   }
 
@@ -1151,8 +1175,7 @@ ${hasAgentIdHeader() ? `You have a pre-defined agent ID via header: ${mcpConfig?
             editedPath.startsWith("/workspace/shared/memory/"))
         ) {
           try {
-            const apiUrl =
-              process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
+            const apiUrl = getMcpBaseUrl();
             const apiKey = getApiKey();
             const fileContent = await Bun.file(editedPath).text();
             const isShared = editedPath.startsWith("/workspace/shared/");

package/src/http/index.ts

@@ -42,6 +42,7 @@ import { handleInboxState } from "./inbox-state";
 import { handleIntegrations } from "./integrations";
 import { handleKv } from "./kv";
 import { handleMcp } from "./mcp";
+import { handleMcpBridge } from "./mcp-bridge";
 import { handleMcpOAuth, startMcpOAuthPendingGc, stopMcpOAuthPendingGc } from "./mcp-oauth";
 import { handleMcpServers } from "./mcp-servers";
 import { handleMcpUser } from "./mcp-user";
@@ -96,9 +97,47 @@ const globalState = globalThis as typeof globalThis & {
   __transportsUser?: Record<string, StreamableHTTPServerTransport>;
   __sessionUsers?: Record<string, string>;
   __sigintRegistered?: boolean;
+  __apiGcInterval?: ReturnType<typeof setInterval>;
   __runId?: string;
 };
 
+const API_GC_INTERVAL_MS = 5 * 60 * 1000;
+
+type GcCapableGlobal = typeof globalThis & { gc?: () => void };
+
+function scheduleApiGc(reason: string): boolean {
+  const gc = (globalThis as GcCapableGlobal).gc;
+  if (typeof gc !== "function") return false;
+
+  const timer = setTimeout(() => {
+    const startedAt = Date.now();
+    try {
+      gc();
+      console.log(`[HTTP] Explicit GC completed after ${reason} in ${Date.now() - startedAt}ms`);
+    } catch (err) {
+      console.warn(`[HTTP] Explicit GC failed after ${reason}: ${err}`);
+    }
+  }, 0);
+  timer.unref?.();
+  return true;
+}
+
+function startApiGcInterval() {
+  if (globalState.__apiGcInterval) return;
+
+  const gc = (globalThis as GcCapableGlobal).gc;
+  if (typeof gc !== "function") {
+    console.log("[HTTP] Explicit GC unavailable; start API with --expose-gc to enable sweeps");
+    return;
+  }
+
+  const interval = setInterval(() => {
+    scheduleApiGc("periodic API sweep");
+  }, API_GC_INTERVAL_MS);
+  interval.unref?.();
+  globalState.__apiGcInterval = interval;
+}
+
 // Clean up previous server on hot reload
 if (globalState.__httpServer) {
   console.log("[HTTP] Hot reload detected, closing previous server...");
@@ -234,6 +273,7 @@ const httpServer = createHttpServer(async (req, res) => {
         () => handleRepos(req, res, pathSegments, queryParams),
         () => handleSkills(req, res, pathSegments, queryParams, myAgentId),
         () => handleScripts(req, res, pathSegments, queryParams, myAgentId),
+        () => handleMcpBridge(req, res, pathSegments, queryParams, myAgentId),
         () => handleMcpServers(req, res, pathSegments, queryParams),
         () => handleMcpOAuth(req, res, pathSegments, queryParams),
         () => handleMemory(req, res, pathSegments, myAgentId),
@@ -315,6 +355,11 @@ async function shutdown() {
   // Stop MCP OAuth pending-session garbage collector
   stopMcpOAuthPendingGc();
 
+  if (globalState.__apiGcInterval) {
+    clearInterval(globalState.__apiGcInterval);
+    delete globalState.__apiGcInterval;
+  }
+
   // Close all active transports (SSE connections, etc.)
   for (const [id, transport] of Object.entries(transports)) {
     console.log(`[HTTP] Closing transport ${id}`);
@@ -349,6 +394,8 @@ if (!globalState.__runId) {
   globalState.__runId = `run_${Date.now()}`;
 }
 
+startApiGcInterval();
+
 // Load global swarm configs before the server starts listening so decrypt/key
 // failures fail closed instead of leaving the runtime half-initialized.
 let startupConfigsInjected: string[] = [];

package/src/http/integrations.ts

@@ -88,7 +88,12 @@ function resolveConfigValue(key: string): string | null {
 }
 
 function resolveMcpBaseUrl(): string {
-  const configured = resolveConfigValue("MCP_BASE_URL");
+  // Browser-facing connect URLs: prefer the public ingress origin
+  // (PUBLIC_MCP_BASE_URL) over the internal MCP_BASE_URL so split deployments
+  // (Helm) surface a host the user's browser can actually reach. Both honor the
+  // swarm_config → env resolution order. Falls back to the localhost dev base.
+  const configured =
+    resolveConfigValue("PUBLIC_MCP_BASE_URL") ?? resolveConfigValue("MCP_BASE_URL");
   const fallback = `http://localhost:${process.env.PORT || "3013"}`;
   return (configured || fallback).replace(/\/+$/, "");
 }

package/src/http/mcp-bridge.ts

@@ -0,0 +1,117 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { createServer } from "@/server";
+import { isSdkToolAllowed } from "../scripts-runtime/sdk-allowlist";
+import { route } from "./route-def";
+import { json, jsonError } from "./utils";
+
+// Lazy singleton — created once on first bridge call to avoid boot-time cost.
+let _bridgeServer: McpServer | null = null;
+function getBridgeServer(): McpServer {
+  if (!_bridgeServer) {
+    _bridgeServer = createServer();
+  }
+  return _bridgeServer;
+}
+
+type RegisteredTool = {
+  handler: Function;
+  inputSchema?: unknown;
+  enabled?: boolean;
+};
+
+type ToolRegistry = Record<string, RegisteredTool>;
+
+const mcpBridgeRoute = route({
+  method: "post",
+  path: "/api/mcp-bridge",
+  pattern: ["api", "mcp-bridge"],
+  summary: "Generic MCP tool proxy for the scripts SDK bridge",
+  tags: ["Scripts"],
+  body: z.object({
+    tool: z.string().min(1).max(200),
+    args: z.record(z.string(), z.unknown()).default({}),
+  }),
+  responses: {
+    200: { description: "Tool result" },
+    400: { description: "Invalid tool name or args" },
+    403: { description: "Tool not in SDK allowlist" },
+    404: { description: "Tool not found" },
+  },
+});
+
+export async function handleMcpBridge(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  _queryParams?: URLSearchParams,
+  myAgentId?: string,
+): Promise<boolean> {
+  if (!mcpBridgeRoute.match(req.method, pathSegments)) return false;
+
+  const parsed = await mcpBridgeRoute.parse(req, res, pathSegments, new URLSearchParams());
+  if (!parsed) return true;
+
+  const { tool: toolName, args } = parsed.body;
+
+  if (!isSdkToolAllowed(toolName)) {
+    jsonError(res, `Tool '${toolName}' is not in the SDK allowlist`, 403);
+    return true;
+  }
+
+  const server = getBridgeServer();
+  const tools = (server as unknown as { _registeredTools: ToolRegistry })._registeredTools;
+
+  const tool = tools[toolName];
+  if (!tool) {
+    jsonError(res, `Tool '${toolName}' not found in the MCP registry`, 404);
+    return true;
+  }
+
+  if (tool.enabled === false) {
+    jsonError(res, `Tool '${toolName}' is disabled`, 400);
+    return true;
+  }
+
+  const sourceTaskId = Array.isArray(req.headers["x-source-task-id"])
+    ? req.headers["x-source-task-id"][0]
+    : (req.headers["x-source-task-id"] as string | undefined);
+
+  const extra = {
+    sessionId: "mcp-bridge",
+    requestInfo: {
+      headers: {
+        "x-agent-id": myAgentId ?? "",
+        ...(sourceTaskId ? { "x-source-task-id": sourceTaskId } : {}),
+      },
+    },
+  };
+
+  try {
+    const result = tool.inputSchema
+      ? await Promise.resolve(tool.handler(args, extra))
+      : await Promise.resolve(tool.handler(extra));
+
+    if (result && typeof result === "object" && "structuredContent" in result) {
+      json(res, result.structuredContent);
+    } else if (result && typeof result === "object" && "content" in result) {
+      const content = (result as { content: Array<{ type: string; text?: string }> }).content;
+      const text = content
+        .filter((c) => c.type === "text" && c.text)
+        .map((c) => c.text)
+        .join("\n");
+      try {
+        json(res, JSON.parse(text));
+      } catch {
+        json(res, { result: text });
+      }
+    } else {
+      json(res, result ?? {});
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    jsonError(res, message, 500);
+  }
+  return true;
+}

package/src/http/mcp-oauth.ts

@@ -1,6 +1,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import { getMcpServerById } from "../be/db";
+import type { McpOAuthToken } from "../be/db-queries/mcp-oauth";
 import {
   applyMcpOAuthRefresh,
   consumeMcpOAuthPending,
@@ -23,6 +24,7 @@ import {
   registerClient,
   revokeMcpToken,
 } from "../oauth/mcp-wrapper";
+import { getAppUrl, getPublicMcpBaseUrl } from "../utils/constants";
 import { route } from "./route-def";
 import { json, jsonError } from "./utils";
 
@@ -36,12 +38,14 @@ function ssrfOptions() {
 }
 
 function callbackRedirectUri(): string {
-  const base = process.env.APP_URL?.replace(/\/+$/, "") ?? "http://localhost:3013";
-  return `${base}/api/mcp-oauth/callback`;
+  // The callback route lives on the API server, so it must use the PUBLIC MCP
+  // base (externally reachable), not the dashboard APP_URL.
+  return `${getPublicMcpBaseUrl()}/api/mcp-oauth/callback`;
 }
 
 function dashboardBase(): string {
-  return process.env.DASHBOARD_URL?.replace(/\/+$/, "") ?? "http://localhost:5274";
+  // getAppUrl absorbs DASHBOARD_URL as a deprecated alias.
+  return getAppUrl();
 }
 
 function defaultFinalRedirect(mcpServerId: string): string {
@@ -61,6 +65,43 @@ interface DiscoveryResult {
   bearerMethodsSupported: string[] | null;
 }
 
+interface OAuthClientForAuthorize {
+  clientId: string;
+  clientSecret: string | null;
+  resourceUrl: string;
+  authorizationServerIssuer: string;
+  authorizeUrl: string;
+  tokenUrl: string;
+  revocationUrl: string | null;
+  scopes: string[];
+}
+
+function splitScopes(scopes: string | null | undefined): string[] {
+  return scopes?.split(/\s+/).filter(Boolean) ?? [];
+}
+
+function manualClientFromToken(token: McpOAuthToken | null): OAuthClientForAuthorize | null {
+  if (!token || token.clientSource !== "manual" || !token.dcrClientId) return null;
+
+  // The manual-client route validates these on write. Re-check before using the
+  // stored endpoints because /authorize redirects the browser to authorizeUrl.
+  assertUrlSafe(token.resourceUrl, ssrfOptions());
+  assertUrlSafe(token.authorizeUrl, ssrfOptions());
+  assertUrlSafe(token.tokenUrl, ssrfOptions());
+  if (token.revocationUrl) assertUrlSafe(token.revocationUrl, ssrfOptions());
+
+  return {
+    clientId: token.dcrClientId,
+    clientSecret: token.dcrClientSecret,
+    resourceUrl: token.resourceUrl,
+    authorizationServerIssuer: token.authorizationServerIssuer,
+    authorizeUrl: token.authorizeUrl,
+    tokenUrl: token.tokenUrl,
+    revocationUrl: token.revocationUrl,
+    scopes: splitScopes(token.scope),
+  };
+}
+
 async function discoverForMcp(resourceUrl: string): Promise<DiscoveryResult | null> {
   assertUrlSafe(resourceUrl, ssrfOptions());
 
@@ -266,10 +307,10 @@ interface AuthorizeFlowQuery {
 }
 
 /**
- * Discover metadata, DCR-register (or fail), build the authorize URL, and
- * persist the pending session. Returns the provider `providerUrl` the caller
- * should redirect to / respond with. On failure, writes a JSON error response
- * and returns null.
+ * Use a stored manual client or discover metadata + DCR-register, build the
+ * authorize URL, and persist the pending session. Returns the provider
+ * `providerUrl` the caller should redirect to / respond with. On failure,
+ * writes a JSON error response and returns null.
  */
 async function prepareAuthorizeFlow(
   res: ServerResponse,
@@ -277,15 +318,26 @@ async function prepareAuthorizeFlow(
   server: NonNullable<ReturnType<typeof getMcpServerById>>,
   q: AuthorizeFlowQuery,
 ): Promise<string | null> {
-  const discovery = await discoverForMcp(server.url!);
-  if (!discovery) {
-    jsonError(res, "MCP server does not require OAuth", 400);
-    return null;
-  }
+  const userId = q.userId ?? null;
+  let client = manualClientFromToken(getMcpOAuthToken(mcpServerId, userId));
+
+  if (!client) {
+    const discovery = await discoverForMcp(server.url!);
+    if (!discovery) {
+      jsonError(res, "MCP server does not require OAuth", 400);
+      return null;
+    }
 
-  let clientId: string | null = null;
-  let clientSecret: string | null = null;
-  if (discovery.dcrSupported && discovery.registrationEndpoint) {
+    if (!discovery.dcrSupported || !discovery.registrationEndpoint) {
+      jsonError(
+        res,
+        "DCR not supported — paste client_id/client_secret via POST /api/mcp-oauth/:id/manual-client first.",
+        400,
+      );
+      return null;
+    }
+
+    const scopes = q.scopes ? splitScopes(q.scopes) : discovery.scopes;
     const dcr = await registerClient(discovery.registrationEndpoint, {
       client_name: `agent-swarm (${server.name})`,
       redirect_uris: [callbackRedirectUri()],
@@ -293,43 +345,45 @@ async function prepareAuthorizeFlow(
       response_types: ["code"],
       token_endpoint_auth_method: "client_secret_basic",
       application_type: "web",
-      scope: (q.scopes ?? discovery.scopes.join(" ")) || undefined,
+      scope: scopes.join(" ") || undefined,
     });
-    clientId = dcr.client_id;
-    clientSecret = dcr.client_secret ?? null;
-  } else {
-    jsonError(
-      res,
-      "DCR not supported — paste client_id/client_secret via POST /api/mcp-oauth/:id/manual-client first.",
-      400,
-    );
-    return null;
+
+    client = {
+      clientId: dcr.client_id,
+      clientSecret: dcr.client_secret ?? null,
+      resourceUrl: discovery.resourceUrl,
+      authorizationServerIssuer: discovery.authorizationServerIssuer,
+      authorizeUrl: discovery.authorizeUrl,
+      tokenUrl: discovery.tokenUrl,
+      revocationUrl: discovery.revocationUrl,
+      scopes,
+    };
   }
 
-  const scopes = q.scopes ? q.scopes.split(" ").filter(Boolean) : discovery.scopes;
+  const scopes = q.scopes ? splitScopes(q.scopes) : client.scopes;
 
   const built = await buildAuthorizeUrl({
-    authorizeUrl: discovery.authorizeUrl,
-    tokenUrl: discovery.tokenUrl,
-    clientId: clientId!,
+    authorizeUrl: client.authorizeUrl,
+    tokenUrl: client.tokenUrl,
+    clientId: client.clientId,
     redirectUri: callbackRedirectUri(),
     scopes,
-    resource: discovery.resourceUrl,
+    resource: client.resourceUrl,
   });
 
   insertMcpOAuthPending({
     state: built.state,
     mcpServerId,
-    userId: q.userId ?? null,
+    userId,
     codeVerifier: built.codeVerifier,
-    resourceUrl: discovery.resourceUrl,
-    authorizationServerIssuer: discovery.authorizationServerIssuer,
-    authorizeUrl: discovery.authorizeUrl,
-    tokenUrl: discovery.tokenUrl,
-    revocationUrl: discovery.revocationUrl,
+    resourceUrl: client.resourceUrl,
+    authorizationServerIssuer: client.authorizationServerIssuer,
+    authorizeUrl: client.authorizeUrl,
+    tokenUrl: client.tokenUrl,
+    revocationUrl: client.revocationUrl,
     scopes: scopes.join(" "),
-    dcrClientId: clientId!,
-    dcrClientSecret: clientSecret,
+    dcrClientId: client.clientId,
+    dcrClientSecret: client.clientSecret,
     redirectUri: callbackRedirectUri(),
     finalRedirect: q.redirect ?? null,
   });
@@ -390,6 +444,10 @@ export async function handleMcpOAuth(
         codeVerifier: pending.codeVerifier,
         resource: pending.resourceUrl,
       });
+      const existing = getMcpOAuthToken(pending.mcpServerId, pending.userId);
+      const clientSource =
+        existing?.clientSource ??
+        (pending.dcrClientId ? ("dcr" as const) : ("preregistered" as const));
 
       upsertMcpOAuthToken({
         mcpServerId: pending.mcpServerId,
@@ -406,7 +464,7 @@ export async function handleMcpOAuth(
         revocationUrl: pending.revocationUrl,
         dcrClientId: pending.dcrClientId,
         dcrClientSecret: pending.dcrClientSecret,
-        clientSource: pending.dcrClientId ? "dcr" : "preregistered",
+        clientSource,
         lastRefreshedAt: new Date().toISOString(),
       });
 

package/src/http/memory.ts

@@ -54,6 +54,8 @@ const searchMemory = route({
   body: z.object({
     query: z.string().min(1),
     limit: z.number().int().min(1).max(20).default(5),
+    scope: z.enum(["agent", "swarm", "all"]).default("all"),
+    source: z.enum(["manual", "file_index", "session_summary", "task_completion"]).optional(),
   }),
   responses: {
     200: { description: "Search results" },
@@ -325,7 +327,7 @@ export async function handleMemory(
     const parsed = await searchMemory.parse(req, res, pathSegments, new URLSearchParams());
     if (!parsed) return true;
 
-    const { query, limit } = parsed.body;
+    const { query, limit, scope, source } = parsed.body;
 
     try {
       const provider = getEmbeddingProvider();
@@ -339,8 +341,9 @@ export async function handleMemory(
 
       const candidateLimit = Math.min(limit, 20) * CANDIDATE_SET_MULTIPLIER;
       const candidates = store.search(queryEmbedding, myAgentId, {
-        scope: "all",
+        scope,
         limit: candidateLimit,
+        source,
         isLead: false,
       });
       const ranked = rerank(candidates, { limit: Math.min(limit, 20) });

package/src/http/openapi.ts

@@ -4,6 +4,7 @@ import {
   OpenApiGeneratorV31,
 } from "@asteasolutions/zod-to-openapi";
 import { z } from "zod";
+import { getPublicMcpBaseUrl } from "../utils/constants";
 import { routeRegistry } from "./route-def";
 
 extendZodWithOpenApi(z);
@@ -74,8 +75,7 @@ export function generateOpenApiSpec(opts: OpenApiOptions): string {
     });
   }
 
-  const serverUrl =
-    opts.serverUrl || process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
+  const serverUrl = opts.serverUrl || getPublicMcpBaseUrl();
 
   const generator = new OpenApiGeneratorV31(registry.definitions);
   const doc = generator.generateDocument({

package/src/http/pages-public.ts

@@ -25,6 +25,7 @@ import { z } from "zod";
 import { BROWSER_SDK_JS, SWARM_UI_JS } from "../artifact-sdk/browser-sdk";
 import { getPage, incrementPageViewCount } from "../be/db";
 import type { Page } from "../types";
+import { getAppUrl, getConfiguredAppUrls } from "../utils/constants";
 import { extractAndVerifyCookie, issuePageSessionCookie } from "../utils/page-session";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { route } from "./route-def";
@@ -159,14 +160,15 @@ function stripJsonSuffix(idSegment: string): string | null {
 }
 
 /**
- * Compute the SPA base URL (`APP_URL`). Mirrors `getAppBaseUrl` in pages.ts —
- * duplicated here to keep this module standalone (no cross-import inside the
- * http/ layer).
+ * Compute the SPA base URL. Public JSON pages historically redirect to the
+ * local dashboard when no app URL is configured; keep that route-local
+ * fallback while still delegating `APP_URL`/`DASHBOARD_URL` resolution to the
+ * shared helper.
  */
+const LOCAL_PAGE_APP_URL = "http://localhost:5274";
+
 function getAppBaseUrl(): string {
-  const env = process.env.APP_URL?.trim();
-  if (env) return env.replace(/\/+$/, "");
-  return "http://localhost:5274";
+  return getAppUrl(LOCAL_PAGE_APP_URL);
 }
 
 /**
@@ -177,15 +179,12 @@ function getAppBaseUrl(): string {
  */
 function buildCsp(): string {
   // `frame-ancestors` lists every origin allowed to iframe `/p/:id`. We must
-  // include the SPA origin(s). `APP_URL` may carry a comma-separated list so
+  // include the SPA origin(s). Configured app URLs may be comma-separated so
   // portless dev (`https://ui.swarm.localhost`), a Vite port (`http://localhost:5274`),
   // and a tunnel/staging origin can all coexist. Additionally, in non-production
   // we always allow `http://localhost:*` and `https://*.localhost` so swapping
   // between Vite ports / portless dev doesn't require restarting the API.
-  const configured = (process.env.APP_URL ?? "")
-    .split(",")
-    .map((s) => s.trim().replace(/\/+$/, ""))
-    .filter(Boolean);
+  const configured = getConfiguredAppUrls();
   const devFallbacks =
     process.env.NODE_ENV === "production"
       ? []

package/src/http/pages.ts

@@ -14,6 +14,7 @@ import {
 } from "../be/db";
 import { snapshotPage } from "../pages/version";
 import { type Page, PageAuthModeSchema, PageContentTypeSchema, type PageSummary } from "../types";
+import { getAppUrl, getPublicMcpBaseUrl } from "../utils/constants";
 import { issuePageSessionCookie } from "../utils/page-session";
 import { route } from "./route-def";
 import { BODY_TOO_LARGE, enforceContentLengthCap, json, jsonError } from "./utils";
@@ -280,25 +281,20 @@ function applyLaunchCors(req: IncomingMessage, res: ServerResponse): void {
 
 /**
  * Resolve the public API base URL used to build a page's `api_url` share
- * pointer. Falls back to `http://localhost:<PORT>` when `MCP_BASE_URL` is
- * unset (same convention as src/tools/memory-rate.ts, etc.). Trailing slashes
- * are stripped so callers can concatenate `/p/:id` directly.
+ * pointer (handed to a browser). Delegates to the shared
+ * {@link getPublicMcpBaseUrl} helper (trailing slashes already stripped) so
+ * callers can concatenate `/p/:id` directly.
  */
 function getApiBaseUrl(): string {
-  const env = process.env.MCP_BASE_URL?.trim();
-  if (env) return env.replace(/\/+$/, "");
-  return `http://localhost:${process.env.PORT || "3013"}`;
+  return getPublicMcpBaseUrl();
 }
 
 /**
  * Resolve the SPA / dashboard base URL used to build a page's `app_url` share
- * pointer (→ `/pages/:id`). `APP_URL` is the canonical env (matches the
- * request-human-input tool); falls back to the local dev port `5274`.
+ * pointer (→ `/pages/:id`). Delegates to the shared {@link getAppUrl} helper.
  */
 function getAppBaseUrl(): string {
-  const env = process.env.APP_URL?.trim();
-  if (env) return env.replace(/\/+$/, "");
-  return "http://localhost:5274";
+  return getAppUrl();
 }
 
 /** Decorate a page row with share-URL pointers. */