Skip to content

πŸ™Œ 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.md
index 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> --yes
Then 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.yml
index bae15a48a7..8f93d5ef8d 100644
--- a/.github/workflows/npm-publish.yml
+++ b/.github/workflows/npm-publish.yml
@@ -90,11 +90,11 @@ jobs:
fi
echo "βœ“ 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_tag
run: |
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* ]]; then
DIST_TAG="alpha"
elif [[ "$VERSION" == *-beta* ]]; then
DIST_TAG="beta"
@@ -112,7 +120,7 @@ jobs:
DIST_TAG="latest"
fi
echo "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 provenance
run: npm publish --access public --provenance --tag ${{ steps.dist_tag.outputs.dist_tag }}
diff --git a/AGENTS.md b/AGENTS.md
index 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.