feat: automate Agent Server contract drift checks

[neubig]

• A human has tested these changes.

---

Why

Pinned regeneration must fail deterministically when the committed Agent Server
contract is stale, while upcoming SDK-main drift should be visible without
making ordinary client PRs depend on a moving target.

Fixes OpenHands/software-agent-sdk#4754
Linear: OSS-6126

Summary

• Replace the git-diff wrapper with a byte-comparing pinned checker and add
  fixture coverage proving an additive server field generates a diff and a
  stale checked-in file fails.
• Add reusable generated-contract summaries and exact-SHA drift report tooling
  used by the SDK release handoff.
• Add a weekly informational SDK-main audit that exports one exact commit,
  uploads the candidate, and opens/updates/resolves a drift issue containing the
  full tested SHA.

Issue Number

OpenHands/software-agent-sdk#4754 / OSS-6126

How to Test

• npm run test:agent-server-api-tooling — additive generation, stale-file
  failure/regeneration, clean rerun, diff summary, and exact 40-character SDK
  SHA report fixtures passed.
• npm run check:agent-server-api — clean deterministic regeneration against
  ghcr.io/openhands/agent-server:1.37.0-python.
• npm run build
• npm run lint — 0 errors; 17 pre-existing warnings.
• npm run format:check
• env -u AGENT_SERVER_URL -u OPENHANDS_AGENT_SERVER_URL npm run test:coverage
  — 18 suites and 299 tests passed.
• Parsed both modified/new workflow YAML documents.
• Simulated the scheduled audit against exact SDK commit
  da2876f6192eb5748e0eed3584c6d26b54927801; the generated source and report
  preserved the full SHA and emitted a concrete API summary.

Agent Canvas was tested against this exact packed client in a disposable copy;
npm run typecheck and npm run build passed. HOME, XDG config/data/cache,
Canvas state, and OpenHands settings all lived under the temporary tree;
~/.openhands was never used, and the tree was removed.

Video/Screenshots

Not applicable: CI and release automation only.

Type

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

Notes

Stacked directly on #301 and should be rebased to main after that generated-contract PR
merges. It is independent of PR #302 MCP mutation work. The matching SDK release handoff is OpenHands/software-agent-sdk#4234.
The scheduled workflow is separate from PR CI and informational by design.

[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

[enyst]

Thank you for this. I’d love Vasco’s 👀 on it, I do think it’s safe enough and WIP as we get this better in shape so it’s cool either way!

[neubig]

Great, thank you! I'll test and tighten it after we release the SDK