π OpenHands: AI-Driven Development
feat(dev): surface dev-stack runtime services in agent system prompt (#503)
Tim O'Farrellb2b71855c644
diff --git a/AGENTS.md b/AGENTS.mdindex d9e02baea6..6b6035e499 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -19,6 +19,81 @@- Verification command: `npm run typecheck && npm run build`.- GitHub automation now includes `.github/workflows/ci.yml` for `npm ci`, `npm test`, and `npm run build`, plus `.github/dependabot.yml` with weekly npm/github-actions updates gated by a 7-day cooldown.+## Runtime Services in Dev Stacks++- When the agent-canvas dev launchers (`npm run dev:safe` / `dev:automation` / `dev:docker` / the published `agent-canvas` binary) start a stack, they set a `VITE_RUNTIME_SERVICES_INFO` env var on the frontend describing which services are running and how the agent should reach them. The frontend forwards this verbatim as `AgentContext.system_message_suffix` on every `POST /api/conversations`, so conversations land with a `<RUNTIME_SERVICES>` block appended to the system prompt.+- The block lists URLs **from the agent's point of view**:+ - The Agent Server is always reachable as `http://localhost:<port>` from inside the sandbox β but that is _you_, not the automation backend.+ - Host-side services (ingress, Vite, automation) are reachable as `http://localhost:<port>` in dockerless modes and `http://host.docker.internal:<port>` in `dev:docker`.+- Agents should treat the `<RUNTIME_SERVICES>` block as authoritative: don't hardcode `localhost:8000` for "the automation server", and don't probe random ports trying to discover services. If the block says automation is not running, skip `/api/automation` calls; otherwise use the listed `url_from_agent` + `api_prefix` (default `/api/automation`) and the `X-API-Key: $OPENHANDS_AUTOMATION_API_KEY` header.+- The launcher β frontend β suffix plumbing is:+ - `scripts/dev-safe.mjs::buildRuntimeServicesInfo()` β pure helper that constructs the info object.+ - `scripts/dev-with-automation.mjs::buildAutomationRuntimeServicesInfo()` β wraps it with automation details; called from both Vite spawn (`startVite`) and the static build (`static-build.mjs`).+ - `scripts/dev-docker.mjs` and `bin/agent-canvas.mjs` pass `agentHostAlias: "host.docker.internal"` to `main()` because the agent-server runs in a container in those modes.+ - `src/api/agent-server-adapter.ts::buildRuntimeServicesSystemSuffix()` reads `VITE_RUNTIME_SERVICES_INFO` and renders the `<RUNTIME_SERVICES>` markdown block; `createAgentFromSettings()` attaches it to `agent_context.system_message_suffix` when present.++### `VITE_RUNTIME_SERVICES_INFO` shape++The env var is a JSON string of:++```json+{+ "mode": "dev:docker",+ "agent_host_alias": "host.docker.internal",+ "services": {+ "agent_server": {+ "description": "The OpenHands Agent Server this agent is running inside. ...",+ "url_from_agent": "http://localhost:8000"+ },+ "ingress": {+ "description": "Unified entry point. Routes /api/automation/* ...",+ "url_from_agent": "http://host.docker.internal:8000"+ },+ "frontend": {+ "kind": "vite",+ "description": "Vite dev server hosting the agent-canvas frontend.",+ "url_from_agent": "http://host.docker.internal:3001"+ },+ "automation": {+ "description": "OpenHands Automations service. All routes are mounted under '/api/automation'. Authenticate with header 'X-API-Key: $OPENHANDS_AUTOMATION_API_KEY'.",+ "url_from_agent": "http://host.docker.internal:18001",+ "api_prefix": "/api/automation",+ "docs_url": "http://host.docker.internal:18001/api/automation/docs",+ "openapi_url": "http://host.docker.internal:18001/api/automation/openapi.json",+ "auth_env_var": "OPENHANDS_AUTOMATION_API_KEY"+ }+ }+}+```++All keys under `services` are optional and omitted when the corresponding service isn't running. `frontend.kind` is `"vite"` for dev launchers running the Vite dev server and `"static"` for stacks serving a pre-built `build/` directory (`dev:docker`, `dev:dangerously-dockerless`, the published `agent-canvas` binary). `services.vite` is accepted as a legacy alias for `services.frontend` by the renderer.++### Example `<RUNTIME_SERVICES>` block (dev:docker with automation)++```+<RUNTIME_SERVICES>+You are running inside an agent-canvas dev stack started in 'dev:docker' mode.+The following services are reachable from your sandbox. URLs are written+from your point of view (i.e., as you should curl/fetch them).++* Agent Server (you): http://localhost:8000+ The OpenHands Agent Server this agent is running inside. Tool calls (terminal, file_editor, browser, etc.) execute here.+* Ingress: http://host.docker.internal:8000+ Unified entry point. Routes /api/automation/* to the automation backend, /api/* and /sockets to the agent-server, and /* to the frontend.+* Frontend: http://host.docker.internal:3001+ Static-file server hosting the agent-canvas production build.+* Automation backend: http://host.docker.internal:18001+ OpenHands Automations service. All routes are mounted under '/api/automation'. Authenticate with header 'X-API-Key: $OPENHANDS_AUTOMATION_API_KEY'.+ Docs: http://host.docker.internal:18001/api/automation/docs+ OpenAPI: http://host.docker.internal:18001/api/automation/openapi.json+ Auth: header 'X-API-Key: $OPENHANDS_AUTOMATION_API_KEY'++Trust this block over guessing: do not assume any other URLs are running.+In particular, http://localhost:8000 inside your sandbox is the Agent Server+you are running inside of β NOT the automation backend.+</RUNTIME_SERVICES>+```+## Visual Snapshot Testing- Snapshot tests live in `tests/e2e/snapshots/` and compare screenshots against baselines stored as GitHub Actions artifacts (NOT in git).diff --git a/__tests__/api/agent-server-adapter.test.ts b/__tests__/api/agent-server-adapter.test.tsindex 3bdab168ab..4af700b203 100644--- a/__tests__/api/agent-server-adapter.test.ts+++ b/__tests__/api/agent-server-adapter.test.ts@@ -1,6 +1,7 @@-import { beforeEach, describe, expect, it, vi } from "vitest";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";import {+ buildRuntimeServicesSystemSuffix,buildStartConversationRequest,getDefaultConversationTitle,toAppConversation,@@ -13,9 +14,7 @@ const {mockIsAgentServerToolAvailable,mockGetEffectiveLocalBackend,} = vi.hoisted(() => ({- mockGetAgentServerWorkingDir: vi.fn(- () => "/workspace/project/agent-canvas",- ),+ mockGetAgentServerWorkingDir: vi.fn(() => "/workspace/project/agent-canvas"),mockIsAgentServerToolAvailable: vi.fn(() => true),mockGetEffectiveLocalBackend: vi.fn(() => ({id: "default-local",@@ -151,7 +150,6 @@ describe("buildStartConversationRequest", () => {expect(payload.agent.enable_switch_llm_tool).toBeUndefined();});-it("omits browser_tool_set when the server does not advertise browser support", () => {mockIsAgentServerToolAvailable.mockReturnValue(false);@@ -320,7 +318,6 @@ describe("buildStartConversationRequest", () => {},});});-});describe("getDefaultConversationTitle", () => {@@ -366,3 +363,191 @@ describe("toAppConversation", () => {expect(result.title).toBe("My real title");});});++describe("buildRuntimeServicesSystemSuffix", () => {+ afterEach(() => {+ vi.unstubAllEnvs();+ });++ it("returns undefined when VITE_RUNTIME_SERVICES_INFO is unset", () => {+ expect(buildRuntimeServicesSystemSuffix()).toBeUndefined();+ });++ it("returns undefined when the env var is malformed JSON", () => {+ vi.stubEnv("VITE_RUNTIME_SERVICES_INFO", "{not valid json");+ expect(buildRuntimeServicesSystemSuffix()).toBeUndefined();+ });++ it("returns undefined when the JSON has no services", () => {+ vi.stubEnv("VITE_RUNTIME_SERVICES_INFO", JSON.stringify({ mode: "x" }));+ expect(buildRuntimeServicesSystemSuffix()).toBeUndefined();+ });++ it("renders a <RUNTIME_SERVICES> block when an automation entry is present", () => {+ vi.stubEnv(+ "VITE_RUNTIME_SERVICES_INFO",+ JSON.stringify({+ mode: "dev:docker",+ agent_host_alias: "host.docker.internal",+ services: {+ agent_server: {+ description: "self",+ url_from_agent: "http://localhost:8000",+ },+ automation: {+ description: "automations",+ url_from_agent: "http://host.docker.internal:18001",+ api_prefix: "/api/automation",+ docs_url: "http://host.docker.internal:18001/api/automation/docs",+ openapi_url:+ "http://host.docker.internal:18001/api/automation/openapi.json",+ auth_env_var: "OPENHANDS_AUTOMATION_API_KEY",+ },+ },+ }),+ );+ const suffix = buildRuntimeServicesSystemSuffix();+ expect(suffix).toBeDefined();+ expect(suffix).toContain("<RUNTIME_SERVICES>");+ expect(suffix).toContain("dev:docker");+ expect(suffix).toContain("http://localhost:8000");+ expect(suffix).toContain("http://host.docker.internal:18001");+ expect(suffix).toContain(+ "http://host.docker.internal:18001/api/automation/docs",+ );+ expect(suffix).toContain("X-API-Key: $OPENHANDS_AUTOMATION_API_KEY");+ expect(suffix).toContain("</RUNTIME_SERVICES>");+ // The "don't guess" line should reference the actual agent-server URL+ // for this stack, not a hardcoded :8000. We pinned :8000 here but the+ // assertion specifically anchors on the URL we supplied.+ expect(suffix).toContain(+ "In particular, http://localhost:8000 inside your sandbox is the Agent Server",+ );+ });++ it("uses the configured agent-server URL in the don't-guess line (not a hardcoded :8000)", () => {+ // dev:safe runs the agent-server on :18000, not :8000. Make sure the+ // rendered block doesn't lie to the agent about its own URL.+ vi.stubEnv(+ "VITE_RUNTIME_SERVICES_INFO",+ JSON.stringify({+ mode: "dev:safe",+ services: {+ agent_server: { url_from_agent: "http://localhost:18000" },+ },+ }),+ );+ const suffix = buildRuntimeServicesSystemSuffix();+ expect(suffix).toBeDefined();+ expect(suffix).toContain(+ "In particular, http://localhost:18000 inside your sandbox is the Agent Server",+ );+ expect(suffix).not.toContain(+ "In particular, http://localhost:8000 inside your sandbox",+ );+ });++ it("renders the frontend entry with the new key", () => {+ vi.stubEnv(+ "VITE_RUNTIME_SERVICES_INFO",+ JSON.stringify({+ mode: "dev:docker",+ services: {+ agent_server: { url_from_agent: "http://localhost:8000" },+ frontend: {+ kind: "static",+ description: "Static-file server hosting the agent-canvas build.",+ url_from_agent: "http://host.docker.internal:3001",+ },+ },+ }),+ );+ const suffix = buildRuntimeServicesSystemSuffix();+ expect(suffix).toContain("* Frontend: http://host.docker.internal:3001");+ expect(suffix).toContain("Static-file server");+ // Should NOT mislabel a static-build frontend as "Vite frontend".+ expect(suffix).not.toContain("Vite frontend");+ });++ it("accepts the legacy `vite` service key", () => {+ // Older launchers may still emit `services.vite`. Render it under the+ // new "Frontend" label rather than dropping the entry.+ vi.stubEnv(+ "VITE_RUNTIME_SERVICES_INFO",+ JSON.stringify({+ mode: "dev:safe",+ services: {+ agent_server: { url_from_agent: "http://localhost:18000" },+ vite: {+ description: "Vite dev server",+ url_from_agent: "http://localhost:3001",+ },+ },+ }),+ );+ const suffix = buildRuntimeServicesSystemSuffix();+ expect(suffix).toContain("* Frontend: http://localhost:3001");+ });++ it("explicitly mentions when automation is absent", () => {+ vi.stubEnv(+ "VITE_RUNTIME_SERVICES_INFO",+ JSON.stringify({+ mode: "dev:safe",+ services: {+ agent_server: { url_from_agent: "http://localhost:18000" },+ },+ }),+ );+ const suffix = buildRuntimeServicesSystemSuffix();+ expect(suffix).toBeDefined();+ expect(suffix).toContain("Automation backend: not running");+ });+});++describe("createAgentFromSettings runtime services suffix", () => {+ afterEach(() => {+ vi.unstubAllEnvs();+ });++ it("does not set system_message_suffix when no runtime info is provided", () => {+ const payload = buildStartConversationRequest({+ settings: DEFAULT_SETTINGS,+ query: "hello",+ }) as {+ agent: { agent_context: Record<string, unknown> };+ };+ expect(payload.agent.agent_context).toEqual({+ load_public_skills: true,+ load_user_skills: true,+ });+ });++ it("sets system_message_suffix when runtime info is provided", () => {+ vi.stubEnv(+ "VITE_RUNTIME_SERVICES_INFO",+ JSON.stringify({+ mode: "dev:docker",+ services: {+ agent_server: { url_from_agent: "http://localhost:8000" },+ automation: {+ url_from_agent: "http://host.docker.internal:18001",+ },+ },+ }),+ );+ const payload = buildStartConversationRequest({+ settings: DEFAULT_SETTINGS,+ query: "hello",+ }) as {+ agent: { agent_context: Record<string, unknown> };+ };+ expect(payload.agent.agent_context).toMatchObject({+ load_public_skills: true,+ load_user_skills: true,+ });+ expect(+ payload.agent.agent_context.system_message_suffix as string,+ ).toContain("<RUNTIME_SERVICES>");+ });+});diff --git a/__tests__/scripts/dev-safe.test.ts b/__tests__/scripts/dev-safe.test.tsindex 3abccc05d4..929851ee27 100644--- a/__tests__/scripts/dev-safe.test.ts+++ b/__tests__/scripts/dev-safe.test.ts@@ -12,6 +12,7 @@ import {buildSafeDevConfigAsync,buildNpmScriptCommand,buildAgentServerCommand,+ buildRuntimeServicesInfo,formatMissingUvxGuidance,formatMissingFrontendDependenciesGuidance,getMissingFrontendDependencyBins,@@ -287,7 +288,9 @@ describe("formatMissingUvxGuidance", () => {"/workspace/project/agent-canvas",);- expect(guidance).toContain("curl -LsSf https://astral.sh/uv/install.sh | sh");+ expect(guidance).toContain(+ "curl -LsSf https://astral.sh/uv/install.sh | sh",+ );expect(guidance).toContain('export PATH="$HOME/.local/bin:$PATH"');expect(guidance).toContain("command -v uvx");expect(guidance).toContain(@@ -338,7 +341,9 @@ describe("buildAgentServerCommand", () => {});it("uses git ref with subdirectory syntax for monorepo", () => {- const cmd = buildAgentServerCommand({ OH_AGENT_SERVER_GIT_REF: "feature-branch" });+ const cmd = buildAgentServerCommand({+ OH_AGENT_SERVER_GIT_REF: "feature-branch",+ });expect(cmd.command).toBe("uvx");expect(cmd.args).toEqual([@@ -736,3 +741,154 @@ describe("dev-safe CLI startup", () => {expect(output).toContain("spawn uvx ENOENT");});});++interface RuntimeServiceEntry {+ kind?: string;+ description?: string;+ url_from_agent?: string;+ api_prefix?: string;+ docs_url?: string;+ openapi_url?: string;+ auth_env_var?: string;+}+interface RuntimeServicesInfoShape {+ mode: string;+ agent_host_alias: string;+ services: {+ agent_server?: RuntimeServiceEntry;+ ingress?: RuntimeServiceEntry;+ frontend?: RuntimeServiceEntry;+ automation?: RuntimeServiceEntry;+ };+}++describe("buildRuntimeServicesInfo", () => {+ it("describes only the agent-server in a minimal dev-safe stack", () => {+ const info = buildRuntimeServicesInfo({+ mode: "dev:safe",+ agentServerPort: 18000,+ }) as RuntimeServicesInfoShape;+ expect(info).toEqual({+ mode: "dev:safe",+ agent_host_alias: "localhost",+ services: {+ agent_server: {+ description: expect.any(String),+ url_from_agent: "http://localhost:18000",+ },+ },+ });+ });++ it("includes ingress, frontend (vite), and automation entries when ports are provided", () => {+ const info = buildRuntimeServicesInfo({+ mode: "dev:automation",+ agentServerPort: 18000,+ ingressPort: 8000,+ frontendPort: 3001,+ automation: { port: 18001 },+ }) as RuntimeServicesInfoShape;+ expect(info.services.ingress?.url_from_agent).toBe("http://localhost:8000");+ expect(info.services.frontend).toMatchObject({+ kind: "vite",+ url_from_agent: "http://localhost:3001",+ });+ expect(info.services.frontend?.description).toMatch(/Vite dev server/i);+ expect(info.services.automation).toMatchObject({+ url_from_agent: "http://localhost:18001",+ api_prefix: "/api/automation",+ docs_url: "http://localhost:18001/api/automation/docs",+ openapi_url: "http://localhost:18001/api/automation/openapi.json",+ auth_env_var: "OPENHANDS_AUTOMATION_API_KEY",+ });+ });++ it("uses host.docker.internal as the agent host alias in docker mode", () => {+ const info = buildRuntimeServicesInfo({+ mode: "dev:docker",+ agentHostAlias: "host.docker.internal",+ agentServerPort: 8000,+ ingressPort: 8000,+ frontendPort: 3001,+ frontendKind: "static",+ automation: { port: 18001 },+ }) as RuntimeServicesInfoShape;+ // Agent-server URL is always localhost (the agent is *inside* it).+ expect(info.services.agent_server?.url_from_agent).toBe(+ "http://localhost:8000",+ );+ // Host-side services use the docker alias.+ expect(info.services.ingress?.url_from_agent).toBe(+ "http://host.docker.internal:8000",+ );+ expect(info.services.frontend?.url_from_agent).toBe(+ "http://host.docker.internal:3001",+ );+ // Static-mode description, not "Vite dev server".+ expect(info.services.frontend?.kind).toBe("static");+ expect(info.services.frontend?.description).toMatch(/Static-file server/i);+ expect(info.services.frontend?.description).not.toMatch(/Vite/i);+ expect(info.services.automation?.url_from_agent).toBe(+ "http://host.docker.internal:18001",+ );+ });++ it("allows overriding the api prefix and auth env var", () => {+ const info = buildRuntimeServicesInfo({+ mode: "dev:custom",+ agentServerPort: 18000,+ automation: {+ port: 9000,+ apiPrefix: "/v2/auto",+ authEnvVar: "MY_KEY",+ },+ }) as RuntimeServicesInfoShape;+ expect(info.services.automation).toMatchObject({+ api_prefix: "/v2/auto",+ docs_url: "http://localhost:9000/v2/auto/docs",+ openapi_url: "http://localhost:9000/v2/auto/openapi.json",+ auth_env_var: "MY_KEY",+ });+ });++ it("omits the automation entry when none is provided", () => {+ const info = buildRuntimeServicesInfo({+ mode: "dev:safe",+ agentServerPort: 18000,+ ingressPort: 8000,+ }) as RuntimeServicesInfoShape;+ expect(info.services.automation).toBeUndefined();+ });++ it("omits the automation entry when the object lacks a port", () => {+ // A bare `{}` previously slipped through and produced+ // `http://localhost:undefined`; require the port explicitly.+ const info = buildRuntimeServicesInfo({+ mode: "dev:safe",+ agentServerPort: 18000,+ automation: {},+ }) as RuntimeServicesInfoShape;+ expect(info.services.automation).toBeUndefined();+ });++ it("throws when agentServerPort is missing", () => {+ expect(() =>+ buildRuntimeServicesInfo({+ mode: "dev:safe",+ }),+ ).toThrow(/agentServerPort is required/);+ });++ it("accepts the legacy vitePort alias for frontendPort", () => {+ // dev-safe.mjs's `main()` and some external callers still pass the+ // older option name; keep them working for one release.+ const info = buildRuntimeServicesInfo({+ mode: "dev:safe",+ agentServerPort: 18000,+ vitePort: 3001,+ }) as RuntimeServicesInfoShape;+ expect(info.services.frontend?.url_from_agent).toBe(+ "http://localhost:3001",+ );+ });+});diff --git a/bin/agent-canvas.mjs b/bin/agent-canvas.mjsindex c9076e2ff3..686ff15b33 100755--- a/bin/agent-canvas.mjs+++ b/bin/agent-canvas.mjs@@ -81,11 +81,8 @@ this is a packaging error. If running from source:let main, checkDockerPrereqs, startAgentServerDocker, CONTAINER_WORKSPACES_DIR;try {({ main } = await import("../scripts/dev-with-automation.mjs"));- ({- checkDockerPrereqs,- startAgentServerDocker,- CONTAINER_WORKSPACES_DIR,- } = await import("../scripts/dev-docker.mjs"));+ ({ checkDockerPrereqs, startAgentServerDocker, CONTAINER_WORKSPACES_DIR } =+ await import("../scripts/dev-docker.mjs"));} catch (err) {console.error("Failed to load required scripts. Try reinstalling:");console.error(" npm install -g @openhands/agent-canvas@latest");@@ -100,6 +97,10 @@ main({viteWorkingDir: CONTAINER_WORKSPACES_DIR,staticMode: true,staticDir: BUILD_DIR,+ // Agent-server runs in a Docker container; host services are reached+ // via "host.docker.internal" from the agent's POV.+ agentHostAlias: "host.docker.internal",+ mode: "agent-canvas",}).catch((err) => {console.error(`Fatal error: ${err.message}`);if (err.stack) {diff --git a/scripts/dev-docker.mjs b/scripts/dev-docker.mjsindex a3283c9ec2..ff6e5224aa 100644--- a/scripts/dev-docker.mjs+++ b/scripts/dev-docker.mjs@@ -365,6 +365,11 @@ if (isMainModule) {viteWorkingDir: CONTAINER_WORKSPACES_DIR,defaultStaticMode: true,buildStaticFrontend: buildFrontend,+ // The agent-server runs inside a Docker container in this mode, so+ // host services (ingress, automation, vite) are reachable via+ // "host.docker.internal" rather than "localhost" from the agent's POV.+ agentHostAlias: "host.docker.internal",+ mode: "dev:docker",}).catch((err) => {logError(`Fatal error: ${err.message}`);if (err.stack) {diff --git a/scripts/dev-safe.mjs b/scripts/dev-safe.mjsindex b6892c6612..b456648af3 100644--- a/scripts/dev-safe.mjs+++ b/scripts/dev-safe.mjs@@ -454,10 +454,7 @@ export function buildSafeDevConfig(cwd = process.cwd(), env = process.env) {env.OH_CANVAS_SAFE_BACKEND_PORT,DEFAULT_BACKEND_PORT,);- const vscodePort = parsePort(- env.OH_CANVAS_SAFE_VSCODE_PORT,- backendPort + 1,- );+ const vscodePort = parsePort(env.OH_CANVAS_SAFE_VSCODE_PORT, backendPort + 1);return buildConfigFromPorts({ backendPort, vscodePort }, cwd, env);}@@ -603,6 +600,124 @@ export function buildAgentServerEnv(config) {};}+/**+ * 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. In dev-safe /+ * dev-with-automation the agent-server runs on the host, so the host+ * alias is "localhost". In dev-docker the agent-server runs inside a+ * container and reaches host services via "host.docker.internal".+ *+ * @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-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,+ };+}+export function buildNpmScriptCommand(scriptName,platform = process.platform,@@ -636,9 +751,7 @@ export function validateLocalAgentServerPath(localPath) {);}if (!existsSync(localPath)) {- throw new Error(- `OH_AGENT_SERVER_LOCAL_PATH does not exist: ${localPath}`,- );+ throw new Error(`OH_AGENT_SERVER_LOCAL_PATH does not exist: ${localPath}`);}for (const subdir of LOCAL_AGENT_SERVER_SUBDIRS) {const subdirPath = path.join(localPath, subdir);@@ -670,10 +783,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") {@@ -810,6 +927,10 @@ async function main() {}const frontendCommand = buildNpmScriptCommand("dev:frontend");+ const runtimeServicesInfo = buildRuntimeServicesInfo({+ mode: "dev:safe",+ agentServerPort: config.backendPort,+ });frontend = spawnProcess(frontendCommand.command, frontendCommand.args, {cwd: config.cwd,env: {@@ -819,6 +940,9 @@ async function main() {VITE_WORKING_DIR: config.workingDir,// Pass session API key so frontend can authenticate with agent-serverVITE_SESSION_API_KEY: config.sessionApiKey,+ // Inform the frontend (and downstream, the agent's system prompt) about+ // which services are available in this dev stack.+ VITE_RUNTIME_SERVICES_INFO: JSON.stringify(runtimeServicesInfo),},});diff --git a/scripts/dev-with-automation.mjs b/scripts/dev-with-automation.mjsindex 8dc5460133..46b30a26e9 100644--- a/scripts/dev-with-automation.mjs+++ b/scripts/dev-with-automation.mjs@@ -51,6 +51,7 @@ import {buildSafeDevConfig,buildAgentServerEnv,buildNpmScriptCommand,+ buildRuntimeServicesInfo,formatMissingUvxGuidance,findFreePorts,getOrCreatePersistedApiKey,@@ -671,10 +672,32 @@ function startIngress(config) {);}+/**+ * Build the JSON-serializable runtime services info for an automation+ * stack. Used by both the Vite dev server (dev mode) and static-build.mjs+ * (static mode) so the frontend can populate the agent's+ * `<RUNTIME_SERVICES>` system-prompt block.+ */+export function buildAutomationRuntimeServicesInfo(config) {+ return buildRuntimeServicesInfo({+ mode: config.mode ?? "dev:automation",+ agentHostAlias: config.agentHostAlias ?? "localhost",+ agentServerPort: config.agentServerPort,+ ingressPort: config.ingressPort,+ frontendPort: config.vitePort,+ // The same port hosts Vite in dynamic mode and a static-file server+ // in static mode. The launcher records this on the config so the+ // description shown to the agent matches reality.+ frontendKind: config.frontendKind ?? "vite",+ automation: { port: config.autoBackendPort },+ });+}+function startVite(config) {logService("vite", `Starting on port ${config.vitePort}...`, c.magenta);const frontendCommand = buildNpmScriptCommand("dev:frontend");+ const runtimeServicesInfo = buildAutomationRuntimeServicesInfo(config);spawnService("vite", frontendCommand.command, frontendCommand.args, {cwd: config.canvasPath,@@ -689,6 +712,9 @@ function startVite(config) {VITE_SESSION_API_KEY: config.sessionApiKey,// Automation API key for frontend to authenticate with automation backendVITE_AUTOMATION_API_KEY: config.localApiKey,+ // Inform the frontend (and downstream, the agent's system prompt) about+ // which services are available in this dev stack.+ VITE_RUNTIME_SERVICES_INFO: JSON.stringify(runtimeServicesInfo),// Session API key for agent-server auth (when SESSION_API_KEY is set)...(config.sessionApiKey && {VITE_SESSION_API_KEY: config.sessionApiKey,@@ -840,6 +866,14 @@ async function main(options = {}) {defaultStaticMode = false,buildStaticFrontend,staticDir: staticDirOverride,+ // Hostname the agent uses to reach services running on the host.+ // dev-docker.mjs overrides this to "host.docker.internal" because the+ // agent-server runs in a container and the host is not "localhost"+ // from its perspective.+ agentHostAlias = "localhost",+ // Human-readable label for the dev mode, surfaced in the agent's+ // <RUNTIME_SERVICES> system-prompt block.+ mode = "dev:automation",} = options;const args = parseArgs();@@ -869,6 +903,12 @@ async function main(options = {}) {// Build config with dynamic port allocationconst config = await buildConfig(args);if (viteWorkingDir) config.viteWorkingDir = viteWorkingDir;+ // Stamp the dev-mode label, host alias, and frontend kind on the config+ // so downstream helpers (Vite spawn, static build) can produce a+ // runtime-services info object describing what the agent can reach.+ config.mode = mode;+ config.agentHostAlias = agentHostAlias;+ config.frontendKind = useStaticMode ? "static" : "vite";ensureDirectories(config);if (typeof extraPrereqs === "function") {extraPrereqs(config);diff --git a/scripts/static-build.mjs b/scripts/static-build.mjsindex 3d094331e8..5f60f1b6f1 100644--- a/scripts/static-build.mjs+++ b/scripts/static-build.mjs@@ -3,6 +3,7 @@ import { existsSync } from "node:fs";import { join } from "node:path";import {+ buildAutomationRuntimeServicesInfo,c,logError,logService,@@ -50,6 +51,12 @@ export function buildFrontend(config, args = {}) {// a fresh browser session seeds the Local backend with an empty key and// all authenticated agent-server calls fail with 401.VITE_SESSION_API_KEY: config.sessionApiKey,+ // Bake a description of the runtime services in this dev stack so the+ // frontend can populate the agent's <RUNTIME_SERVICES> system-prompt+ // block when creating a conversation.+ VITE_RUNTIME_SERVICES_INFO: JSON.stringify(+ buildAutomationRuntimeServicesInfo(config),+ ),// Intentionally do NOT set VITE_BACKEND_BASE_URL: leaving it unset makes// the runtime fall back to window.location.origin, which keeps the build// portable across localhost, LAN hosts, and tunnels such as ngrok.diff --git a/src/api/agent-server-adapter.ts b/src/api/agent-server-adapter.tsindex f7f9885a2f..b768b8cc16 100644--- a/src/api/agent-server-adapter.ts+++ b/src/api/agent-server-adapter.ts@@ -51,6 +51,146 @@ function browserToolsEnabled() {return import.meta.env.VITE_ENABLE_BROWSER_TOOLS !== "false";}+/**+ * Shape of `VITE_RUNTIME_SERVICES_INFO` (set by the dev launchers in+ * scripts/dev-*.mjs). All URLs are written from the agent's point of view,+ * not the browser's. The block is rendered into the agent's system prompt+ * via `AgentContext.system_message_suffix` so the agent knows what's+ * reachable from inside its sandbox without having to probe.+ */+interface RuntimeServicesInfo {+ mode?: string;+ agent_host_alias?: string;+ services?: {+ agent_server?: { description?: string; url_from_agent?: string };+ ingress?: { description?: string; url_from_agent?: string };+ frontend?: {+ kind?: "vite" | "static";+ description?: string;+ url_from_agent?: string;+ };+ // `vite` is the legacy key name for the frontend entry, accepted for+ // one release while older dev-stack launchers may still emit it.+ vite?: { description?: string; url_from_agent?: string };+ automation?: {+ description?: string;+ url_from_agent?: string;+ api_prefix?: string;+ docs_url?: string;+ openapi_url?: string;+ auth_env_var?: string;+ };+ };+}++function parseRuntimeServicesInfo(): RuntimeServicesInfo | null {+ const raw = import.meta.env.VITE_RUNTIME_SERVICES_INFO?.trim();+ if (!raw) return null;+ try {+ const parsed = JSON.parse(raw) as RuntimeServicesInfo;+ if (!parsed || typeof parsed !== "object") return null;+ return parsed;+ } catch {+ // Malformed JSON: ignore and fall back to no runtime info, rather than+ // tearing down conversation creation over a misconfigured dev env var.+ return null;+ }+}++/**+ * Render the runtime services info into a markdown block suitable for+ * appending to the system prompt via `AgentContext.system_message_suffix`.+ *+ * Returns `undefined` when no runtime info is configured, so callers can+ * safely omit the field on production builds (where the launcher doesn't+ * set `VITE_RUNTIME_SERVICES_INFO`).+ */+export function buildRuntimeServicesSystemSuffix(): string | undefined {+ const info = parseRuntimeServicesInfo();+ if (!info?.services) return undefined;++ const lines: string[] = [];+ lines.push("<RUNTIME_SERVICES>");+ if (info.mode) {+ lines.push(+ `You are running inside an agent-canvas dev stack started in '${info.mode}' mode.`,+ );+ } else {+ lines.push("You are running inside an agent-canvas dev stack.");+ }+ lines.push(+ "The following services are reachable from your sandbox. URLs are written",+ "from your point of view (i.e., as you should curl/fetch them).",+ "",+ );++ const { agent_server, ingress, automation } = info.services;+ // Accept `frontend` (current key) or `vite` (legacy key) for the+ // frontend service entry. The legacy fallback can be removed once all+ // launchers in this repo emit `frontend`.+ const frontend = info.services.frontend ?? info.services.vite;++ if (agent_server?.url_from_agent) {+ lines.push(+ `* Agent Server (you): ${agent_server.url_from_agent}`,+ ` ${agent_server.description ?? "The agent-server hosting your tool calls."}`,+ );+ }+ if (ingress?.url_from_agent) {+ lines.push(+ `* Ingress: ${ingress.url_from_agent}`,+ ` ${ingress.description ?? "Unified entry point for browser-facing traffic."}`,+ );+ }+ if (frontend?.url_from_agent) {+ lines.push(+ `* Frontend: ${frontend.url_from_agent}`,+ ` ${frontend.description ?? "Frontend dev server."}`,+ );+ }+ if (automation?.url_from_agent) {+ lines.push(+ `* Automation backend: ${automation.url_from_agent}`,+ ` ${automation.description ?? "OpenHands Automations service."}`,+ );+ if (automation.docs_url) {+ lines.push(` Docs: ${automation.docs_url}`);+ }+ if (automation.openapi_url) {+ lines.push(` OpenAPI: ${automation.openapi_url}`);+ }+ if (automation.auth_env_var) {+ lines.push(+ ` Auth: header 'X-API-Key: $${automation.auth_env_var}'`,+ );+ }+ } else {+ lines.push(+ "* Automation backend: not running in this dev mode (skip /api/automation calls).",+ );+ }++ // Anchor the "don't guess" warning to the actual agent-server URL for+ // this stack instead of a hardcoded port. The agent-server listens on+ // different ports across dev modes (18000 in dev:safe, 8000 in+ // dev:docker, ...), and baking the wrong port into the system prompt+ // is exactly the kind of confusion this block is meant to prevent.+ const agentServerUrl = agent_server?.url_from_agent;+ lines.push(+ "",+ "Trust this block over guessing: do not assume any other URLs are running.",+ );+ if (agentServerUrl) {+ lines.push(+ `In particular, ${agentServerUrl} inside your sandbox is the Agent Server`,+ "you are running inside of β NOT the automation backend.",+ );+ }+ lines.push("</RUNTIME_SERVICES>");++ return lines.join("\n");+}+export function toConversationUrl(conversationId: string): string {// Local-format conversation URL β points at whichever local agent-server// is actually serving the conversation (the bundled one when the active@@ -309,12 +449,20 @@ function buildConfiguredAgentSettings(settings: Settings): SettingsRecord {}function createAgentFromSettings(agentSettings: SettingsRecord) {+ const runtimeServicesSuffix = buildRuntimeServicesSystemSuffix();return {kind: "Agent",...agentSettings,agent_context: {load_public_skills: true,load_user_skills: true,+ // When the dev launcher provided `VITE_RUNTIME_SERVICES_INFO`, append+ // a <RUNTIME_SERVICES> block to the system prompt so the agent knows+ // which services exist in this dev stack (e.g. automation backend+ // URL, ingress URL) instead of having to probe.+ ...(runtimeServicesSuffix+ ? { system_message_suffix: runtimeServicesSuffix }+ : {}),},};}