feat: generate pinned Agent Server API types

.github/workflows/ci.yml

@@ -7,6 +7,25 @@ on:
     branches: [ main, develop ]
 
 jobs:
+  agent-server-api:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Use Node.js 22.12
+      uses: actions/setup-node@v6
+      with:
+        node-version: 22.12
+        cache: 'npm'
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Check generated Agent Server contract
+      run: npm run check:agent-server-api
+
   test:
     runs-on: ubuntu-latest
 

AGENTS.md

@@ -43,9 +43,12 @@ This TypeScript client is based on the following source materials:
 
 ### 1. OpenAPI Specification
 
-- **Source**: [OpenHands Docs - Agent SDK OpenAPI](https://github.com/OpenHands/docs/blob/main/openapi/agent-sdk.json)
+- **Source**: The `openapi.json` artifact for the exact SDK release pinned by
+  `package.json` → `config.agentServerImage`
 - **Purpose**: Defines the complete REST API specification for the OpenHands Agent Server
-- **Usage**: Used to generate TypeScript interfaces, API client methods, and ensure complete endpoint coverage
+- **Usage**: Generates `src/generated/agent-server-schema.ts`, whose selected
+  operations and components are exposed through stable aliases and checked
+  against handwritten client methods
 
 ### 2. Python SDK Reference Implementation
 
@@ -328,6 +331,14 @@ so merging it means the client has been validated against that server version.
 This is independent of the npm package version — bumping the tracked server does
 **not** cut a client release.
 
+The generated transport contract in
+`src/generated/agent-server-schema.ts` comes from that same exact pin. Run
+`npm run generate:agent-server-api` after changing the pin and
+`npm run check:agent-server-api` to enforce a clean regeneration. Released SDK
+versions use the `openapi.json` release artifact. Legacy releases without the
+artifact are exported from an isolated temporary container of the exact pinned
+image. The generator never reads from an unpinned `latest` endpoint.
+
 ## Local Setup and Validation
 
 Use the same bootstrap command as CI and `.openhands/setup.sh`:

README.md

@@ -50,6 +50,25 @@ npm install github:OpenHands/typescript-client
 
 This git-based install runs the package `prepare` script during installation so the published `dist/` entrypoints and subpath exports are built automatically.
 
+## Agent Server API contract
+
+Selected handwritten clients are statically checked against generated types in
+`src/generated/agent-server-schema.ts`. The source is the exact Agent Server
+release configured by `package.json` → `config.agentServerImage`.
+
+```bash
+npm run generate:agent-server-api
+npm run check:agent-server-api
+```
+
+The generator downloads the matching SDK release's `openapi.json`. For older
+releases that predate that artifact, it starts the exact pinned image in a
+temporary Docker container with no host mounts, exports `/openapi.json`, and
+removes the container. CI regenerates the file and fails if it differs. During
+SDK development, `AGENT_SERVER_OPENAPI_PATH=/path/to/openapi.json` can supply a
+local candidate contract while retaining the pinned image metadata in the
+generated file.
+
 ## Quick Start
 
 ### Start an AgentServer