@openhands/agent-canvas 1.15.0 → 1.16.0

package/dist/utils/vscode-origin.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Whether *this browser origin* can serve the editor, and whether a given
+ * editor URL is one it will actually route.
+ *
+ * Editor availability is not a property of the agent-server process alone. The
+ * agent-server answers `/api/vscode/status` for whatever conversation you ask
+ * about, and builds `/api/vscode/url` from the `base_url` the caller sends —
+ * which is always `window.location.origin`. So a server can truthfully report
+ * an editor that the page's own origin has no route to. Two supported layouts
+ * hit that:
+ *
+ *   - **Public mode** (`docker/entrypoint.sh`, `--auth-required`): a second
+ *     static server on its own port, sharing the same agent-server but
+ *     deliberately without the editor route, because the editor's connection
+ *     token is the session API key (OpenHands/software-agent-sdk#4317) and that
+ *     origin exists to test the *unauthenticated* case.
+ *   - **Extra backends** (`scripts/dev-extra-backend.mjs`): a second
+ *     agent-server registered from a browser whose origin belongs to another
+ *     stack. That origin's editor route, if any, points at the *bundled*
+ *     stack's editor — a different container's workspace.
+ *
+ * In both cases a control gated only on the server probe renders and then
+ * resolves to the canvas SPA or, worse, someone else's workspace. So the
+ * frontend has to intersect the server's capability with the origin's route
+ * table, and this module is the origin half of that.
+ */
+/**
+ * The path prefix this origin serves the editor under, or `null` if it serves
+ * no editor at all.
+ *
+ * Two sources, in order — mirroring `getRawRuntimeServicesInfo` in
+ * `agent-server-adapter.ts`:
+ *   1. `VITE_VSCODE_BASE_PATH` — baked in at build time by the dev launchers
+ *      that proxy the editor (`npm run dev`, dev:static).
+ *   2. `window.__AGENT_CANVAS_VSCODE_BASE_PATH__` — injected into index.html at
+ *      serve time by `scripts/static-server.mjs --vscode-base-path <path>`,
+ *      which refuses to start unless a matching `--route` exists. That is the
+ *      path used by static builds (the Docker image, the published binary),
+ *      where the env var is empty in the prebuilt bundle.
+ *
+ * Absent from both means "this origin does not serve the editor" and the
+ * control is hidden. That is the pre-existing behavior for every local backend,
+ * so a deployment this cannot detect is no worse off than before.
+ */
+export declare function getOriginVSCodeBasePath(): string | null;
+/**
+ * Whether `url` is an editor URL this origin will actually route.
+ *
+ * The agent-server appends its own `vscode_base_path` to the origin we send it,
+ * so the returned URL carries the prefix of the server that answered — not
+ * necessarily the prefix this origin routes. An extra backend that configures
+ * no prefix yields `<origin>/?tkn=…`, which is the canvas root: same origin,
+ * wrong destination. Comparing paths is what separates the two.
+ */
+export declare function isVSCodeUrlServedByOrigin(url: string | null | undefined, basePath: string | null): boolean;

package/dist/utils/vscode-origin.js

@@ -0,0 +1,27 @@
+//#region src/utils/vscode-origin.ts
+var e = "__AGENT_CANVAS_VSCODE_BASE_PATH__";
+function t() {
+	if (typeof window < "u") {
+		let t = window[e];
+		if (typeof t == "string" && t.trim()) return n(t.trim());
+	}
+	return null;
+}
+function n(e) {
+	let t = e.startsWith("/") ? e : `/${e}`;
+	return t.length > 1 ? t.replace(/\/+$/, "") : t;
+}
+function r(e, t) {
+	if (!e || !t) return !1;
+	let n;
+	try {
+		n = new URL(e, typeof window < "u" ? window.location.href : void 0);
+	} catch {
+		return !1;
+	}
+	return typeof window < "u" && n.origin !== window.location.origin ? !1 : n.pathname === t || n.pathname.startsWith(`${t}/`);
+}
+//#endregion
+export { t as getOriginVSCodeBasePath, r as isVSCodeUrlServedByOrigin };
+
+//# sourceMappingURL=vscode-origin.js.map

package/dist/utils/vscode-origin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vscode-origin.js","names":[],"sources":["../../src/utils/vscode-origin.ts"],"sourcesContent":["/**\n * Whether *this browser origin* can serve the editor, and whether a given\n * editor URL is one it will actually route.\n *\n * Editor availability is not a property of the agent-server process alone. The\n * agent-server answers `/api/vscode/status` for whatever conversation you ask\n * about, and builds `/api/vscode/url` from the `base_url` the caller sends —\n * which is always `window.location.origin`. So a server can truthfully report\n * an editor that the page's own origin has no route to. Two supported layouts\n * hit that:\n *\n *   - **Public mode** (`docker/entrypoint.sh`, `--auth-required`): a second\n *     static server on its own port, sharing the same agent-server but\n *     deliberately without the editor route, because the editor's connection\n *     token is the session API key (OpenHands/software-agent-sdk#4317) and that\n *     origin exists to test the *unauthenticated* case.\n *   - **Extra backends** (`scripts/dev-extra-backend.mjs`): a second\n *     agent-server registered from a browser whose origin belongs to another\n *     stack. That origin's editor route, if any, points at the *bundled*\n *     stack's editor — a different container's workspace.\n *\n * In both cases a control gated only on the server probe renders and then\n * resolves to the canvas SPA or, worse, someone else's workspace. So the\n * frontend has to intersect the server's capability with the origin's route\n * table, and this module is the origin half of that.\n */\n\nconst VSCODE_BASE_PATH_WINDOW_KEY = \"__AGENT_CANVAS_VSCODE_BASE_PATH__\";\n\n/**\n * The path prefix this origin serves the editor under, or `null` if it serves\n * no editor at all.\n *\n * Two sources, in order — mirroring `getRawRuntimeServicesInfo` in\n * `agent-server-adapter.ts`:\n *   1. `VITE_VSCODE_BASE_PATH` — baked in at build time by the dev launchers\n *      that proxy the editor (`npm run dev`, dev:static).\n *   2. `window.__AGENT_CANVAS_VSCODE_BASE_PATH__` — injected into index.html at\n *      serve time by `scripts/static-server.mjs --vscode-base-path <path>`,\n *      which refuses to start unless a matching `--route` exists. That is the\n *      path used by static builds (the Docker image, the published binary),\n *      where the env var is empty in the prebuilt bundle.\n *\n * Absent from both means \"this origin does not serve the editor\" and the\n * control is hidden. That is the pre-existing behavior for every local backend,\n * so a deployment this cannot detect is no worse off than before.\n */\nexport function getOriginVSCodeBasePath(): string | null {\n  const envRaw = import.meta.env.VITE_VSCODE_BASE_PATH?.trim();\n  if (envRaw) return normalizePrefix(envRaw);\n\n  if (typeof window !== \"undefined\") {\n    const injected = (window as unknown as Record<string, unknown>)[\n      VSCODE_BASE_PATH_WINDOW_KEY\n    ];\n    if (typeof injected === \"string\" && injected.trim()) {\n      return normalizePrefix(injected.trim());\n    }\n  }\n\n  return null;\n}\n\nfunction normalizePrefix(value: string): string {\n  const withLeadingSlash = value.startsWith(\"/\") ? value : `/${value}`;\n  return withLeadingSlash.length > 1\n    ? withLeadingSlash.replace(/\\/+$/, \"\")\n    : withLeadingSlash;\n}\n\n/**\n * Whether `url` is an editor URL this origin will actually route.\n *\n * The agent-server appends its own `vscode_base_path` to the origin we send it,\n * so the returned URL carries the prefix of the server that answered — not\n * necessarily the prefix this origin routes. An extra backend that configures\n * no prefix yields `<origin>/?tkn=…`, which is the canvas root: same origin,\n * wrong destination. Comparing paths is what separates the two.\n */\nexport function isVSCodeUrlServedByOrigin(\n  url: string | null | undefined,\n  basePath: string | null,\n): boolean {\n  if (!url || !basePath) return false;\n\n  let parsed: URL;\n  try {\n    parsed = new URL(\n      url,\n      typeof window !== \"undefined\" ? window.location.href : undefined,\n    );\n  } catch {\n    return false;\n  }\n\n  // A cross-origin URL is somebody else's problem to route, not ours to vouch\n  // for. The local path always builds on `window.location.origin`, so this only\n  // fires on a value we did not construct.\n  if (\n    typeof window !== \"undefined\" &&\n    parsed.origin !== window.location.origin\n  ) {\n    return false;\n  }\n\n  return (\n    parsed.pathname === basePath || parsed.pathname.startsWith(`${basePath}/`)\n  );\n}\n"],"mappings":";AA2BA,IAAM,IAA8B;AAoBpC,SAAgB,IAAyC;CAIvD,IAAI,OAAO,SAAW,KAAa;EACjC,IAAM,IAAY,OAChB;EAEF,IAAI,OAAO,KAAa,YAAY,EAAS,KAAK,GAChD,OAAO,EAAgB,EAAS,KAAK,CAAC;CAE1C;CAEA,OAAO;AACT;AAEA,SAAS,EAAgB,GAAuB;CAC9C,IAAM,IAAmB,EAAM,WAAW,GAAG,IAAI,IAAQ,IAAI;CAC7D,OAAO,EAAiB,SAAS,IAC7B,EAAiB,QAAQ,QAAQ,EAAE,IACnC;AACN;AAWA,SAAgB,EACd,GACA,GACS;CACT,IAAI,CAAC,KAAO,CAAC,GAAU,OAAO;CAE9B,IAAI;CACJ,IAAI;EACF,IAAS,IAAI,IACX,GACA,OAAO,SAAW,MAAc,OAAO,SAAS,OAAO,KAAA,CACzD;CACF,QAAQ;EACN,OAAO;CACT;CAYA,OANE,OAAO,SAAW,OAClB,EAAO,WAAW,OAAO,SAAS,SAE3B,KAIP,EAAO,aAAa,KAAY,EAAO,SAAS,WAAW,GAAG,EAAS,EAAE;AAE7E"}

