@openhands/agent-canvas 1.5.1 → 1.6.1

package/scripts/dev-process-utils.mjs

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import process from "node:process";
 
 /**
@@ -33,6 +34,40 @@ export function getProcessTreeSpawnOptions(options = {}) {
   };
 }
 
+/**
+ * Resolve a service command to a directly spawnable target on Windows.
+ *
+ * Services spawn without a shell so argument values reach the child verbatim.
+ * Spawning `uvx` via cmd.exe instead makes it parse the args: a constraint like
+ * `agent-client-protocol<0.11` is read as `<` input redirection and the spawn
+ * dies with "The system cannot find the file specified." Resolving to an
+ * absolute path lets callers spawn it shell-free.
+ *
+ * Returns `command` unchanged off Windows, when already a path, or if the lookup
+ * fails.
+ */
+export function resolveWindowsCommand(
+  command,
+  platform = process.platform,
+  lookup = whereCommandLookup,
+) {
+  if (platform !== "win32") {
+    return command;
+  }
+  if (command.includes("/") || command.includes("\\")) {
+    return command;
+  }
+  return lookup(command) || command;
+}
+
+function whereCommandLookup(command) {
+  const result = spawnSync("where.exe", [command], { encoding: "utf8" });
+  if (result.status !== 0 || !result.stdout) {
+    return null;
+  }
+  return result.stdout.split(/\r?\n/).find(Boolean)?.trim() || null;
+}
+
 /**
  * Signal the whole spawned service tree when possible.
  *
@@ -48,7 +83,9 @@ export function signalProcessTree(proc, signal) {
   }
 
   try {
-    if (process.platform === "win32" || !proc.pid) {
+    if (process.platform === "win32" && proc.pid) {
+      killWindowsProcessTree(proc, signal);
+    } else if (!proc.pid) {
       proc.kill(signal);
     } else {
       process.kill(-proc.pid, signal);
@@ -62,6 +99,30 @@ export function signalProcessTree(proc, signal) {
   }
 }
 
+/**
+ * Windows has no POSIX process groups: ChildProcess#kill reaches only the
+ * direct child (e.g. the uvx wrapper), leaving grandchildren — the actual
+ * python agent-server holding its port — running. `taskkill /t` walks the
+ * child tree instead. Windows also has no graceful tree signal (taskkill
+ * without /f posts WM_CLOSE, which console processes ignore), so SIGTERM and
+ * SIGKILL both map to the same forceful /f kill; callers' delayed SIGKILL
+ * pass skips already-exited trees via isProcessRunning, so the repeat is a
+ * no-op. A non-zero taskkill exit just means the tree already exited — only
+ * a failure to spawn taskkill itself falls back to the direct kill.
+ */
+function killWindowsProcessTree(proc, signal) {
+  const result = spawnSync(
+    "taskkill",
+    ["/pid", String(proc.pid), "/t", "/f"],
+    // windowsHide avoids a console window flash when invoked from the
+    // packaged (GUI) Electron process.
+    { stdio: "ignore", windowsHide: true },
+  );
+  if (result.error) {
+    proc.kill(signal);
+  }
+}
+
 export function createShutdownHookRegistry(onError) {
   const hooks = new Set();
 

package/scripts/dev-safe.mjs

@@ -48,7 +48,7 @@ const LOCAL_AGENT_SERVER_SUBDIRS = [
   "openhands-workspace",
 ];
 const DEFAULT_AGENT_SERVER_VERSION = SHARED_DEFAULTS.versions.agentServer;
-// Temporary transitive-dep pin: openhands-sdk 1.36.1 leaves agent-client-protocol
+// Temporary transitive-dep pin: openhands-sdk 1.37.0 leaves agent-client-protocol
 // unbounded (>=0.10.1), but acp 0.11.0 reordered the ACP prompt() args and breaks
 // the SDK's ACP client. Hold acp <0.11 until a fixed SDK ships. See config/defaults.json.
 const AGENT_CLIENT_PROTOCOL_CONSTRAINT =
@@ -399,7 +399,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.36.1")
+ * - OH_AGENT_SERVER_VERSION: Specific PyPI version (e.g., "1.37.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

package/scripts/dev-static.mjs

@@ -54,11 +54,13 @@ import {
 import {
   getProcessTreeSpawnOptions,
   isProcessRunning,
+  resolveWindowsCommand,
   signalProcessTree,
 } from "./dev-process-utils.mjs";
 import {
   buildAgentServerAutomationEnv,
   buildAutomationCommand,
+  buildAutomationTelemetryEnv,
   buildConfig,
 } from "./dev-with-automation.mjs";
 
@@ -215,13 +217,12 @@ let shuttingDown = false;
 
 function spawnService(name, command, args, options = {}) {
   const proc = spawn(
-    command,
+    resolveWindowsCommand(command),
     args,
     getProcessTreeSpawnOptions({
       stdio: ["ignore", "pipe", "pipe"],
       env: { ...process.env, ...options.env },
       cwd: options.cwd,
-      shell: process.platform === "win32",
     }),
   );
 
@@ -323,7 +324,7 @@ function startAgentServer(config) {
   );
 }
 
-function buildAutomationBackendEnv(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}`,
@@ -332,6 +333,7 @@ function buildAutomationBackendEnv(config) {
     AUTOMATION_BASE_URL: `http://localhost:${config.ingressPort}`,
     AUTOMATION_WORKSPACE_BASE: join(config.stateDir, "workspaces"),
     AUTOMATION_LOCAL_API_KEY: config.sessionApiKey,
+    ...buildAutomationTelemetryEnv(env),
     AUTOMATION_CORS_ORIGINS: `http://localhost:${config.ingressPort},http://127.0.0.1:${config.ingressPort},http://localhost:3001,http://127.0.0.1:3001`,
     FILE_STORE: "local",
     LOCAL_STORAGE_PATH: join(config.stateDir, "storage"),

package/scripts/dev-with-automation.mjs

@@ -60,7 +60,6 @@ import {
   buildNpmScriptCommand,
   buildRuntimeServicesInfo,
   formatMissingUvxGuidance,
-  getOrCreatePersistedApiKey,
   validateFrontendDependencies,
   validateLocalAgentServerPath,
 } from "./dev-safe.mjs";
@@ -68,6 +67,7 @@ import {
   createShutdownHookRegistry,
   getProcessTreeSpawnOptions,
   isProcessRunning,
+  resolveWindowsCommand,
   signalProcessTree,
 } from "./dev-process-utils.mjs";
 import { fileLog, stripAnsi } from "./logger.mjs";
@@ -86,6 +86,8 @@ const DEFAULT_AUTOMATION_VERSION = SHARED_DEFAULTS.versions.automation;
 const DEFAULT_AUTOMATION_SDK_VERSION = SHARED_DEFAULTS.versions.agentServer;
 const DEFAULT_BACKEND_PORT = SHARED_DEFAULTS.ports.agentServer;
 const DEFAULT_AUTOMATION_PORT = SHARED_DEFAULTS.ports.automation;
+const DEFAULT_POSTHOG_API_KEY = SHARED_DEFAULTS.telemetry.posthogApiKey;
+const DEFAULT_POSTHOG_HOST = SHARED_DEFAULTS.telemetry.posthogHost;
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Terminal Styling
@@ -545,19 +547,38 @@ const shutdownHooks = createShutdownHookRegistry((err) => {
   logService("cleanup", `Cleanup hook failed: ${err.message}`, c.yellow);
 });
 
+// Optional external listener for every service log line. Set by `main()` from
+// its `onServiceLog` option so embedded launchers (e.g. the Electron desktop
+// app) can stream uvx download / install progress to their loading window
+// without touching the terminal logging path. Receives `(name, line, level)`
+// where `level` is one of "stdout" | "stderr" | "info" | "warn" | "error".
+let serviceLogListener = null;
+
+export function setServiceLogListener(listener) {
+  serviceLogListener = typeof listener === "function" ? listener : null;
+}
+
+function emitServiceLog(name, line, level) {
+  if (!serviceLogListener) return;
+  try {
+    serviceLogListener(name, line, level);
+  } catch {
+    // Never let a listener bug crash the dev stack.
+  }
+}
+
 function registerShutdownHook(hook) {
   return shutdownHooks.add(hook);
 }
 
 function spawnService(name, command, args, options = {}) {
   const proc = spawn(
-    command,
+    resolveWindowsCommand(command),
     args,
     getProcessTreeSpawnOptions({
       stdio: ["ignore", "pipe", "pipe"],
       env: { ...process.env, ...options.env },
       cwd: options.cwd,
-      shell: process.platform === "win32",
     }),
   );
 
@@ -570,12 +591,14 @@ function spawnService(name, command, args, options = {}) {
       .split("\n")
       .filter(Boolean)
       .forEach((line) => {
-        const parsed = parseLogLine ? parseLogLine(line.trim()) : null;
+        const trimmed = line.trim();
+        const parsed = parseLogLine ? parseLogLine(trimmed) : null;
         logService(
           name,
-          parsed ? parsed.text : line.trim(),
+          parsed ? parsed.text : trimmed,
           parsed ? parsed.color : color,
         );
+        emitServiceLog(name, trimmed, "stdout");
       });
   });
 
@@ -585,22 +608,26 @@ function spawnService(name, command, args, options = {}) {
       .split("\n")
       .filter(Boolean)
       .forEach((line) => {
-        const parsed = parseLogLine ? parseLogLine(line.trim()) : null;
+        const trimmed = line.trim();
+        const parsed = parseLogLine ? parseLogLine(trimmed) : null;
         logService(
           name,
-          parsed ? parsed.text : line.trim(),
+          parsed ? parsed.text : trimmed,
           parsed ? parsed.color : c.yellow,
         );
+        emitServiceLog(name, trimmed, "stderr");
       });
   });
 
   proc.on("error", (error) => {
     logError(`${name} failed to start: ${error.message}`);
+    emitServiceLog(name, `failed to start: ${error.message}`, "error");
   });
 
-  proc.on("exit", (code, signal) => {
+  proc.on("exit", (code, _signal) => {
     if (code !== 0 && code !== null && !shuttingDown) {
       logService(name, `Exited with code ${code}`, c.red);
+      emitServiceLog(name, `exited with code ${code}`, "error");
     }
     processes.delete(name);
   });
@@ -727,6 +754,24 @@ function buildAgentServerAutomationEnv(config) {
   };
 }
 
+function buildAutomationTelemetryEnv(env = process.env) {
+  const telemetryDisabled = env.VITE_DO_NOT_TRACK === "1";
+  const apiKey =
+    env.AUTOMATION_POSTHOG_API_KEY ||
+    env.VITE_POSTHOG_API_KEY ||
+    (telemetryDisabled ? "" : DEFAULT_POSTHOG_API_KEY);
+
+  if (!apiKey) return {};
+
+  return {
+    AUTOMATION_POSTHOG_API_KEY: apiKey,
+    AUTOMATION_POSTHOG_HOST:
+      env.AUTOMATION_POSTHOG_HOST ||
+      env.VITE_POSTHOG_HOST ||
+      DEFAULT_POSTHOG_HOST,
+  };
+}
+
 function startAgentServer(config) {
   logService(
     "agent-server",
@@ -858,6 +903,7 @@ function startAutomationBackend(config) {
           join(config.stateDir, "workspaces"),
         // Session API key for self-hosted auth — shared with agent-server via X-Session-API-Key header
         AUTOMATION_LOCAL_API_KEY: config.sessionApiKey,
+        ...buildAutomationTelemetryEnv(),
         // KV store secret — required for automations to use the built-in
         // key-value store for state persistence between runs. Used for JWT
         // signing and value encryption.
@@ -1106,7 +1152,8 @@ function printBanner(config) {
 
   // padEnd counts invisible ANSI escape bytes as visible characters, so we
   // compute the visible length separately and pad with spaces accordingly.
-  const ansiRe = /\x1b\[[0-9;]*m/g;
+  const ansiEscape = String.fromCharCode(27);
+  const ansiRe = new RegExp(`${ansiEscape}\\[[0-9;]*m`, "g");
   const ansiPadEnd = (str, targetVisible) => {
     const visible = str.replace(ansiRe, "").length;
     return str + " ".repeat(Math.max(0, targetVisible - visible));
@@ -1210,8 +1257,28 @@ async function main(options = {}) {
     // When true, enable public mode (require LOCAL_BACKEND_API_KEY,
     // don't bake session key into frontend).
     isPublic: isPublicOverride,
+    // When true, skip the npm prerequisite check. Used by the Electron desktop
+    // launcher where npm is not needed at runtime in static mode.
+    skipNpmCheck = false,
+    // How long to wait for the agent-server's `/server_info` to return 200
+    // before continuing. Defaults to 60 s, which is fine for warm-cache dev
+    // workflows. The Electron desktop launcher bumps this to several minutes
+    // because first-launch on a fresh machine runs `uvx` to download Python
+    // and install `openhands-agent-server` from PyPI, which can take much
+    // longer than 60 s on a slow network.
+    agentServerReadyTimeoutMs = 60_000,
+    // Optional `(name, line, level)` callback that receives every service log
+    // line (stdout, stderr, and lifecycle events) emitted by any spawned
+    // backend process. Used by the Electron loading screen to surface uvx
+    // download / install progress to the user. `level` is one of
+    // "stdout" | "stderr" | "info" | "warn" | "error".
+    onServiceLog,
   } = options;
 
+  // Install the listener early so log lines emitted before the first
+  // `spawnService` call (e.g. by future setup steps) are also captured.
+  setServiceLogListener(onServiceLog);
+
   const args = parseArgs();
 
   // Allow options to override CLI args for public mode
@@ -1239,9 +1306,13 @@ async function main(options = {}) {
     checkUvx: !args.frontendOnly,
     // Static-mode + backend-only has no frontend to build, so npm is not
     // required — unless the caller provides a custom buildStaticFrontend hook.
+    // The Electron desktop launcher passes `skipNpmCheck: true` because the
+    // packaged binary serves a pre-built static frontend and never invokes
+    // npm at runtime, so we suppress the check unconditionally there.
     checkNpm:
-      (!useStaticMode && !args.backendOnly) ||
-      typeof buildStaticFrontend === "function",
+      !skipNpmCheck &&
+      ((!useStaticMode && !args.backendOnly) ||
+        typeof buildStaticFrontend === "function"),
     checkFrontendDependencies:
       (!useStaticMode && !args.backendOnly) ||
       typeof buildStaticFrontend === "function",
@@ -1303,16 +1374,23 @@ async function main(options = {}) {
 
   let agentServerReady = false;
 
-  // 1. Start agent-server first (automation depends on it)
+  // 1. Start agent-server first (automation depends on it).
+  //
+  // Readiness timeout defaults to 60 s, which is fine for `npm run dev` against
+  // a warm uvx cache. The Electron desktop launcher overrides this via the
+  // `agentServerReadyTimeoutMs` option because first-launch on a fresh machine
+  // runs `uvx` to download Python + install `openhands-agent-server` from PyPI,
+  // which can take several minutes. Dropping the user into a half-booted UI
+  // before that completes triggers axios "Request timeout" popups on the first
+  // SPA fetch that hits an unbound port 18000.
   if (config.launchAgentServer) {
     const agentServerStarter = startAgentServerOverride ?? startAgentServer;
     agentServerStarter(config);
 
-    // Wait for agent-server to be ready (60s timeout for slow systems)
     agentServerReady = await waitForService(
       "agent-server",
       `http://localhost:${config.agentServerPort}/server_info`,
-      60000, // 60 second timeout for initial startup
+      agentServerReadyTimeoutMs,
     );
   }
 
@@ -1353,6 +1431,11 @@ async function main(options = {}) {
   await delay(1000);
 
   printBanner(config);
+
+  // Return the resolved config + readiness signal so embedded launchers can
+  // (a) build URLs from the actual allocated ports and (b) decide whether to
+  // show an error to the user when the agent-server never came up.
+  return { config, agentServerReady };
 }
 
 function startStaticFrontend(config, staticDir) {
@@ -1412,6 +1495,7 @@ function startStaticFrontend(config, staticDir) {
 export {
   buildAgentServerAutomationEnv,
   buildAutomationCommand,
+  buildAutomationTelemetryEnv,
   buildConfig,
   buildRouteArgs,
   buildViteBackendEnv,