Merge branch 'main' into vincentkoc-code/config-docs-drift-baseline

2026-04-21 22:21:33 +00:00 · 2026-03-14 10:37:52 -07:00
parent cae3417fea c30cabcca4
commit 1e56f3eec7
1828 changed files with 61405 additions and 31968 deletions
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -7,7 +7,7 @@ on:

 concurrency:
  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+  cancel-in-progress: true

 env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
@@ -38,9 +38,8 @@ jobs:
        id: check
        uses: ./.github/actions/detect-docs-changes

-  # Detect which heavy areas are touched so PRs can skip unrelated expensive jobs.
-  # Push to main keeps broad coverage, but this job still needs to run so
-  # downstream jobs that list it in `needs` are not skipped.
+  # Detect which heavy areas are touched so CI can skip unrelated expensive jobs.
+  # Fail-safe: if detection fails, downstream jobs run.
  changed-scope:
    needs: [docs-scope]
    if: needs.docs-scope.outputs.docs_only != 'true'
@@ -82,7 +81,7 @@ jobs:
  # Build dist once for Node-relevant changes and share it with downstream jobs.
  build-artifacts:
    needs: [docs-scope, changed-scope]
-    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_node == 'true')
+    if: github.event_name == 'push' && needs.docs-scope.outputs.docs_only != 'true' && needs.changed-scope.outputs.run_node == 'true'
    runs-on: blacksmith-16vcpu-ubuntu-2404
    steps:
      - name: Checkout
@@ -141,7 +140,7 @@ jobs:

  checks:
    needs: [docs-scope, changed-scope]
-    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_node == 'true')
+    if: needs.docs-scope.outputs.docs_only != 'true' && needs.changed-scope.outputs.run_node == 'true'
    runs-on: blacksmith-16vcpu-ubuntu-2404
    strategy:
      fail-fast: false
@@ -149,6 +148,13 @@ jobs:
        include:
          - runtime: node
            task: test
+            shard_index: 1
+            shard_count: 2
+            command: pnpm canvas:a2ui:bundle && pnpm test
+          - runtime: node
+            task: test
+            shard_index: 2
+            shard_count: 2
            command: pnpm canvas:a2ui:bundle && pnpm test
          - runtime: node
            task: extensions
@@ -160,40 +166,47 @@ jobs:
            task: test
            command: pnpm canvas:a2ui:bundle && bunx vitest run --config vitest.unit.config.ts
    steps:
-      - name: Skip bun lane on push
-        if: github.event_name == 'push' && matrix.runtime == 'bun'
-        run: echo "Skipping bun test lane on push events."
+      - name: Skip bun lane on pull requests
+        if: github.event_name == 'pull_request' && matrix.runtime == 'bun'
+        run: echo "Skipping Bun compatibility lane on pull requests."

      - name: Checkout
-        if: github.event_name != 'push' || matrix.runtime != 'bun'
+        if: github.event_name != 'pull_request' || matrix.runtime != 'bun'
        uses: actions/checkout@v6
        with:
          submodules: false

      - name: Setup Node environment
-        if: matrix.runtime != 'bun' || github.event_name != 'push'
+        if: matrix.runtime != 'bun' || github.event_name != 'pull_request'
        uses: ./.github/actions/setup-node-env
        with:
          install-bun: "${{ matrix.runtime == 'bun' }}"
          use-sticky-disk: "false"

      - name: Configure Node test resources
-        if: (github.event_name != 'push' || matrix.runtime != 'bun') && matrix.task == 'test' && matrix.runtime == 'node'
+        if: (github.event_name != 'pull_request' || matrix.runtime != 'bun') && matrix.task == 'test' && matrix.runtime == 'node'
+        env:
+          SHARD_COUNT: ${{ matrix.shard_count || '' }}
+          SHARD_INDEX: ${{ matrix.shard_index || '' }}
        run: |
          # `pnpm test` runs `scripts/test-parallel.mjs`, which spawns multiple Node processes.
          # Default heap limits have been too low on Linux CI (V8 OOM near 4GB).
          echo "OPENCLAW_TEST_WORKERS=2" >> "$GITHUB_ENV"
          echo "OPENCLAW_TEST_MAX_OLD_SPACE_SIZE_MB=6144" >> "$GITHUB_ENV"
