feat: add aggregate cloud and agent-server clients

[neubig]

• A human has tested these changes.

---

Live evidence

Added by OpenHands on July 10, 2026 after updating this branch to current main (db5e5f6, tracked agent-server image ghcr.io/openhands/agent-server:1.34.0-python).

Local/package checks:

• npm ci completed and ran prepare / npm run build.
• npm run lint passed with existing warnings only (0 errors).
• npm run build passed.
• npm run test:coverage passed: 15 suites, 288 tests.
• npm run format:check passed.
• npm audit --audit-level=moderate --omit=dev and npm audit --audit-level=high --production both reported 0 vulnerabilities.

Live agent-server checks:

• Started ghcr.io/openhands/agent-server:1.34.0-python on localhost:8010 with /tmp/agent-workspace mounted at /workspace.
• /server_info reported version: 1.34.0; npm run audit:endpoints passed against the live OpenAPI spec.
• AGENT_SERVER_URL=http://localhost:8010 HOST_WORKSPACE_DIR=/tmp/agent-workspace AGENT_WORKSPACE_DIR=/workspace TEST_TIMEOUT=180000 npm run test:integration:deterministic passed: 2 suites, 13 tests.
• Built-package smoke imported ./dist/clients.js; AgentServerClient read /health and executed printf aggregate-agent-server-smoke through client.bash with exit code 0.

Live Cloud checks:

• Built-package smoke imported CloudClient, used OPENHANDS_API_KEY against https://app.all-hands.dev, and printed only sanitized counts/booleans.

LIVE_CLIENT_EVIDENCE {"ok":true,"agentServer":{"version":"1.34.0","aggregateKind":"agent-server","healthStatus":"ok","bashExitCode":0,"bashStdout":"aggregate-agent-server-smoke"},"cloud":{"hostRecognized":true,"currentApiKey":{"authTypePresent":true,"orgIdPresent":true},"organizations":{"itemCount":2,"currentOrgIdPresent":true},"conversationSearch":{"itemCount":1,"nextPageIdPresent":true},"scopedSettings":{"agentSettingsDerived":true,"conversationSettingsDerived":true,"llmApiKeySetFieldPresent":true}}}

Why

agent-canvas currently owns OpenHands Cloud transport, proxy, and device-flow auth code while using this package for agent-server APIs. This adds shared client primitives so browser clients can use the TypeScript client for both local agent-server and cloud backends without breaking the current endpoint-client API.

Summary

• Added OpenHandsClient, AgentServerClient, and CloudClient aggregate clients while preserving existing named endpoint clients and exports.
• Moved cloud API helpers and device-flow auth into the package, including direct cloud requests, runtime proxy envelopes, org scoping, blob responses, and cloud settings/profile/git/secrets/skills/conversation helpers.
• Updated the dist rewrite step to emit standards-compliant JSON import attributes for copied JSON assets.
• Merged current main so this PR is validated against the repository's current agent-server:1.34.0-python baseline.

Issue Number

N/A

How to Test

• npm ci
• npm run lint
• npm run build
• npm run test:coverage
• npm run format:check
• With the tracked agent-server image running on localhost:8010: npm run audit:endpoints and npm run test:integration:deterministic
• Optional live Cloud smoke: import CloudClient from ./dist/clients.js and call read-only Cloud endpoints with OPENHANDS_API_KEY, logging only sanitized metadata.

Video/Screenshots

N/A - library/client API change.

Type

• Bug fix
• Feature
• Refactor
• Breaking change
• Docs / chore

Notes

Stacked consumer PR: OpenHands/agent-canvas#1621 uses CloudClient and the shared device-flow helpers from this branch. That downstream PR is currently separate and has its own merge conflict/PR-description blocker; this package PR no longer depends on an unmerged base branch and its diff remains scoped to the six intended files.

Validation context: current main includes ACP registry changes from #272. Its companion SDK PR is OpenHands/software-agent-sdk#4056; the validate-acp-providers workflow uses that link when checking the merged PR context.

Closes #274

[github-actions]

Endpoint audit

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

Category	Count
❌ Off-contract (not on agent-server)	40
⛔ no known backend	15
↗️ served by cloud	25
➕ Missing API (agent-server has, client lacks)	9
agent-server endpoints	119
client endpoints	148

❌ Not on agent-server (gated, 40)

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

• DELETE /api/automation/v1/{}
• DELETE /api/meta-profiles/{}
• GET /api/automation/health
• GET /api/automation/v1
• GET /api/automation/v1/{}
• GET /api/automation/v1/{}/runs
• GET /api/automation/v1/{}/tarball
• GET /api/meta-profiles
• GET /api/meta-profiles/{}
• GET /api/v1/config/models/search{}
• GET /api/v1/config/providers/search{}
• PATCH /api/automation/v1/{}
• POST /api/automation/v1/{}/dispatch
• POST /api/meta-profiles/{}
• POST /api/meta-profiles/{}/activate

↗️ served by cloud (25)

• DELETE /api/v1/app-conversations/{}
• DELETE /api/v1/secrets/{}
• GET /api/keys/current
• GET /api/organizations
• GET /api/shared-events/search
• GET /api/v1/app-conversations/search
• GET /api/v1/app-conversations/{}/download
• GET /api/v1/app-conversations/{}/file
• GET /api/v1/git/branches/search
• GET /api/v1/git/installations/search
• GET /api/v1/git/repositories/search
• GET /api/v1/secrets/search
• GET /api/v1/settings
• GET /api/v1/settings/agent-schema
• GET /api/v1/settings/conversation-schema
• GET /api/v1/skills/search
• PATCH /api/v1/app-conversations/{}
• POST /api/v1/app-conversations
• POST /api/v1/app-conversations/{}/switch_acp_model
• POST /api/v1/app-conversations/{}/switch_profile
• POST /api/v1/sandboxes/{}/pause
• POST /api/v1/sandboxes/{}/resume
• POST /api/v1/secrets
• POST /api/v1/settings
• PUT /api/v1/secrets/{}

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

• 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/init