feat(client): add SubAgentsClient for POST /api/sub-agents

[VascoSch92]

Summary

The agent-server exposes a read-only POST /api/sub-agents endpoint (added in software-agent-sdk #3911, released in v1.31.0) that lists the file-based and built-in sub-agents (delegate agents) available to a workspace. It mirrors POST /api/skills. This endpoint was missing from the TypeScript client — this PR adds it.

What's included

• SubAgentsClient (src/client/sub-agents-client.ts) with getSubAgents(request) → POST /api/sub-agents, following the same shape as SkillsClient/PluginsClient.
• Types (src/models/api.ts): SubAgentsRequest, SubAgentInfo, SubAgentsResponse, and SubAgentLevel. SubAgentInfo is a lossless mirror of the server's AgentDefinition view — every frontmatter field plus the discovered level/source, is_builtin, and the inline system_prompt.
• Wiring: manager.subAgents on ConversationManager (constructed + closed alongside the other clients); exported from clients.ts and the model types from index.ts.

Tests

• Unit (api-clients.test.ts): manager.subAgents namespace assertion; request/response mapping to /api/sub-agents (incl. API-key header, full SubAgentInfo payload); default empty-body behavior.
• Integration (deterministic-api.integration.test.ts):
  • The bundled read test now also exercises getSubAgents (builtin discovery), asserting the contract shape.
  • A dedicated test writes a project-level agent into the workspace and verifies the endpoint discovers it losslessly (name/level/source/tools/system_prompt), then cleans up.

Verification

• npm test — 273 unit tests pass.
• Integration tests run and pass against the pinned ghcr.io/openhands/agent-server:1.31.0-python image (the project-level discovery test confirms the endpoint end-to-end). Note: the frozen image ships no built-in agent files, so the builtin path returns an empty list — the assertions account for this.
• tsc --noEmit, eslint, and prettier --check all clean.

[github-actions]

Endpoint audit

❌ 6 off-contract call(s) — not on the agent-server · classifiers: cloud

Category	Count
❌ Off-contract (not on agent-server)	6
⛔ no known backend	5
↗️ served by cloud	1
➕ Missing API (agent-server has, client lacks)	10
agent-server endpoints	116
client endpoints	110

❌ Not on agent-server (gated, 6)

⛔ (no known backend) — served by no backend we can see (5)

• DELETE /api/meta-profiles/{}
• GET /api/meta-profiles
• GET /api/meta-profiles/{}
• POST /api/meta-profiles/{}
• POST /api/meta-profiles/{}/activate

↗️ served by cloud (1)

• GET /api/shared-events/search

➕ Missing API — agent-server exposes it, client does not implement (10)

• GET /
• GET /api/conversations
• GET /api/conversations/{}/events
• GET /api/conversations/{}/workspace
• GET /api/conversations/{}/workspace/{}
• GET /api/file/archive
• GET /api/init
• POST /api/conversations/{}/load_plugin
• POST /api/conversations/{}/navigate
• POST /api/init

[enyst]

@OpenHands why did the CI fail? “HttpError: HTTP request failed (500 Internal Server Error): {"detail":"Internal Server Error","exception":"500: Failed to activate profile"}”

/codereview

[openhands-ai]

I'm on it! enyst can track my progress at all-hands.dev

[enyst]

I checked the failed integration-test job. The /api/sub-agents calls themselves passed; the failure is a side effect from the new project-level sub-agent integration test.

What happened:

• The new test writes .openhands/agents/<agent>.md directly into the mounted host workspace with Node fs.
• That creates /tmp/agent-workspace/.openhands as the GitHub runner user with default non-world-writable directory permissions.
• Later, the existing profile round-trip test calls POST /api/profiles/<name>/activate.
• Inside the container, agent-server tries to update/chmod workspace/.openhands, but the container user does not own the host-created directory.
• The server log shows the real cause just before the 500:
  • Failed to set permissions on workspace/.openhands: [Errno 1] Operation not permitted: 'workspace/.openhands'
  • Failed to activate profile - file I/O error

So the CI failure is not from SubAgentsClient request/response mapping itself; it is test pollution/permission coupling caused by creating .openhands from the host side before the profile activation test runs.

Likely fixes: create the test agent file through the agent-server/workspace path as the container user, or explicitly make/chown/chmod the host-created .openhands directory so the container user can write to it, and clean up the directory after the sub-agent test.

This comment was created by an AI agent (OpenHands) on behalf of the user.

[VascoSch92]

@enyst if you have time :)

[openhands-release-bot]

🚀 Released in v1.32.0.