+          if [ -n "$SHARD_COUNT" ] && [ -n "$SHARD_INDEX" ]; then
+            echo "OPENCLAW_TEST_SHARDS=$SHARD_COUNT" >> "$GITHUB_ENV"
+            echo "OPENCLAW_TEST_SHARD_INDEX=$SHARD_INDEX" >> "$GITHUB_ENV"
+          fi

      - name: Run ${{ matrix.task }} (${{ matrix.runtime }})
-        if: matrix.runtime != 'bun' || github.event_name != 'push'
+        if: matrix.runtime != 'bun' || github.event_name != 'pull_request'
        run: ${{ matrix.command }}

  # Types, lint, and format check.
  check:
    name: "check"
    needs: [docs-scope, changed-scope]
-    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_node == 'true')
+    if: needs.docs-scope.outputs.docs_only != 'true' && needs.changed-scope.outputs.run_node == 'true'
    runs-on: blacksmith-16vcpu-ubuntu-2404
    steps:
      - name: Checkout
@@ -239,7 +252,7 @@ jobs:
  compat-node22:
    name: "compat-node22"
    needs: [docs-scope, changed-scope]
-    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_node == 'true')
+    if: github.event_name == 'push' && needs.docs-scope.outputs.docs_only != 'true' && needs.changed-scope.outputs.run_node == 'true'
    runs-on: blacksmith-16vcpu-ubuntu-2404
    steps:
      - name: Checkout
@@ -272,7 +285,7 @@ jobs:

  skills-python:
    needs: [docs-scope, changed-scope]
-    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_node == 'true' || needs.changed-scope.outputs.run_skills_python == 'true')
+    if: needs.docs-scope.outputs.docs_only != 'true' && needs.changed-scope.outputs.run_skills_python == 'true'
    runs-on: blacksmith-16vcpu-ubuntu-2404
    steps:
      - name: Checkout
@@ -365,7 +378,7 @@ jobs:

  checks-windows:
    needs: [docs-scope, changed-scope]
-    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_windows == 'true')
+    if: needs.docs-scope.outputs.docs_only != 'true' && needs.changed-scope.outputs.run_windows == 'true'
    runs-on: blacksmith-32vcpu-windows-2025
    timeout-minutes: 45
    env:
@@ -727,7 +740,7 @@ jobs:

  android:
    needs: [docs-scope, changed-scope]
-    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_android == 'true')
+    if: needs.docs-scope.outputs.docs_only != 'true' && needs.changed-scope.outputs.run_android == 'true'
    runs-on: blacksmith-16vcpu-ubuntu-2404
    strategy:
      fail-fast: false
--- a/.github/workflows/docker-release.yml
+++ b/.github/workflows/docker-release.yml
@@ -12,9 +12,15 @@ on:
      - "**/*.mdx"
      - ".agents/**"
      - "skills/**"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing release tag to backfill (for example v2026.3.13)
+        required: true
+        type: string

 concurrency:
-  group: docker-release-${{ github.workflow }}-${{ github.ref }}
+  group: docker-release-${{ github.workflow }}-${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref }}
  cancel-in-progress: false

 env:
@@ -23,9 +29,46 @@ env:
  IMAGE_NAME: ${{ github.repository }}

 jobs:
+  validate_manual_backfill:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    steps:
+      - name: Validate tag input format
+        env:
+          RELEASE_TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          if [[ ! "${RELEASE_TAG}" =~ ^v[0-9]{4}\.[1-9][0-9]*\.[1-9][0-9]*(-beta\.[1-9][0-9]*)?$ ]]; then
+            echo "Invalid release tag: ${RELEASE_TAG}"
+            exit 1
+          fi
+
+      - name: Checkout selected tag
+        uses: actions/checkout@v6
+        with:
+          ref: refs/tags/${{ inputs.tag }}
+          fetch-depth: 0
+
+  approve_manual_backfill:
+    if: github.event_name == 'workflow_dispatch'
+    needs: validate_manual_backfill
+    # WARNING: KEEP MANUAL BACKFILLS GATED BY THE docker-release ENVIRONMENT.
+    runs-on: ubuntu-24.04
+    environment: docker-release
+    steps:
+      - name: Approve Docker backfill
+        run: echo "Approved Docker backfill for ${{ inputs.tag }}"
+
+  # KEEP THIS WORKFLOW ON GITHUB-HOSTED RUNNERS.
+  # DO NOT MOVE IT BACK TO BLACKSMITH WITHOUT RE-VALIDATING TAG BUILDS AND BACKFILLS.
  # Build amd64 images (default + slim share the build stage cache)
  build-amd64:
