Skip to content

πŸ™Œ OpenHands: AI-Driven Development

feat: request Docker execution workspaces from Docker servers (#17177)

Graham Neubiga5eb10d584f4
diff --git a/src/api/agent-server-adapter.test.ts b/src/api/agent-server-adapter.test.ts
index a23a154399..3e2759c345 100644
--- a/src/api/agent-server-adapter.test.ts
+++ b/src/api/agent-server-adapter.test.ts
@@ -197,6 +197,39 @@ describe("buildStartConversationRequest", () => {
expect(payload.parent_conversation_id).toBe("parent-1");
});
+ it("requests DockerExecutionWorkspace for the planner on Docker execution servers", () => {
+ const payload = buildStartPlanningConversationRequest({
+ encryptedAgentSettings: {
+ agent_kind: "openhands",
+ llm: { model: "openhands/minimax-m2.7" },
+ },
+ workingDir: "/workspace",
+ parentConversationId: "parent-1",
+ executionRuntime: "docker",
+ });
+
+ expect(payload.workspace).toEqual({
+ kind: "DockerExecutionWorkspace",
+ working_dir: "/workspace",
+ });
+ });
+
+ it("defaults the planner to LocalWorkspace when executionRuntime is not docker", () => {
+ const payload = buildStartPlanningConversationRequest({
+ encryptedAgentSettings: {
+ agent_kind: "openhands",
+ llm: { model: "openhands/minimax-m2.7" },
+ },
+ workingDir: "/host/workspace/project",
+ parentConversationId: "parent-1",
+ });
+
+ expect(payload.workspace).toEqual({
+ kind: "LocalWorkspace",
+ working_dir: "/host/workspace/project",
+ });
+ });
+
it("defaults the planner's max_iterations to 500 when not provided", () => {
const payload = buildStartPlanningConversationRequest({
encryptedAgentSettings: {
@@ -402,6 +435,34 @@ describe("buildStartConversationRequest", () => {
});
});
+describe("buildStartConversationRequest β€” execution runtime", () => {
+ it("requests DockerExecutionWorkspace from Docker execution servers", () => {
+ const payload = buildStartConversationRequest({
+ settings: makeSettings({ agent_kind: "openhands" }),
+ workingDir: "/host/workspace",
+ executionRuntime: "docker",
+ });
+
+ expect(payload.workspace).toEqual({
+ kind: "DockerExecutionWorkspace",
+ working_dir: "/workspace",
+ });
+ expect(payload.worktree).toBe(false);
+ });
+
+ it("keeps LocalWorkspace for local and older servers", () => {
+ const payload = buildStartConversationRequest({
+ settings: makeSettings({ agent_kind: "openhands" }),
+ workingDir: "/host/workspace",
+ });
+
+ expect(payload.workspace).toEqual({
+ kind: "LocalWorkspace",
+ working_dir: "/host/workspace",
+ });
+ });
+});
+
describe("buildStartPlanningConversationRequestWithEncryptedSettings", () => {
const globallyActiveSettings = {
agentSettings: {
@@ -621,6 +682,33 @@ describe("buildStartPlanningConversationRequestWithEncryptedSettings", () => {
expect(skillNames).not.toContain("agent-memory");
expect(skillNames).toContain("add-javadoc");
});
+
+ it("threads executionRuntime through to DockerExecutionWorkspace selection", async () => {
+ const payload =
+ await buildStartPlanningConversationRequestWithEncryptedSettings({
+ workingDir: "/workspace",
+ parentConversationId: "parent-1",
+ executionRuntime: "docker",
+ });
+
+ expect(payload.workspace).toEqual({
+ kind: "DockerExecutionWorkspace",
+ working_dir: "/workspace",
+ });
+ });
+
+ it("defaults to LocalWorkspace when executionRuntime is not provided", async () => {
+ const payload =
+ await buildStartPlanningConversationRequestWithEncryptedSettings({
+ workingDir: "/host/workspace/project",
+ parentConversationId: "parent-1",
+ });
+
+ expect(payload.workspace).toEqual({
+ kind: "LocalWorkspace",
+ working_dir: "/host/workspace/project",
+ });
+ });
});
describe("buildStartConversationRequest β€” agentProfileId path", () => {
diff --git a/src/api/agent-server-adapter.ts b/src/api/agent-server-adapter.ts
index 559e669487..23fb3393ae 100644
--- a/src/api/agent-server-adapter.ts
+++ b/src/api/agent-server-adapter.ts
@@ -17,6 +17,7 @@ import { getAgentServerClientOptions } from "./agent-server-client-options";
import {
getCachedAgentServerInfo,
isAgentServerToolAvailable,
+ type AgentServerInfo,
} from "./agent-server-compatibility";
import { getAgentServerWorkingDir } from "./agent-server-config";
import { getEffectiveLocalBackend } from "./backend-registry/active-store";
@@ -210,7 +211,7 @@ export function parseRuntimeServicesInfo(
return parsed;
}
-export async function fetchBackendRuntimeServicesInfo(): Promise<RuntimeServicesInfo | null> {
+async function fetchBackendServerInfo(): Promise<AgentServerInfo | null> {
let clientOptions: ReturnType<typeof getAgentServerClientOptions>;
try {
clientOptions = getAgentServerClientOptions({ timeout: 3000 });
@@ -218,21 +219,32 @@ export async function fetchBackendRuntimeServicesInfo(): Promise<RuntimeServices
return null;
}
- const cached = parseRuntimeServicesInfo(
- getCachedAgentServerInfo({ host: clientOptions.host })?.runtime_services,
- );
+ const cached = getCachedAgentServerInfo({ host: clientOptions.host });
if (cached) return cached;
try {
- const serverInfo = await new ServerClient(clientOptions).getServerInfo();
- return parseRuntimeServicesInfo(
- (serverInfo as { runtime_services?: unknown }).runtime_services,
- );
+ return (await new ServerClient(
+ clientOptions,
+ ).getServerInfo()) as AgentServerInfo;
} catch {
return null;
}
}
+export async function fetchBackendRuntimeServicesInfo(): Promise<RuntimeServicesInfo | null> {
+ const serverInfo = await fetchBackendServerInfo();
+ return parseRuntimeServicesInfo(
+ (serverInfo as { runtime_services?: unknown } | null)?.runtime_services,
+ );
+}
+
+export async function fetchBackendExecutionRuntime(): Promise<
+ AgentServerInfo["execution_runtime"]
+> {
+ const serverInfo = await fetchBackendServerInfo();
+ return serverInfo?.execution_runtime;
+}
+
/**
* Return the deployment mode from the runtime services info, e.g. "docker",
* "dev:automation", etc. Returns `null` when no runtime info is supplied.
@@ -473,6 +485,15 @@ interface LocalWorkspacePayload {
working_dir: string;
}
+const DOCKER_EXECUTION_WORKING_DIR = "/workspace" as const;
+
+interface DockerExecutionWorkspacePayload {
+ kind: "DockerExecutionWorkspace";
+ working_dir: typeof DOCKER_EXECUTION_WORKING_DIR;
+}
+
+type WorkspacePayload = LocalWorkspacePayload | DockerExecutionWorkspacePayload;
+
interface InitialMessagePayload {
role: "user";
content: Array<{ type: "text"; text: string }>;
@@ -480,7 +501,7 @@ interface InitialMessagePayload {
}
type ConversationSettingsPayload = SettingsRecord & {
- workspace: LocalWorkspacePayload;
+ workspace: WorkspacePayload;
initial_message?: InitialMessagePayload;
};
@@ -1048,9 +1069,16 @@ function buildConfiguredConversationSettings(options: {
conversationInstructions?: string;
plugins?: PluginSpec[];
workingDir?: string;
+ executionRuntime?: AgentServerInfo["execution_runtime"];
}): ConversationSettingsPayload {
- const { settings, query, conversationInstructions, plugins, workingDir } =
- options;
+ const {
+ settings,
+ query,
+ conversationInstructions,
+ plugins,
+ workingDir,
+ executionRuntime,
+ } = options;
const conversationSettings = toRecord(settings.conversation_settings);
const initialMessage = buildInitialMessage(query, conversationInstructions);
@@ -1058,12 +1086,19 @@ function buildConfiguredConversationSettings(options: {
(key) => delete conversationSettings[key],
);
+ const workspace: WorkspacePayload =
+ executionRuntime === "docker"
+ ? {
+ kind: "DockerExecutionWorkspace",
+ working_dir: DOCKER_EXECUTION_WORKING_DIR,
+ }
+ : {
+ kind: "LocalWorkspace",
+ working_dir: workingDir ?? getAgentServerWorkingDir(),
+ };
const payload: ConversationSettingsPayload = {
...conversationSettings,
- workspace: {
- kind: "LocalWorkspace",
- working_dir: workingDir ?? getAgentServerWorkingDir(),
- },
+ workspace,
...(initialMessage ? { initial_message: initialMessage } : {}),
...(plugins?.length
? {
@@ -1090,7 +1125,7 @@ interface LookupSecret {
type CustomSecretInput = { name: string; description?: string };
type StartConversationPayloadBase = Record<string, unknown> & {
- workspace: LocalWorkspacePayload;
+ workspace: WorkspacePayload;
confirmation_policy: SettingsRecord;
security_analyzer?: SettingsRecord;
initial_message?: InitialMessagePayload;
@@ -1148,6 +1183,7 @@ export interface StartConversationOptions {
agentProfileKind?: AgentKind;
titleLlmProfile?: string;
runtimeServicesInfo?: RuntimeServicesInfo | null;
+ executionRuntime?: AgentServerInfo["execution_runtime"];
workspaceHookConfig?: HookConfig | null;
}
@@ -1215,9 +1251,10 @@ export function buildStartConversationRequest(
}
: options;
- const conversationSettings = buildConfiguredConversationSettings(
- sourceConversationOptions,
- );
+ const conversationSettings = buildConfiguredConversationSettings({
+ ...sourceConversationOptions,
+ executionRuntime: options.executionRuntime,
+ });
const payload: AgentSettingsStartConversationPayload = {
// ``agent_profile_id`` and ``agent_settings`` are mutually exclusive agent
@@ -1262,7 +1299,10 @@ export function buildStartConversationRequest(
...(options.titleLlmProfile
? { title_llm_profile: options.titleLlmProfile }
: {}),
- worktree: options.worktree ?? true,
+ worktree:
+ options.executionRuntime === "docker"
+ ? false
+ : (options.worktree ?? true),
};
// Stamp the client source tag so the agent-server can attribute the
@@ -1355,6 +1395,8 @@ export function buildStartPlanningConversationRequest(options: {
maxIterations?: number;
/** Mirrors the code agent's skill filtering β€” see buildConfiguredOpenHandsAgentSettings. */
skillEnablement?: SkillEnablement;
+ /** Mirrors the main conversation's workspace selection β€” see buildConfiguredConversationSettings. */
+ executionRuntime?: AgentServerInfo["execution_runtime"];
}): RawAgentStartConversationPayload {
const agentSettings = toRecord(options.encryptedAgentSettings);
const llm = buildNormalizedLlmSettings(agentSettings.llm);
@@ -1419,10 +1461,16 @@ export function buildStartPlanningConversationRequest(options: {
keep_first: 6,
},
},
- workspace: {
- kind: "LocalWorkspace",
- working_dir: options.workingDir,
- },
+ workspace:
+ options.executionRuntime === "docker"
+ ? {
+ kind: "DockerExecutionWorkspace",
+ working_dir: DOCKER_EXECUTION_WORKING_DIR,
+ }
+ : {
+ kind: "LocalWorkspace",
+ working_dir: options.workingDir,
+ },
// No Canvas UI client tool: the planner's only output is PLAN.md, which the
// Planner tab surfaces on its own via PlanningFileEditorObservation. Handing
// it the panel-control tool would only let it navigate the right-side panel
@@ -1535,6 +1583,8 @@ export async function buildStartPlanningConversationRequestWithEncryptedSettings
*/
parentAgentProfileId?: string | null;
initialMessage?: string;
+ /** The server's `execution_runtime` β€” threads through to workspace selection. */
+ executionRuntime?: AgentServerInfo["execution_runtime"];
}): Promise<RawAgentStartConversationPayload> {
const { SecretsService } = await import("./secrets-service");
@@ -1613,20 +1663,20 @@ export async function buildStartConversationRequestWithEncryptedSettings(options
import("./hooks-service"),
]);
- const [
- settingsResult,
- customSecrets,
- runtimeServicesInfo,
- workspaceHookConfig,
- ] = await Promise.all([
- SettingsService.getSettingsForConversation(),
- SecretsService.getSecrets(),
- fetchBackendRuntimeServicesInfo(),
- HooksService.loadWorkspaceHooks(options.hooksProjectDir),
- ]);
+ const [settingsResult, customSecrets, serverInfo, workspaceHookConfig] =
+ await Promise.all([
+ SettingsService.getSettingsForConversation(),
+ SecretsService.getSecrets(),
+ fetchBackendServerInfo(),
+ HooksService.loadWorkspaceHooks(options.hooksProjectDir),
+ ]);
const { agentSettings, conversationSettings, secretsEncrypted } =
settingsResult;
+ const runtimeServicesInfo = parseRuntimeServicesInfo(
+ (serverInfo as { runtime_services?: unknown } | null)?.runtime_services,
+ );
+ const executionRuntime = serverInfo?.execution_runtime;
// A profile launch resolves the LLM server-side, so the current-settings
// subscription check doesn't apply (and can't see the profile's LLM).
@@ -1641,6 +1691,7 @@ export async function buildStartConversationRequestWithEncryptedSettings(options
secretsEncrypted,
customSecrets,
runtimeServicesInfo,
+ executionRuntime,
workspaceHookConfig,
});
}
diff --git a/src/api/agent-server-compatibility.ts b/src/api/agent-server-compatibility.ts
index a2834b6423..fb64cb35a6 100644
--- a/src/api/agent-server-compatibility.ts
+++ b/src/api/agent-server-compatibility.ts
@@ -35,6 +35,7 @@ export interface AgentServerInfo extends BaseServerInfo {
sdk_version?: string;
usable_tools?: string[] | null;
runtime_services?: unknown;
+ execution_runtime?: "local" | "docker";
}
let cachedAgentServerInfo: AgentServerInfo | null = null;
diff --git a/src/api/conversation-service/agent-server-conversation-service.api.ts b/src/api/conversation-service/agent-server-conversation-service.api.ts
index 736f9dfbd3..7f140c7773 100644
--- a/src/api/conversation-service/agent-server-conversation-service.api.ts
+++ b/src/api/conversation-service/agent-server-conversation-service.api.ts
@@ -43,6 +43,7 @@ import {
buildStartConversationRequestWithEncryptedSettings,
buildStartPlanningConversationRequestWithEncryptedSettings,
emptyHooksResponse,
+ fetchBackendExecutionRuntime,
getDefaultConversationTitle,
toAppConversation,
toConversationPage,
@@ -614,10 +615,17 @@ class AgentServerConversationService {
const workingDir =
parent?.workspace?.working_dir ?? getAgentServerWorkingDir();
+ // The planner must use the same workspace variety as the parent
+ // conversation's server. A Docker execution server enforces one workspace
+ // variety per server, so requesting LocalWorkspace for the planner would
+ // be rejected.
+ const executionRuntime = await fetchBackendExecutionRuntime();
+
const payload =
await buildStartPlanningConversationRequestWithEncryptedSettings({
workingDir,
parentConversationId,
+ executionRuntime,
// Pin the planner to the parent's own current model. Only meaningful
// for "openhands"-kind parents: an ACP parent's active_profile is a
// stale launch-time snapshot (/model is a no-op for ACP), not a live