@openhands/agent-canvas 1.0.0-rc.2 → 1.0.0-rc.4

package/scripts/dev-safe.mjs

@@ -21,6 +21,11 @@ import {
   isProcessRunning,
   signalProcessTree,
 } from "./dev-process-utils.mjs";
+// buildRuntimeServicesInfo moved to its own dependency-free module so the
+// Docker entrypoint can run it as a CLI. Re-exported below for back-compat
+// (dev-with-automation.mjs and tests still import it from here).
+import { buildRuntimeServicesInfo } from "./runtime-services-info.mjs";
+import { fileLog, stripAnsi } from "./logger.mjs";
 
 // ── Centralized config (single source of truth for versions, ports, etc.) ───
 const __dev_safe_dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -31,6 +36,32 @@ const SHARED_DEFAULTS = JSON.parse(
   ),
 );
 
+/**
+ * Extract the pinned commit SHA for @openhands/extensions from package.json.
+ * Returns the 40-char hex SHA when the dependency is a git+https URL with a
+ * commit hash fragment (e.g. "git+https://…#62594156…"), null otherwise.
+ * @returns {string | null}
+ */
+function getExtensionsRef() {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(
+        path.join(__dev_safe_dirname, "..", "package.json"),
+        "utf-8",
+      ),
+    );
+    const url =
+      (pkg.dependencies ?? pkg.devDependencies ?? {})["@openhands/extensions"] ??
+      "";
+    return url.match(/#([0-9a-f]{40})$/i)?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Pinned extensions commit SHA derived from package.json, or null if not pinned. */
+export const DEFAULT_EXTENSIONS_REF = getExtensionsRef();
+
 const DEFAULT_BACKEND_PORT = SHARED_DEFAULTS.ports.agentServer;
 const DEFAULT_VITE_PORT = 3001;
 const DEFAULT_WAIT_TIMEOUT_MS = 30_000;
@@ -389,7 +420,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.24.0")
+ * - OH_AGENT_SERVER_VERSION: Specific PyPI version (e.g., "1.26.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
@@ -426,14 +457,23 @@ export function buildAgentServerCommand(env = process.env) {
     );
     source = `local (${localPath})`;
   } else if (gitRef) {
-    // Use git ref with subdirectory syntax for uv workspace monorepo
+    // Use git ref with subdirectory syntax for uv workspace monorepo.
     // The software-agent-sdk repo has packages in subdirectories:
-    // openhands-agent-server/, openhands-tools/, openhands-workspace/
+    // openhands-agent-server/, openhands-sdk/, openhands-tools/, openhands-workspace/
+    // All four must come from the same ref so inter-package APIs stay in sync.
+    //
+    // --reinstall is required because the git branch may carry the same version
+    // string as the current PyPI release (e.g. both "1.26.0"). Without it, uv
+    // silently reuses the cached PyPI wheels and the git ref is never actually
+    // used, even though it was explicitly requested.
     const baseGitUrl = `git+${AGENT_SERVER_GIT_REPO}@${gitRef}`;
     uvxArgs.push(
+      "--reinstall",
       "--from",
       `${baseGitUrl}#subdirectory=openhands-agent-server`,
       "--with",
+      `${baseGitUrl}#subdirectory=openhands-sdk`,
+      "--with",
       `${baseGitUrl}#subdirectory=openhands-tools`,
       "--with",
       `${baseGitUrl}#subdirectory=openhands-workspace`,
@@ -697,124 +737,20 @@ export function buildAgentServerEnv(config) {
     // Make the host tools/ directory importable so the agent-server can
     // resolve modules listed in tool_module_qualnames (e.g. canvas_ui_tool).
     OH_EXTRA_PYTHON_PATH: config.canvasToolsDir,
+    // Tell the agent-server which extensions commit to use for the public
+    // skills catalog. Derived from the @openhands/extensions pin in
+    // package.json; the SDK skips network polling when it already has this
+    // SHA cached. Only injected when the caller has not already set it.
+    ...(DEFAULT_EXTENSIONS_REF && !process.env.EXTENSIONS_REF
+      ? { EXTENSIONS_REF: DEFAULT_EXTENSIONS_REF }
+      : {}),
   };
 }
 
-/**
- * Build a structured description of the dev-stack services that are
- * reachable from inside the agent's sandbox. The frontend forwards this
- * (verbatim, as a JSON string in `VITE_RUNTIME_SERVICES_INFO`) and renders
- * it into the system prompt via `AgentContext.system_message_suffix`, so
- * the agent sees a `<RUNTIME_SERVICES>` block listing what's available
- * without having to probe.
- *
- * URLs are written from the *agent's* point of view. The agent-server
- * runs on the host, so the host alias is "localhost".
- *
- * @param {object} options
- * @param {string} [options.mode] - Human-readable dev mode label (e.g. "dev:safe").
- * @param {string} [options.agentHostAlias="localhost"] - Hostname the agent
- *   uses to reach services running on the host machine.
- * @param {number} [options.agentServerPort] - Port the agent-server listens on.
- *   Required at runtime; the function throws if missing because the resulting
- *   URL would otherwise bake `undefined` into the agent's system prompt.
- *   Typed as optional only so TypeScript callers can negative-test the guard.
- * @param {number} [options.ingressPort] - Ingress port (omit if no ingress).
- * @param {number} [options.frontendPort] - Frontend port (Vite dev server
- *   or static-file server). Omit if no frontend is exposed.
- * @param {number} [options.vitePort] - Deprecated alias for `frontendPort`,
- *   accepted for backward compat with older launchers. Remove after one release.
- * @param {"vite"|"static"} [options.frontendKind="vite"] - Whether the
- *   frontend port hosts Vite or a static build. Only affects the
- *   description shown to the agent.
- * @param {object} [options.automation] - Automation backend info. Skipped
- *   entirely if `.port` is missing, so passing `{}` is safe.
- * @param {number} [options.automation.port] - Automation backend port.
- * @param {string} [options.automation.apiPrefix="/api/automation"] - Path
- *   prefix all automation routes are mounted under.
- * @param {string} [options.automation.authEnvVar="OPENHANDS_AUTOMATION_API_KEY"]
- *   - Env var holding the API key.
- * @returns {object} A JSON-serializable runtime services info object.
- */
-export function buildRuntimeServicesInfo(options) {
-  const {
-    mode,
-    agentHostAlias = "localhost",
-    agentServerPort,
-    ingressPort,
-    // Accept legacy `vitePort` for one release so external callers keep working.
-    vitePort,
-    frontendPort = vitePort,
-    frontendKind = "vite",
-    automation,
-  } = options;
-
-  if (agentServerPort === undefined || agentServerPort === null) {
-    // Without this the URL becomes `http://localhost:undefined` and ends up
-    // verbatim in the agent's system prompt, which is worse than failing fast.
-    throw new Error(
-      "buildRuntimeServicesInfo: agentServerPort is required " +
-        "(otherwise the agent_server URL would be `http://localhost:undefined`).",
-    );
-  }
-
-  const services = {
-    agent_server: {
-      description:
-        "The OpenHands Agent Server this agent is running inside. " +
-        "Tool calls (terminal, file_editor, browser, etc.) execute here.",
-      // From the agent's POV, the agent-server it's *inside* is on
-      // localhost, regardless of where the host is.
-      url_from_agent: `http://localhost:${agentServerPort}`,
-    },
-  };
-
-  if (ingressPort !== undefined) {
-    services.ingress = {
-      description:
-        "Unified entry point. Routes /api/automation/* to the automation " +
-        "backend, /api/* and /sockets to the agent-server, and /* to the " +
-        "frontend.",
-      url_from_agent: `http://${agentHostAlias}:${ingressPort}`,
-    };
-  }
-
-  if (frontendPort !== undefined) {
-    services.frontend = {
-      kind: frontendKind,
-      description:
-        frontendKind === "static"
-          ? "Static-file server hosting the agent-canvas production build."
-          : "Vite dev server hosting the agent-canvas frontend.",
-      url_from_agent: `http://${agentHostAlias}:${frontendPort}`,
-    };
-  }
-
-  // Require an explicit port so we don't bake `:undefined` into the
-  // automation URL when the caller passes `automation: {}`.
-  if (automation?.port !== undefined && automation.port !== null) {
-    const apiPrefix = automation.apiPrefix ?? "/api/automation";
-    const authEnvVar = automation.authEnvVar ?? "OPENHANDS_AUTOMATION_API_KEY";
-    const baseUrl = `http://${agentHostAlias}:${automation.port}`;
-    services.automation = {
-      description:
-        "OpenHands Automations service. All routes are mounted under " +
-        `'${apiPrefix}'. Authenticate with header ` +
-        `'X-Session-API-Key: $${authEnvVar}'.`,
-      url_from_agent: baseUrl,
-      api_prefix: apiPrefix,
-      docs_url: `${baseUrl}${apiPrefix}/docs`,
-      openapi_url: `${baseUrl}${apiPrefix}/openapi.json`,
-      auth_env_var: authEnvVar,
-    };
-  }
-
-  return {
-    mode,
-    agent_host_alias: agentHostAlias,
-    services,
-  };
-}
+// Re-export so existing importers (dev-with-automation.mjs, tests) keep
+// resolving `buildRuntimeServicesInfo` from this module. The implementation
+// now lives in ./runtime-services-info.mjs (imported at the top of this file).
+export { buildRuntimeServicesInfo };
 
 export function buildNpmScriptCommand(
   scriptName,
@@ -899,13 +835,16 @@ function spawnProcess(command, args, options = {}) {
 
   child.once("error", (error) => {
     if (isEnoentError(error) && command === "uvx") {
-      console.error(formatMissingUvxGuidance(options?.cwd));
+      const msg = formatMissingUvxGuidance(options?.cwd);
+      console.error(msg);
+      fileLog("error", stripAnsi(msg));
     } else if (isEnoentError(error)) {
-      console.error(
-        `Failed to start ${command}. Make sure it is installed and on your PATH.`,
-      );
+      const msg = `Failed to start ${command}. Make sure it is installed and on your PATH.`;
+      console.error(msg);
+      fileLog("error", msg);
     } else {
       console.error(`Failed to start ${command}:`, error);
+      fileLog("error", `Failed to start ${command}: ${error.message}`);
     }
   });
 
@@ -914,9 +853,12 @@ function spawnProcess(command, args, options = {}) {
 
 async function main() {
   console.log("Starting isolated agent-server + frontend dev stack...");
+  fileLog("info", "Starting isolated agent-server + frontend dev stack...");
   validateFrontendDependencies();
   console.log("Frontend dependencies found.");
+  fileLog("info", "Frontend dependencies found.");
   console.log("Allocating ports...");
+  fileLog("info", "Allocating ports...");
 
   // Use async config builder with dynamic port allocation
   const config = await buildSafeDevConfigAsync();
@@ -955,6 +897,16 @@ async function main() {
   console.log(`- secret key: ${secretKeySource}`);
   console.log(`- session API key: ${sessionKeySource}`);
   console.log("");
+  fileLog(
+    "info",
+    [
+      "Agent-server stack config:",
+      `  agent-server: ${agentServerCmd.source}`,
+      `  backend:      ${config.backendBaseUrl}`,
+      `  working dir:  ${config.workingDir}`,
+      `  state dir:    ${config.stateDir}`,
+    ].join("\n"),
+  );
 
   const backend = spawnProcess(
     agentServerCmd.command,
@@ -1055,7 +1007,9 @@ async function main() {
 
   backend.once("exit", (code) => {
     if (!shuttingDown) {
-      console.error(`agent-server exited unexpectedly with code ${code ?? 0}`);
+      const msg = `agent-server exited unexpectedly with code ${code ?? 0}`;
+      console.error(msg);
+      fileLog("error", msg);
       shutdown();
       process.exitCode = code ?? 1;
     }
@@ -1142,7 +1096,12 @@ if (
   import.meta.url === pathToFileURL(process.argv[1]).href
 ) {
   main().catch((error) => {
-    console.error(error instanceof Error ? error.message : error);
+    const msg = error instanceof Error ? error.message : String(error);
+    console.error(msg);
+    fileLog("error", `Fatal error: ${msg}`);
+    if (error instanceof Error && error.stack) {
+      fileLog("error", error.stack);
+    }
     process.exit(1);
   });
 }

package/scripts/dev-with-automation.mjs

@@ -68,6 +68,7 @@ import {
   isProcessRunning,
   signalProcessTree,
 } from "./dev-process-utils.mjs";
+import { fileLog, stripAnsi } from "./logger.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const projectRoot = resolve(__dirname, "..");
@@ -105,18 +106,54 @@ const c = {
 function logService(name, message, color = c.reset) {
   const ts = new Date().toISOString().split("T")[1].split(".")[0];
   console.log(`${c.dim}${ts}${c.reset} ${color}[${name}]${c.reset} ${message}`);
+  fileLog("info", `[${name}] ${stripAnsi(message)}`);
 }
 
 function logStep(step, message) {
   console.log(`${c.cyan}[${step}]${c.reset} ${message}`);
+  fileLog("info", `[${step}] ${message}`);
 }
 
 function logSuccess(message) {
   console.log(`${c.green}✓${c.reset} ${message}`);
+  fileLog("info", `✓ ${message}`);
 }
 
 function logError(message) {
   console.error(`${c.red}✗${c.reset} ${message}`);
+  fileLog("error", `✗ ${stripAnsi(message)}`);
+}
+
+/**
+ * Parse one JSON log line produced by the SDK's JsonFormatter and return a
+ * single-line human-readable string + an appropriate ANSI color.
+ *
+ * Returns null for non-JSON lines so callers can fall back to the raw text.
+ *
+ * @param {string} rawLine
+ * @returns {{ text: string; color: string } | null}
+ */
+function parseAgentServerLogLine(rawLine) {
+  try {
+    const obj = JSON.parse(rawLine);
+    if (!obj.levelname || obj.message === undefined) return null;
+    const level = obj.levelname.padEnd(8);
+    const location =
+      obj.filename && obj.lineno ? `  ${obj.filename}:${obj.lineno}` : "";
+    const text = `${level} ${obj.message}${location}`;
+    const lvl = obj.levelname;
+    const color =
+      lvl === "DEBUG"
+        ? c.dim
+        : lvl === "WARNING"
+          ? c.yellow
+          : lvl === "ERROR" || lvl === "CRITICAL"
+            ? c.red
+            : c.blue;
+    return { text, color };
+  } catch {
+    return null;
+  }
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -440,7 +477,9 @@ function checkPrerequisites({
 
   if (checkUvx) {
     if (!commandExists("uvx")) {
-      console.error(formatMissingUvxGuidance(projectRoot));
+      const uvxGuidance = formatMissingUvxGuidance(projectRoot);
+      console.error(uvxGuidance);
+      fileLog("error", stripAnsi(uvxGuidance));
       process.exit(1);
     }
     logSuccess("uvx found");
@@ -521,6 +560,7 @@ function spawnService(name, command, args, options = {}) {
   );
 
   const color = options.color || c.reset;
+  const parseLogLine = options.parseLogLine;
 
   proc.stdout.on("data", (data) => {
     data
@@ -528,7 +568,8 @@ function spawnService(name, command, args, options = {}) {
       .split("\n")
       .filter(Boolean)
       .forEach((line) => {
-        logService(name, line.trim(), color);
+        const parsed = parseLogLine ? parseLogLine(line.trim()) : null;
+        logService(name, parsed ? parsed.text : line.trim(), parsed ? parsed.color : color);
       });
   });
 
@@ -538,7 +579,8 @@ function spawnService(name, command, args, options = {}) {
       .split("\n")
       .filter(Boolean)
       .forEach((line) => {
-        logService(name, line.trim(), c.yellow);
+        const parsed = parseLogLine ? parseLogLine(line.trim()) : null;
+        logService(name, parsed ? parsed.text : line.trim(), parsed ? parsed.color : c.yellow);
       });
   });
 
@@ -699,6 +741,11 @@ function startAgentServer(config) {
     // Ensure the agent-server uses the resolved key from config. This is
     // LOCAL_BACKEND_API_KEY when set, or the auto-generated persisted key.
     OH_SESSION_API_KEYS_0: config.sessionApiKey,
+    // Emit structured JSON log lines instead of Rich-formatted output.
+    // Rich wraps long messages across multiple lines and prepends its own
+    // timestamp; LOG_JSON=true produces one JSON object per record which
+    // parseAgentServerLogLine re-formats into a clean single-line entry.
+    LOG_JSON: "true",
   };
 
   spawnService(
@@ -715,6 +762,7 @@ function startAgentServer(config) {
       cwd: safeConfig.workspacesPath,
       env: agentServerEnv,
       color: c.blue,
+      parseLogLine: parseAgentServerLogLine,
     },
   );
 }
@@ -796,8 +844,10 @@ 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,
-        // CORS: allow localhost origins for dev
-        AUTOMATION_CORS_ORIGINS: `http://localhost:${config.ingressPort},http://127.0.0.1:${config.ingressPort},http://localhost:3001,http://127.0.0.1:3001`,
+        // CORS: allow localhost origins for dev, unless explicitly overridden.
+        AUTOMATION_CORS_ORIGINS:
+          process.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"),
         OPENHANDS_SUPPRESS_BANNER: "1",
@@ -819,6 +869,7 @@ function shutdown() {
 
   console.log("");
   console.log(`${c.yellow}Shutting down...${c.reset}`);
+  fileLog("info", "Shutting down...");
 
   for (const [name, proc] of processes) {
     logService(name, "Stopping...", c.dim);
@@ -1090,6 +1141,20 @@ function printBanner(config) {
   console.log(`${c.dim}State directory: ${config.stateDir}${c.reset}`);
   console.log(`${c.dim}Press Ctrl+C to stop${c.reset}`);
   console.log("");
+
+  // Write a compact plain-text summary to the log file.
+  const summary = [
+    `${stackName} — started`,
+    `  Ingress:         http://localhost:${config.ingressPort}/`,
+    ...(config.launchFrontend
+      ? [`  Main UI:         http://localhost:${config.ingressPort}/`]
+      : []),
+    ...(config.launchAutomation
+      ? [`  API Docs:        http://localhost:${config.ingressPort}/api/automation/docs`]
+      : []),
+    `  State directory: ${config.stateDir}`,
+  ];
+  fileLog("info", summary.join("\n"));
 }
 
 async function main(options = {}) {
@@ -1143,6 +1208,7 @@ async function main(options = {}) {
   console.log("");
   console.log(`${c.cyan}${c.bold}${titleWithMode}${c.reset}`);
   console.log("");
+  fileLog("info", titleWithMode);
 
   // Setup phase
   checkPrerequisites({
@@ -1269,6 +1335,13 @@ function startStaticFrontend(config, staticDir) {
   logService("static", `Starting on port ${config.vitePort}...`, c.magenta);
   logService("static", `Serving from: ${staticDir}`, c.dim);
 
+  // Build the runtime-services info JSON so the pre-built frontend can
+  // populate the agent's <RUNTIME_SERVICES> system-prompt block without
+  // VITE_RUNTIME_SERVICES_INFO baked in at build time.
+  const runtimeServicesInfo = config.launchAgentServer
+    ? JSON.stringify(buildAutomationRuntimeServicesInfo(config))
+    : null;
+
   const staticServerScript = join(projectRoot, "scripts", "static-server.mjs");
   spawnService(
     "static",
@@ -1288,6 +1361,10 @@ function startStaticFrontend(config, staticDir) {
       ...(config.launchAgentServer && config.isPublic
         ? ["--auth-required"]
         : []),
+      // Inject runtime-services info so the agent knows what's reachable.
+      ...(runtimeServicesInfo
+        ? ["--runtime-services-info", runtimeServicesInfo]
+        : []),
       // Proxy routes only to services that this launch mode started.
       ...buildRouteArgs(getLocalServiceRoutes(config)),
       // Reject known API prefixes that have no backend — returns 503
@@ -1343,6 +1420,7 @@ if (isMainModule) {
     logError(`Fatal error: ${err.message}`);
     if (err.stack) {
       console.error(c.dim + err.stack + c.reset);
+      fileLog("error", err.stack);
     }
     process.exit(1);
   });

package/scripts/logger.mjs

@@ -0,0 +1,77 @@
+/**
+ * Shared file logger for agent-canvas dev scripts.
+ *
+ * Writes log output to a daily-rotating file under <project-root>/logs/
+ * alongside the existing console output (which is unchanged).
+ *
+ * File naming:  logs/agent-canvas.YYYY-MM-DD.log
+ * Retention:    7 days (files older than 7 days are automatically deleted)
+ */
+
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+import { createLogger, format } from "winston";
+import DailyRotateFile from "winston-daily-rotate-file";
+
+// Mirror the state-directory logic from dev-safe.mjs so log files live
+// alongside all other agent-canvas runtime state (e.g. ~/.openhands/agent-canvas).
+// The same env var (OH_CANVAS_SAFE_STATE_DIR) overrides both.
+const stateDir =
+  process.env.OH_CANVAS_SAFE_STATE_DIR ||
+  join(homedir(), ".openhands", "agent-canvas");
+const logDir = join(stateDir, "logs");
+
+// Ensure the logs directory exists before the transport tries to open a file.
+mkdirSync(logDir, { recursive: true });
+
+// Matches any ANSI CSI escape sequence (colors, cursor movement, etc.).
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+/**
+ * Remove ANSI escape codes so log files contain clean plain text.
+ * @param {string} str
+ * @returns {string}
+ */
+export function stripAnsi(str) {
+  return typeof str === "string" ? str.replace(ANSI_RE, "") : String(str);
+}
+
+const fileTransport = new DailyRotateFile({
+  dirname: logDir,
+  filename: "agent-canvas.%DATE%.log",
+  datePattern: "YYYY-MM-DD",
+  maxFiles: "7d",
+  // Audit file tracks which rotated files exist; kept alongside log files.
+  auditFile: join(logDir, ".log-audit.json"),
+  createSymlink: false,
+});
+
+const fileLogger = createLogger({
+  level: "debug",
+  format: format.combine(
+    format.timestamp({ format: "YYYY-MM-DD HH:mm:ss" }),
+    format.printf(
+      ({ timestamp, level, message }) =>
+        `${timestamp} [${level.toUpperCase().padEnd(5)}] ${message}`,
+    ),
+  ),
+  transports: [fileTransport],
+});
+
+// Swallow any transport-level errors (e.g. disk full) so a logging failure
+// never crashes the dev server.
+fileLogger.on("error", () => {});
+fileTransport.on("error", () => {});
+
+/**
+ * Write a message to the rotating log file.
+ * ANSI escape codes are stripped automatically; console output is unaffected.
+ *
+ * @param {'info' | 'warn' | 'error' | 'debug'} level
+ * @param {string} message
+ */
+export function fileLog(level, message) {
+  fileLogger.log(level, stripAnsi(message));
+}