package/dist/utils/workspace-mode.d.ts

@@ -1,4 +1,8 @@
 import type { BackendKind } from "#/api/backend-registry/types";
 import type { WorkspaceMode } from "#/api/conversation-metadata-store";
 import { I18nKey } from "#/i18n/declaration";
+export declare const DEFAULT_WORKSPACE_MODE: WorkspaceMode;
+export declare const LAST_LOCAL_WORKSPACE_MODE_STORAGE_KEY = "openhands-last-local-workspace-mode";
+export declare function readStoredLocalWorkspaceMode(): WorkspaceMode;
+export declare function writeStoredLocalWorkspaceMode(mode: WorkspaceMode): void;
 export declare function getWorkspaceModeI18nKey(mode: WorkspaceMode, backendKind: BackendKind): I18nKey;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openhands/agent-canvas",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Agent Canvas UI for OpenHands - run AI coding agents with a visual interface",
   "license": "MIT",
   "private": false,
@@ -23,8 +23,8 @@
     "@heroui/react": "2.8.10",
     "@microlink/react-json-view": "1.31.25",
     "@monaco-editor/react": "4.7.0",
-    "@openhands/extensions": "0.18.0",
-    "@openhands/typescript-client": "1.38.1",
+    "@openhands/extensions": "0.19.0",
+    "@openhands/typescript-client": "1.39.0",
     "@react-router/node": "7.18.2",
     "@react-router/serve": "7.18.2",
     "@tailwindcss/vite": "4.3.3",

