From 6f56e297d9e5f0ec8ecafa710301a217bb6f5d21 Mon Sep 17 00:00:00 2001
From: Chisanan232 <chi10211201@cycu.org.tw>
Date: Mon, 15 Jun 2026 08:24:56 +0800
Subject: [PATCH 1/5] =?UTF-8?q?=F0=9F=90=9B=20(readme):=20Add=20GitHub=20r?=
 =?UTF-8?q?elease=20version=20badge=20next=20to=20PyPI?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Surfaces the published GitHub Release (v0.0.1-beta.1) alongside the
existing PyPI badge (0.0.1b1) so the org profile + README reflect the
coordinated release rather than the v0.0.2a1 source-of-truth tag.

Refs AAASM-2956.
---
 README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/README.md b/README.md
index 049f1f59..ca54c83a 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,7 @@
 [![CI](https://img.shields.io/github/actions/workflow/status/ai-agent-assembly/python-sdk/ci.yaml?branch=master&logo=githubactions&logoColor=white&label=CI)](https://github.com/ai-agent-assembly/python-sdk/actions/workflows/ci.yaml)
 [![Docs](https://img.shields.io/github/actions/workflow/status/ai-agent-assembly/python-sdk/documentation.yaml?branch=master&logo=readthedocs&logoColor=white&label=docs)](https://github.com/ai-agent-assembly/python-sdk/actions/workflows/documentation.yaml)
 [![PyPI version](https://img.shields.io/pypi/v/agent-assembly?logo=pypi&logoColor=white)](https://pypi.org/project/agent-assembly/)
+[![GitHub release](https://img.shields.io/github/v/release/ai-agent-assembly/python-sdk?include_prereleases&sort=semver&label=release&logo=github)](https://github.com/ai-agent-assembly/python-sdk/releases)
 [![Python versions](https://img.shields.io/pypi/pyversions/agent-assembly?logo=python&logoColor=white)](https://pypi.org/project/agent-assembly/)
 [![Coverage](https://img.shields.io/codecov/c/github/ai-agent-assembly/python-sdk?logo=codecov&logoColor=white)](https://codecov.io/gh/ai-agent-assembly/python-sdk)
 [![Quality Gate](https://img.shields.io/sonar/quality_gate/AI-agent-assembly_python-sdk?server=https%3A%2F%2Fsonarcloud.io&logo=sonarcloud)](https://sonarcloud.io/project/overview?id=AI-agent-assembly_python-sdk)

From 0e40f722b719a75ddbbc0e0d9a8f83c5d266a9e8 Mon Sep 17 00:00:00 2001
From: Chisanan232 <chi10211201@cycu.org.tw>
Date: Mon, 15 Jun 2026 08:25:34 +0800
Subject: [PATCH 2/5] =?UTF-8?q?=E2=9C=A8=20(release):=20Add=20pep440-to-ta?=
 =?UTF-8?q?g.sh=20reverse=20version=20converter?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Inverse of tag-to-pep440.sh: maps a published PEP 440 version
(e.g. 0.0.1b1) back to its canonical SemVer release tag
(v0.0.1-beta.1) so release-python.yml can cut the SDK's own
GitHub Release at the published version.

Refs AAASM-2956.
---
 .github/scripts/pep440-to-tag.sh | 53 ++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100755 .github/scripts/pep440-to-tag.sh

diff --git a/.github/scripts/pep440-to-tag.sh b/.github/scripts/pep440-to-tag.sh
new file mode 100755
index 00000000..da21ccc0
--- /dev/null
+++ b/.github/scripts/pep440-to-tag.sh
@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+#
+# Convert a PEP 440 version string to the canonical SemVer release tag.
+# Inverse of tag-to-pep440.sh — used by release-python.yml to cut the
+# python-sdk's own GitHub Release at the published version.
+#
+# Examples:
+#   0.0.1      -> v0.0.1
+#   0.0.1a8    -> v0.0.1-alpha.8
+#   0.0.1b2    -> v0.0.1-beta.2
+#   0.0.1rc3   -> v0.0.1-rc.3
+#
+# Usage (CLI):
+#   .github/scripts/pep440-to-tag.sh 0.0.1b1
+#
+# Usage (library — preferred from CI/workflows):
+#   source .github/scripts/pep440-to-tag.sh
+#   tag="$(pep440_to_tag "0.0.1b1")"
+#
+# This is the single source of truth for the reverse conversion. The
+# release-python.yml `resolve` job sources this file so the workflow and
+# the AAASM-2956 fixture suite exercise the exact same code path.
+#
+# Owner: python-sdk release pipeline (AAASM-2956).
+
+# Conversion function. Reads the PEP 440 version from $1 and prints the
+# SemVer tag (with a leading `v`) to stdout. Returns non-zero only if the
+# input is empty. `.post`/`.dev` suffixes are not valid SemVer pre-release
+# identifiers in this scheme, so they are rejected — those are PyPI-only
+# republish forms that do not correspond to a new GitHub Release tag.
+pep440_to_tag() {
+    local version="${1-}"
+    if [[ -z "$version" ]]; then
+        echo "pep440_to_tag: missing version argument" >&2
+        return 1
+    fi
+    # Strip any leading `v` the caller may have passed by mistake.
+    local stripped="${version#v}"
+    # Expand the PEP 440 pre-release shorthand (a/b/rc) back to the
+    # hyphenated SemVer form. Anchored on the digits immediately following
+    # the marker so we never touch the base x.y.z component.
+    local tag
+    tag="$(printf '%s\n' "$stripped" | sed -E 's/a([0-9]+)$/-alpha.\1/; s/b([0-9]+)$/-beta.\1/; s/rc([0-9]+)$/-rc.\1/')"
+    printf 'v%s\n' "$tag"
+}
+
+# When executed directly (not sourced), behave as a CLI: take the version
+# as $1 and print the converted tag. When sourced, define the function
+# only and let the caller drive it.
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    set -euo pipefail
+    pep440_to_tag "${1-}"
+fi

From c210202a7d1e67d57bf433344136babe7843a525 Mon Sep 17 00:00:00 2001
From: Chisanan232 <chi10211201@cycu.org.tw>
Date: Mon, 15 Jun 2026 08:27:40 +0800
Subject: [PATCH 3/5] =?UTF-8?q?=E2=9C=85=20(release):=20Add=20fixture=20su?=
 =?UTF-8?q?ite=20for=20pep440-to-tag.sh?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Mirrors test_tag_to_pep440.sh: covers stable/alpha/beta/rc forms, the
0.0.1b1 -> v0.0.1-beta.1 backfill case, a tag<->pep440 roundtrip, and
the empty-input guard.

Refs AAASM-2956.
---
 .github/scripts/test_pep440_to_tag.sh | 101 ++++++++++++++++++++++++++
 1 file changed, 101 insertions(+)
 create mode 100755 .github/scripts/test_pep440_to_tag.sh

diff --git a/.github/scripts/test_pep440_to_tag.sh b/.github/scripts/test_pep440_to_tag.sh
new file mode 100755
index 00000000..5ebce0f2
--- /dev/null
+++ b/.github/scripts/test_pep440_to_tag.sh
@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+#
+# Unit tests for `.github/scripts/pep440-to-tag.sh`.
+#
+# Exercises the conversion function that release-python.yml's `resolve`
+# job sources to turn a published PEP 440 version back into the canonical
+# SemVer release tag the create-github-release job cuts. Because the
+# workflow sources the same file, these tests cover the actual code path
+# CI runs, not a copy of the regex.
+#
+# Run locally:
+#   bash .github/scripts/test_pep440_to_tag.sh
+#
+# Run from CI: see .github/workflows/release-python-conversion-test.yml.
+#
+# Exits 0 when every fixture passes, 1 otherwise.
+#
+# Refs AAASM-2956.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=.github/scripts/pep440-to-tag.sh
+source "${SCRIPT_DIR}/pep440-to-tag.sh"
+# shellcheck source=.github/scripts/tag-to-pep440.sh
+source "${SCRIPT_DIR}/tag-to-pep440.sh"
+
+pass=0
+fail=0
+total=0
+
+# assert_eq <label> <expected> <actual>
+assert_eq() {
+    local label="$1"
+    local expected="$2"
+    local actual="$3"
+    total=$((total + 1))
+    if [[ "$expected" == "$actual" ]]; then
+        printf 'OK    %-50s -> %s\n' "$label" "$actual"
+        pass=$((pass + 1))
+    else
+        printf 'FAIL  %-50s expected=%q actual=%q\n' "$label" "$expected" "$actual" >&2
+        fail=$((fail + 1))
+    fi
+}
+
+# check <pep440> <expected_tag>
+check() {
+    local version="$1"
+    local expected="$2"
+    local actual
+    actual="$(pep440_to_tag "$version")"
+    assert_eq "$version" "$expected" "$actual"
+}
+
+echo "== pep440_to_tag fixtures =="
+
+# Stable form (no pre-release suffix).
+check "0.0.1"        "v0.0.1"
+
+# Alpha pre-release, single + double digit.
+check "0.0.1a1"      "v0.0.1-alpha.1"
+check "0.0.1a10"     "v0.0.1-alpha.10"
+
+# Beta — the version this ticket backfills (0.0.1b1 -> v0.0.1-beta.1).
+check "0.0.1b1"      "v0.0.1-beta.1"
+check "0.0.1b2"      "v0.0.1-beta.2"
+
+# Release candidate.
+check "0.0.1rc3"     "v0.0.1-rc.3"
+
+# Multi-digit base components + large pre-release counter — guard against
+# greedy matching clobbering the minor/patch numbers.
+check "1.23.456a789" "v1.23.456-alpha.789"
+
+# A stray leading "v" the caller passed by mistake is tolerated.
+check "v0.0.1b1"     "v0.0.1-beta.1"
+
+echo "== roundtrip with tag_to_pep440 =="
+# Every canonical tag must survive a tag -> pep440 -> tag roundtrip.
+for tag in v0.0.1 v0.0.1-alpha.8 v0.0.1-beta.1 v0.0.1-rc.3 v1.23.456-alpha.789; do
+    pep="$(tag_to_pep440 "$tag")"
+    back="$(pep440_to_tag "$pep")"
+    assert_eq "roundtrip ${tag}" "$tag" "$back"
+done
+
+echo "== empty-input guard =="
+total=$((total + 1))
+if err="$(pep440_to_tag "" 2>&1 >/dev/null)"; then
+    printf 'FAIL  empty input should have exited non-zero (stderr=%q)\n' "$err" >&2
+    fail=$((fail + 1))
+else
+    printf 'OK    empty input rejected (stderr=%q)\n' "$err"
+    pass=$((pass + 1))
+fi
+
+echo
+echo "Summary: ${pass} passed, ${fail} failed, ${total} total"
+if (( fail > 0 )); then
+    exit 1
+fi

From 460167aae648146dcfdca94d7c89883e05b44758 Mon Sep 17 00:00:00 2001
From: Chisanan232 <chi10211201@cycu.org.tw>
Date: Mon, 15 Jun 2026 08:27:51 +0800
Subject: [PATCH 4/5] =?UTF-8?q?=F0=9F=94=A7=20(release):=20Cut=20python-sd?=
 =?UTF-8?q?k=20GitHub=20Release=20at=20published=20version?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

After a successful PyPI publish, resolve the canonical SemVer release
tag (repository_dispatch carries it; workflow_dispatch derives it from
pypi_version via pep440-to-tag.sh) and add a create-github-release job
that cuts the tag + GitHub Release at that version. Gated on the
real-publish path; idempotent on re-run; re-validates the tag shape
before use. Keeps the repo's release line tracking PyPI instead of
drifting onto a source-of-truth tag like v0.0.2a1.

Refs AAASM-2956.
---
 .github/workflows/release-python.yml | 84 ++++++++++++++++++++++++++--
 1 file changed, 80 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/release-python.yml b/.github/workflows/release-python.yml
index db164e42..4c62d385 100644
--- a/.github/workflows/release-python.yml
+++ b/.github/workflows/release-python.yml
@@ -51,11 +51,13 @@ jobs:
       binary_source_tag: ${{ steps.r.outputs.binary_source_tag }}
       pypi_version: ${{ steps.r.outputs.pypi_version }}
       dry_run: ${{ steps.r.outputs.dry_run }}
+      release_tag: ${{ steps.r.outputs.release_tag }}
     steps:
       # Need the working tree on disk so the resolve step can source the
-      # tag → PEP 440 conversion script (.github/scripts/tag-to-pep440.sh).
-      # That script is the single source of truth for the conversion,
-      # shared with the AAASM-2863 unit tests.
+      # tag → PEP 440 conversion script (.github/scripts/tag-to-pep440.sh)
+      # and its inverse (.github/scripts/pep440-to-tag.sh). Those scripts
+      # are the single source of truth for the conversion, shared with the
+      # AAASM-2863 / AAASM-2956 unit tests.
       - uses: actions/checkout@v6
       - id: r
         env:
@@ -124,12 +126,32 @@ jobs:
             echo "::error::pypi_version '$pypi_version' is not valid PEP 440 (use 0.0.1a8.post1 not 0.0.1-alpha.8.1)"
             exit 1
           fi
+          # Resolve the canonical SemVer release tag the create-github-release
+          # job will cut at the published version (AAASM-2956). The
+          # repository_dispatch event already carries the canonical tag, so use
+          # it verbatim. The workflow_dispatch path only has the PEP 440
+          # pypi_version, so derive the tag from it via the single-source-of-
+          # truth inverse converter. .post/.dev republish forms have no own
+          # GitHub Release tag, so leave release_tag empty for those.
+          release_tag=""
+          if [[ "$dry_run" != "true" ]]; then
+            if [[ "$EVENT_NAME" == "repository_dispatch" ]]; then
+              release_tag="$DISPATCH_PAYLOAD_TAG"
+            elif [[ "$pypi_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(a|b|rc)?[0-9]*$ ]]; then
+              # shellcheck source=.github/scripts/pep440-to-tag.sh
+              source "${GITHUB_WORKSPACE}/.github/scripts/pep440-to-tag.sh"
+              release_tag="$(pep440_to_tag "$pypi_version")"
+            else
+              echo "::notice::pypi_version '$pypi_version' is a post/dev republish — no GitHub Release tag will be cut"
+            fi
+          fi
           {
             echo "binary_source_tag=${binary_source_tag}"
             echo "pypi_version=${pypi_version}"
             echo "dry_run=${dry_run}"
+            echo "release_tag=${release_tag}"
           } >> "$GITHUB_OUTPUT"
-          echo "Resolved binary_source_tag=${binary_source_tag} pypi_version=${pypi_version} dry_run=${dry_run}"
+          echo "Resolved binary_source_tag=${binary_source_tag} pypi_version=${pypi_version} dry_run=${dry_run} release_tag=${release_tag}"
 
   build-sdist:
     name: Build sdist
@@ -415,6 +437,60 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
         # No `with: password:` — Trusted Publisher uses OIDC, no token stored.
 
+  # Cut python-sdk's own GitHub Release at the just-published version so the
+  # repo's release line tracks PyPI (and the README `github/v/release` badge
+  # resolves) instead of drifting onto a separate source-of-truth tag like
+  # v0.0.2a1. Runs only on the real-publish path, gated on `publish` so the
+  # tag is never created for a wheel that failed to upload. See AAASM-2956.
+  create-github-release:
+    name: Cut GitHub Release at published version
+    needs:
+      - resolve
+      - publish
+    runs-on: ubuntu-latest
+    # Real publish only, and only when resolve produced a SemVer tag (empty
+    # for .post/.dev republishes, which do not get their own Release).
+    if: needs.resolve.outputs.dry_run != 'true' && needs.resolve.outputs.release_tag != ''
+    permissions:
+      contents: write  # create the git tag + GitHub Release
+    steps:
+      - uses: actions/checkout@v6
+      - name: Create tag and GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # client_payload is attacker-controllable on repository_dispatch;
+          # RELEASE_TAG was validated as a SemVer tag by the resolve job and
+          # is only ever passed through env (never inlined into a run: body).
+          RELEASE_TAG: ${{ needs.resolve.outputs.release_tag }}
+          PYPI_VERSION: ${{ needs.resolve.outputs.pypi_version }}
+        run: |
+          set -euo pipefail
+          # Defence in depth: re-validate the tag shape here so a future
+          # change to resolve cannot smuggle an arbitrary string into the
+          # tag/gh commands below.
+          if [[ ! "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-(alpha|beta|rc)\.[0-9]+)?$ ]]; then
+            echo "::error::release_tag '$RELEASE_TAG' is not a valid SemVer release tag"
+            exit 1
+          fi
+          # Idempotent: skip if a Release already exists for this tag (e.g. a
+          # re-run after a partial failure), so the job never errors on retry.
+          if gh release view "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            echo "::notice::GitHub Release $RELEASE_TAG already exists — nothing to do"
+            exit 0
+          fi
+          prerelease_flag=""
+          if [[ "$RELEASE_TAG" =~ -(alpha|beta|rc)\. ]]; then
+            prerelease_flag="--prerelease"
+          fi
+          # `gh release create` creates the annotated tag at the current
+          # commit (the workflow ref) when the tag does not yet exist.
+          gh release create "$RELEASE_TAG" \
+            --repo "$GITHUB_REPOSITORY" \
+            $prerelease_flag \
+            --title "$RELEASE_TAG" \
+            --notes "python-sdk agent-assembly==${PYPI_VERSION} — coordinated with agent-assembly ${RELEASE_TAG}."
+          echo "Created GitHub Release $RELEASE_TAG (agent-assembly==${PYPI_VERSION})"
+
   # Publish the *real* release tag as a tiny artifact so the documentation
   # workflow (which is triggered by `workflow_run` after this workflow
   # completes) can label the frozen docs snapshot with the human-facing tag

From 645b1d91e6289485bb1d5e01900897890e5352b9 Mon Sep 17 00:00:00 2001
From: Chisanan232 <chi10211201@cycu.org.tw>
Date: Mon, 15 Jun 2026 08:27:59 +0800
Subject: [PATCH 5/5] =?UTF-8?q?=F0=9F=94=A7=20(ci):=20Gate=20pep440-to-tag?=
 =?UTF-8?q?=20scripts=20in=20conversion-test=20workflow?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add the new converter + its fixture suite to the trigger paths and run
both shellcheck + the new fixture suite alongside the existing
tag-to-pep440 harness.

Refs AAASM-2956.
---
 .github/workflows/release-python-conversion-test.yml | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/release-python-conversion-test.yml b/.github/workflows/release-python-conversion-test.yml
index 6aedfcd9..576fb23d 100644
--- a/.github/workflows/release-python-conversion-test.yml
+++ b/.github/workflows/release-python-conversion-test.yml
@@ -15,6 +15,8 @@ on:
     paths:
       - ".github/scripts/tag-to-pep440.sh"
       - ".github/scripts/test_tag_to_pep440.sh"
+      - ".github/scripts/pep440-to-tag.sh"
+      - ".github/scripts/test_pep440_to_tag.sh"
       - ".github/workflows/release-python.yml"
       - ".github/workflows/release-python-conversion-test.yml"
   pull_request:
@@ -23,6 +25,8 @@ on:
     paths:
       - ".github/scripts/tag-to-pep440.sh"
       - ".github/scripts/test_tag_to_pep440.sh"
+      - ".github/scripts/pep440-to-tag.sh"
+      - ".github/scripts/test_pep440_to_tag.sh"
       - ".github/workflows/release-python.yml"
       - ".github/workflows/release-python-conversion-test.yml"
 
@@ -43,5 +47,9 @@ jobs:
         run: |
           shellcheck .github/scripts/tag-to-pep440.sh
           shellcheck -x .github/scripts/test_tag_to_pep440.sh
-      - name: Run fixture suite
+          shellcheck .github/scripts/pep440-to-tag.sh
+          shellcheck -x .github/scripts/test_pep440_to_tag.sh
+      - name: Run tag → PEP 440 fixture suite
         run: bash .github/scripts/test_tag_to_pep440.sh
+      - name: Run PEP 440 → tag fixture suite
+        run: bash .github/scripts/test_pep440_to_tag.sh