@openhands/agent-canvas 1.15.0 → 1.17.0

package/scripts/dev-extra-backend.mjs

@@ -43,7 +43,10 @@ function parsePort(value, fallback) {
  * @param {string} cwd
  * @param {Record<string, string | undefined>} env
  */
-export function buildExtraBackendConfig(cwd = process.cwd(), env = process.env) {
+export function buildExtraBackendConfig(
+  cwd = process.cwd(),
+  env = process.env,
+) {
   const base = buildSafeDevConfig(cwd, env);
 
   const backendPort = parsePort(
@@ -70,7 +73,7 @@ function isEnoentError(error) {
       typeof error === "object" &&
       "code" in error &&
       error.code === "ENOENT") ||
-      /ENOENT/.test(String(error)),
+    /ENOENT/.test(String(error)),
   );
 }
 
@@ -94,10 +97,14 @@ async function waitForServer(url, timeoutMs = DEFAULT_WAIT_TIMEOUT_MS) {
 }
 
 function spawnProcess(command, args, options = {}) {
-  const child = spawn(command, args, getProcessTreeSpawnOptions({
-    stdio: "inherit",
-    ...options,
-  }));
+  const child = spawn(
+    command,
+    args,
+    getProcessTreeSpawnOptions({
+      stdio: "inherit",
+      ...options,
+    }),
+  );
 
   child.once("error", (error) => {
     if (isEnoentError(error) && command === "uvx") {
@@ -164,6 +171,14 @@ async function main() {
     {
       cwd: config.cwd,
       env: {
+        // Deliberately not opting into the editor path prefix. This server is
+        // reached by registering it as an extra backend from a browser whose
+        // origin belongs to some *other* stack, so a prefix on that origin
+        // either does not resolve or — worse — resolves to the bundled
+        // stack's editor, silently handing back a different container's
+        // workspace. No single global prefix can disambiguate the two, so this
+        // launcher stays out of prefix-mode; the editor button is unavailable
+        // for conversations on an extra backend.
         ...process.env,
         ...buildAgentServerEnv(config),
       },
@@ -190,6 +205,12 @@ async function main() {
 
   process.on("SIGINT", () => shutdown("SIGINT"));
   process.on("SIGTERM", () => shutdown("SIGTERM"));
+  // The agent-server is spawned detached, so a SIGHUP that kills this launcher
+  // (terminal or multiplexer death) would otherwise leave it running and holding
+  // its port. 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));
@@ -221,9 +242,7 @@ async function main() {
 
   backend.once("exit", (code) => {
     if (!shuttingDown) {
-      console.error(
-        `agent-server exited unexpectedly with code ${code ?? 0}`,
-      );
+      console.error(`agent-server exited unexpectedly with code ${code ?? 0}`);
       shutdown();
       process.exitCode = code ?? 1;
     } else {

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.46.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,42 +290,25 @@ async function waitForService(name, url, timeoutMs = 30000) {
 // dev-with-automation; the only difference is the frontend service.)
 // ═══════════════════════════════════════════════════════════════════════════
 
-// Both backends bind to `0.0.0.0`, which only accepts IPv4, but localhost can
-// resolve to ::1 first (notably on Windows). Every proxy target and readiness
-// probe pointed at them must therefore address IPv4 explicitly.
-function getAgentServerBaseUrl(config) {
-  return `http://127.0.0.1:${config.agentServerPort}`;
-}
-
-function getAutomationBaseUrl(config) {
-  return `http://127.0.0.1:${config.autoBackendPort}`;
-}
-
-const AUTOMATION_ROUTE_PREFIX = "/api/automation";
-const AGENT_SERVER_ROUTE_PREFIXES = [
-  "/api",
-  "/sockets",
-  "/server_info",
-  "/health",
-  "/ready",
-  "/alive",
-  "/docs",
-  "/redoc",
-  "/openapi.json",
-];
-
-// The static server and the ingress proxy front the same two local backends,
-// so they share one route table.
+// 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) {
-  const agentServerUrl = getAgentServerBaseUrl(config);
-  return [
-    "--route",
-    `${AUTOMATION_ROUTE_PREFIX}=${getAutomationBaseUrl(config)}`,
-    ...AGENT_SERVER_ROUTE_PREFIXES.flatMap((prefix) => [
-      "--route",
-      `${prefix}=${agentServerUrl}`,
-    ]),
-  ];
+  return buildRouteArgs(
+    getLocalServiceRoutes({
+      ...config,
+      launchAgentServer: true,
+      launchAutomation: true,
+    }),
+  );
 }
 
 function startAgentServer(config) {
@@ -341,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),
   };
 
@@ -444,6 +437,11 @@ function startStaticServer(config) {
       "--runtime-services-info",
       runtimeServicesInfo,
       ...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,
@@ -473,6 +471,7 @@ function startIngress(config) {
       "--runtime-services-info",
       runtimeServicesInfo,
       ...buildLocalServiceRouteArgs(config),
+      ...getNoReferrerPrefixArgs(config),
       "--default",
       `http://localhost:${config.vitePort}`,
     ],
@@ -645,7 +644,6 @@ export {
   buildAutomationBackendEnv,
   buildFrontend,
   buildLocalServiceRouteArgs,
-  getAgentServerBaseUrl,
   startStaticServer,
 };
 

package/scripts/dev-with-automation.mjs

@@ -28,7 +28,7 @@
  *
  * Environment variables:
  *   - PORT: Ingress port (default: 8000)
- *   - OH_AUTOMATION_GIT_REF: Git ref for automation (default: main)
+ *   - OH_AUTOMATION_GIT_REF: Git ref for automation (overrides default version)
  *   - OH_AGENT_SERVER_LOCAL_PATH: Absolute path to a local software-agent-sdk
  *     checkout. Highest precedence for agent-server source selection: rebuilds
  *     the agent-server from local source and installs openhands-sdk,
@@ -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,
@@ -757,6 +761,20 @@ function getLocalServiceRoutes(config) {
     for (const prefix of AGENT_SERVER_ROUTE_PREFIXES) {
       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}`,
+      ]);
+    }
   }
 
   return routes;
@@ -766,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
@@ -780,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;
 }
@@ -872,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",
@@ -1061,6 +1116,7 @@ function startIngress(config) {
         ? ["--runtime-services-info", runtimeServicesInfo]
         : []),
       ...buildRouteArgs(getLocalServiceRoutes(config)),
+      ...getNoReferrerPrefixArgs(config),
       ...(frontendBackend ? ["--default", frontendBackend] : []),
     ],
     {
@@ -1108,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
@@ -1571,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)),
@@ -1596,6 +1674,9 @@ export {
   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) &&