From 5fa8757219cbf6529b2e6e14694c6fc4ffe0c51f Mon Sep 17 00:00:00 2001 From: Barak Korren Date: Wed, 27 May 2026 09:10:13 +0300 Subject: [PATCH] docs(adr): propose ADR 0041 synchronous workflow_call dispatch Replace dispatch.yml gh workflow run fan-out with workflow_call for UI traceability, and drop ADR 26 dynamic agent discovery without adding a compile-time sync substitute. Discovery may be revisited after ADR 38. Signed-off-by: Barak Korren --- ...ynchronous-workflow-call-event-dispatch.md | 134 ++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 docs/ADRs/0041-synchronous-workflow-call-event-dispatch.md diff --git a/docs/ADRs/0041-synchronous-workflow-call-event-dispatch.md b/docs/ADRs/0041-synchronous-workflow-call-event-dispatch.md new file mode 100644 index 0000000000..c83136a57a --- /dev/null +++ b/docs/ADRs/0041-synchronous-workflow-call-event-dispatch.md @@ -0,0 +1,134 @@ +--- +title: "41. Synchronous workflow_call for event-driven agent dispatch" +status: Proposed +relates_to: + - agent-infrastructure + - operational-observability +topics: + - dispatch + - workflows + - observability + - workflow-call +--- + +# 41. Synchronous workflow_call for event-driven agent dispatch + +Date: 2026-05-20 + +## Status + +Proposed + +## Context + +The per-org event path still fans out from `dispatch.yml` to stage workflows +(`code.yml`, `review.yml`, …) via `gh workflow run` and `on: workflow_dispatch` +([ADR 0026](0026-stage-based-dispatch-for-agent-workflow-decoupling.md), +[ADR 0031](0031-reusable-workflows-for-action-installed-distribution.md)). +That hop is **asynchronous**: the dispatch job exits when GitHub accepts the +API call, not when the agent finishes. GitHub Actions does not link the +dispatched run to the caller in the UI — operators see unrelated top-level runs +in `.fullsend` with no parent workflow, which makes it hard to answer “is the +agent still running?” from a PR or issue and hard to debug failures. + +Operational pain is documented across multiple issues: + +- [#504](https://github.com/fullsend-ai/fullsend/issues/504) — enrolled-repo shim + can show green before review finishes or posts PR feedback. +- [#896](https://github.com/fullsend-ai/fullsend/issues/896) — agent runs lack + structured source/destination metadata; correlation requires log parsing. +- [#1048](https://github.com/fullsend-ai/fullsend/issues/1048) — `fullsend run` + and trigger resources are not linked; revives fragile `post-run-link` ideas. +- [#863](https://github.com/fullsend-ai/fullsend/issues/863) / [#529](https://github.com/fullsend-ai/fullsend/issues/529) — + `post-run-link` was dropped during `workflow_call` shim migration; run links + no longer posted on triggers. +- [#272](https://github.com/fullsend-ai/fullsend/issues/272) — no lifecycle + indicators (emoji reactions) on trigger comments/issues/PRs. +- [#957](https://github.com/fullsend-ai/fullsend/issues/957) / [#988](https://github.com/fullsend-ai/fullsend/issues/988) — + “working on this” comments without reliable failure follow-up when dispatch + and agent runs are decoupled. +- [#837](https://github.com/fullsend-ai/fullsend/issues/837) — failed review runs + should update PR status comments. +- [#763](https://github.com/fullsend-ai/fullsend/issues/763) — post-run feedback + should come from the agent App, not GitHub Actions bot identity. +- [#872](https://github.com/fullsend-ai/fullsend/issues/872) / [#934](https://github.com/fullsend-ai/fullsend/issues/934) — + silent failures when users cannot find the right `.fullsend` run. + +Band-aids (extra comments, annotations, emoji, separate `post-run-link` jobs) +fight the async model. **Per-repo mode** already uses a synchronous +`workflow_call` chain (`reusable-dispatch.yml` → `reusable-{stage}.yml`; +[ADR 0033](0033-per-repo-installation-mode.md), PR #799). Per-org should +converge on the same property for the **event-driven** path. + +Cross-repo shim → `.fullsend` is already `workflow_call` ([ADR 0029](0029-central-token-mint-secretless-fullsend.md), +[ADR 0034](0034-centralized-shim-routing-via-dispatch.md)). This ADR targets +only **in-config-repo** dispatch from `dispatch.yml` to agent stages. + +[ADR 0026](0026-stage-based-dispatch-for-agent-workflow-decoupling.md) Option C +introduced runtime `# fullsend-stage:` scanning so org-specific agent workflows +could be wired without editing `dispatch.yml`. Static `workflow_call` jobs in +`dispatch.yml` are incompatible with that model. This ADR drops dynamic agent +discovery rather than replacing it with compile-time tooling. After agent +architecture is revised to support [ADR 0038](0038-universal-harness-access.md), +we may revisit this decision and re-evaluate whether a discovery mechanism is +needed. + +## Options + +### Option A: Keep `workflow_dispatch` + marker scan (status quo) + +Preserves dynamic `# fullsend-stage:` discovery and nesting reset +([ADR 0031](0031-reusable-workflows-for-action-installed-distribution.md)). +Does not fix UI correlation or “dispatch succeeded ≠ agent done” ([#504](https://github.com/fullsend-ai/fullsend/issues/504)). + +### Option B: Static `workflow_call` jobs in `dispatch.yml` (recommended) + +Replace the scan/`gh workflow run` loop with conditional `workflow_call` jobs +in `dispatch.yml`, aligned with `reusable-dispatch.yml` +([ADR 0033](0033-per-repo-installation-mode.md)). Each stage workflow is wired +explicitly; adding or removing an agent workflow requires editing +`dispatch.yml`. + +### Option C: Mitigations only (annotations, comments, reactions) + +Implement [#896](https://github.com/fullsend-ai/fullsend/issues/896), [#1048](https://github.com/fullsend-ai/fullsend/issues/1048), +[#272](https://github.com/fullsend-ai/fullsend/issues/272) without changing dispatch +mechanism. Reduces pain but leaves orphan runs and early-success dispatch jobs. + +## Decision + +For **event-driven** agent dispatch (webhook → shim → routing → agent), eliminate +`workflow_dispatch` and `gh workflow run` between `dispatch.yml` and stage +execution. Use **Option B**: static `workflow_call` jobs in `dispatch.yml`. + +Drop the dynamic agent discovery introduced in [ADR 0026](0026-stage-based-dispatch-for-agent-workflow-decoupling.md) +Option C — remove the runtime `# fullsend-stage:` scanner and the marker +convention. Do not add compile-time sync tooling as a substitute. + +`workflow_dispatch` remains allowed for **non-event** entry points only (e.g. +`repo-maintenance.yml`, manual prioritize, admin/CLI triggers). + +Prefer `dispatch.yml` → `reusable-*.yml@*` where possible to stay within four +`workflow_call` nesting levels. + +After agent architecture is revised to support [ADR 0038](0038-universal-harness-access.md), +re-evaluate whether a discovery mechanism is needed. + +## Consequences + +- PR/issue observers can use one Actions run to see agent completion without + hunting orphan `.fullsend` runs; mitigates [#504](https://github.com/fullsend-ai/fullsend/issues/504), + [#896](https://github.com/fullsend-ai/fullsend/issues/896), [#1048](https://github.com/fullsend-ai/fullsend/issues/1048), + and the silent-failure cluster ([#957](https://github.com/fullsend-ai/fullsend/issues/957), + [#988](https://github.com/fullsend-ai/fullsend/issues/988)); notification UX + may still need follow-up issues. +- **Supersedes** [ADR 0026](0026-stage-based-dispatch-for-agent-workflow-decoupling.md) + Option C for the event path, including dynamic `# fullsend-stage:` discovery; + centralized routing in `dispatch.yml` + ([ADR 0034](0034-centralized-shim-routing-via-dispatch.md)) remains. +- Adding or removing org-specific agent workflows requires editing + `dispatch.yml` directly; the single-file marker pattern from ADR 0026 is gone. +- Per-org and per-repo dispatch shapes converge; enrolled-repo shims may need + `needs:` / concurrency review ([#504](https://github.com/fullsend-ai/fullsend/issues/504)). +- Discovery may be revisited after [ADR 0038](0038-universal-harness-access.md) + agent architecture changes land.