-    runs-on: blacksmith-16vcpu-ubuntu-2404
+    needs: [approve_manual_backfill]
+    if: ${{ always() && (github.event_name != 'workflow_dispatch' || needs.approve_manual_backfill.result == 'success') }}
+    # WARNING: DO NOT REVERT THIS TO A BLACKSMITH RUNNER WITHOUT RE-VALIDATING TAG BACKFILLS.
+    runs-on: ubuntu-24.04
    permissions:
      packages: write
      contents: read
@@ -35,6 +78,9 @@ jobs:
    steps:
      - name: Checkout
        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/{0}', inputs.tag) || github.ref }}
+          fetch-depth: 0

      - name: Set up Docker Builder
        uses: docker/setup-buildx-action@v4
@@ -51,21 +97,22 @@ jobs:
        shell: bash
        env:
          IMAGE: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          SOURCE_REF: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/{0}', inputs.tag) || github.ref }}
        run: |
          set -euo pipefail
          tags=()
          slim_tags=()
-          if [[ "${GITHUB_REF}" == "refs/heads/main" ]]; then
+          if [[ "${SOURCE_REF}" == "refs/heads/main" ]]; then
            tags+=("${IMAGE}:main-amd64")
            slim_tags+=("${IMAGE}:main-slim-amd64")
          fi
