Your lightweight open-source personal agent.
Python agent-frameworkai-agentai-agentschatbotchatopsdiscord-botllm-agentsllmslocal-llmmcpmodel-context-protocolmulti-agentopenai-compatibleopenclawpersonal-ai-assistantpythonself-hostedtelegram-bot-ai-assistantwebuiworkflow-automation
ci(release): verify exact candidate wheels on all five native targets
Xubin Ren897c8b013f4a
diff --git a/.github/workflows/native-acceptance.yml b/.github/workflows/native-acceptance.ymlindex 4ae00231c..4c741425e 100644--- a/.github/workflows/native-acceptance.yml+++ b/.github/workflows/native-acceptance.yml@@ -13,12 +13,13 @@ on:manifest_sha256:type: stringdefault: ''- linux_artifact_id:+ candidate_artifact_id:type: stringdefault: ''- windows_artifact_id:+ platforms:+ description: Native runner and wheel pairs; ordinary PRs keep the two-platform budgettype: string- default: ''+ default: '[{"os":"ubuntu-latest","target":"linux-x64","wheel_tag":"manylinux_2_17_x86_64"},{"os":"windows-latest","target":"win32-x64","wheel_tag":"win_amd64"}]'permissions:contents: read@@ -31,13 +32,7 @@ jobs:strategy:fail-fast: falsematrix:- include:- - os: ubuntu-latest- target: linux-x64- wheel_tag: manylinux_2_17_x86_64- - os: windows-latest- target: win32-x64- wheel_tag: win_amd64+ include: ${{ fromJSON(inputs.platforms) }}defaults:run:shell: bash@@ -81,7 +76,7 @@ jobs:uses: actions/download-artifact@v4with:# Producer IDs survive a failed-jobs-only retry without rebuilding bytes.- artifact-ids: ${{ matrix.target == 'linux-x64' && inputs.linux_artifact_id || inputs.windows_artifact_id }}+ artifact-ids: ${{ inputs.candidate_artifact_id }}merge-multiple: truepath: ${{ runner.temp }}/native-wheeldiff --git a/.github/workflows/release-candidate.yml b/.github/workflows/release-candidate.ymlindex b6e6f6e4b..fb7e37e9f 100644--- a/.github/workflows/release-candidate.yml+++ b/.github/workflows/release-candidate.yml@@ -36,8 +36,7 @@ jobs:outputs:candidate_commit: ${{ steps.identity.outputs.candidate_commit }}manifest_sha256: ${{ steps.identity.outputs.manifest_sha256 }}- linux_artifact_id: ${{ steps.linux_input.outputs.artifact-id }}- windows_artifact_id: ${{ steps.windows_input.outputs.artifact-id }}+ candidate_artifact_id: ${{ steps.native_input.outputs.artifact-id }}prepared_artifact_id: ${{ steps.prepared.outputs.artifact-id }}env:SOURCE_COMMIT: ${{ github.sha }}@@ -164,25 +163,13 @@ jobs:PY# Temporary same-run inputs, not approved release handoffs. Do not rebuild on consumers.- - name: Transfer exact Linux acceptance input- id: linux_input+ - name: Transfer exact native acceptance inputs+ id: native_inputuses: actions/upload-artifact@v4with:- name: candidate-native-linux-x64-${{ github.run_number }}-${{ github.run_attempt }}+ name: candidate-native-wheels-${{ github.run_number }}-${{ github.run_attempt }}path: |- ${{ runner.temp }}/release-artifacts/*-manylinux_2_17_x86_64.whl- ${{ runner.temp }}/release-artifacts/release-manifest.json- if-no-files-found: error- retention-days: 1- compression-level: 0-- - name: Transfer exact Windows acceptance input- id: windows_input- uses: actions/upload-artifact@v4- with:- name: candidate-native-win32-x64-${{ github.run_number }}-${{ github.run_attempt }}- path: |- ${{ runner.temp }}/release-artifacts/*-win_amd64.whl+ ${{ runner.temp }}/release-artifacts/*.whl${{ runner.temp }}/release-artifacts/release-manifest.jsonif-no-files-found: errorretention-days: 1@@ -236,8 +223,13 @@ jobs:candidate: truecandidate_commit: ${{ needs.candidate.outputs.candidate_commit }}manifest_sha256: ${{ needs.candidate.outputs.manifest_sha256 }}- linux_artifact_id: ${{ needs.candidate.outputs.linux_artifact_id }}- windows_artifact_id: ${{ needs.candidate.outputs.windows_artifact_id }}+ candidate_artifact_id: ${{ needs.candidate.outputs.candidate_artifact_id }}+ platforms: >-+ [{"os":"ubuntu-latest","target":"linux-x64","wheel_tag":"manylinux_2_17_x86_64"},+ {"os":"ubuntu-24.04-arm","target":"linux-arm64","wheel_tag":"manylinux_2_17_aarch64"},+ {"os":"windows-latest","target":"win32-x64","wheel_tag":"win_amd64"},+ {"os":"macos-15","target":"darwin-arm64","wheel_tag":"macosx_13_0_arm64"},+ {"os":"macos-15-intel","target":"darwin-x64","wheel_tag":"macosx_13_0_x86_64"}]verified:name: Candidate required@@ -246,7 +238,7 @@ jobs:runs-on: ubuntu-latesttimeout-minutes: 10steps:- - name: Require build and both native acceptance jobs+ - name: Require build and every native acceptance jobenv:BUILD_RESULT: ${{ needs.candidate.result }}NATIVE_RESULT: ${{ needs.native.result }}@@ -275,5 +267,5 @@ jobs:CANDIDATE_COMMIT: ${{ needs.candidate.outputs.candidate_commit }}MANIFEST_SHA256: ${{ needs.candidate.outputs.manifest_sha256 }}run: |- printf 'Candidate: `%s`\n\nManifest SHA-256: `%s`\n\nLinux and Windows native acceptance passed. Publication requires separate approval.\n' \+ printf 'Candidate: `%s`\n\nManifest SHA-256: `%s`\n\nAll five native targets passed installation and update/recovery acceptance. Publication requires separate approval.\n' \"$CANDIDATE_COMMIT" "$MANIFEST_SHA256" >> "$GITHUB_STEP_SUMMARY"diff --git a/docs/releasing.md b/docs/releasing.mdindex dc723072d..7f7d333b1 100644--- a/docs/releasing.md+++ b/docs/releasing.md@@ -24,8 +24,8 @@ Packaging is maintainer-triggered, not scheduled or push-triggered. Record the r### Maintainer-triggered Preview procedure1. Select an exact reviewed `main` commit with passing required CI; skip it if its source SHA matches the last accepted candidate. Record the next unreleased stable base and an unused increasing Preview sequence.-2. Run **Verify Release Candidate** for that ref and base. It prepares a version-only candidate, builds the WebUI and five native TUI bundles once, and runs Linux x64 and Windows x64 clean-install and packaged update/recovery acceptance against the exact manifest-bound wheels without publication. Require the **Candidate required** check to pass; build-only reports are insufficient. Users receive built packages, not a checkout requiring Bun.-3. Select `retain_installable` and preserve the accepted `installable-candidate` handoff before expiry. Temporary `candidate-native` inputs and `prepared-candidate` artifacts are not accepted handoffs. Complete the remaining native-platform and real historical-baseline acceptance against those exact bytes; the automated fault-injection fixtures do not establish compatibility with a previously published version. Keep candidate SHA, manifest hash, coverage, known issues and source-offer approval together; CI reports alone are neither installable artifacts nor publication consent.+2. Run **Verify Release Candidate** for that ref and base. It prepares a version-only candidate, builds the WebUI and five native TUI bundles once, and runs macOS arm64/x64, Linux arm64/x64 and Windows x64 clean-install and packaged update/recovery acceptance against the exact manifest-bound wheels without publication. Ordinary PR CI keeps its Linux x64/Windows x64 matrix; the manually requested candidate pays for all five native runners. Require the **Candidate required** check to pass; build-only reports are insufficient. Users receive built packages, not a checkout requiring Bun.+3. Select `retain_installable` and preserve the accepted `installable-candidate` handoff before expiry. Temporary `candidate-native` inputs and `prepared-candidate` artifacts are not accepted handoffs. Complete real historical-baseline and interactive acceptance against those exact bytes; the automated fault-injection fixtures do not establish compatibility with a previously published version or interactive desktop behavior. Keep candidate SHA, manifest hash, coverage, known issues and source-offer approval together; CI reports alone are neither installable artifacts nor publication consent.4. With separate approval, publish immutable `v<version>` at the **candidate** commit and a GitHub prerelease, never the latest stable release. Upload the complete verified set, manifest and notes; make the pinned installer source publicly reachable.5. Verify all public sizes/hashes and clean public install/update acceptance before advancing `preview` with a new catalogue generation. Validate against the latest catalogue, preserve `stable` and withdrawals, and serialize stable, Preview and withdrawal writes. A stale publisher must reread and revalidate.6. After partial upload, leave the feed unchanged and resume only from the original verified files. Lost or changed bytes require a new version and repeated acceptance. Withdraw unsafe candidates with a reason and offer a newer fix; never rewind the feed or restore user data.@@ -103,7 +103,7 @@ PyPI receives **five platform wheels and one sdist**, not the intermediate univeFinal releases also require `release-manifest.json` for `stable`. Run `scripts.release_candidate assemble` as shown below from the clean final-version checkout, using that final commit as `--source-commit` without Preview preparation. GitHub receives the same wheels/sdist, ten archive/checksum files and manifest; PyPI receives only wheels/sdist. Verify final source and public bytes before catalogue advancement. A TUI-only GitHub Release cannot deliver the final release to Preview subscribers.-For the same-build Linux and Windows candidate acceptance, run **Verify Release Candidate** at the exact final-version ref with `channel=stable`, `next_stable` equal to that declared version and `retain_installable=true`. Stable preparation copies the exact commit without changing version declarations or creating a Preview commit; it rejects mismatched versions and existing stable tags. The default `channel=preview` retains the version-only Preview preparation. Both modes are read-only preparation, require **Candidate required** and retain accepted files for one day; neither publishes a tag, release, PyPI package or feed. Download and independently preserve the accepted handoff before expiry, then complete native macOS and historical-owner acceptance against that same manifest.+For same-build candidate acceptance on all five native targets, run **Verify Release Candidate** at the exact final-version ref with `channel=stable`, `next_stable` equal to that declared version and `retain_installable=true`. Stable preparation copies the exact commit without changing version declarations or creating a Preview commit; it rejects mismatched versions and existing stable tags. The default `channel=preview` retains the version-only Preview preparation. Both modes are read-only preparation, require **Candidate required** and retain accepted files for one day; neither publishes a tag, release, PyPI package or feed. Download and independently preserve the accepted handoff before expiry, then complete remaining interactive and real historical-owner acceptance against that same manifest.## Publish, with maintainer approval@@ -160,7 +160,7 @@ These exact-version handoffs do not discover Preview, change subscriptions, stop### Packaged upgrade and recovery acceptance-Linux/Windows native CI runs `scripts/verify_packaged_update.py` against its wheel; manual candidate preparation uses the assembled Linux wheel. Run macOS acceptance against the candidate's macOS wheel:+Linux/Windows native CI runs `scripts/verify_packaged_update.py` against its wheel; manual candidate preparation tests each of the five assembled platform wheels on a matching native runner. Run macOS acceptance against the candidate's macOS wheel:```bash<build-tools-python> -I scripts/verify_packaged_update.py \@@ -212,7 +212,7 @@ Discovery grants no installation authority. Only the official managed venv and sDefault retention is small identity/manifest/probe reports and installation guide for **three days**, without installable binaries. `retain_installable` preserves those exact checked artifacts plus a self-contained shallow Git repository for **one day** (about 400 MB). Keep this storage exception off for routine preflight or schedules; assess storage and call it out explicitly in workflow-change PRs before merge. Preserve approved handoffs before expiry; rebuilding expired files cannot reuse their verification. The source contains only candidate/source-parent history, not configuration or untracked files. `handoff.json` is written only after copied artifacts verify; interruption is not an accepted handoff.-After assembly, the workflow installs the Linux x64 wheel and binary dependencies into a separate venv without Bun/Node/Git on the install PATH. Isolated Python checks version/commit/import identity, all Vite-manifest assets including lazy chunks through the installed handler, and bundled TUI `--desktop-protocol` with downloads disabled and empty private HOME. With `--gateway`, it starts a private foreground CLI gateway with no provider/MCP configuration, disabled heartbeat and two loopback ports, then checks readiness, protected version identity, HTML and process/listener cleanup. Unix shutdown must be graceful; Windows termination is labelled, not graceful-shutdown evidence. No model task or external channel is exercised.+After assembly, the workflow transfers all five manifest-bound wheels by immutable artifact ID; each matching native runner installs its wheel and binary dependencies into a separate venv without Bun/Node/Git on the install PATH. Isolated Python checks version/commit/import identity, all Vite-manifest assets including lazy chunks through the installed handler, and bundled TUI `--desktop-protocol` with downloads disabled and empty private HOME. With `--gateway`, it starts a private foreground CLI gateway with no provider/MCP configuration, disabled heartbeat and two loopback ports, then checks readiness, protected version identity, HTML and process/listener cleanup. Unix shutdown must be graceful; Windows termination is labelled, not graceful-shutdown evidence. No model task or external channel is exercised.On another supported platform, check a disposable native installation without changing its package:diff --git a/tests/scripts/test_ci_workflows.py b/tests/scripts/test_ci_workflows.pyindex 1d54783d8..f47c79594 100644--- a/tests/scripts/test_ci_workflows.py+++ b/tests/scripts/test_ci_workflows.py@@ -1,8 +1,8 @@"""Producer/consumer artifact wiring must survive failed-jobs-only retries."""+import jsonfrom pathlib import Path-import pytestimport yamlWORKFLOWS = Path(__file__).resolve().parents[2] / ".github/workflows"@@ -12,10 +12,10 @@ def workflow(name):return yaml.load((WORKFLOWS / name).read_text(encoding="utf-8"), Loader=yaml.BaseLoader)[email protected]("platform,step", [("linux", "linux_input"), ("windows", "windows_input")])-def test_native_consumers_receive_immutable_producer_ids(platform, step):+def test_native_consumers_receive_immutable_producer_ids():jobs = workflow("release-candidate.yml")["jobs"]- key = f"{platform}_artifact_id"+ key = "candidate_artifact_id"+ step = "native_input"producer = jobs["candidate"]assert producer["outputs"][key] == "${{ steps." + step + ".outputs.artifact-id }}"upload = next(item for item in producer["steps"] if item.get("id") == step)@@ -28,6 +28,22 @@ def test_native_consumers_receive_immutable_producer_ids(platform, step):assert download["with"]["merge-multiple"] == "true"+def test_candidate_executes_all_five_native_wheels_without_expanding_pr_matrix():+ native = workflow("native-acceptance.yml")+ assert native["jobs"]["native"]["strategy"]["matrix"]["include"] == "${{ fromJSON(inputs.platforms) }}"+ defaults = json.loads(native["on"]["workflow_call"]["inputs"]["platforms"]["default"])+ assert {item["target"] for item in defaults} == {"linux-x64", "win32-x64"}+ candidate = workflow("release-candidate.yml")["jobs"]["native"]["with"]+ assert candidate["candidate"] == "true"+ assert {(item["os"], item["target"], item["wheel_tag"]) for item in json.loads(candidate["platforms"])} == {+ ("ubuntu-latest", "linux-x64", "manylinux_2_17_x86_64"),+ ("ubuntu-24.04-arm", "linux-arm64", "manylinux_2_17_aarch64"),+ ("windows-latest", "win32-x64", "win_amd64"),+ ("macos-15", "darwin-arm64", "macosx_13_0_arm64"),+ ("macos-15-intel", "darwin-x64", "macosx_13_0_x86_64"),+ }++def test_accepted_handoff_uses_the_producer_id_and_requires_native_success():jobs = workflow("release-candidate.yml")["jobs"]assert jobs["candidate"]["outputs"]["prepared_artifact_id"] == "${{ steps.prepared.outputs.artifact-id }}"