Docker conversation runtime: built-in sub-agents are not registered (task tool fails with "none registered") #5380

Summary

With the docker conversation runtime (OH_CONVERSATION_RUNTIME=docker), task_tool_set can't delegate to any built-in sub-agent. Every task call fails:

Failed to execute task: Unknown agent 'general-purpose'. Available types: none registered. Use register_agent() to add custom agent types.

The same happens for web-researcher, code-explorer and bash-runner. With the local runtime, the same profile and prompt delegate fine.

Reproduction

• Host: Agent Canvas with OH_CONVERSATION_RUNTIME=docker.
• Start a conversation whose agent has tools [terminal, task_tool_set].
• Ask it to delegate to general-purpose (or web-researcher).
• The TaskObservation has is_error: true, status: error, and the message above.

Evidence

Reproduced on the shared OSS automation VM, 2026-09-29:

So this happens with a released image too, and is not introduced by #5151.

Relevant pieces:

• tool_router.py calls register_builtins_agents() when it is imported.
• agent-server.spec bundles openhands.tools.preset/subagents/*.md (fix(agent-server): bundle built-in subagent .md files in PyInstaller binary #3290).
• docker_runtime/mediation.py (prepare_start / serialize_start) forwards no sub-agent definitions to the container, so the container relies entirely on its own registration.
• In the frozen container the sub-agent registry is empty when TaskManager looks the agent up.

The root cause inside the container isn't confirmed yet. Candidates: the PyInstaller data path for subagents/, or the import-time registration not running in the process that serves conversations.

Impact

#5151 makes task_tool_set user-selectable in the Canvas tool catalog. On a docker-runtime deployment, users can pick it and it silently does nothing useful.

Suggested fix

• Make the container register the built-in sub-agents, and add a smoke test that a docker-runtime conversation can list or launch general-purpose.
• Alternatively (or as well), have the host forward its registered definitions through agent_definitions in serialize_start.

OpenHands AI triage

The following comments and acceptance criteria were added by the OpenHands AI agent.

Triage

With OH_CONVERSATION_RUNTIME=docker, each conversation is served by its own agent-server container (docker_runtime/registry.py), and serialize_start (docker_runtime/mediation.py) forwards no sub-agent definitions, so the container relies on its own startup registration. The agent-server registers built-ins at import time (register_builtins_agents() in tool_router.py), and the .md definitions are already bundled in the PyInstaller build (agent-server.spec, #3290) and shipped as package data. The observed failure is that this registration is not in effect in the frozen container process that serves the conversation, so the registry is empty when TaskManager looks up general-purpose.

Scope: make the built-in sub-agents resolvable inside the docker conversation runtime so task_tool_set delegates to general-purpose, web-researcher, code-explorer, and bash-runner exactly as it does on the local runtime. The repository already has one authoritative registration path (agent-server startup registration of openhands.tools.preset/subagents/*.md); reuse it rather than adding a parallel mechanism.

Non-goals: no new built-in sub-agents; no change to local-runtime registration or precedence; no change to the agent_definitions request field or the agent-server REST/OpenAPI contract; no task-tool redesign.

Actual Behavior

Every task call in a docker-runtime conversation fails:

Failed to execute task: Unknown agent 'general-purpose'. Available types: none registered. Use register_agent() to add custom agent types.

The TaskObservation has is_error: true, status: error. The same happens for web-researcher, code-explorer, and bash-runner. Reproduced on ghcr.io/openhands/agent-server:rel-1.49.6-python and on a SHA-tagged image, so it is not introduced by #5151.

Steps to Reproduce

1. Run Agent Canvas with OH_CONVERSATION_RUNTIME=docker.
2. Start a conversation whose agent has tools [terminal, task_tool_set].
3. Ask it to delegate to general-purpose (or web-researcher).
4. Observe the error above. With the local runtime and the same profile and prompt, delegation succeeds.

Acceptance Criteria

• With OH_CONVERSATION_RUNTIME=docker, a conversation whose agent includes task_tool_set can delegate to general-purpose, web-researcher, code-explorer, and bash-runner, and each call returns a TaskObservation with is_error: false / status: completed (no "none registered" error).
• The container serving the conversation reports the built-in sub-agents as available (for example POST /api/sub-agents and/or the task tool description lists the built-ins), rather than an empty registry.
• Delegating to a genuinely unknown sub-agent still returns the existing unknown-agent error; registry lookup failure behavior is unchanged.
• web-researcher remains gated on browser availability (register_builtins_agents(enable_browser=...)): absent when browser is disabled, present when enabled, with the other three always present.
• Local-runtime behavior is unchanged: the same profile and prompt delegate successfully as before.
• The packaged conversation-container artifact ships the built-in sub-agent definitions (PyInstaller bundle and package data for openhands.tools.preset/subagents/*.md), verified by a packaging/build check rather than an in-process unit test alone.
• A docker-runtime smoke/integration test starts a conversation and asserts a built-in sub-agent can be listed or launched; it fails against the pre-fix behavior.
• The host-to-container agent_definitions forwarding and the agent-server REST/OpenAPI contract are unchanged (no breaking change).