-          if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
-            version="${GITHUB_REF#refs/tags/v}"
+          if [[ "${SOURCE_REF}" == refs/tags/v* ]]; then
+            version="${SOURCE_REF#refs/tags/v}"
            tags+=("${IMAGE}:${version}-amd64")
            slim_tags+=("${IMAGE}:${version}-slim-amd64")
          fi
          if [[ ${#tags[@]} -eq 0 ]]; then
-            echo "::error::No amd64 tags resolved for ref ${GITHUB_REF}"
+            echo "::error::No amd64 tags resolved for ref ${SOURCE_REF}"
            exit 1
          fi
          {
@@ -82,19 +129,22 @@ jobs:
      - name: Resolve OCI labels (amd64)
        id: labels
        shell: bash
+        env:
+          SOURCE_REF: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/{0}', inputs.tag) || github.ref }}
        run: |
          set -euo pipefail
-          version="${GITHUB_SHA}"
-          if [[ "${GITHUB_REF}" == "refs/heads/main" ]]; then
+          source_sha="$(git rev-parse HEAD)"
+          version="${source_sha}"
+          if [[ "${SOURCE_REF}" == "refs/heads/main" ]]; then
            version="main"
          fi
-          if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
-            version="${GITHUB_REF#refs/tags/v}"
+          if [[ "${SOURCE_REF}" == refs/tags/v* ]]; then
+            version="${SOURCE_REF#refs/tags/v}"
          fi
          created="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
          {
            echo "value<<EOF"
-            echo "org.opencontainers.image.revision=${GITHUB_SHA}"
+            echo "org.opencontainers.image.revision=${source_sha}"
            echo "org.opencontainers.image.version=${version}"
            echo "org.opencontainers.image.created=${created}"
            echo "EOF"
@@ -102,7 +152,8 @@ jobs:

      - name: Build and push amd64 image
        id: build
-        uses: useblacksmith/build-push-action@v2
+        # WARNING: KEEP THE OFFICIAL DOCKER ACTION HERE; DO NOT SWITCH THIS BACK TO BLACKSMITH BLINDLY.
+        uses: docker/build-push-action@v6
        with:
          context: .
          platforms: linux/amd64
@@ -113,7 +164,8 @@ jobs:

      - name: Build and push amd64 slim image
        id: build-slim
-        uses: useblacksmith/build-push-action@v2
+        # WARNING: KEEP THE OFFICIAL DOCKER ACTION HERE; DO NOT SWITCH THIS BACK TO BLACKSMITH BLINDLY.
+        uses: docker/build-push-action@v6
        with:
          context: .
          platforms: linux/amd64
@@ -126,7 +178,10 @@ jobs:

  # Build arm64 images (default + slim share the build stage cache)
  build-arm64:
-    runs-on: blacksmith-16vcpu-ubuntu-2404-arm
+    needs: [approve_manual_backfill]
+    if: ${{ always() && (github.event_name != 'workflow_dispatch' || needs.approve_manual_backfill.result == 'success') }}
+    # WARNING: DO NOT REVERT THIS TO A BLACKSMITH RUNNER WITHOUT RE-VALIDATING TAG BACKFILLS.
+    runs-on: ubuntu-24.04-arm
    permissions:
      packages: write
      contents: read
@@ -136,6 +191,9 @@ jobs:
    steps:
      - name: Checkout
        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/{0}', inputs.tag) || github.ref }}
+          fetch-depth: 0

      - name: Set up Docker Builder
        uses: docker/setup-buildx-action@v4
@@ -152,21 +210,22 @@ jobs:
        shell: bash
        env:
          IMAGE: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          SOURCE_REF: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/{0}', inputs.tag) || github.ref }}
        run: |
          set -euo pipefail
          tags=()
          slim_tags=()
-          if [[ "${GITHUB_REF}" == "refs/heads/main" ]]; then
+          if [[ "${SOURCE_REF}" == "refs/heads/main" ]]; then
            tags+=("${IMAGE}:main-arm64")
            slim_tags+=("${IMAGE}:main-slim-arm64")
          fi
-          if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
-            version="${GITHUB_REF#refs/tags/v}"
+          if [[ "${SOURCE_REF}" == refs/tags/v* ]]; then
+            version="${SOURCE_REF#refs/tags/v}"
            tags+=("${IMAGE}:${version}-arm64")
            slim_tags+=("${IMAGE}:${version}-slim-arm64")
          fi
          if [[ ${#tags[@]} -eq 0 ]]; then
-            echo "::error::No arm64 tags resolved for ref ${GITHUB_REF}"
+            echo "::error::No arm64 tags resolved for ref ${SOURCE_REF}"
            exit 1
          fi
          {
@@ -183,19 +242,22 @@ jobs:
      - name: Resolve OCI labels (arm64)
        id: labels
        shell: bash
+        env:
+          SOURCE_REF: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/{0}', inputs.tag) || github.ref }}
        run: |
          set -euo pipefail
-          version="${GITHUB_SHA}"
-          if [[ "${GITHUB_REF}" == "refs/heads/main" ]]; then
+          source_sha="$(git rev-parse HEAD)"
+          version="${source_sha}"
+          if [[ "${SOURCE_REF}" == "refs/heads/main" ]]; then
            version="main"
          fi
-          if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
-            version="${GITHUB_REF#refs/tags/v}"
+          if [[ "${SOURCE_REF}" == refs/tags/v* ]]; then
+            version="${SOURCE_REF#refs/tags/v}"
          fi
          created="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
          {
            echo "value<<EOF"
-            echo "org.opencontainers.image.revision=${GITHUB_SHA}"
+            echo "org.opencontainers.image.revision=${source_sha}"
            echo "org.opencontainers.image.version=${version}"
            echo "org.opencontainers.image.created=${created}"
            echo "EOF"
@@ -203,7 +265,8 @@ jobs:

      - name: Build and push arm64 image
        id: build
-        uses: useblacksmith/build-push-action@v2
+        # WARNING: KEEP THE OFFICIAL DOCKER ACTION HERE; DO NOT SWITCH THIS BACK TO BLACKSMITH BLINDLY.
+        uses: docker/build-push-action@v6
        with:
          context: .
          platforms: linux/arm64
@@ -214,7 +277,8 @@ jobs:

      - name: Build and push arm64 slim image
        id: build-slim
-        uses: useblacksmith/build-push-action@v2
+        # WARNING: KEEP THE OFFICIAL DOCKER ACTION HERE; DO NOT SWITCH THIS BACK TO BLACKSMITH BLINDLY.
+        uses: docker/build-push-action@v6
        with:
          context: .
          platforms: linux/arm64
@@ -227,14 +291,19 @@ jobs:

  # Create multi-platform manifests
  create-manifest:
-    runs-on: blacksmith-16vcpu-ubuntu-2404
+    needs: [approve_manual_backfill, build-amd64, build-arm64]
+    if: ${{ always() && needs.build-amd64.result == 'success' && needs.build-arm64.result == 'success' && (github.event_name != 'workflow_dispatch' || needs.approve_manual_backfill.result == 'success') }}
+    # WARNING: DO NOT REVERT THIS TO A BLACKSMITH RUNNER WITHOUT RE-VALIDATING TAG BACKFILLS.
+    runs-on: ubuntu-24.04
    permissions:
      packages: write
      contents: read
-    needs: [build-amd64, build-arm64]
    steps:
      - name: Checkout
        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/{0}', inputs.tag) || github.ref }}
+          fetch-depth: 0

      - name: Login to GitHub Container Registry
        uses: docker/login-action@v4
@@ -248,25 +317,28 @@ jobs:
        shell: bash
        env:
          IMAGE: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          SOURCE_REF: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/{0}', inputs.tag) || github.ref }}
+          IS_MANUAL_BACKFILL: ${{ github.event_name == 'workflow_dispatch' && '1' || '0' }}
        run: |
          set -euo pipefail
          tags=()
          slim_tags=()
-          if [[ "${GITHUB_REF}" == "refs/heads/main" ]]; then
+          if [[ "${SOURCE_REF}" == "refs/heads/main" ]]; then
            tags+=("${IMAGE}:main")
            slim_tags+=("${IMAGE}:main-slim")
          fi
-          if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
-            version="${GITHUB_REF#refs/tags/v}"
+          if [[ "${SOURCE_REF}" == refs/tags/v* ]]; then
+            version="${SOURCE_REF#refs/tags/v}"
            tags+=("${IMAGE}:${version}")
            slim_tags+=("${IMAGE}:${version}-slim")
-            if [[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9]+)?$ ]]; then
+            # Manual backfills should only republish the requested version tags.
+            if [[ "${IS_MANUAL_BACKFILL}" != "1" && "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9]+)?$ ]]; then
              tags+=("${IMAGE}:latest")
              slim_tags+=("${IMAGE}:slim")
            fi
          fi
          if [[ ${#tags[@]} -eq 0 ]]; then
-            echo "::error::No manifest tags resolved for ref ${GITHUB_REF}"
+            echo "::error::No manifest tags resolved for ref ${SOURCE_REF}"
            exit 1
          fi
          {
--- a/.github/workflows/openclaw-npm-release.yml
+++ b/.github/workflows/openclaw-npm-release.yml
@@ -4,9 +4,15 @@ on:
  push:
    tags:
      - "v*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Release tag to publish (for example v2026.3.14 or v2026.3.14-beta.1)
+        required: true
+        type: string

 concurrency:
-  group: openclaw-npm-release-${{ github.ref }}
+  group: openclaw-npm-release-${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref }}
  cancel-in-progress: false

 env:
@@ -15,12 +21,11 @@ env:
  PNPM_VERSION: "10.23.0"

 jobs:
-  publish_openclaw_npm:
-    # npm trusted publishing + provenance requires a GitHub-hosted runner.
+  preview_openclaw_npm:
+    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    permissions:
      contents: read
-      id-token: write
    steps:
      - name: Checkout
        uses: actions/checkout@v6
@@ -35,13 +40,107 @@ jobs:
          install-bun: "false"
          use-sticky-disk: "false"

+      - name: Print release plan
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          RELEASE_SHA=$(git rev-parse HEAD)
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          echo "Release plan for ${RELEASE_TAG}:"
+          echo "Resolved release SHA: ${RELEASE_SHA}"
+          echo "Resolved package version: ${PACKAGE_VERSION}"
+          echo "Would run: git fetch --no-tags origin +refs/heads/main:refs/remotes/origin/main"
+          echo "Would run with env: RELEASE_SHA=${RELEASE_SHA} RELEASE_TAG=${RELEASE_TAG} RELEASE_MAIN_REF=origin/main pnpm release:openclaw:npm:check"
+          echo "Would run: npm view openclaw@${PACKAGE_VERSION} version"
+          echo "Would run: pnpm check"
+          echo "Would run: pnpm build"
+          echo "Would run: pnpm release:check"
+
      - name: Validate release tag and package metadata
        env:
-          RELEASE_SHA: ${{ github.sha }}
          RELEASE_TAG: ${{ github.ref_name }}
          RELEASE_MAIN_REF: origin/main
+        run: |
+          set -euxo pipefail
+          RELEASE_SHA=$(git rev-parse HEAD)
+          export RELEASE_SHA RELEASE_TAG RELEASE_MAIN_REF
+          # Fetch the full main ref so merge-base ancestry checks keep working
+          # for older tagged commits that are still contained in main.
+          git fetch --no-tags origin +refs/heads/main:refs/remotes/origin/main
+          pnpm release:openclaw:npm:check
+
+      - name: Ensure version is not already published
+        run: |
+          set -euxo pipefail
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+
+          if npm view "openclaw@${PACKAGE_VERSION}" version >/dev/null 2>&1; then
+            echo "openclaw@${PACKAGE_VERSION} is already published on npm."
+            exit 1
+          fi
+
+          echo "Previewing openclaw@${PACKAGE_VERSION}"
+
+      - name: Check
+        run: |
+          set -euxo pipefail
+          pnpm check
+
+      - name: Build
+        run: |
+          set -euxo pipefail
+          pnpm build
+
+      - name: Verify release contents
+        run: |
+          set -euxo pipefail
+          pnpm release:check
+
+      - name: Preview publish command
+        run: bash scripts/openclaw-npm-publish.sh --dry-run
+
+  publish_openclaw_npm:
+    if: github.event_name == 'workflow_dispatch'
+    # npm trusted publishing + provenance requires a GitHub-hosted runner.
+    runs-on: ubuntu-latest
+    environment: npm-release
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Validate tag input format
+        env:
+          RELEASE_TAG: ${{ inputs.tag }}
        run: |
          set -euo pipefail
+          if [[ ! "${RELEASE_TAG}" =~ ^v[0-9]{4}\.[1-9][0-9]*\.[1-9][0-9]*(-beta\.[1-9][0-9]*)?$ ]]; then
+            echo "Invalid release tag format: ${RELEASE_TAG}"
+            exit 1
+          fi
+
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          ref: refs/tags/${{ inputs.tag }}
+          fetch-depth: 0
+
+      - name: Setup Node environment
+        uses: ./.github/actions/setup-node-env
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          pnpm-version: ${{ env.PNPM_VERSION }}
+          install-bun: "false"
+          use-sticky-disk: "false"
+
+      - name: Validate release tag and package metadata
+        env:
+          RELEASE_TAG: ${{ inputs.tag }}
+          RELEASE_MAIN_REF: origin/main
+        run: |
+          set -euo pipefail
+          RELEASE_SHA=$(git rev-parse HEAD)
+          export RELEASE_SHA RELEASE_TAG RELEASE_MAIN_REF
          # Fetch the full main ref so merge-base ancestry checks keep working
          # for older tagged commits that are still contained in main.
          git fetch --no-tags origin +refs/heads/main:refs/remotes/origin/main
@@ -69,12 +168,4 @@ jobs:
        run: pnpm release:check

      - name: Publish
-        run: |
-          set -euo pipefail
-          PACKAGE_VERSION=$(node -p "require('./package.json').version")
-
-          if [[ "$PACKAGE_VERSION" == *-beta.* ]]; then
-            npm publish --access public --tag beta --provenance
-          else
-            npm publish --access public --provenance
-          fi
+        run: bash scripts/openclaw-npm-publish.sh --publish