[AAASM-2336] ♻️ (release): Add notify-downstream — repository_dispatch to node-sdk + python-sdk after Release publishes

[Chisanan232]

Description

Replaces the AAASM-2328 retry-with-backoff workaround in node-sdk (and the silent 2>/dev/null swallow in python-sdk) with explicit event-driven cross-repo coordination. After agent-assembly's publish job creates the GitHub Release, this new notify-downstream job fires a repository_dispatch event to the SDK repos so their consume-the-binaries workflows only run once the binaries are actually available on the GH Release.

Dispatch targets

Repo	Dispatched?	Why
ai-agent-assembly/node-sdk	✅	release-node.yml does gh release download on aasm-*.tar.gz. Was retry-with-backoff per AAASM-2328
ai-agent-assembly/python-sdk	✅	release-python.yml does gh release download --pattern 'aasm-*' across four runners (linux x86_64, linux aarch64, macos arm64, macos x86_64). Current workaround swallows the failure with 2>/dev/null and silently ships a wheel without the bundled aasm binary on race. Adding the dispatch is more urgent here than for node-sdk.
ai-agent-assembly/go-sdk	❌	Pure-Go module, no aasm binary consumption in its release pipeline. goreleaser.yaml is a check-only workflow; Go module proxy auto-indexes from git tags. If go-sdk ever starts consuming agent-assembly binaries, add a third dispatch step.

🚨 OPERATOR PREREQUISITE

Before merging, configure secret CROSS_REPO_DISPATCH_PAT in ai-agent-assembly/agent-assembly repo settings with EITHER:

• Classic PAT: repo scope covering both ai-agent-assembly/node-sdk AND ai-agent-assembly/python-sdk
• Fine-grained PAT (preferred): Contents:Read, Metadata:Read, Actions:R/W, Dispatches permission on both node-sdk and python-sdk

Cannot be automated — needs operator to create the PAT.

Companion PRs

• node-sdk (existing): node-sdk#XX — listens for the dispatch event + removes the retry loop. Both this PR and node-sdk's must merge for node-sdk's flow to work end-to-end.
• python-sdk (follow-up): AAASM-2342 tracks switching release-python.yml's trigger from push: tags to on: repository_dispatch: { types: [agent-assembly-release-published] } and dropping the silent 2>/dev/null swallow. Until that lands, python-sdk continues firing on tag-push as today; the new dispatch is harmless on python-sdk side because release-python.yml doesn't yet listen for it.

Related

• Jira: AAASM-2336
• Supersedes: AAASM-2328 workaround
• Follow-up: AAASM-2342 — python-sdk repository_dispatch wiring

— Claude Code

[Chisanan232]

Claude Code review — AAASM-2336 (agent-assembly side)

CI state

statusCheckRollup is empty (check_count: 0) — expected. The diff is restricted to .github/workflows/release.yml, which no other workflow's paths: filter matches on master push. mergeable=MERGEABLE, mergeStateStatus=CLEAN.

The actual verification happens on the next release-tag push: the new notify-downstream job will fire repository_dispatch to node-sdk, which triggers node-sdk's release-node (per companion PR #66).

Scope vs. AC

AC	Verified	Status
release.yml has a new notify-downstream job	yes — appended at end after smoke-test job	✅
Job needs: publish (only fires after Release object publishes)	yes	✅
Job if: github.event_name == 'push' (only on tag-push, not workflow_dispatch)	yes	✅
Uses peter-evans/repository-dispatch@v3 pinned to SHA ff45666b9427631e3450c54a1bcbee4d9ff4d7c0	yes — SHA-pinned action call	✅
client-payload includes release_tag from github.ref_name	yes	✅
Permissions block: contents: read (no extra GITHUB_TOKEN scope needed; dispatch uses the secret PAT)	yes	✅
actionlint clean	yes	✅
Comment explains the cross-repo coordination + supersedes AAASM-2328	yes	✅

🚨 Operator prerequisite (called out in PR body + commit message)

Before this PR can functionally work end-to-end, the operator must configure secret CROSS_REPO_DISPATCH_PAT in ai-agent-assembly/agent-assembly repo settings with:

• Scope: repo access on ai-agent-assembly/node-sdk
• Or fine-grained: Contents:Read, Metadata:Read, Actions:R/W, Dispatches permission on node-sdk

Without this secret, the notify-downstream job will fail when it runs on the next tag-push. That's an acceptable failure mode (loud error, no silent data loss), but the operator should configure the PAT BEFORE the next release tag is pushed.

Companion PR

node-sdk#66 listens for the dispatch event + removes the AAASM-2328 retry loop. Both PRs must be in master for the new flow to work end-to-end. Merging this one first is safe — if node-sdk hasn't merged its side yet, the notify-downstream job fires the event but no listener catches it (no error, just a no-op event on node-sdk).

