π OpenHands: AI-Driven Development
chore: auto-graduate npm dist-tag from latest to per-tier once first stable release ships (#1028)
Tim O'Farrell3e51a68bd495
diff --git a/.agents/skills/release.md b/.agents/skills/release.mdindex 1235c41460..47195fd527 100644--- a/.agents/skills/release.md+++ b/.agents/skills/release.md@@ -23,6 +23,19 @@ Releases use a **long-lived release branch** model:npm dist-tags by version tier:+The workflow checks npm at publish time to see whether any full stable release (no pre-release suffix) has ever been published:++**Before the first stable release** β all versions use `--tag latest`:++| Version | Example | npm dist-tag | `npm install` resolves? |+|---|---|---|---|+| Alpha | `1.0.0-alpha.1` | `latest` | β default |+| Beta | `1.0.0-beta.1` | `latest` | β default |+| RC | `1.0.0-rc.1` | `latest` | β default |+| Stable | `1.0.0` | `latest` | β default |++**After the first stable release** β pre-release versions revert to their own dist-tags:+| Version | Example | npm dist-tag | `npm install` resolves? ||---|---|---|---|| Alpha | `1.0.0-alpha.1` | `alpha` | `@alpha` only |@@ -30,6 +43,8 @@ npm dist-tags by version tier:| RC | `1.0.0-rc.1` | `rc` | `@rc` only || Stable | `1.0.0` | `latest` | β default |+This transition is automatic β no workflow changes are needed when the first stable version ships.+---## Step 1: Confirm the Release Branch Exists@@ -150,4 +165,4 @@ gh release delete v<version> --yesThen the workflow will re-create it on the next tag push (or run it manually from the Actions tab).### npm publish failed mid-way-Check the `npm-publish.yml` run logs. The dist-tag is resolved from the `package.json` version β if the version string contains `alpha`, `beta`, or `rc`, it uses the matching dist-tag; otherwise `latest`.+Check the `npm-publish.yml` run logs. The dist-tag is resolved dynamically: if no stable release (no `-` in the version) has ever been published to npm, all versions use `latest`; once a stable version exists, pre-release versions use their own tag (`alpha` / `beta` / `rc`) and only stable versions use `latest`.diff --git a/.github/workflows/npm-publish.yml b/.github/workflows/npm-publish.ymlindex bae15a48a7..8f93d5ef8d 100644--- a/.github/workflows/npm-publish.yml+++ b/.github/workflows/npm-publish.yml@@ -90,11 +90,11 @@ jobs:fiecho "β Version $PACKAGE_VERSION matches release tag"- # Resolve the npm dist-tag from the version's pre-release identifier:- # alpha β --tag alpha (e.g. 1.0.0-alpha.1)- # beta β --tag beta (e.g. 1.0.0-beta.1)- # rc β --tag rc (e.g. 1.0.0-rc.1)- # stable β --tag latest (e.g. 1.0.0)+ # Determine if any full stable release (no pre-release suffix) has ever been+ # published. Until one exists, all releases use --tag latest so plain+ # `npm install @openhands/agent-canvas` always resolves to the newest build.+ # Once a stable version is published, pre-release versions revert to their+ # own dist-tags (alpha / beta / rc) and only stable versions keep latest.# Note: OIDC trusted-publishing tokens cover only the `npm publish` call# itself; a separate `npm dist-tag add` would fail with E401, so the tag# is resolved and passed directly in one step.@@ -102,7 +102,15 @@ jobs:id: dist_tagrun: |VERSION=$(node -p "require('./package.json').version")- if [[ "$VERSION" == *-alpha* ]]; then+ VERSIONS_JSON=$(npm view @openhands/agent-canvas versions --json 2>/dev/null || echo "[]")+ STABLE_EXISTS=$(VERSIONS_JSON="$VERSIONS_JSON" node -e "+ const vs = JSON.parse(process.env.VERSIONS_JSON);+ const arr = Array.isArray(vs) ? vs : [vs];+ console.log(arr.some(v => !v.includes('-')));+ ")+ if [[ "$STABLE_EXISTS" != "true" ]]; then+ DIST_TAG="latest"+ elif [[ "$VERSION" == *-alpha* ]]; thenDIST_TAG="alpha"elif [[ "$VERSION" == *-beta* ]]; thenDIST_TAG="beta"@@ -112,7 +120,7 @@ jobs:DIST_TAG="latest"fiecho "dist_tag=$DIST_TAG" >> "$GITHUB_OUTPUT"- echo "π¦ Version $VERSION β dist-tag: $DIST_TAG"+ echo "π¦ Version $VERSION β dist-tag: $DIST_TAG (stable release exists: $STABLE_EXISTS)"- name: Publish to npm with provenancerun: npm publish --access public --provenance --tag ${{ steps.dist_tag.outputs.dist_tag }}diff --git a/AGENTS.md b/AGENTS.mdindex d83896b26b..15e57ef80c 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -563,6 +563,6 @@ When adding code that needs a new string, decide up front which rule it falls un- Spec files live under `specs/`. Spec IDs are stable β never renumber. Mark deprecated specs with ~~strikethrough~~. Tag implementation code and tests with `// @spec BM-002 β Short title` comments so specs are grep-able across the codebase (`grep -rn '@spec BM-' src/ __tests__/`). Place the comment on the line immediately above the relevant code block or test. When multiple tests cover the same spec, use `it.each` if the test structure is identical.-- Release automation: releases use a **long-lived release branch** model β a `rel-X.Y.Z` branch is created from `main`, QA/fixes land there, and publishing is triggered by pushing a `v*` tag directly to that branch (the branch is never merged back to main). Tag format determines the npm dist-tag: `alpha` β `alpha`, `beta` β `beta`, `rc` β `rc`, no suffix β `latest`. Three workflows fire in parallel on every `v*` tag push: `create-release.yml` (creates the GitHub Release object with auto-generated notes and marks pre-release for hyphenated versions), `npm-publish.yml` (builds and publishes to npm with the correct dist-tag), and `docker.yml` (builds multi-arch Docker images). The release skill (`.agents/skills/release.md`, keyword trigger: `release`) guides agents through the full process.+- Release automation: releases use a **long-lived release branch** model β a `rel-X.Y.Z` branch is created from `main`, QA/fixes land there, and publishing is triggered by pushing a `v*` tag directly to that branch (the branch is never merged back to main). The dist-tag is resolved dynamically at publish time by querying npm: if no stable version (no pre-release suffix) has ever been published, all releases use `--tag latest`; once a stable version exists, pre-release versions get their own dist-tag (`alpha` / `beta` / `rc`) and only stable versions keep `latest`. The transition is automatic β no workflow change is needed when the first stable release ships. Three workflows fire in parallel on every `v*` tag push: `create-release.yml` (creates the GitHub Release object with auto-generated notes and marks pre-release for hyphenated versions), `npm-publish.yml` (builds and publishes to npm with the correct dist-tag), and `docker.yml` (builds multi-arch Docker images). The release skill (`.agents/skills/release.md`, keyword trigger: `release`) guides agents through the full process.- Cloud conversation resume gating: when a cloud conversation is closed from the UI (`pauseCloudSandbox` is called), the conversation's `conversation_url` is NOT cleared -- it still points to the old sandbox host. `WebSocketProviderWrapper` must suppress the URL (pass `null` to `ConversationWebSocketProvider`) while `sandbox_status === "PAUSED"`, otherwise the WebSocket immediately tries the stale URL before the sandbox wakes. Symmetrically, `useActiveConversation`'s refetch interval must fast-poll (3 s) on both `!conversation_url` AND `sandbox_status === "PAUSED"` -- checking only the missing URL would leave the hook on the 30 s interval while the sandbox is resuming. The resume sequence: navigate -> sandbox PAUSED detected -> `resumeCloudSandbox` called (in `conversation.tsx`) -> fast-poll detects RUNNING -> `conversationUrl` unblocked -> WebSocket connects.