chore(adr): record the agent platform stream topology decision#481
Open
yordis wants to merge 23 commits into
Open
chore(adr): record the agent platform stream topology decision#481yordis wants to merge 23 commits into
yordis wants to merge 23 commits into
Conversation
PR SummaryLow Risk Overview ADR#0024 rejects a single fused Agent stream (staging + verdict + activation) in favor of a registry stream per agent (provision, activate, rollback, archive) and a proposal stream per change-in-flight (open, verdict, withdraw). Revision numbers are minted only at activation; immutable verdicts are passed in as proven input rather than co-located for transactional coupling. Includes a placement rule, per-stream invariants, and illustrative event examples. ADR#0025 defines four logical records ( Reviewed by Cursor Bugbot for commit 66cbff5. Bugbot is set up for automated code reviews on this repo. Configure here. |
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughThe PR adds ADRs for agent stream topology and data ownership, a reusable research methodology, a cross-product agent research corpus, product dossiers, and a synthesis of resulting platform design decisions. It also updates ADR navigation and reformats two existing ADRs. ChangesAgent platform design and research
Estimated code review effort: 3 (Moderate) | ~25 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
yordis
force-pushed
the
yordis/docs-agent-stream-topology-adr
branch
from
July 13, 2026 21:23
532fe29 to
69eb62e
Compare
yordis
changed the title
enilsen16
reviewed
Jul 13, 2026
enilsen16
reviewed
Jul 13, 2026
enilsen16
reviewed
Jul 13, 2026
enilsen16
reviewed
Jul 13, 2026
This comment was marked as abuse.
This comment was marked as abuse.
Sorry, something went wrong.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (2)
docs/research/agent-platform/products/jido.md (1)
3-10: 📐 Maintainability & Code Quality | 🔵 Trivial | 🏗️ Heavy liftPin the research corpus to reproducible evidence.
The dossiers identify sources, but generally omit immutable revisions, retrieval timestamps, and direct claim-level references. That weakens the PR’s stated auditability for version-sensitive and time-sensitive conclusions.
docs/research/agent-platform/products/jido.md#L3-L10: add the Jido commit/tag, retrieval date, and direct source references.docs/research/agent-platform/products/langgraph-platform.md#L3-L6: pin the LangGraph source revision and documentation snapshot.docs/research/agent-platform/products/netclaw.md#L3-L10: add an immutable archive/reference for the omitted companion dossier, or exclude claims that depend on it.docs/research/agent-platform/products/openai-agents-sdk.md#L3-L7: record the SDK/documentation revision and retrieval date.docs/research/agent-platform/products/openclaw.md#L3-L9: pin the source revision and timestamp the popularity/history claims.docs/research/agent-platform/products/opencomputer.md#L3-L6: record revisions for each repository and direct documentation links.docs/research/agent-platform/products/vercel.md#L3-L8: pin the AI SDK/platform source snapshot and retrieval date.docs/research/agent-platform/synthesis.md (1)
10-20: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd claim-level citations to the synthesis.
docs/research/agent-platform/synthesis.md#L10-L20makes broad universal claims without tying them back to the dossier entries. Add per-claim links/quotes or soften the wording to make the synthesis’s scope explicit.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/research/agent-platform/synthesis.md` around lines 10 - 20, The synthesis’s universal definition claims need claim-level support. In docs/research/agent-platform/synthesis.md lines 10-20, add links or quoted evidence from the relevant dossier entries for each claim, or explicitly narrow the wording to the reviewed sources; in docs/research/agent-platform/RESEARCH_PROMPT.md lines 81-87, apply the corresponding citation/scope guidance requested there.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/adr/0024-agent-platform-stream-topology.md`:
- Line 91: Update the fenced code block near the “Concrete message, package, and
field names” text to include a language identifier after its opening fence,
using text or another appropriate language, while preserving the block’s
contents.
In `@docs/research/agent-platform/products/adk-a2a.md`:
- Around line 4-8: Make the research corpus independently auditable by updating
the introductory evidence sections in
docs/research/agent-platform/products/adk-a2a.md lines 4-8, bedrock-agentcore.md
lines 4-6, claude-code-agent-sdk.md lines 4-5, claude-managed-agents.md lines
4-6, cloudflare-agents.md lines 4-6, crewai.md lines 4-6, devin.md lines 4-6,
and hermes-agent.md lines 4-11. Add stable URLs or document sections, repository
commits or symbols, package/API versions, and retrieval dates for the cited
claims; date-stamp volatile release-status and star-count claims, including the
repository claims in hermes-agent.md.
In `@docs/research/agent-platform/RESEARCH_PROMPT.md`:
- Around line 81-87: Update the “Method” evidence-capture guidance in
RESEARCH_PROMPT.md to require each quoted source record to include a durable
archive or snapshot reference, or a checked-in source excerpt, in addition to
its URL and retrieval date; request a content hash where available so citations
remain auditable despite link rot.
---
Nitpick comments:
In `@docs/research/agent-platform/synthesis.md`:
- Around line 10-20: The synthesis’s universal definition claims need
claim-level support. In docs/research/agent-platform/synthesis.md lines 10-20,
add links or quoted evidence from the relevant dossier entries for each claim,
or explicitly narrow the wording to the reviewed sources; in
docs/research/agent-platform/RESEARCH_PROMPT.md lines 81-87, apply the
corresponding citation/scope guidance requested there.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 7f18fe6f-54e2-4e3d-99e3-386cd85bc035
📒 Files selected for processing (21)
docs/adr/0024-agent-platform-stream-topology.mddocs/adr/index.mddocs/research/agent-platform/RESEARCH_PROMPT.mddocs/research/agent-platform/decision-record.mddocs/research/agent-platform/index.mddocs/research/agent-platform/products/adk-a2a.mddocs/research/agent-platform/products/bedrock-agentcore.mddocs/research/agent-platform/products/claude-code-agent-sdk.mddocs/research/agent-platform/products/claude-managed-agents.mddocs/research/agent-platform/products/cloudflare-agents.mddocs/research/agent-platform/products/crewai.mddocs/research/agent-platform/products/devin.mddocs/research/agent-platform/products/hermes-agent.mddocs/research/agent-platform/products/jido.mddocs/research/agent-platform/products/langgraph-platform.mddocs/research/agent-platform/products/netclaw.mddocs/research/agent-platform/products/openai-agents-sdk.mddocs/research/agent-platform/products/openclaw.mddocs/research/agent-platform/products/opencomputer.mddocs/research/agent-platform/products/vercel.mddocs/research/agent-platform/synthesis.md
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/research/agent-platform/products/cloudflare-agents.md (1)
128-135: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winUndefined
facetconcept.
cf_agents_facet_runsis the only place “facet” appears here, so the table mapping reads incomplete. Add a short definition of what a facet is in this runtime, or drop the term if it isn’t part of the agent model.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/research/agent-platform/products/cloudflare-agents.md` around lines 128 - 135, The “facet” concept is undefined in the Relationships between nouns section. Add a brief definition describing what facets represent in the runtime before or alongside the cf_agents_facet_runs mapping, or remove cf_agents_facet_runs if facets are not part of the agent model.
🧹 Nitpick comments (1)
docs/research/agent-platform/products/hermes-agent.md (1)
12-12: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winSection heading diverges from sibling dossiers.
This dossier uses "Evidence anchors" while the other product dossiers reviewed in this cohort (
cloudflare-agents.md,kagent.md) use "Source anchors" for the equivalent section. Align the heading for consistency across the corpus.✏️ Proposed fix
-## Evidence anchors +## Source anchors🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/research/agent-platform/products/hermes-agent.md` at line 12, Rename the “Evidence anchors” section heading in the Hermes dossier to “Source anchors” to match the equivalent headings in sibling product dossiers.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@docs/research/agent-platform/products/cloudflare-agents.md`:
- Around line 128-135: The “facet” concept is undefined in the Relationships
between nouns section. Add a brief definition describing what facets represent
in the runtime before or alongside the cf_agents_facet_runs mapping, or remove
cf_agents_facet_runs if facets are not part of the agent model.
---
Nitpick comments:
In `@docs/research/agent-platform/products/hermes-agent.md`:
- Line 12: Rename the “Evidence anchors” section heading in the Hermes dossier
to “Source anchors” to match the equivalent headings in sibling product
dossiers.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: f45ea88e-06fb-4fbb-b9fa-987fc5ec7c75
📒 Files selected for processing (15)
docs/adr/0024-agent-platform-stream-topology.mddocs/research/agent-platform/RESEARCH_PROMPT.mddocs/research/agent-platform/decision-record.mddocs/research/agent-platform/index.mddocs/research/agent-platform/products/adk-a2a.mddocs/research/agent-platform/products/bedrock-agentcore.mddocs/research/agent-platform/products/claude-code-agent-sdk.mddocs/research/agent-platform/products/claude-managed-agents.mddocs/research/agent-platform/products/cloudflare-agents.mddocs/research/agent-platform/products/crewai.mddocs/research/agent-platform/products/devin.mddocs/research/agent-platform/products/hermes-agent.mddocs/research/agent-platform/products/kagent.mddocs/research/agent-platform/products/netclaw.mddocs/research/agent-platform/synthesis.md
🚧 Files skipped from review as they are similar to previous changes (11)
- docs/research/agent-platform/RESEARCH_PROMPT.md
- docs/research/agent-platform/products/netclaw.md
- docs/research/agent-platform/products/claude-code-agent-sdk.md
- docs/research/agent-platform/synthesis.md
- docs/research/agent-platform/products/bedrock-agentcore.md
- docs/research/agent-platform/products/devin.md
- docs/research/agent-platform/products/crewai.md
- docs/adr/0024-agent-platform-stream-topology.md
- docs/research/agent-platform/products/adk-a2a.md
- docs/research/agent-platform/decision-record.md
- docs/research/agent-platform/products/claude-managed-agents.md
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/adr/0025-agent-definition-data-ownership.md`:
- Around line 116-150: Update the worked example in the normative section to
match the canonical AgentRevision and Proposal shapes: represent
AgentRevision.source directly as provisioning or a proposal_id, and replace
evaluation_results entries with the separate evaluation_result_refs and
evaluation_result_digests fields. Remove the legacy
source.kind/source.proposal_id and result_ref/result_digest representations
while preserving the surrounding record structure.
- Around line 152-160: Update the canonical normative model in the ADR to
include audit identity fields for WorkContract, ToolDefinition, and Memory,
including the later-referenced content_digest, snapshot_ref, and snapshot_digest
values; alternatively define a shared referenced-record type and use it
consistently. Ensure the model clearly establishes where these fields live and
aligns with the bindings described in later sections.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 0ba20083-bd26-47e8-8e70-c39585296ed9
📒 Files selected for processing (7)
docs/adr/0023-secret-management-and-key-custody-direction.mddocs/adr/0024-agent-platform-stream-topology.mddocs/adr/0025-agent-definition-data-ownership.mddocs/adr/index.mddocs/research/agent-platform/decision-record.mddocs/research/agent-platform/index.mddocs/research/agent-platform/synthesis.md
🚧 Files skipped from review as they are similar to previous changes (5)
- docs/research/agent-platform/index.md
- docs/adr/index.md
- docs/research/agent-platform/synthesis.md
- docs/adr/0024-agent-platform-stream-topology.md
- docs/research/agent-platform/decision-record.md
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/research/agent-platform/products/aws-agentcore-harness.md`:
- Around line 249-252: The AWS-owned loop description must make history loading
conditional on memory configuration. Update the surrounding session contract to
state that the harness loads history when Memory is enabled or configured by
default, and document that callers must provide prior conversation context after
microVM expiry when Memory is disabled. Keep the existing client-message and
streaming behavior unchanged.
- Around line 95-100: Revise the “Conceptual model: agent-as-config over a
vendor-owned loop” wording to qualify that the harness orchestration loop is
configured rather than shipped as customer code, while client-owned inline
functions and tool implementations may still execute customer code and return
control to caller code. Apply the same clarification to the corresponding model
statement near the other referenced section, without implying that all
executable logic is AWS-owned.
In `@docs/research/agent-platform/products/bedrock-agentcore.md`:
- Around line 130-136: Update the package-size wording in the deployment-path
description to “container-based packages can be up to 2 GB in size,” correcting
the hyphenation, spacing, and “up to” phrasing while preserving the surrounding
limits.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: e9cc83ef-ee09-4860-a3c4-5b2acfe80694
📒 Files selected for processing (3)
docs/research/agent-platform/index.mddocs/research/agent-platform/products/aws-agentcore-harness.mddocs/research/agent-platform/products/bedrock-agentcore.md
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/research/agent-platform/index.md
yordis
force-pushed
the
yordis/docs-agent-stream-topology-adr
branch
from
July 16, 2026 02:08
3967f9e to
6156f4e
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/research/agent-platform/products/netclaw.md (1)
5-8: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd source anchors to the dossier preambles. Match the release/commit + retrieval-date pattern used elsewhere in the corpus.
docs/research/agent-platform/products/netclaw.md: replace the mutabledev/v0.24.xreference with a commit or release pin and retrieval date.docs/research/agent-platform/products/openai-agents-sdk.md: add the specific source snapshot and retrieval date to make the introductory evidence trail reproducible.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/research/agent-platform/products/netclaw.md` around lines 5 - 8, Update the preambles in docs/research/agent-platform/products/netclaw.md (lines 5-8) and docs/research/agent-platform/products/openai-agents-sdk.md (lines 5-7) to include reproducible source anchors: replace NetClaw’s mutable dev/v0.24.x reference with a specific commit or release pin and retrieval date, and add the corresponding snapshot and retrieval date for the OpenAI Agents SDK, following the release/commit-date pattern used elsewhere in the corpus.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/adr/0025-agent-definition-data-ownership.md`:
- Around line 123-135: Define a canonical identity for BehaviorBundle by adding
bundle_ref and bundle_digest to its model, or by specifying a shared
referenced-record shape that includes both fields. Ensure the canonical
representation supports AgentRevision.bundle_ref, Proposal.candidate_bundle_ref,
activation provenance, and the worked example without allowing ambiguous or
unaddressable bundles.
---
Nitpick comments:
In `@docs/research/agent-platform/products/netclaw.md`:
- Around line 5-8: Update the preambles in
docs/research/agent-platform/products/netclaw.md (lines 5-8) and
docs/research/agent-platform/products/openai-agents-sdk.md (lines 5-7) to
include reproducible source anchors: replace NetClaw’s mutable dev/v0.24.x
reference with a specific commit or release pin and retrieval date, and add the
corresponding snapshot and retrieval date for the OpenAI Agents SDK, following
the release/commit-date pattern used elsewhere in the corpus.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 6a4974cd-cc4c-43af-af74-ccd35e242441
📒 Files selected for processing (26)
docs/adr/0016-protobuf-rpc-over-nats-micro-binding.mddocs/adr/0017-aauth-agent-authentication.mddocs/adr/0024-agent-platform-stream-topology.mddocs/adr/0025-agent-definition-data-ownership.mddocs/adr/index.mddocs/research/agent-platform/RESEARCH_PROMPT.mddocs/research/agent-platform/decision-record.mddocs/research/agent-platform/index.mddocs/research/agent-platform/products/adk-a2a.mddocs/research/agent-platform/products/aws-agentcore-harness.mddocs/research/agent-platform/products/bedrock-agentcore.mddocs/research/agent-platform/products/claude-code-agent-sdk.mddocs/research/agent-platform/products/claude-managed-agents.mddocs/research/agent-platform/products/cloudflare-agents.mddocs/research/agent-platform/products/crewai.mddocs/research/agent-platform/products/devin.mddocs/research/agent-platform/products/hermes-agent.mddocs/research/agent-platform/products/jido.mddocs/research/agent-platform/products/kagent.mddocs/research/agent-platform/products/langgraph-platform.mddocs/research/agent-platform/products/netclaw.mddocs/research/agent-platform/products/openai-agents-sdk.mddocs/research/agent-platform/products/openclaw.mddocs/research/agent-platform/products/opencomputer.mddocs/research/agent-platform/products/vercel.mddocs/research/agent-platform/synthesis.md
🚧 Files skipped from review as they are similar to previous changes (13)
- docs/research/agent-platform/products/jido.md
- docs/adr/index.md
- docs/research/agent-platform/index.md
- docs/research/agent-platform/products/cloudflare-agents.md
- docs/research/agent-platform/synthesis.md
- docs/research/agent-platform/products/langgraph-platform.md
- docs/research/agent-platform/products/openclaw.md
- docs/research/agent-platform/RESEARCH_PROMPT.md
- docs/research/agent-platform/products/devin.md
- docs/research/agent-platform/products/hermes-agent.md
- docs/adr/0024-agent-platform-stream-topology.md
- docs/research/agent-platform/products/bedrock-agentcore.md
- docs/research/agent-platform/products/claude-managed-agents.md
yordis
force-pushed
the
yordis/docs-agent-stream-topology-adr
branch
from
July 16, 2026 09:10
a1fc655 to
6d1ce73
Compare
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 6d1ce73. Configure here.
Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
Labels are the selector surface, so their ownership must move with the versioned revision to keep routing, evaluation, and comparison semantics reproducible. Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
yordis
force-pushed
the
yordis/docs-agent-stream-topology-adr
branch
from
July 16, 2026 09:31
21ba0d9 to
cba994e
Compare
…eam-topology-adr # Conflicts: # docs/adr/index.md
Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
…n prose Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.