Verdict

Ready for human approval and merge AFTER the operator confirms the CROSS_REPO_DISPATCH_PAT secret is configured (or accepts the trade-off that the first post-merge release will have a red notify-downstream job until the secret lands).

The SHA-pinned action call (peter-evans/repository-dispatch@ff45666...) is a good supply-chain hygiene choice — won't break under tag/version changes upstream.

— Claude Code (Opus 4.7, 1M context)

[Chisanan232]

Claude Code review — AAASM-2336

CI state — green for merge

statusCheckRollup is empty (0 checks reported), mergeable: MERGEABLE, mergeStateStatus: CLEAN. This is the expected state, not broken CI.

The diff is scoped to .github/workflows/release.yml (plus an inherited smoke-test.yml commit from #839 which already landed on master). No other workflow's paths: filter matches .github/workflows/release.yml, and release.yml's own trigger is push: tags — so it never fires on a PR by design. Same "verification-report PRs fire no CI" pattern documented elsewhere in this repo.

The branch is behind master because PR #843 (AAASM-2340) merged a substantial release.yml overhaul on top, but GitHub still reports cleanly mergeable: the only field the two PRs both touch is the very end of release.yml where the new notify-downstream job lives. A rebase would tidy the diff view but isn't required to merge.

Scope vs. acceptance criteria

AC (from ticket description)	Status	Evidence
agent-assembly's release.yml has a notify-downstream job that fires after publish succeeds	✅	Commit 020ac633; notify-downstream: job has needs: publish and if: github.event_name == 'push'
node-sdk's release-node.yml listens for repository_dispatch: types: [agent-assembly-release-published]	⏳ companion	Tracked in node-sdk#66 per the ticket's comment thread
The retry-with-backoff loop from AAASM-2328 is removed	⏳ companion	Tracked in the same node-sdk#66 — out of scope for this agent-assembly PR
End-to-end verification on next release tag: dispatch fires, release-node runs without retry, total time ~10 min (vs ~10–20 min with retry)	⏳ post-merge	Cannot satisfy pre-merge by design — requires the next coordinated release tag

Operator prerequisite

CROSS_REPO_DISPATCH_PAT secret must be configured in ai-agent-assembly/agent-assembly before merge. The PR body documents the joint scope (covering BOTH node-sdk AND python-sdk — see scope extension below). The ticket comment thread already flags this.

Scope extensions during review (commit 89b9a82f)

The ticket description's design block contains a placeholder line:

# Future: also dispatch to python-sdk if it ever consumes agent-assembly binaries

Investigation during the review session confirmed: python-sdk already does. python-sdk/.github/workflows/release-python.yml calls gh release download --pattern 'aasm-*' across four runners (linux x86_64, linux aarch64, macos arm64, macos x86_64) and currently swallows the race with 2>/dev/null + a warning, silently shipping wheels without the bundled aasm binary on race. Strictly worse than node-sdk's loud retry-with-backoff.

This PR therefore:

1. Adds a second peter-evans/repository-dispatch step targeting ai-agent-assembly/python-sdk with the same event-type: agent-assembly-release-published payload.
2. Records why go-sdk is intentionally not dispatched (pure-Go module, no aasm binary consumption — goreleaser.yaml is a check-only workflow; Go module proxy auto-indexes from git tags).
3. Updates the operator-prereq section so CROSS_REPO_DISPATCH_PAT is scoped on both node-sdk AND python-sdk.

Companion follow-up for the python-sdk side is filed as AAASM-2342 (subtask of AAASM-1202 / F112), tracking the python-sdk release-python.yml changes: switch trigger from push: tags to on: repository_dispatch, and drop the silent 2>/dev/null swallow. Until that lands, python-sdk continues firing on tag-push as today — the new dispatch is harmless on python-sdk side because release-python.yml doesn't yet listen for it.

This extension goes beyond the original ticket's literal AC table but stays inside the design block's explicit anticipation. The alternative ("file python-sdk dispatch as a separate ticket against agent-assembly's release.yml later") would have left the operator to provision a wider PAT scope twice and would have left python-sdk on its silent-degradation path for one more release.

Verdict

Ready for human approval and merge once the CROSS_REPO_DISPATCH_PAT secret is in place. Three of the four ACs land in this PR or its node-sdk companion; the fourth (end-to-end timing verification) requires the next release tag to fire and is appropriately deferred. Zero workflow failures (zero checks reported by design). The scope extension to python-sdk is well-aligned with the ticket's # Future: placeholder and lifts a known silent-failure mode for python-sdk wheels.

— Claude Code (Opus 4.7, 1M context)