@openhands/agent-canvas 1.14.0 → 1.16.0

package/scripts/dev-safe.mjs

@@ -37,6 +37,11 @@ const SHARED_DEFAULTS = JSON.parse(
 );
 
 const DEFAULT_BACKEND_PORT = SHARED_DEFAULTS.ports.agentServer;
+// Path prefix the bundled editor is served under. The same value has to reach
+// agent-server (as OH_VSCODE_BASE_PATH, so openvscode-server is launched with
+// --server-base-path and advertises the prefix) and the ingress route table,
+// or the advertised URL and the route that serves it disagree.
+export const VSCODE_BASE_PATH = SHARED_DEFAULTS.paths.vscodeBasePath;
 const DEFAULT_VITE_PORT = 3001;
 const DEFAULT_WAIT_TIMEOUT_MS = 30_000;
 const DEFAULT_AGENT_SERVER_PACKAGE = SHARED_DEFAULTS.packages.agentServer;
@@ -396,6 +401,16 @@ export function validateFrontendDependencies(
   }
 }
 
+/**
+ * Modules the agent-server imports at startup (`--import-modules`). They are
+ * resolved from `tools/`, which `buildAgentServerEnv` exposes through
+ * OH_EXTRA_PYTHON_PATH. Importing `canvas_ui_tool` eagerly registers the SDK's
+ * builtin FinishTool so automation presets (openhands-automation >= 1.9.0) can
+ * resolve it on the remote conversations they dispatch — see the note at the
+ * bottom of tools/canvas_ui_tool.py.
+ */
+export const AGENT_SERVER_IMPORT_MODULES = "canvas_ui_tool";
+
 /**
  * Build the uvx command and arguments for running agent-server.
  *
@@ -406,7 +421,7 @@ export function validateFrontendDependencies(
  *   edits are picked up without a manual reinstall. The agent-server itself
  *   is rebuilt from local source on each invocation (--reinstall).
  * - OH_AGENT_SERVER_GIT_REF: Git commit SHA or branch name
- * - OH_AGENT_SERVER_VERSION: Specific PyPI version (e.g., "1.42.1")
+ * - OH_AGENT_SERVER_VERSION: Specific PyPI version (e.g., "1.44.0")
  *
  * If none are set, defaults to the released version specified by
  * DEFAULT_AGENT_SERVER_VERSION. Set OH_AGENT_SERVER_GIT_REF to use a
@@ -511,6 +526,10 @@ export function buildAgentServerCommand(env = process.env) {
     source = `PyPI (${DEFAULT_AGENT_SERVER_VERSION}, default)`;
   }
 
+  // Everything after the executable name is an agent-server CLI argument.
+  // Import the registration module before any conversation is created.
+  uvxArgs.push("--import-modules", AGENT_SERVER_IMPORT_MODULES);
+
   return {
     command: "uvx",
     args: uvxArgs,
@@ -599,6 +618,7 @@ export async function buildSafeDevConfigAsync(
  * @property {string} cwd
  * @property {number} backendPort
  * @property {number} vscodePort
+ * @property {string} vscodeBasePath
  * @property {string} stateDir
  * @property {string} tmuxTmpDir
  * @property {string} conversationsPath
@@ -657,6 +677,7 @@ function buildConfigFromPorts(ports, cwd, env) {
     cwd,
     backendPort,
     vscodePort,
+    vscodeBasePath: VSCODE_BASE_PATH,
     stateDir,
     // tmux socket directory. Defaults to <stateDir>/tmux (under
     // ~/.openhands/agent-canvas), matching where the rest of dev state lives
@@ -688,13 +709,13 @@ function buildConfigFromPorts(ports, cwd, env) {
 }
 
 /**
- * Build the environment variables object for spawning the agent-server process.
+ * Telemetry-related env vars for the agent-server process.
  *
- * This is exported so downstream consumers (e.g., automation service) can use
- * the same env vars without duplicating the mapping logic.
+ * Split out from `buildAgentServerEnv` so callers that assemble their own
+ * agent-server environment can reuse the same mapping.
  *
- * @param {ReturnType<typeof buildSafeDevConfig>} config - Config from buildSafeDevConfig
- * @returns {Record<string, string>} Environment variables for agent-server
+ * @param {Record<string, string | undefined>} [env] - Source environment.
+ * @returns {Record<string, string>} Telemetry env vars for agent-server
  */
 export function buildAgentServerTelemetryEnv(env = process.env) {
   const telemetryDisabled =
@@ -739,7 +760,35 @@ export function buildAgentServerTelemetryEnv(env = process.env) {
   return result;
 }
 
-export function buildAgentServerEnv(config, env = process.env) {
+/**
+ * Build the environment variables object for spawning the agent-server process.
+ *
+ * This is exported so downstream consumers (e.g., automation service) can use
+ * the same env vars without duplicating the mapping logic.
+ *
+ * `vscodeBasePath` is an explicit opt-in rather than a field read off `config`,
+ * and that is deliberate. Setting it changes the URL `/api/vscode/url`
+ * advertises: agent-server appends the prefix to the browser origin the
+ * frontend sends, so the editor is only reachable if the same origin also
+ * routes that prefix to the editor port. A launcher that sets it without
+ * registering the route advertises `<origin>/vscode/…`, which serves the
+ * canvas SPA shell instead of the editor.
+ *
+ * Requiring the caller to name it makes the pairing greppable: every call site
+ * that passes `vscodeBasePath` must also register a matching route, and
+ * `__tests__/scripts/vscode-base-path-opt-in.test.ts` asserts that no launcher
+ * opts in without one.
+ *
+ * @param {ReturnType<typeof buildSafeDevConfig>} config - Config from buildSafeDevConfig
+ * @param {{vscodeBasePath?: string | null, env?: Record<string, string | undefined>}} [options]
+ * @param {string | null} [options.vscodeBasePath] - Opt into prefix-mode by
+ *   passing the path prefix the caller also routes to `config.vscodePort`.
+ * @param {Record<string, string | undefined>} [options.env] - Source
+ *   environment for the telemetry mapping (defaults to `process.env`).
+ * @returns {Record<string, string>} Environment variables for agent-server
+ */
+export function buildAgentServerEnv(config, options = {}) {
+  const { vscodeBasePath = null, env = process.env } = options;
   return {
     ...buildAgentServerTelemetryEnv(env),
     // Force Python to use UTF-8 for all file I/O and streams.
@@ -759,6 +808,13 @@ export function buildAgentServerEnv(config, env = process.env) {
     OH_CONVERSATIONS_PATH: config.conversationsPath,
     OH_BASH_EVENTS_DIR: config.bashEventsDir,
     OH_VSCODE_PORT: String(config.vscodePort),
+    // Serve the editor under a path prefix on the canvas origin rather than on
+    // its own published port. agent-server passes this to openvscode-server as
+    // --server-base-path and includes it in the URL from /api/vscode/url, which
+    // matches the ingress route the caller registers for the same prefix.
+    //
+    // Omitted unless the caller opts in — see the note on this function.
+    ...(vscodeBasePath ? { OH_VSCODE_BASE_PATH: vscodeBasePath } : {}),
     OH_SECRET_KEY: config.secretKey,
     // Use OH_SESSION_API_KEYS_0 for agent-server V1 config format
     OH_SESSION_API_KEYS_0: config.sessionApiKey,
@@ -954,7 +1010,12 @@ async function main() {
       cwd: config.cwd,
       env: {
         ...process.env,
-        ...buildAgentServerEnv(config),
+        // Opt into prefix-mode: the Vite dev server proxies the same prefix to
+        // `config.vscodePort` (see VITE_VSCODE_TARGET below), so the advertised
+        // URL resolves on the frontend origin the browser is actually on.
+        ...buildAgentServerEnv(config, {
+          vscodeBasePath: config.vscodeBasePath,
+        }),
       },
     },
   );
@@ -986,6 +1047,12 @@ async function main() {
 
   process.on("SIGINT", () => shutdown("SIGINT"));
   process.on("SIGTERM", () => shutdown("SIGTERM"));
+  // Services are spawned detached, so a SIGHUP that kills this launcher (terminal
+  // or multiplexer death) would otherwise leave the whole tree running. Forward
+  // SIGTERM rather than SIGHUP: uvicorn only handles SIGINT/SIGTERM, so a
+  // forwarded SIGHUP would terminate the agent-server by default action instead
+  // of shutting it down gracefully.
+  process.on("SIGHUP", () => shutdown("SIGTERM"));
 
   const backendErrored = new Promise((_, reject) => {
     backend.once("error", (error) => reject(error));
@@ -1023,6 +1090,12 @@ async function main() {
       VITE_WORKING_DIR: config.workingDir,
       // Pass session API key so frontend can authenticate with agent-server
       VITE_SESSION_API_KEY: config.sessionApiKey,
+      // This mode has no static server or ingress in front of Vite, so Vite's
+      // own proxy is the only thing that can serve the editor prefix on the
+      // frontend origin. The editor is a separate process on a port of its
+      // own, so it needs its own proxy target rather than VITE_BACKEND_HOST.
+      VITE_VSCODE_BASE_PATH: config.vscodeBasePath,
+      VITE_VSCODE_TARGET: `http://127.0.0.1:${config.vscodePort}`,
       // dev:minimal deliberately does NOT supply runtime-services info (the
       // frontend here talks straight to the agent-server over
       // VITE_BACKEND_BASE_URL — there is no ingress or static-server in front

package/scripts/dev-static.mjs

@@ -63,6 +63,11 @@ import {
   buildAutomationTelemetryEnv,
   buildAutomationRuntimeServicesInfo,
   buildConfig,
+  buildRouteArgs,
+  getAgentServerBaseUrl,
+  getLocalServiceRoutes,
+  getNoReferrerPrefixArgs,
+  getVSCodeAdvertiseArgs,
 } from "./dev-with-automation.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -285,6 +290,27 @@ async function waitForService(name, url, timeoutMs = 30000) {
 // dev-with-automation; the only difference is the frontend service.)
 // ═══════════════════════════════════════════════════════════════════════════
 
+// The static server and the ingress proxy front the same local backends, so
+// they share one route table — dev-with-automation's, rather than a second
+// copy here. The copy this replaces claimed to stay identical to that table
+// but nothing enforced it, and it had already drifted: the editor prefix was
+// missing, so `/vscode` fell through to the SPA fallback and answered editor
+// requests with the canvas shell.
+//
+// This mode always launches both local backends (it never runs frontend-only),
+// so it asks for their routes unconditionally. Every target is IPv4 loopback:
+// the backends bind to `0.0.0.0`, which only accepts IPv4, but localhost can
+// resolve to ::1 first (notably on Windows).
+function buildLocalServiceRouteArgs(config) {
+  return buildRouteArgs(
+    getLocalServiceRoutes({
+      ...config,
+      launchAgentServer: true,
+      launchAutomation: true,
+    }),
+  );
+}
+
 function startAgentServer(config) {
   logService(
     "agent-server",
@@ -303,7 +329,12 @@ function startAgentServer(config) {
   });
 
   const agentServerEnv = {
-    ...buildAgentServerEnv(safeConfig),
+    // Opt into prefix-mode: both the static server and the ingress below build
+    // their route tables from `getLocalServiceRoutes`, which registers this
+    // same prefix against `config.vscodePort`.
+    ...buildAgentServerEnv(safeConfig, {
+      vscodeBasePath: config.vscodeBasePath,
+    }),
     ...buildAgentServerAutomationEnv(config),
   };
 
@@ -328,7 +359,7 @@ function startAgentServer(config) {
 function buildAutomationBackendEnv(config, env = process.env) {
   // Both backends share the same session API key value.
   return {
-    AUTOMATION_AGENT_SERVER_URL: `http://localhost:${config.agentServerPort}`,
+    AUTOMATION_AGENT_SERVER_URL: getAgentServerBaseUrl(config),
     AUTOMATION_AGENT_SERVER_API_KEY: config.sessionApiKey,
     AUTOMATION_DB_URL: `sqlite+aiosqlite:///${join(config.stateDir, "automations.db")}`,
     AUTOMATION_BASE_URL: `http://localhost:${config.ingressPort}`,
@@ -405,26 +436,12 @@ function startStaticServer(config) {
         : []),
       "--runtime-services-info",
       runtimeServicesInfo,
-      "--route",
-      `/api/automation=http://localhost:${config.autoBackendPort}`,
-      "--route",
-      `/api=http://localhost:${config.agentServerPort}`,
-      "--route",
-      `/sockets=http://localhost:${config.agentServerPort}`,
-      "--route",
-      `/server_info=http://localhost:${config.agentServerPort}`,
-      "--route",
-      `/health=http://localhost:${config.agentServerPort}`,
-      "--route",
-      `/ready=http://localhost:${config.agentServerPort}`,
-      "--route",
-      `/alive=http://localhost:${config.agentServerPort}`,
-      "--route",
-      `/docs=http://localhost:${config.agentServerPort}`,
-      "--route",
-      `/redoc=http://localhost:${config.agentServerPort}`,
-      "--route",
-      `/openapi.json=http://localhost:${config.agentServerPort}`,
+      ...buildLocalServiceRouteArgs(config),
+      // Only the static server injects into the document, so only it can tell
+      // the frontend this origin serves the editor. The ingress below routes
+      // the same prefix but proxies the HTML through untouched.
+      ...getVSCodeAdvertiseArgs(config),
+      ...getNoReferrerPrefixArgs(config),
     ],
     {
       cwd: config.canvasPath,
@@ -453,26 +470,8 @@ function startIngress(config) {
       config.ingressPort.toString(),
       "--runtime-services-info",
       runtimeServicesInfo,
-      "--route",
-      `/api/automation=http://localhost:${config.autoBackendPort}`,
-      "--route",
-      `/api=http://localhost:${config.agentServerPort}`,
-      "--route",
-      `/sockets=http://localhost:${config.agentServerPort}`,
-      "--route",
-      `/server_info=http://localhost:${config.agentServerPort}`,
-      "--route",
-      `/health=http://localhost:${config.agentServerPort}`,
-      "--route",
-      `/ready=http://localhost:${config.agentServerPort}`,
-      "--route",
-      `/alive=http://localhost:${config.agentServerPort}`,
-      "--route",
-      `/docs=http://localhost:${config.agentServerPort}`,
-      "--route",
-      `/redoc=http://localhost:${config.agentServerPort}`,
-      "--route",
-      `/openapi.json=http://localhost:${config.agentServerPort}`,
+      ...buildLocalServiceRouteArgs(config),
+      ...getNoReferrerPrefixArgs(config),
       "--default",
       `http://localhost:${config.vitePort}`,
     ],
@@ -621,7 +620,7 @@ async function main() {
   startAgentServer(config);
   await waitForService(
     "agent-server",
-    `http://localhost:${config.agentServerPort}/server_info`,
+    `${getAgentServerBaseUrl(config)}/server_info`,
   );
 
   startAutomationBackend(config);
@@ -641,7 +640,12 @@ async function main() {
 // Exports for testing
 // ═══════════════════════════════════════════════════════════════════════════
 
-export { buildAutomationBackendEnv, buildFrontend, startStaticServer };
+export {
+  buildAutomationBackendEnv,
+  buildFrontend,
+  buildLocalServiceRouteArgs,
+  startStaticServer,
+};
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Main entry point (only when run directly, not when imported)

package/scripts/dev-with-automation.mjs

@@ -485,6 +485,10 @@ async function buildConfig(args, env = process.env) {
     autoBackendPort: preferredAutomationPort,
     vitePort: preferredVitePort,
     vscodePort,
+    // Prefix the editor is served under on the ingress origin. Carried on the
+    // config so the route table and the agent-server env are built from one
+    // value (see getLocalServiceRoutes / buildAgentServerEnv).
+    vscodeBasePath: safeConfig.vscodeBasePath,
 
     // Paths
     canvasPath: projectRoot,
@@ -735,6 +739,13 @@ const AGENT_SERVER_ROUTE_PREFIXES = [
   "/openapi.json",
 ];
 
+// This launcher starts the agent-server with `--host 127.0.0.1`, but localhost
+// can resolve to ::1 first (notably on Windows), so every request this process
+// or the automation backend makes to it must address IPv4 explicitly.
+function getAgentServerBaseUrl(config) {
+  return `http://127.0.0.1:${config.agentServerPort}`;
+}
+
 function getLocalServiceRoutes(config) {
   const routes = [];
 
@@ -748,7 +759,21 @@ function getLocalServiceRoutes(config) {
 
   if (config.launchAgentServer) {
     for (const prefix of AGENT_SERVER_ROUTE_PREFIXES) {
-      routes.push([prefix, `http://127.0.0.1:${config.agentServerPort}`]);
+      routes.push([prefix, getAgentServerBaseUrl(config)]);
+    }
+
+    // The editor is a separate process on its own port, but it is reached
+    // through the same origin as the canvas so no second port has to be
+    // published. The prefix is deliberately preserved rather than stripped:
+    // agent-server launches openvscode-server with `--server-base-path`, so
+    // the editor generates its own HTTP and WebSocket URLs beneath the prefix
+    // and only answers there. `createRouter` matches the longest prefix and
+    // the proxy forwards the original path, so both are already handled.
+    if (config.vscodeBasePath) {
+      routes.push([
+        config.vscodeBasePath,
+        `http://127.0.0.1:${config.vscodePort}`,
+      ]);
     }
   }
 
@@ -759,6 +784,32 @@ function buildRouteArgs(routes) {
   return routes.flatMap(([prefix, url]) => ["--route", `${prefix}=${url}`]);
 }
 
+/**
+ * The editor prefix, if this mode serves it, as `--no-referrer-prefix` args.
+ *
+ * agent-server hands the editor a connection token derived from its session
+ * key and advertises it in the URL's query string, so the workbench document
+ * must not leak a Referer to the subresources it loads.
+ */
+function getNoReferrerPrefixArgs(config) {
+  if (!config.launchAgentServer || !config.vscodeBasePath) return [];
+  return ["--no-referrer-prefix", config.vscodeBasePath];
+}
+
+/**
+ * The editor prefix, if this mode serves it, as `--vscode-base-path` args.
+ *
+ * Gated on exactly the same condition as the editor route in
+ * `getLocalServiceRoutes`, because they answer the same question: an origin
+ * advertises the editor if and only if it routes it. static-server enforces
+ * that pairing at startup, so a future edit that breaks it fails loudly rather
+ * than shipping a control that opens the SPA.
+ */
+function getVSCodeAdvertiseArgs(config) {
+  if (!config.launchAgentServer || !config.vscodeBasePath) return [];
+  return ["--vscode-base-path", config.vscodeBasePath];
+}
+
 /**
  * Build --reject-prefix args for the static server.
  * In frontend-only mode, API paths that have no backend should return 503
@@ -773,6 +824,12 @@ function getRejectPrefixes(config) {
     for (const prefix of AGENT_SERVER_ROUTE_PREFIXES) {
       prefixes.push(prefix);
     }
+    // No agent-server means no editor behind this prefix either. Reject it
+    // rather than SPA-fallbacking to index.html, which would answer an editor
+    // request with the canvas shell.
+    if (config.vscodeBasePath) {
+      prefixes.push(config.vscodeBasePath);
+    }
   }
   return prefixes;
 }
@@ -865,7 +922,12 @@ function startAgentServer(config) {
   });
 
   const agentServerEnv = {
-    ...buildAgentServerEnv(safeConfig),
+    // Opt into prefix-mode: `getLocalServiceRoutes` registers the matching
+    // route on both the static server and the ingress, so the prefix this
+    // advertises resolves to the editor port on the canvas origin.
+    ...buildAgentServerEnv(safeConfig, {
+      vscodeBasePath: config.vscodeBasePath,
+    }),
     ...buildAgentServerAutomationEnv(config),
     OPENHANDS_REMOTE_WS_READY_REQUIRED:
       process.env.OPENHANDS_REMOTE_WS_READY_REQUIRED || "false",
@@ -931,10 +993,10 @@ function startAutomationBackend(config) {
         //
         // Priority:
         //   1. AUTOMATION_AGENT_SERVER_URL explicitly set in the user's env
-        //   2. `localhost:<agentServerPort>`
+        //   2. `127.0.0.1:<agentServerPort>`
         AUTOMATION_AGENT_SERVER_URL:
           process.env.AUTOMATION_AGENT_SERVER_URL ||
-          `http://localhost:${config.agentServerPort}`,
+          getAgentServerBaseUrl(config),
         // The URL exported into the in-sandbox bash chain as
         // `AGENT_SERVER_URL` (read by main.py / setup.sh to call back into
         // the agent-server).
@@ -1054,6 +1116,7 @@ function startIngress(config) {
         ? ["--runtime-services-info", runtimeServicesInfo]
         : []),
       ...buildRouteArgs(getLocalServiceRoutes(config)),
+      ...getNoReferrerPrefixArgs(config),
       ...(frontendBackend ? ["--default", frontendBackend] : []),
     ],
     {
@@ -1101,6 +1164,23 @@ function startVite(config) {
     viteEnv.VITE_WORKING_DIR = config.viteWorkingDir;
   }
 
+  // Vite serves the HTML for this mode's browser origin, so this is where the
+  // editor-capability advertisement has to be baked. The ingress in front of it
+  // routes the prefix but is a pure proxy — it injects nothing into the
+  // document, so it cannot tell the frontend what it serves.
+  //
+  // Both variables or neither: `vite.config.ts` only registers the editor proxy
+  // when it has a target as well as a prefix, and this stack has two supported
+  // browser origins — the ingress and Vite's own port, which is why the latter
+  // is in AUTOMATION_CORS_ORIGINS. On the ingress the prefix is routed by the
+  // ingress itself; on the Vite origin only this proxy can serve it. Baking the
+  // prefix alone would advertise an editor on the Vite origin whose URL then
+  // falls through to the SPA — the dead button this gating exists to prevent.
+  if (config.launchAgentServer && config.vscodeBasePath) {
+    viteEnv.VITE_VSCODE_BASE_PATH = config.vscodeBasePath;
+    viteEnv.VITE_VSCODE_TARGET = `http://127.0.0.1:${config.vscodePort}`;
+  }
+
   // In local mode, bake the session key into the frontend so the user
   // never has to paste it. In public mode, omit the key and set
   // VITE_AUTH_REQUIRED so the frontend shows the API key entry screen
@@ -1141,7 +1221,7 @@ async function seedAutomationSecret(config, options = {}) {
 
   logService("secrets", `Seeding ${secretName} into agent-server...`, c.dim);
 
-  const url = `http://localhost:${config.agentServerPort}/api/settings/secrets`;
+  const url = `${getAgentServerBaseUrl(config)}/api/settings/secrets`;
   const body = JSON.stringify({
     name: secretName,
     value: config.sessionApiKey,
@@ -1476,7 +1556,7 @@ async function main(options = {}) {
 
     agentServerReady = await waitForService(
       "agent-server",
-      `http://localhost:${config.agentServerPort}/server_info`,
+      `${getAgentServerBaseUrl(config)}/server_info`,
       agentServerReadyTimeoutMs,
     );
   }
@@ -1564,6 +1644,11 @@ function startStaticFrontend(config, staticDir) {
         : []),
       // Proxy routes only to services that this launch mode started.
       ...buildRouteArgs(getLocalServiceRoutes(config)),
+      // Only the static server injects into the document, so only it can tell
+      // the frontend this origin serves the editor. The ingress routes the same
+      // prefix but proxies the HTML through untouched.
+      ...getVSCodeAdvertiseArgs(config),
+      ...getNoReferrerPrefixArgs(config),
       // Reject known API prefixes that have no backend — returns 503
       // instead of SPA-fallbacking to index.html.
       ...buildRejectPrefixArgs(getRejectPrefixes(config)),
@@ -1586,8 +1671,12 @@ export {
   buildConfig,
   buildRouteArgs,
   buildViteBackendEnv,
+  getAgentServerBaseUrl,
   getFrontendBackend,
   getLocalServiceRoutes,
+  getNoReferrerPrefixArgs,
+  getRejectPrefixes,
+  getVSCodeAdvertiseArgs,
   main,
   registerShutdownHook,
   spawnService,

package/scripts/ingress.mjs

@@ -30,6 +30,7 @@ import {
   createRouter,
   isBenignSocketError,
   isServerInfoRequest,
+  matchesPathPrefix,
   proxyServerInfoRequest,
 } from "./proxy-utils.mjs";
 
@@ -43,6 +44,7 @@ function parseArgs() {
     port: 8000,
     routes: {},
     defaultBackend: null,
+    noReferrerPrefixes: [],
     runtimeServicesInfo: null,
   };
 
@@ -62,6 +64,16 @@ function parseArgs() {
       case "--default":
         config.defaultBackend = args[++i];
         break;
+      case "--no-referrer-prefix": {
+        const prefix = args[++i];
+        if (!prefix || !prefix.startsWith("/")) {
+          throw new Error(
+            `--no-referrer-prefix value must start with '/': ${prefix ?? "(empty)"}`,
+          );
+        }
+        config.noReferrerPrefixes.push(prefix);
+        break;
+      }
       case "--runtime-services-info":
         config.runtimeServicesInfo = args[++i] || null;
         break;
@@ -88,6 +100,9 @@ OPTIONS:
   -p, --port <port>           Port to listen on (default: 8000)
   -r, --route <path=url>      Add a route (can be repeated)
   -d, --default <url>         Default backend for unmatched routes
+  --no-referrer-prefix <p>    Send "Referrer-Policy: no-referrer" on proxied
+                              responses under <p>. For upstreams whose URL
+                              carries a credential in the query string.
   --runtime-services-info     Runtime services JSON for /server_info
   -h, --help                  Show this help
 
@@ -136,6 +151,7 @@ function buildConfig(args, env = process.env) {
     port: args.port || parseInt(env.INGRESS_PORT, 10) || 8000,
     routes,
     defaultBackend: args.defaultBackend || env.INGRESS_DEFAULT || null,
+    noReferrerPrefixes: args.noReferrerPrefixes ?? [],
     runtimeServicesInfo:
       args.runtimeServicesInfo || env.INGRESS_RUNTIME_SERVICES_INFO || null,
   };
@@ -150,8 +166,11 @@ export function startIngress(config) {
   const proxy = createProxyHandlers({ label: `ingress:${config.port}` });
   const uninstallDiagnostics = proxy.installDiagnostics();
 
+  const noReferrerPrefixes = config.noReferrerPrefixes ?? [];
+
   const server = createServer((req, res) => {
-    const backend = route(req.url ?? "/");
+    const url = req.url ?? "/";
+    const backend = route(url);
 
     if (!backend) {
       res.writeHead(503);
@@ -159,6 +178,13 @@ export function startIngress(config) {
       return;
     }
 
+    // See the matching note in static-server.mjs: the editor's URL carries
+    // agent-server's session key as a query parameter, so the document must
+    // not send a Referer on the subresources the workbench loads.
+    if (noReferrerPrefixes.some((prefix) => matchesPathPrefix(url, prefix))) {
+      res.setHeader("Referrer-Policy", "no-referrer");
+    }
+
     if (
       config.runtimeServicesInfo &&
       isServerInfoRequest(req) &&