Skip to content

πŸ™Œ OpenHands: AI-Driven Development

fix: provide runtime services to named agent profiles (#17279)

simonrosenbergea2e6dfd6946
diff --git a/.pr/persona-00-modes.png b/.pr/persona-00-modes.png
deleted file mode 100644
index 2093c5d585..0000000000
Binary files a/.pr/persona-00-modes.png and /dev/null differ
diff --git a/.pr/persona-01-editor-persona.png b/.pr/persona-01-editor-persona.png
deleted file mode 100644
index d09903bcae..0000000000
Binary files a/.pr/persona-01-editor-persona.png and /dev/null differ
diff --git a/.pr/persona-02-editor-instructions.png b/.pr/persona-02-editor-instructions.png
deleted file mode 100644
index fa21fea926..0000000000
Binary files a/.pr/persona-02-editor-instructions.png and /dev/null differ
diff --git a/.pr/persona-03-editor-default-profile.png b/.pr/persona-03-editor-default-profile.png
deleted file mode 100644
index dd90118b9b..0000000000
Binary files a/.pr/persona-03-editor-default-profile.png and /dev/null differ
diff --git a/.pr/persona-04-persona-system-message.png b/.pr/persona-04-persona-system-message.png
deleted file mode 100644
index 48ed63ead1..0000000000
Binary files a/.pr/persona-04-persona-system-message.png and /dev/null differ
diff --git a/.pr/persona-05-persona-kept.png b/.pr/persona-05-persona-kept.png
deleted file mode 100644
index 70a2f919f7..0000000000
Binary files a/.pr/persona-05-persona-kept.png and /dev/null differ
diff --git a/.pr/persona-06-instructions-system-message.png b/.pr/persona-06-instructions-system-message.png
deleted file mode 100644
index 43208a52c8..0000000000
Binary files a/.pr/persona-06-instructions-system-message.png and /dev/null differ
diff --git a/.pr/persona-07-default-system-message.png b/.pr/persona-07-default-system-message.png
deleted file mode 100644
index 75a9ebb2c1..0000000000
Binary files a/.pr/persona-07-default-system-message.png and /dev/null differ
diff --git a/.pr/persona-live-check.md b/.pr/persona-live-check.md
deleted file mode 100644
index e6ae11afd2..0000000000
--- a/.pr/persona-live-check.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# Persona / instructions live check
-
-- Date: 2026-10-05
-- Canvas: `c9fd7fd11` (#17843 stacked on #17516), `npm run dev`, fresh state dir, agent-server run with an isolated `HOME`
-- Agent-server: 1.53.0 (`/server_info`), browser tool usable
-- LLM: recording mock (`openai/mock-test-model`); facts below come from its `GET /admin/requests`
-- Launches: each profile picked in the home chat profile menu (`agent_profile_id` path)
-
-| Profile | Mode | Starts with persona | Kept sections sent | Persona-layer sections sent | Instructions sent |
-|---|---|---|---|---|---|
-| `explorer` | Custom persona | true | MEMORY, SECURITY, SECURITY_RISK_ASSESSMENT, BROWSER_TOOLS, EXTERNAL_SERVICES, PROCESS_MANAGEMENT, SKILLS | none (no SOUL, ROLE, EFFICIENCY, FILE_SYSTEM_GUIDELINES, CODE_QUALITY, VERSION_CONTROL, PULL_REQUESTS, PROBLEM_SOLVING_WORKFLOW, SELF_DOCUMENTATION, ENVIRONMENT_SETUP, TROUBLESHOOTING) | n/a |
-| `helper` | Default + your instructions | false | all of the above | SOUL, ROLE, EFFICIENCY, … TROUBLESHOOTING (full default set) | true ("Always answer in bullet points." after `</SKILLS>`) |
-| `plain` | OpenHands default | false | all of the above | full default set | n/a |
-
-All three conversations finished with the mock's reply.
-
-Page errors: none. The only console error is a 404 from `GET /api/file/search_subdirs?path=/projects` (the workspace picker probing a missing folder; unrelated to this PR).
diff --git a/.pr/socketio-removal-verification.png b/.pr/socketio-removal-verification.png
deleted file mode 100644
index ffda0f156c..0000000000
Binary files a/.pr/socketio-removal-verification.png and /dev/null differ
diff --git a/.pr/tools-01-standard.png b/.pr/tools-01-standard.png
deleted file mode 100644
index 7d80c38429..0000000000
Binary files a/.pr/tools-01-standard.png and /dev/null differ
diff --git a/.pr/tools-02-choose.png b/.pr/tools-02-choose.png
deleted file mode 100644
index 7ed6d5f50e..0000000000
Binary files a/.pr/tools-02-choose.png and /dev/null differ
diff --git a/.pr/tools-03-global-notice.png b/.pr/tools-03-global-notice.png
deleted file mode 100644
index 83d9f0677c..0000000000
Binary files a/.pr/tools-03-global-notice.png and /dev/null differ
diff --git a/__tests__/api/agent-server-adapter.test.ts b/__tests__/api/agent-server-adapter.test.ts
index 6a14177c0a..2b58f195b0 100644
--- a/__tests__/api/agent-server-adapter.test.ts
+++ b/__tests__/api/agent-server-adapter.test.ts
@@ -1519,6 +1519,94 @@ describe("agent_settings runtime services suffix", () => {
payload.agent_settings.agent_context.system_message_suffix as string,
).toContain("<RUNTIME_SERVICES>");
});
+
+ it("carries runtime services on the profile path, where agent_settings can't be sent", () => {
+ // agent_profile_id and agent_settings are mutually exclusive.
+ const payload = buildStartConversationRequest({
+ settings: DEFAULT_SETTINGS,
+ query: "hello",
+ agentProfileId: "profile-openhands",
+ agentProfileKind: "openhands",
+ runtimeServicesInfo: {
+ mode: "dev:automation",
+ services: {
+ agent_server: { url_from_agent: "http://localhost:18000" },
+ automation: { url_from_agent: "http://localhost:18001" },
+ },
+ },
+ }) as {
+ agent_profile_id?: string;
+ agent_settings?: unknown;
+ agent_launch_additions?: { system_message_suffix_append?: string };
+ };
+
+ expect(payload.agent_profile_id).toBe("profile-openhands");
+ expect(payload.agent_settings).toBeUndefined();
+ expect(
+ payload.agent_launch_additions?.system_message_suffix_append,
+ ).toContain("<RUNTIME_SERVICES>");
+ expect(
+ payload.agent_launch_additions?.system_message_suffix_append,
+ ).toContain("http://localhost:18001");
+ });
+
+ it("keeps the route-at-conversation-start suffix off the profile path", () => {
+ const payload = buildStartConversationRequest({
+ settings: { ...DEFAULT_SETTINGS, run_router_at_conversation_start: true },
+ hasActiveMetaProfile: true,
+ query: "hello",
+ agentProfileId: "profile-openhands",
+ agentProfileKind: "openhands",
+ runtimeServicesInfo: {
+ mode: "dev:automation",
+ services: {
+ automation: { url_from_agent: "http://localhost:18001" },
+ },
+ },
+ }) as {
+ agent_launch_additions?: { system_message_suffix_append?: string };
+ };
+
+ const appended =
+ payload.agent_launch_additions?.system_message_suffix_append;
+ expect(appended).toContain("<RUNTIME_SERVICES>");
+ expect(appended).not.toContain("ROUTE_AT_CONVERSATION_START");
+ });
+
+ it("carries runtime services on an ACP profile launch too", () => {
+ const payload = buildStartConversationRequest({
+ settings: DEFAULT_SETTINGS,
+ query: "hello",
+ agentProfileId: "profile-acp",
+ agentProfileKind: "acp",
+ runtimeServicesInfo: {
+ mode: "dev:automation",
+ services: {
+ automation: { url_from_agent: "http://localhost:18001" },
+ },
+ },
+ }) as {
+ agent_profile_id?: string;
+ agent_launch_additions?: { system_message_suffix_append?: string };
+ };
+
+ expect(payload.agent_profile_id).toBe("profile-acp");
+ expect(
+ payload.agent_launch_additions?.system_message_suffix_append,
+ ).toContain("<RUNTIME_SERVICES>");
+ });
+
+ it("omits the additions entirely when there is no runtime services info", () => {
+ // A deployment without them must send no deployment context at all, not an
+ // empty string the server would append as a blank line.
+ const payload = buildStartConversationRequest({
+ settings: DEFAULT_SETTINGS,
+ query: "hello",
+ agentProfileId: "profile-openhands",
+ agentProfileKind: "openhands",
+ }) as { agent_launch_additions?: unknown };
+ expect(payload.agent_launch_additions).toBeUndefined();
+ });
});
describe("buildStartConversationRequest β€” ACP discriminator", () => {
@@ -2016,7 +2104,9 @@ describe("buildStartConversationRequestWithEncryptedSettings", () => {
});
it("omits the route-at-start suffix when the meta-profiles endpoint fails (fails closed)", async () => {
- mockListMetaProfiles.mockRejectedValue(new Error("503 Service Unavailable"));
+ mockListMetaProfiles.mockRejectedValue(
+ new Error("503 Service Unavailable"),
+ );
const payload = (await buildStartConversationRequestWithEncryptedSettings({
settings: {
diff --git a/src/api/agent-server-adapter.ts b/src/api/agent-server-adapter.ts
index cb1dec949e..59a7514819 100644
--- a/src/api/agent-server-adapter.ts
+++ b/src/api/agent-server-adapter.ts
@@ -1169,6 +1169,8 @@ type AgentSettingsStartConversationPayload = StartConversationPayloadBase & {
// exclusive agent sources; the server resolves the profile server-side.
agent_settings?: AgentSettingsPayload;
agent_profile_id?: string;
+ // Appended to the profile-resolved agent's system-message suffix.
+ agent_launch_additions?: { system_message_suffix_append?: string };
agent?: never;
};
@@ -1269,6 +1271,11 @@ export function buildStartConversationRequest(
options.query,
options.hasActiveMetaProfile,
);
+ // The router-at-start instruction stays inline-only: a profile-resolved
+ // agent has no ``route_task_to_model`` tool to act on it.
+ const profileLaunchSuffix = buildRuntimeServicesSystemSuffix(
+ options.runtimeServicesInfo,
+ );
const acpServerTag = acpMode
? getAcpServerTag(sourceAgentSettings)
: undefined;
@@ -1299,10 +1306,12 @@ export function buildStartConversationRequest(
// server/SDK's responsibility to restore on the profile path β€” tracked in
// software-agent-sdk#3967 (profile resolution must attach the default
// toolset + public skills, else a profile-launched OpenHands agent has only
- // Finish/Think). The dev ``RUNTIME_SERVICES`` system-message suffix remains
- // agent-settings-only; the Canvas UI tool is a top-level client tool and
+ // Finish/Think). The Canvas UI tool is a top-level client tool and
// therefore works on both inline-agent and profile launch paths.
//
+ // ``RUNTIME_SERVICES`` (this stack's sandbox-facing URLs) only exists
+ // client-side, so the profile path sends it as ``agent_launch_additions``.
+ //
// Persistent memory is NOT on that boundary: ``load_memory`` is a global
// user preference, so the agent-server stamps the stored
// ``agent_settings.agent_context.load_memory`` onto the profile-resolved
@@ -1311,7 +1320,16 @@ export function buildStartConversationRequest(
// re-send it here (``agent_profile_id`` and ``agent_settings`` are
// mutually exclusive).
...(options.agentProfileId
- ? { agent_profile_id: options.agentProfileId }
+ ? {
+ agent_profile_id: options.agentProfileId,
+ ...(profileLaunchSuffix
+ ? {
+ agent_launch_additions: {
+ system_message_suffix_append: profileLaunchSuffix,
+ },
+ }
+ : {}),
+ }
: { agent_settings: agentSettings }),
workspace: conversationSettings.workspace,
// The agent-server caches each client tool's schema per tool *name* for the
diff --git a/src/hooks/mutation/use-create-conversation.ts b/src/hooks/mutation/use-create-conversation.ts
index 68e53b1586..6b5c3cb85b 100644
--- a/src/hooks/mutation/use-create-conversation.ts
+++ b/src/hooks/mutation/use-create-conversation.ts
@@ -152,19 +152,18 @@ export const useCreateConversation = () => {
) {
// The seeded OpenHands `default` profile is the enriched baseline, not a
// deliberate profile pick β€” it mirrors global agent_settings. Launch it
- // via agent_settings so the canvas-only enrichments the profile-resolution
- // path drops survive for the common home-launch: the <RUNTIME_SERVICES>
- // system-message suffix and project-skill loading (buildAgentContext).
+ // via agent_settings so the global settings and the canvas skill
+ // selection (buildAgentContext) apply to the common home-launch; the
+ // profile path resolves skills server-side instead.
// Named profiles are deliberate custom configs and still use the profile
- // path (accepting that enrichment boundary).
+ // path.
// Trade-off: per-profile fields set on `default` itself don't apply on
// home-launch β€” custom per-profile config belongs in a named profile.
//
// Scoped to OpenHands: an ACP `default` must keep the profile path.
// Activation is pointer-only, so global agent_settings is stale (often
// still OpenHands) when an ACP profile is active β€” launching it via
- // agent_settings would start the wrong agent. ACP carries no
- // <RUNTIME_SERVICES> enrichment, so there's nothing to preserve.
+ // agent_settings would start the wrong agent.
//
// Scoped to local: cloud never writes agent_settings, so it always
// resolves `default` server-side via agent_profile_id (validated below).