package/scripts/check-sdk-version-sync.mjs

@@ -19,7 +19,7 @@
  *
  * Usage:
  *   node scripts/check-sdk-version-sync.mjs
- *   EXPECTED_SDK_VERSION=1.42.1 node scripts/check-sdk-version-sync.mjs
+ *   EXPECTED_SDK_VERSION=1.44.0 node scripts/check-sdk-version-sync.mjs
  *   node scripts/check-sdk-version-sync.mjs --check-pypi
  *
  * Environment variables:
@@ -78,7 +78,7 @@ Triggering from other repos:
     -H "Authorization: token \$GITHUB_TOKEN" \\
     -H "Accept: application/vnd.github.v3+json" \\
     https://api.github.com/repos/OpenHands/OpenHands/dispatches \\
-    -d '{"event_type": "sdk-version-check", "client_payload": {"version": "1.42.1"}}'
+    -d '{"event_type": "sdk-version-check", "client_payload": {"version": "1.44.0"}}'
 `);
   process.exit(0);
 }
@@ -260,9 +260,9 @@ async function fetchPyPIDependencies(packageName, version) {
  * Parse PyPI requires_dist array and extract SDK package versions
  *
  * PyPI returns dependencies in PEP 508 format like:
- *   "openhands-sdk>=1.42.1,<2.0.0"
- *   "openhands-tools==1.42.1"
- *   "openhands-workspace (>=1.42.1)"
+ *   "openhands-sdk>=1.44.0,<2.0.0"
+ *   "openhands-tools==1.44.0"
+ *   "openhands-workspace (>=1.44.0)"
  */
 function parseSdkVersionsFromRequiresDist(requiresDist) {
   const versions = {};
@@ -276,7 +276,7 @@ function parseSdkVersionsFromRequiresDist(requiresDist) {
       }
 
       // Extract the version number - look for patterns like:
-      // ">=1.42.1", "==1.42.1", "(>=1.42.1)", "~=1.42.1"
+      // ">=1.44.0", "==1.44.0", "(>=1.44.0)", "~=1.44.0"
       // After the package name and before any comma or closing paren
       const versionPattern = /[><=~!]+\s*([0-9]+(?:\.[0-9]+)*)/;
       const match = dep.match(versionPattern);

package/scripts/check-translation-completeness.cjs

@@ -60,6 +60,7 @@ const IDENTICAL_VALUE_ALLOWLIST = new Set([
   'SETTINGS$MCP_SERVER_TYPE_SSE',
   'SETTINGS$MCP_SERVER_TYPE_STDIO',
   'SETTINGS$NAV_LLM',
+  'SETTINGS$OPENHANDS_API_KEY_HELP_LINK',
   'SETTINGS$SKILLS_PILLS_MORE',
   'SETTINGS$SKILLS_VERSION',
   'SETTINGS$SLACK',

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.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,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,
 };