π OpenHands: AI-Driven Development
docs: document cross-repository version compatibility (#16884)
nicolasdmolina35dc8aafaad2
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.mdindex 56faebd18b..2bd2afc8f1 100644--- a/docs/DEVELOPMENT.md+++ b/docs/DEVELOPMENT.md@@ -13,11 +13,10 @@ Docker.This repository contains the Agent Canvas frontend and local-stack orchestration. Use the sibling repositories for their owned layers:- [`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk) owns the Python SDK, Agent Server, agent/tool behavior, conversations, workspaces, events, and server API.-- [`OpenHands/typescript-client`](https://github.com/OpenHands/typescript-client) owns browser-compatible typed access to that Agent Server API. Add client methods there rather than reimplementing API calls in Canvas.+- [`software-agent-sdk/clients/typescript`](https://github.com/OpenHands/software-agent-sdk/tree/main/clients/typescript) owns browser-compatible typed access to that Agent Server API. Add client methods there rather than reimplementing API calls in Canvas.- [`OpenHands/extensions`](https://github.com/OpenHands/extensions) owns reusable skills, plugins, automations, and integrations; [`OpenHands/automation`](https://github.com/OpenHands/automation) owns automation definitions, scheduling, webhooks, run history, and dispatching; Agent Server/SDK code executes the dispatched conversations.-When a feature crosses repositories, implement the backend contract in the SDK first, expose it through `typescript-client`, and consume it in Canvas. Coordinate automation lifecycle changes in `automation`. See the repository [contributor notes](../AGENTS.md) and follow the [custom code-review guide](../.agents/skills/custom-codereview-guide.md) for every pull request.-+When a feature crosses repositories, implement the backend contract in the SDK first, expose it through `typescript-client`, and consume it in Canvas. Coordinate automation lifecycle changes in `automation`. Version pins, local-stack overrides, and PR ordering are in [Cross-repository version compatibility](#cross-repository-version-compatibility). See the repository [contributor notes](../AGENTS.md) and follow the [custom code-review guide](../.agents/skills/custom-codereview-guide.md) for every pull request.For a static frontend build (better for slow networks, remote access, tunnels):@@ -47,11 +46,15 @@ it instead.### Environment Variables-| Variable | Description | Default |-| ------------------------- | ------------------------------ | ------- |-| `PORT` | Ingress port | `8000` |-| `OH_AUTOMATION_GIT_REF` | Git ref for automation backend (overrides the pinned default version) | *(unset)* |-| `OH_AGENT_SERVER_GIT_REF` | Git ref for agent-server (overrides the pinned default version) | *(unset)* |+| Variable | Description | Default |+| ---------------------------- | -------------------------------------- | ------------------------------ |+| `PORT` | Ingress port | `8000` |+| `OH_AGENT_SERVER_LOCAL_PATH` | Absolute `software-agent-sdk` checkout | unset |+| `OH_AGENT_SERVER_GIT_REF` | Git ref for agent-server | unset (`config/defaults.json`) |+| `OH_AGENT_SERVER_VERSION` | PyPI version for agent-server | unset (`config/defaults.json`) |+| `OH_AUTOMATION_LOCAL_PATH` | Absolute `automation` checkout | unset |+| `OH_AUTOMATION_GIT_REF` | Git ref for automation backend | unset (`config/defaults.json`) |+| `OH_AUTOMATION_VERSION` | PyPI version for automation | unset (`config/defaults.json`) |### Alternative: Minimal Mode (without Automation)@@ -64,23 +67,147 @@ npm run dev:minimalThis runs only agent-server + Vite (no automation backend or ingress).Access at `http://localhost:3001/`-### Agent server version selection--By default, the latest released version from PyPI is used. You can override this (highest precedence first):+### Cross-repository version compatibility++The default local stack for this checkout is the **pins recorded below**, not+an open-ended matrix of sibling `main` branches. Connecting to another Agent+Server is allowed down to `compatibility.minimumAgentServer`. Mixing an+unpinned Git backend with the committed TypeScript client (or the reverse) is+unsupported and often looks like a product bug.++Owning repositories:++- [`OpenHands/OpenHands`](https://github.com/OpenHands/OpenHands) (this repo) β Agent Canvas+- [`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk) β Python SDK and Agent Server+- [`software-agent-sdk/clients/typescript`](https://github.com/OpenHands/software-agent-sdk/tree/main/clients/typescript) β `@openhands/typescript-client`+- [`OpenHands/automation`](https://github.com/OpenHands/automation) β scheduling, webhooks, run history+- [`OpenHands/extensions`](https://github.com/OpenHands/extensions) β `@openhands/extensions` skills and integrations++#### Source of truth++| Surface | Supported version lives in |+| ------------------------------------------ | ----------------------------------------------------------------------------- |+| Bundled Agent Server / SDK PyPI pin | [`config/defaults.json`](../config/defaults.json) `versions.agentServer` |+| Bundled automation PyPI pin | `config/defaults.json` `versions.automation` |+| Oldest Agent Server this frontend accepts | `config/defaults.json` `compatibility.minimumAgentServer` |+| `@openhands/typescript-client` | [`package.json`](../package.json) (exact npm pin) |+| `@openhands/extensions` | `package.json` (exact npm pin) |+| Released automation β SDK dependency match | [`scripts/check-sdk-version-sync.mjs`](../scripts/check-sdk-version-sync.mjs) |++`config/defaults.json` is the source of truth for the Python backend pins used+by the npm and Docker install paths. `agent-canvas --info` prints the same+Agent Server and automation pins plus the minimum compatible Agent Server.++Those files describe **this revision**. They are not a historical compatibility+matrix. They do not promise that Git `main` of every sibling repository works+together, or that independently chosen PyPI/npm numbers with the same major+version are interchangeable.++Runtime enforcement for a connected Agent Server is+`assertAgentServerVersionIsSupported()` in+[`src/api/agent-server-compatibility.ts`](../src/api/agent-server-compatibility.ts).+Some UI features have additional floors inside `@openhands/typescript-client`.+Meeting `compatibility.minimumAgentServer` does not mean every Canvas feature+is available on that backend.++The TypeScript client records the Agent Server contract it was generated from+in `software-agent-sdk/clients/typescript`. That client+contract pin is independent of Canvas `versions.agentServer`.++#### Released package, Git ref, and local path++`npm run dev`, `npm run dev:static`, and the `agent-canvas` binary select+**Python** backends with the following precedence (highest first).+`npm run dev:minimal` uses the same Agent Server selection and does not start+automation. Leaving an override unset means "use the pin above", not Git+`main`.++**Agent Server** ([`software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk)):++1. `OH_AGENT_SERVER_LOCAL_PATH` β absolute path to a checkout that contains+ `openhands-agent-server`, `openhands-sdk`, `openhands-tools`, and+ `openhands-workspace`. The agent-server package is rebuilt from local+ source on each start (`uvx --reinstall`); the other workspace packages are+ installed editable.+2. `OH_AGENT_SERVER_GIT_REF` β branch, tag, or commit. All four workspace+ packages are installed from that same ref so inter-package APIs stay in+ sync. The launcher passes `uvx --reinstall` so a cached PyPI wheel with+ the same version string is not reused.+3. `OH_AGENT_SERVER_VERSION` β a specific PyPI version of those four packages.+4. Default: `versions.agentServer` from `config/defaults.json`.```sh-# Run against a local software-agent-sdk checkout.OH_AGENT_SERVER_LOCAL_PATH=/abs/path/to/software-agent-sdk npm run dev--# Use a git branch or commit (takes precedence over version)-OH_AGENT_SERVER_GIT_REF=main npm run dev-OH_AGENT_SERVER_GIT_REF=abc1234 npm run dev--# Use a specific PyPI version-OH_AGENT_SERVER_VERSION=1.18.0 npm run dev+OH_AGENT_SERVER_GIT_REF=<branch-or-sha> npm run dev+OH_AGENT_SERVER_VERSION=<versions.agentServer> npm run dev```-`OH_AGENT_SERVER_LOCAL_PATH` must be an absolute path to a `software-agent-sdk` checkout containing the `openhands-agent-server`, `openhands-sdk`, `openhands-tools`, and `openhands-workspace` workspace packages. The agent-server itself is rebuilt from local source on each start (`uvx --reinstall`); the other workspace packages are installed editable, so their source changes take effect without a rebuild.+**Automation** ([`automation`](https://github.com/OpenHands/automation)):++1. `OH_AUTOMATION_LOCAL_PATH` β absolute path to a checkout with+ `pyproject.toml`. `--automation-ref` on the launcher outranks this local+ path.+2. `OH_AUTOMATION_GIT_REF` (or `--automation-ref`) β branch, tag, or commit.+ `OH_AUTOMATION_REPO` only applies when a git ref is selected.+3. `OH_AUTOMATION_VERSION` β a specific PyPI version of `openhands-automation`.+4. Default: `versions.automation` from `config/defaults.json`.++Released `openhands-automation` is checked against `versions.agentServer`.+CI runs `scripts/check-sdk-version-sync.mjs` on the **published** automation+package, not on a local checkout or Git `main`.++**TypeScript client and extensions:** Canvas does not provide Git-ref or+local-path launcher variables for `@openhands/typescript-client` or+`@openhands/extensions`. Both are exact npm pins in `package.json`. Public+skills are loaded from `@openhands/extensions` at **build time**; the Agent+Server no longer clones the extensions repo or honors `EXTENSIONS_REF`.++Contributor notes require a **published** TypeScript client before Canvas+bumps that pin. Do not point this repository at an unpublished commit SHA.++Iterate on unreleased client work in `software-agent-sdk/clients/typescript`+and extensions work in `OpenHands/extensions`, then+bump the Canvas pin after the package exists on the registry.++#### Cross-repository change checklist++1. Confirm ownership using [Repository boundaries](#repository-boundaries).+2. Read `config/defaults.json` and `package.json` for the pins this Canvas+ revision expects.+3. If the Agent Server API changes, land it in `software-agent-sdk` first.+ For local Canvas testing, use `OH_AGENT_SERVER_LOCAL_PATH` or+ `OH_AGENT_SERVER_GIT_REF`; keep the TypeScript client pin until the client+ is published.+4. Mirror the contract in `software-agent-sdk/clients/typescript` (OpenAPI and handwritten+ clients). Publish that package, then bump `@openhands/typescript-client`+ here.+5. If automation must run against the new SDK, release `openhands-automation`+ with matching SDK dependencies, then update `versions.automation` so+ `scripts/check-sdk-version-sync.mjs` still passes.+6. If public skills or integrations change, publish `@openhands/extensions`+ and then bump that dependency.+7. If a Canvas PR needs an unreleased Agent Server, link the+ `OpenHands/software-agent-sdk` pull request and record the local-path or+ Git-ref verification in the Canvas PR body. E2E workflows run after+ changes reach `main`; for risky pre-merge changes, ask a maintainer to+ manually dispatch the relevant workflow against the PR branch. Do not+ assume a PR link automatically installs an SDK ref in mock-LLM Docker E2E.+8. Do not merge Canvas UI that requires a contract the pinned client does not+ yet expose.++#### Breaking contract sequencing++Usual direction: Agent Server / SDK β OpenAPI contract β `typescript-client` β+Agent Canvas. Automation scheduling flows Canvas β `automation` β Agent+Server / SDK.++REST deprecation and the removal runway are owned by+`software-agent-sdk` (`openhands-agent-server/AGENTS.md`). Canvas must not+skip the client release step or consume an unpublished client SHA.++Event wire types follow the same order: SDK Pydantic model, then TypeScript+client, then Canvas consumption of the client type. See the+[custom code-review guide](../.agents/skills/custom-codereview-guide.md).### Other useful overrides@@ -273,7 +400,6 @@ You can create a `.env` file in the project directory with these variables based| `VITE_FRONTEND_PORT` | Port to run the frontend application | `3001` || `VITE_INSECURE_SKIP_VERIFY` | Skip TLS certificate verification for proxied backend requests | `false` |-### Cloud organization recovery in embedded hosts`AgentServerUIProviders` leaves organization recovery off by default so the host's