docs(adr): serialize agent runs and coalesce subsequent events - #6909
docs(adr): serialize agent runs and coalesce subsequent events#6909ifireball wants to merge 2 commits into
Conversation
PR Summary by QodoDocument serialized agent runs and bounded event coalescing
AI Description
Diagram
High-Level Assessment
Files changed (6)
|
|
🤖 Review · Commit: |
Site previewPreview: https://65a0e30b-site.fullsend-ai.workers.dev Commit: |
Code Review by Qodo
1. Coalescing discards event contents
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
| > **Update (2026-09):** [ADR 0098](0098-serialize-agent-runs-and-coalesce-subsequent-events.md) | ||
| > replaces automatic cancellation with serialized runs and bounded follow-up | ||
| > event coalescing. |
There was a problem hiding this comment.
1. Accepted adr edits unnamed 📘 Rule violation § Compliance
The PR edits accepted ADRs 0034 and 0063, but its description only refers generically to “related ADRs” without identifying either ADR. Each accepted ADR edit must be explicitly named and summarized in the PR description.
Agent Prompt
## Issue description
The PR description does not explicitly identify the edits to accepted ADRs 0034 and 0063.
## Issue Context
Add each ADR identifier or filename to the PR description and briefly state that it now points to ADR 0098 as replacing automatic cancellation with serialized, coalesced follow-up runs.
## Fix Focus Areas
- docs/ADRs/0034-centralized-shim-routing-via-dispatch.md[149-151]
- docs/ADRs/0063-polling-based-work-discovery.md[354-357]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
| `fullsend run` selects the newest matching event, resolves the harness and its | ||
| CEL-guarded overlays against that event, and invokes a fresh sandbox and runtime | ||
| run. Events coalesced into that follow-up do not each receive their own run. |
There was a problem hiding this comment.
2. Coalescing discards event contents 🐞 Bug ≡ Correctness
The follow-up evaluates every event but passes only the newest matching event into the run, so earlier comments and their distinct concerns never reach the agent. This contradicts the stated goal of considering accumulated concerns and silently drops actionable user input.
Agent Prompt
## Issue description
The coalescing algorithm evaluates all later events but invokes the follow-up with only the newest event. Earlier matching comments or edits are therefore absent from the agent's input rather than being considered together.
## Issue Context
The newest event may still control harness and overlay resolution, but the follow-up needs a bounded representation of every coalesced matching event so user concerns are not discarded.
## Fix Focus Areas
- docs/ADRs/0098-serialize-agent-runs-and-coalesce-subsequent-events.md[53-80]
- docs/normative/normalized-event/v1/normalized-event.schema.json[6-27]
- internal/normevent/event.go[11-19]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
| Input drivers MUST provide an operation that accepts the event that started a | ||
| run and returns later events for the same subject as `NormalizedEvent` values. |
There was a problem hiding this comment.
4. Events lack ordering cursor 🐞 Bug ≡ Correctness
The required driver operation receives only the starting NormalizedEvent, but that canonical value has no occurrence ID, timestamp, sequence, or cursor. Repeated transitions on the same subject therefore cannot be reliably classified as later or ordered newest, causing possible replay or omission.
Agent Prompt
## Issue description
The follow-up retrieval API must identify events occurring after the initial event, but its only input has no event occurrence or ordering metadata. Driver-defined ordering cannot establish the starting boundary for repeated indistinguishable transitions.
## Issue Context
Add a canonical source event identifier, sequence/timestamp, or opaque driver cursor and require drivers to use it for exclusive, monotonic retrieval. Update both the normative schema and Go representation.
## Fix Focus Areas
- docs/ADRs/0098-serialize-agent-runs-and-coalesce-subsequent-events.md[65-87]
- docs/normative/normalized-event/v1/normalized-event.schema.json[6-27]
- docs/normative/normalized-event/v1/normalized-event.schema.json[439-459]
- internal/normevent/event.go[160-176]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
e0db092 to
7f56095
Compare
ifireball
changed the title
Signed-off-by: Barak Korren <bkorren@redhat.com> Assisted-by: Codex (gpt-5.6-sol)
|
🤖 Review · Commit: |
7f56095 to
0493886
Compare
|
🤖 Finished Review · ✅ Success · Started 11:59 AM UTC · Completed 12:17 PM UTC Commit: Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $5.93 |
|
Risk Assessment: moderate (2/5) DetailsDocs/config-only PR adding a new ADR with minor cross-references; no protected paths, security-sensitive files, CI, or dependency changes. Slight elevation from medium blast radius and high churn on docs/architecture.md, but the actual change to that file is small (10 added, 1 deleted). Signals unchanged from prior assessment; score preserved at 2. Previous runRisk Assessment: moderate (2/5) DetailsDocs/config-only PR adding a new ADR with minor cross-references; no protected paths, security-sensitive files, CI, or dependency changes. Slight elevation from medium blast radius and high churn on docs/architecture.md, but the actual change to that file is trivial (9 added lines). Overall low-to-moderate risk. |
|
Looks good to me Previous runReviewFindingsMedium
Low
Next steps:
|
![fullsend-ai-review[bot]](https://avatars.githubusercontent.com/in/3478501?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Signed-off-by: Barak Korren <bkorren@redhat.com> Assisted-by: Codex (gpt-5.6-sol)
|
🤖 Finished Review · ✅ Success · Started 11:09 AM UTC · Completed 11:29 AM UTC Commit: Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $5.55 |
Superseded by updated review
fullsend-ai-review
Bot
added
the
ready-for-merge
| The execution platform MUST allow the active run to finish and coalesce later | ||
| matching events into one pending run representing the newest retained event. | ||
| GitHub Actions provides these semantics with a subject-scoped concurrency group, | ||
| `cancel-in-progress: false`, and its default single-pending queue |
There was a problem hiding this comment.
To me this is yet another perfect example of GH-AW overlap.
A thing I find very compelling about GH-AW in this respect is that what GitHub Actions providers, GH-AW automatically provides too!
This is the "input side" mirroring the discussion in #6614
We could expose e.g.
github:
concurrency: cancel-in-progress: false
BTW there's also some experimental support in GH-AW for feeding dynamic events into agent runs automatically, check e.g. https://github.github.com/gh-aw/reference/safe-outputs/#steering-issues-steer
Of course some of this is implementable via prompts; just tell the review agent (for example) to check for changes since it started (though this complicates "what it reviewed").
There was a problem hiding this comment.
ref https://github.github.com/gh-aw/reference/concurrency/#per-workflow-concurrency - the compiler seems to tune some defaults around this
| compatible groups and cancellation settings. Integrations for platforms without | ||
| equivalent semantics MUST emulate them outside the agent execution process. |
There was a problem hiding this comment.
Integrations for platforms without equivalent semantics MUST emulate them outside the agent execution process.
My instinct says that's going to get hard fast without going with my suggestion of actually always executing in e.g. Tekton (Konflux) which then becomes the baseline target...
| Each agent run MUST reconcile the subject's current state rather than assume the | ||
| triggering event describes all outstanding work. The retained event may still |
There was a problem hiding this comment.
Again, the thing I like about GH-AW is it's a very clear framework.
Each agent run MUST reconcile the subject's current state
Do we really need that for all agents? I don't think so.
Also it could mean a review agent on an active PR being discussed spends a long time looping and perhaps gets timed out and killed.
ADR 0098 (#6909) is open and under review, and it and this change were written independently against the same feedback. Saying the dispatch half here is 0098 implemented claims an alignment nobody has established. State the shared first move, that the two were not designed against each other, and that they should be reconciled where they overlap. Assisted-by: Claude Signed-off-by: Wayne Sun <gsun@redhat.com>
ADR 0098 (#6909) is open and under review, and it and this change were written independently against the same feedback. Saying the dispatch half here is 0098 implemented claims an alignment nobody has established. State the shared first move, that the two were not designed against each other, and that they should be reconciled where they overlap. Assisted-by: Claude Signed-off-by: Wayne Sun <gsun@redhat.com>
ADR 0098 (#6909) is open and under review, and it and this change were written independently against the same feedback. Saying the dispatch half here is 0098 implemented claims an alignment nobody has established. State the shared first move, that the two were not designed against each other, and that they should be reconciled where they overlap. Assisted-by: Claude Signed-off-by: Wayne Sun <gsun@redhat.com>
ADR 0098 (#6909) is open and under review, and it and this change were written independently against the same feedback. Saying the dispatch half here is 0098 implemented claims an alignment nobody has established. State the shared first move, that the two were not designed against each other, and that they should be reconciled where they overlap. Assisted-by: Claude Signed-off-by: Wayne Sun <gsun@redhat.com>
3 participants
Summary
fullsend dispatch;fullsend runexecutes one run and does not poll or schedule follow-ups.cancel-in-progress: false, plus the need for equivalent semantics on other execution platforms.Accepted ADR annotations
cancel-in-progressdiscussions as replaced by ADR 0098 while retaining source locks and idempotency as defense in depth.Living documentation
docs/architecture.mdwith the platform-managed coalescing and state-reconciliation model.Verification
make lint