feat: generate pinned Agent Server API types

[neubig]

• A human has tested these changes.

---

Why

The handwritten client currently has no deterministic check against the exact
Agent Server version it claims to support. Server schema drift can therefore
leave stale request/response signatures in a released client.

Fixes OpenHands/software-agent-sdk#4752
Linear: OSS-6122

Summary

• Generate and commit schema-only TypeScript types from the exact
  config.agentServerImage pin, using the matching release artifact or an
  isolated exact-image fallback for legacy releases.
• Add stable public operation aliases and statically check SettingsClient
  request/response signatures while retaining a deprecated compatibility
  overload for existing extension-shaped callers.
• Regenerate in required PR CI and fail on a working-tree diff; never use an
  unpinned latest endpoint.

Issue Number

OpenHands/software-agent-sdk#4752 / OSS-6122

How to Test

• npm ci
• npm run check:agent-server-api
• npm run build
• npm run lint
• npm run format:check
• env -u AGENT_SERVER_URL npm run test:coverage — 17 suites and 291 tests
  passed.

Agent Canvas was tested against the exact locally packed client:

1. Copied Canvas to a temporary tree.
2. Installed this client tarball in that copy.
3. Ran npm run typecheck and npm run build; both passed.

The consumer run used a temporary HOME, separate XDG config/data/cache paths,
and separate Canvas state/settings directories. It did not read or write
~/.openhands, and the complete temporary tree was removed afterward.

Video/Screenshots

Not applicable: this is generated contract and compile-time client
infrastructure with no UI change.

Type

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

Notes

Depends on OpenHands/software-agent-sdk#4229 for release-published OpenAPI
artifacts. The exact-image fallback keeps regeneration reproducible for the
currently pinned 1.37.0 release, which predates those artifacts. Canonical MCP
operation migration remains in OpenHands/software-agent-sdk#4753 / OSS-6123.

[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)	11
agent-server endpoints	121
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 (11)

• GET /
• GET /api/conversations
• GET /api/conversations/{}/events
• GET /api/conversations/{}/workspace
• GET /api/conversations/{}/workspace/{}
• GET /api/file/archive
• GET /api/git/commits
• GET /api/git/commits/{}/changes
• GET /api/init
• POST /api/conversations/{}/load_plugin
• POST /api/init

[hieptl]

Thank you! 🙏

[openhands-release-bot]

🚀 Released in v1.35.0.