Skip to content

πŸ™Œ OpenHands: AI-Driven Development

Fix static automation auth and switch LLM tool (#474)

Graham Neubig2899c7b38326
diff --git a/AGENTS.md b/AGENTS.md
index d47a20d343..da262f58ac 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -143,19 +143,19 @@
- `scripts/dev-safe.mjs` uses `uvx` for temporary agent-server installation β€” no permanent `uv tool install` needed. Environment variables (highest precedence first):
- `OH_AGENT_SERVER_LOCAL_PATH` β€” absolute path to a local `software-agent-sdk` checkout. Runs the local checkout via `uvx` with `--with-editable` for `openhands-sdk`/`openhands-tools`/`openhands-workspace` and `--reinstall` for `openhands-agent-server`, so SDK edits are picked up on restart. Highest precedence.
- `OH_AGENT_SERVER_GIT_REF` β€” git commit SHA or branch name (takes precedence over version)
- - `OH_AGENT_SERVER_VERSION` β€” specific PyPI version (e.g., "1.22.0")
+ - `OH_AGENT_SERVER_VERSION` β€” specific PyPI version (e.g., "1.22.1")
- `OH_SECRET_KEY` β€” secret key for settings encryption; uses a static default for local dev since it's needed for reading persisted encrypted values across restarts
- `SESSION_API_KEY` / `OH_SESSION_API_KEYS_0` / `VITE_SESSION_API_KEY` β€” session API key for agent-server authentication; auto-generated using `crypto.randomBytes(32)` if not set, passed to both agent-server (`OH_SESSION_API_KEYS_0`) and frontend (`VITE_SESSION_API_KEY`)
- - Default: released PyPI version `1.22.0` for agent-server SDK libraries
+ - Default: released PyPI version `1.22.1` for agent-server SDK libraries
- `scripts/dev-docker.mjs` runs the agent-server inside a Docker container instead of via `uvx`, and serves a static frontend build by default for stable user/tunnel access. Use `npm run dev:docker:dynamic` or `node scripts/dev-docker.mjs --dynamic` for the Vite dev server. The default image uses versioned release tags:
- - `DEFAULT_AGENT_SERVER_TAG` β€” uses format `{version}-python` (e.g., `1.22.0-python`) for reproducibility. Note: the SDK build script strips the "v" prefix from semver release tags.
+ - `DEFAULT_AGENT_SERVER_TAG` β€” uses format `{version}-python` (e.g., `1.22.1-python`) for reproducibility. Note: the SDK build script strips the "v" prefix from semver release tags.
- Should stay in sync with `DEFAULT_AGENT_SERVER_VERSION` in `dev-safe.mjs` for consistency between Docker and non-Docker dev modes
- `OH_AGENT_SERVER_GIT_REF` β€” override to use a git ref-based tag (e.g., `main` β†’ `main-python`, `abc1234` β†’ `abc1234-python`)
- Docker images are published from https://github.com/OpenHands/software-agent-sdk via the Agent Server workflow to `ghcr.io/openhands/agent-server`
- The container runs as the host UID/GID when Node exposes `process.getuid()` / `process.getgid()`. In the default isolated-home mode, `/home/openhands` is a writable tmpfs and persistence remains at `/home/openhands/.openhands`, so host-owned bind mounts remain writable without persisting ordinary home cache/config files.
-- Security: Both `scripts/dev-safe.mjs` and `scripts/dev-with-automation.mjs` auto-generate random API keys on each startup for better security isolation:
- - `SESSION_API_KEY` β€” 64-character hex (256-bit) for agent-server API authentication; auto-generated per session unless overridden via env var
- - `AUTOMATION_LOCAL_API_KEY` β€” 64-character hex for automation backend auth; auto-generated per session unless overridden
+- Security: `scripts/dev-safe.mjs` and `scripts/dev-with-automation.mjs` auto-generate random API keys when needed and persist the defaults so static builds, localStorage, and restarted services stay in sync:
+ - `SESSION_API_KEY` β€” 64-character hex (256-bit) for agent-server API authentication; persisted at `~/.openhands/agent-canvas/session-api-key.txt` unless overridden via env var
+ - `AUTOMATION_LOCAL_API_KEY` β€” 64-character hex for automation backend auth; persisted at `~/.openhands/agent-canvas/automation-api-key.txt` unless overridden
- `OH_SECRET_KEY` β€” kept as a static default because it's used for encrypting/decrypting persisted settings values and needs consistency across restarts
- `scripts/dev-safe.mjs` should fail fast if `uvx` cannot be spawned (for example missing PATH entries).
- `npm run dev` now runs the Docker full stack with automation and a static frontend by default (via `dev:docker`). `npm run dev:dangerously-dockerless` does the same without Docker through the `dev-static.mjs` launcher. Use `npm run dev:docker:dynamic` or `npm run dev:dangerously-dockerless:dynamic` for Vite/HMR.
@@ -163,9 +163,10 @@
- `/api/automation/*` β†’ automation backend (:18001)
- `/api/*`, `/sockets`, etc. β†’ agent server (:18000)
- `/*` (default) β†’ frontend server (:3001), either Vite or static depending on launcher mode
- - Environment variables: `PORT` (ingress port, default: 8000), `OH_AUTOMATION_GIT_REF` (git ref, overrides default version), `OH_AUTOMATION_VERSION` (default: `1.0.0a2`), `AUTOMATION_LOCAL_API_KEY` (optional, use a fixed key; default: auto-generated random key per session)
+ - Environment variables: `PORT` (ingress port, default: 8000), `OH_AUTOMATION_GIT_REF` (git ref, overrides default version), `OH_AUTOMATION_VERSION` (default: `1.0.0a2`), `AUTOMATION_LOCAL_API_KEY` (optional, use a fixed key; default: persisted generated key), `OH_AUTOMATION_API_KEY_PATH` (override the persisted default key path)
+ - `scripts/check-sdk-version-sync.mjs` checks the released `openhands-automation` package against `DEFAULT_AUTOMATION_SDK_VERSION` in `scripts/dev-with-automation.mjs`; that value may intentionally lag `DEFAULT_AGENT_SERVER_VERSION` while automation has not yet published a matching release.
- Access points: `http://localhost:8000/` (main UI), `http://localhost:8000/api/automation/docs` (API docs)
- - Security: `AUTOMATION_LOCAL_API_KEY` is auto-generated using `crypto.randomBytes(32)` on each startup for better security isolation. Set the env var explicitly to use a consistent key across restarts. The cipher key (`OH_SECRET_KEY`) keeps a static default for local dev since it's used for encrypting/decrypting persisted settings values.
+ - Security: `AUTOMATION_LOCAL_API_KEY` defaults to a generated key persisted across restarts because static frontend builds bake it into `VITE_AUTOMATION_API_KEY`. Set the env var explicitly to rotate or pin it. The cipher key (`OH_SECRET_KEY`) keeps a static default for local dev since it's used for encrypting/decrypting persisted settings values.
- `scripts/ingress.mjs` is a standalone HTTP reverse proxy that can be used independently to route traffic to multiple backends based on URL path prefix.
- `scripts/dev-safe.mjs` (now `npm run dev:minimal`) runs just agent-server + Vite without automation.
- Vite dev mode can black-screen on first load with `504 Outdated Optimize Dep` if core client-entry deps are not prebundled; keep `react`, `react/jsx-runtime`, `react-dom/client`, and `react-router/dom` in `optimizeDeps.include`.
diff --git a/__tests__/api/agent-server-adapter.test.ts b/__tests__/api/agent-server-adapter.test.ts
index e61cf5b878..3bdab168ab 100644
--- a/__tests__/api/agent-server-adapter.test.ts
+++ b/__tests__/api/agent-server-adapter.test.ts
@@ -82,6 +82,7 @@ describe("buildStartConversationRequest", () => {
agent: Record<string, unknown> & {
llm: Record<string, unknown>;
tools: Array<{ name: string; params: Record<string, unknown> }>;
+ include_default_tools: string[];
};
workspace: { working_dir: string };
initial_message: { content: Array<{ text: string }> };
@@ -109,6 +110,10 @@ describe("buildStartConversationRequest", () => {
{ name: "task_tracker", params: {} },
{ name: "browser_tool_set", params: {} },
]);
+ expect(payload.agent.include_default_tools).toEqual([
+ "FinishTool",
+ "ThinkTool",
+ ]);
expect(payload.agent.agent_context).toEqual({
load_public_skills: true,
load_user_skills: true,
@@ -121,6 +126,31 @@ describe("buildStartConversationRequest", () => {
expect(payload.initial_message.content[0]?.text).toBe("hello");
});
+ it("adds the SDK switch-LLM built-in when the agent-server setting is enabled", () => {
+ const payload = buildStartConversationRequest({
+ settings: {
+ ...DEFAULT_SETTINGS,
+ agent_settings: {
+ ...DEFAULT_SETTINGS.agent_settings,
+ enable_switch_llm_tool: true,
+ llm: { model: "nested-model" },
+ },
+ },
+ }) as {
+ agent: {
+ include_default_tools: string[];
+ enable_switch_llm_tool?: boolean;
+ };
+ };
+
+ expect(payload.agent.include_default_tools).toEqual([
+ "FinishTool",
+ "ThinkTool",
+ "SwitchLLMTool",
+ ]);
+ expect(payload.agent.enable_switch_llm_tool).toBeUndefined();
+ });
+
it("omits browser_tool_set when the server does not advertise browser support", () => {
mockIsAgentServerToolAvailable.mockReturnValue(false);
diff --git a/__tests__/scripts/dev-safe.test.ts b/__tests__/scripts/dev-safe.test.ts
index bc1fb7d84c..3abccc05d4 100644
--- a/__tests__/scripts/dev-safe.test.ts
+++ b/__tests__/scripts/dev-safe.test.ts
@@ -309,14 +309,14 @@ describe("buildAgentServerCommand", () => {
// Defaults to the released PyPI version with all SDK packages pinned to same version
expect(cmd.args).toEqual([
"--from",
- "openhands-agent-server==1.22.0",
+ "openhands-agent-server==1.22.1",
"--with",
- "openhands-tools==1.22.0",
+ "openhands-tools==1.22.1",
"--with",
- "openhands-workspace==1.22.0",
+ "openhands-workspace==1.22.1",
"agent-server",
]);
- expect(cmd.source).toBe("PyPI (1.22.0, default)");
+ expect(cmd.source).toBe("PyPI (1.22.1, default)");
});
it("uses specific PyPI version when OH_AGENT_SERVER_VERSION is set with all packages pinned", () => {
diff --git a/__tests__/scripts/dev-with-automation.test.ts b/__tests__/scripts/dev-with-automation.test.ts
index 9247dbcc6f..38284eae40 100644
--- a/__tests__/scripts/dev-with-automation.test.ts
+++ b/__tests__/scripts/dev-with-automation.test.ts
@@ -131,9 +131,8 @@ describe("buildConfig", () => {
});
/**
- * Build an env that points the persisted session-api-key file at a
- * fresh temp dir, so tests don't write to the user's real
- * ~/.openhands/agent-canvas/session-api-key.txt.
+ * Build an env that points persisted dev API key files at a fresh temp dir,
+ * so tests don't write to the user's real ~/.openhands/agent-canvas files.
*/
function envWithIsolatedKeyPath(
extra: Record<string, string> = {},
@@ -142,6 +141,7 @@ describe("buildConfig", () => {
keyDirs.push(dir);
return {
OH_SESSION_API_KEY_PATH: path.join(dir, "session-api-key.txt"),
+ OH_AUTOMATION_API_KEY_PATH: path.join(dir, "automation-api-key.txt"),
...extra,
};
}
@@ -273,13 +273,26 @@ describe("buildConfig", () => {
expect(config.verbose).toBe(true);
});
- it("auto-generates random local API key by default", async () => {
+ it("uses a persisted generated local automation API key by default", async () => {
const config = await buildConfig({}, envWithIsolatedKeyPath());
// Default is a 64-char hex string (256-bit random key)
expect(config.localApiKey).toMatch(/^[0-9a-f]{64}$/);
});
+ it("reuses the persisted local automation API key across restarts", async () => {
+ const env = envWithIsolatedKeyPath();
+ const first = await buildConfig({}, env);
+
+ // Simulate a fresh process invocation (the file on disk should be
+ // what makes the key stable).
+ resetPersistedSessionApiKeyCache();
+
+ const second = await buildConfig({}, env);
+
+ expect(second.localApiKey).toBe(first.localApiKey);
+ });
+
it("respects custom AUTOMATION_LOCAL_API_KEY from env", async () => {
const config = await buildConfig(
{},
diff --git a/scripts/check-sdk-version-sync.mjs b/scripts/check-sdk-version-sync.mjs
index a12d995323..320393cbcf 100644
--- a/scripts/check-sdk-version-sync.mjs
+++ b/scripts/check-sdk-version-sync.mjs
@@ -4,7 +4,7 @@
* Check SDK Version Sync
*
* Verifies that the released automation package (openhands-automation on PyPI)
- * uses the same SDK version as specified in dev-safe.mjs for all agent SDK libraries:
+ * uses the SDK version expected for that automation release for all agent SDK libraries:
* - openhands-sdk
* - openhands-tools
* - openhands-workspace
@@ -12,6 +12,8 @@
*
* This script checks the RELEASED PyPI version of openhands-automation (as specified
* by DEFAULT_AUTOMATION_VERSION in dev-with-automation.mjs), not the main branch.
+ * DEFAULT_AUTOMATION_SDK_VERSION records the SDK dependency version for that
+ * released automation package and may intentionally lag DEFAULT_AGENT_SERVER_VERSION.
*
* This script is run in CI to catch version drift between projects.
*
@@ -21,7 +23,7 @@
* node scripts/check-sdk-version-sync.mjs --check-pypi
*
* Environment variables:
- * EXPECTED_SDK_VERSION - Override the expected version (instead of reading from dev-safe.mjs)
+ * EXPECTED_SDK_VERSION - Override the expected version (instead of reading from dev-with-automation.mjs)
* AUTOMATION_PACKAGE_NAME - Override the automation package name (default: openhands-automation)
* AUTOMATION_PACKAGE_VERSION - Override the automation package version (instead of reading from dev-with-automation.mjs)
*
@@ -51,11 +53,13 @@ if (showHelp) {
console.log(`
SDK Version Sync Check
-Verifies that the released openhands-automation package on PyPI uses the same
-SDK version as specified in this repo's dev-safe.mjs.
+Verifies that the released openhands-automation package on PyPI uses the
+SDK version expected for that automation release.
The automation version is read from DEFAULT_AUTOMATION_VERSION in
-dev-with-automation.mjs (currently used for local development).
+dev-with-automation.mjs (currently used for local development). The expected
+SDK dependency version is read from DEFAULT_AUTOMATION_SDK_VERSION when present,
+falling back to DEFAULT_AGENT_SERVER_VERSION for older configs.
Usage:
node scripts/check-sdk-version-sync.mjs [options]
@@ -65,7 +69,7 @@ Options:
--help, -h Show this help
Environment variables:
- EXPECTED_SDK_VERSION Override the expected SDK version (instead of reading from dev-safe.mjs)
+ EXPECTED_SDK_VERSION Override the expected SDK version (instead of reading from dev-with-automation.mjs)
AUTOMATION_PACKAGE_NAME Override the automation package name (default: openhands-automation)
AUTOMATION_PACKAGE_VERSION Override the automation package version (instead of reading from dev-with-automation.mjs)
@@ -140,16 +144,9 @@ function sleep(ms) {
}
/**
- * Read the expected SDK version from environment variable or dev-safe.mjs
+ * Read the default agent-server SDK version from dev-safe.mjs.
*/
-function getExpectedVersion() {
- // Allow override via environment variable (useful for CI triggers)
- const envVersion = process.env.EXPECTED_SDK_VERSION;
- if (envVersion && envVersion.trim()) {
- return { version: envVersion.trim(), source: "EXPECTED_SDK_VERSION env var" };
- }
-
- // Read from dev-safe.mjs
+function getDefaultAgentServerVersion() {
const devSafePath = join(projectRoot, "scripts", "dev-safe.mjs");
const content = readFileSync(devSafePath, "utf8");
@@ -164,6 +161,32 @@ function getExpectedVersion() {
return { version: match[1], source: "dev-safe.mjs" };
}
+/**
+ * Read the expected automation SDK dependency version from environment,
+ * dev-with-automation.mjs, or dev-safe.mjs.
+ */
+function getExpectedVersion() {
+ // Allow override via environment variable (useful for CI triggers).
+ const envVersion = process.env.EXPECTED_SDK_VERSION;
+ if (envVersion && envVersion.trim()) {
+ return { version: envVersion.trim(), source: "EXPECTED_SDK_VERSION env var" };
+ }
+
+ const devAutomationPath = join(projectRoot, "scripts", "dev-with-automation.mjs");
+ const content = readFileSync(devAutomationPath, "utf8");
+ const match = content.match(
+ /const DEFAULT_AUTOMATION_SDK_VERSION = "([^"]+)"/,
+ );
+ if (match) {
+ return {
+ version: match[1],
+ source: "DEFAULT_AUTOMATION_SDK_VERSION in dev-with-automation.mjs",
+ };
+ }
+
+ return getDefaultAgentServerVersion();
+}
+
/**
* Fetch the latest version of a package from PyPI
*/
@@ -304,9 +327,16 @@ async function main() {
// Get expected version from env var or dev-safe.mjs
const { version: expectedVersion, source: versionSource } = getExpectedVersion();
console.log(
- `Expected SDK version: ${colors.green}${expectedVersion}${colors.reset} (from ${versionSource})`,
+ `Expected automation SDK version: ${colors.green}${expectedVersion}${colors.reset} (from ${versionSource})`,
);
+ const { version: agentServerVersion } = getDefaultAgentServerVersion();
+ if (!versionsEqual(agentServerVersion, expectedVersion)) {
+ console.log(
+ `${colors.yellow}Note:${colors.reset} DEFAULT_AGENT_SERVER_VERSION is ${agentServerVersion}; automation release dependencies may lag while a compatible automation package is pending.`,
+ );
+ }
+
// Get automation version from env var or dev-with-automation.mjs
const { version: automationVersion, source: automationSource } = getAutomationVersion();
console.log(
@@ -388,7 +418,7 @@ async function main() {
`${colors.red}Version mismatch detected!${colors.reset}`,
);
console.log("");
- console.log(`The released ${AUTOMATION_PACKAGE_NAME}==${automationVersion} uses different SDK versions than expected.`);
+ console.log(`The released ${AUTOMATION_PACKAGE_NAME}==${automationVersion} uses different SDK versions than expected for that automation release.`);
console.log("");
console.log("Mismatched packages:");
for (const m of mismatches) {
@@ -397,7 +427,7 @@ async function main() {
console.log("");
console.log("To fix, update one of the following:");
console.log(
- ` 1. Update DEFAULT_AGENT_SERVER_VERSION in scripts/dev-safe.mjs to match the automation release`,
+ ` 1. Update DEFAULT_AUTOMATION_SDK_VERSION in scripts/dev-with-automation.mjs to match the automation release`,
);
console.log(
` 2. Release a new version of ${AUTOMATION_PACKAGE_NAME} with SDK dependencies pinned to ${expectedVersion}`,
diff --git a/scripts/dev-docker.mjs b/scripts/dev-docker.mjs
index 43dd188d6f..a3283c9ec2 100644
--- a/scripts/dev-docker.mjs
+++ b/scripts/dev-docker.mjs
@@ -75,9 +75,9 @@ const CONTAINER_LOCAL_SDK_DIR = "/agent-server-src";
const AGENT_SERVER_REPO = "ghcr.io/openhands/agent-server";
// Default tag used when OH_AGENT_SERVER_GIT_REF is not set.
// Should match DEFAULT_AGENT_SERVER_VERSION in dev-safe.mjs for consistency.
-// Format: {version}-python (e.g., 1.22.0-python) for released versions.
+// Format: {version}-python (e.g., 1.22.1-python) for released versions.
// Note: The SDK build script strips the "v" prefix from semver release tags.
-const DEFAULT_AGENT_SERVER_TAG = "1.22.0-python";
+const DEFAULT_AGENT_SERVER_TAG = "1.22.1-python";
const CONTAINER_NAME = "agent-canvas-dev-agent-server";
// Keep the in-container home at the path advertised by the agent-server
diff --git a/scripts/dev-safe.mjs b/scripts/dev-safe.mjs
index c6d401ca70..b6892c6612 100644
--- a/scripts/dev-safe.mjs
+++ b/scripts/dev-safe.mjs
@@ -38,7 +38,7 @@ const LOCAL_AGENT_SERVER_SUBDIRS = [
const DEFAULT_SECRET_KEY = "openhands-dev-secret-key-change-in-prod";
// Default agent-server version (released PyPI version)
// Set OH_AGENT_SERVER_GIT_REF to use a git branch/SHA instead
-const DEFAULT_AGENT_SERVER_VERSION = "1.22.0";
+const DEFAULT_AGENT_SERVER_VERSION = "1.22.1";
const FRONTEND_REQUIRED_BINS = ["cross-env", "react-router"];
/**
@@ -68,7 +68,7 @@ export const DEFAULT_SESSION_API_KEY_PATH = path.join(
// Cache so repeated lookups within a single process return the same key,
// keyed by file path so tests can use temp paths in isolation.
-const persistedSessionApiKeyCache = new Map();
+const persistedApiKeyCache = new Map();
/**
* Load the persisted default session API key, generating + persisting one if
@@ -84,21 +84,37 @@ const persistedSessionApiKeyCache = new Map();
export function getOrCreatePersistedSessionApiKey(
filePath = DEFAULT_SESSION_API_KEY_PATH,
) {
- const cached = persistedSessionApiKeyCache.get(filePath);
+ return getOrCreatePersistedApiKey(filePath, "session");
+}
+
+/**
+ * Load a persisted default API key, generating + persisting one if the file
+ * doesn't exist yet.
+ *
+ * Best-effort: if the file can't be written (e.g. read-only home dir), we
+ * fall back to an in-memory key for this process so dev still works -- the
+ * key just won't survive a restart.
+ *
+ * @param {string} filePath - Where to read/write the key.
+ * @param {string} label - Human-readable key label for warning messages.
+ * @returns {string} The (hex) API key.
+ */
+export function getOrCreatePersistedApiKey(filePath, label = "API") {
+ const cached = persistedApiKeyCache.get(filePath);
if (cached) return cached;
// Try to read an existing key.
try {
const existing = readFileSync(filePath, "utf8").trim();
if (existing) {
- persistedSessionApiKeyCache.set(filePath, existing);
+ persistedApiKeyCache.set(filePath, existing);
return existing;
}
// File exists but is empty -- treat as if missing and regenerate.
} catch (error) {
if (!isEnoentError(error)) {
console.warn(
- `Could not read persisted session API key from ${filePath}: ${error.message}. Regenerating.`,
+ `Could not read persisted ${label} API key from ${filePath}: ${error.message}. Regenerating.`,
);
}
}
@@ -110,10 +126,10 @@ export function getOrCreatePersistedSessionApiKey(
writeFileSync(filePath, `${newKey}\n`, { mode: 0o600 });
} catch (error) {
console.warn(
- `Could not persist session API key to ${filePath}: ${error.message}. Falling back to in-memory key (will not survive restarts).`,
+ `Could not persist ${label} API key to ${filePath}: ${error.message}. Falling back to in-memory key (will not survive restarts).`,
);
}
- persistedSessionApiKeyCache.set(filePath, newKey);
+ persistedApiKeyCache.set(filePath, newKey);
return newKey;
}
@@ -122,7 +138,7 @@ export function getOrCreatePersistedSessionApiKey(
* Intended for tests that swap the persisted file path between cases.
*/
export function resetPersistedSessionApiKeyCache() {
- persistedSessionApiKeyCache.clear();
+ persistedApiKeyCache.clear();
}
function isEnoentError(error) {
@@ -317,7 +333,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.22.0")
+ * - OH_AGENT_SERVER_VERSION: Specific PyPI version (e.g., "1.22.1")
*
* If none are set, defaults to the released version specified by
* DEFAULT_AGENT_SERVER_VERSION. Set OH_AGENT_SERVER_GIT_REF to use a
diff --git a/scripts/dev-with-automation.mjs b/scripts/dev-with-automation.mjs
index e2de0d9b82..92242d93e7 100644
--- a/scripts/dev-with-automation.mjs
+++ b/scripts/dev-with-automation.mjs
@@ -31,6 +31,7 @@
* - OH_AUTOMATION_GIT_REF: Git ref for automation (default: main)
* - OH_AGENT_SERVER_GIT_REF: Git ref for agent-server
* - AUTOMATION_LOCAL_API_KEY: Custom API key for automation backend auth
+ * - OH_AUTOMATION_API_KEY_PATH: Override persisted default automation key path
*
* Secrets:
* The automation API key is automatically seeded into agent-server secrets
@@ -51,8 +52,8 @@ import {
buildAgentServerEnv,
buildNpmScriptCommand,
formatMissingUvxGuidance,
- generateRandomApiKey,
findFreePorts,
+ getOrCreatePersistedApiKey,
validateFrontendDependencies,
} from "./dev-safe.mjs";
import {
@@ -70,14 +71,20 @@ const DEFAULT_AUTOMATION_PACKAGE = "openhands-automation";
// Default automation version (released PyPI version)
// Set OH_AUTOMATION_GIT_REF to use a git branch/SHA instead
const DEFAULT_AUTOMATION_VERSION = "1.0.0a2";
+// SDK version used by DEFAULT_AUTOMATION_VERSION. This can intentionally lag
+// DEFAULT_AGENT_SERVER_VERSION while automation releases catch up.
+const DEFAULT_AUTOMATION_SDK_VERSION = "1.22.0";
const DEFAULT_BACKEND_PORT = 18000;
const DEFAULT_AUTOMATION_PORT = 18001;
-
-// Auto-generate a random API key for this dev session.
-// This ensures services share the same key during a single invocation,
-// but each restart gets a fresh key for better security isolation.
-// Set AUTOMATION_LOCAL_API_KEY env var to use a consistent key across restarts.
-const DEFAULT_LOCAL_API_KEY = generateRandomApiKey();
+// Where the auto-generated default automation API key is persisted. Static
+// frontend builds bake VITE_AUTOMATION_API_KEY at build time, so the default
+// must remain stable across restarts and --skip-build reuse.
+const DEFAULT_AUTOMATION_API_KEY_PATH = join(
+ homedir(),
+ ".openhands",
+ "agent-canvas",
+ "automation-api-key.txt",
+);
// ═══════════════════════════════════════════════════════════════════════════
// Terminal Styling
@@ -196,6 +203,7 @@ ENVIRONMENT VARIABLES:
OH_AGENT_SERVER_VERSION Specific PyPI version for agent-server
OH_SECRET_KEY Secret key for sessions
AUTOMATION_LOCAL_API_KEY Custom API key for automation backend auth
+ OH_AUTOMATION_API_KEY_PATH Override persisted default automation key path
SECRETS:
The automation API key is automatically seeded into agent-server secrets
@@ -288,8 +296,13 @@ async function buildConfig(args, env = process.env) {
const vscodePort = ports.backend + 1000;
- // Local API key for automation backend auth
- const localApiKey = env.AUTOMATION_LOCAL_API_KEY || DEFAULT_LOCAL_API_KEY;
+ // Local API key for automation backend auth. Keep the generated default
+ // stable across restarts because static frontend builds bake this value.
+ const automationApiKeyPath =
+ env.OH_AUTOMATION_API_KEY_PATH || DEFAULT_AUTOMATION_API_KEY_PATH;
+ const localApiKey =
+ env.AUTOMATION_LOCAL_API_KEY ||
+ getOrCreatePersistedApiKey(automationApiKeyPath, "automation");
// Session API key for agent-server auth
// Build a preliminary safe config to get the auto-generated session key
@@ -866,7 +879,6 @@ function startStaticFrontend(config, staticDir) {
export {
buildAutomationCommand,
buildConfig,
- generateRandomApiKey,
main,
registerShutdownHook,
spawnService,
@@ -879,8 +891,10 @@ export {
DEFAULT_AUTOMATION_REPO,
DEFAULT_AUTOMATION_PACKAGE,
DEFAULT_AUTOMATION_VERSION,
+ DEFAULT_AUTOMATION_SDK_VERSION,
DEFAULT_BACKEND_PORT,
DEFAULT_AUTOMATION_PORT,
+ DEFAULT_AUTOMATION_API_KEY_PATH,
};
// ═══════════════════════════════════════════════════════════════════════════
diff --git a/src/api/agent-server-adapter.ts b/src/api/agent-server-adapter.ts
index c596db0883..10800e56bd 100644
--- a/src/api/agent-server-adapter.ts
+++ b/src/api/agent-server-adapter.ts
@@ -49,6 +49,8 @@ export interface DirectConversationInfo {
const DEFAULT_TOOL_NAMES = ["terminal", "file_editor", "task_tracker"];
const BROWSER_TOOL_SET_NAME = "browser_tool_set";
+const DEFAULT_BUILT_IN_TOOL_NAMES = ["FinishTool", "ThinkTool"];
+const SWITCH_LLM_TOOL_NAME = "SwitchLLMTool";
function browserToolsEnabled() {
return import.meta.env.VITE_ENABLE_BROWSER_TOOLS !== "false";
@@ -204,6 +206,23 @@ function getAgentTools() {
return tools;
}
+function getBuiltInToolNames(agentSettings: SettingsRecord) {
+ const configured = Array.isArray(agentSettings.include_default_tools)
+ ? agentSettings.include_default_tools.filter(
+ (name): name is string => typeof name === "string" && name.length > 0,
+ )
+ : DEFAULT_BUILT_IN_TOOL_NAMES;
+
+ if (
+ agentSettings.enable_switch_llm_tool === true &&
+ !configured.includes(SWITCH_LLM_TOOL_NAME)
+ ) {
+ return [...configured, SWITCH_LLM_TOOL_NAME];
+ }
+
+ return configured;
+}
+
function buildInitialMessage(
query?: string,
conversationInstructions?: string,
@@ -270,8 +289,10 @@ function buildConfiguredAgentSettings(settings: Settings): SettingsRecord {
}
const condenser = buildCondenserConfig(llm, agentSettings.condenser);
+ const includeDefaultTools = getBuiltInToolNames(agentSettings);
AGENT_SETTINGS_METADATA_KEYS.forEach((key) => delete agentSettings[key]);
+ delete agentSettings.enable_switch_llm_tool;
const mcpConfig = toRecord(agentSettings.mcp_config);
if (Object.keys(mcpConfig).length === 0 || !("mcpServers" in mcpConfig)) {
@@ -288,6 +309,7 @@ function buildConfiguredAgentSettings(settings: Settings): SettingsRecord {
...agentSettings,
llm,
tools: getAgentTools(),
+ include_default_tools: includeDefaultTools,
};
}