chore(research): add agent platform research corpus and decision record

[yordis]

• Freezes the industry research and design discussion that grounds the platform's agent-architecture decisions, so the evidence and reasoning behind those choices stay reproducible and auditable over time.
• Keeps the ADR index authoritative while preserving the raw dossiers, synthesis, and Q&A that fed into it, giving future contributors the "why" without re-running the study.

[cursor]

PR Summary

Low Risk
Documentation-only addition with no runtime, auth, or deployment impact; main risk is maintainability if links or ADR references drift over time.

Overview
Adds docs/research/agent-platform/ as a frozen, auditable research corpus for agent-platform architecture: a reusable RESEARCH_PROMPT (method + per-product output skeleton), an index that links 17 product dossiers, a cross-product synthesis, and a long decision-record (Q1–Q26) that turns the study into directional Agent Service design choices.

The dossiers document how each vendor defines “agent” (nouns, subagents, config, binding time, lifecycle) from primary sources; the decision record captures registry/evolution, charter vs learned layer, hybrid file/record config, runtime vs model, grants/tools/delegation, rubrics/evaluation aside, hierarchy/parent, and related event-model direction. Accepted ADRs stay authoritative where they diverge from this record.

No application or service code changes—documentation and design rationale only.

^{Reviewed by Cursor Bugbot for commit ea2e4c2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Walkthrough

This PR adds a research methodology, an indexed corpus of agent-platform dossiers, a cross-product synthesis, and a frozen decision record defining an agent registry and evolution-service architecture.

Changes

Agent platform research corpus

Layer / File(s)	Summary
Research method and corpus index docs/research/agent-platform/RESEARCH_PROMPT.md, docs/research/agent-platform/index.md	Defines evidence-based research questions, collection requirements, output structure, and corpus navigation.
Cross-product synthesis docs/research/agent-platform/synthesis.md	Summarizes common agent properties, platform divergences, and derived design decisions.
Revision and execution foundation docs/research/agent-platform/decision-record.md	Defines immutable revisions, session pinning, runtime identity, authored content, tools, and skills.
Delegation, governance, and topology decisions docs/research/agent-platform/decision-record.md	Defines delegation, evaluation, prompt assembly, provenance, authorization, hierarchy, change classes, and stream responsibilities.
Product research dossiers docs/research/agent-platform/products/*	Adds research dossiers covering agent definitions, delegation, configuration, binding, relationships, lifecycle, persistence, inferences, and open questions across the surveyed platforms.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

• TrogonStack/trogonai#481: Covers related registry, evolution, proposal, and immutable revision semantics.

Poem

A rabbit reads dossiers by moonlight bright,
Comparing agents through the quiet night.
Revisions freeze, proposals hop,
Evidence guides each future stop.
“Thump!” says the bunny, “the corpus is neat!”

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: adding an agent platform research corpus and decision record.
Description check	✅ Passed	The description is directly related to freezing the research corpus and preserving the ADR index and rationale.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch yordis/barcelona-v1

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 19

🧹 Nitpick comments (9)

docs/research/agent-platform/decision-record.md (4)

99-105: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Specify the fenced-block language.

Add a language identifier such as text to this fence so Markdown linting and renderers can process it consistently.

🤖 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/decision-record.md` around lines 99 - 105,
Update the fenced code block containing the agents/code-reviewer directory tree
in the decision record to include an explicit text language identifier,
preserving the existing block contents.

Source: Linters/SAST tools

---

1020-1025: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Clarify the aauth term.

If aauth is an intentional subsystem name, format and define it; otherwise replace it with the intended authentication term. As written, it reads as an undefined or misspelled identifier in a governance rule.

🤖 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/decision-record.md` around lines 1020 - 1025,
Clarify the authentication reference in the paragraph about principal identity
and kind: if “aauth” is the intentional subsystem name, format it consistently
and define it on first use; otherwise replace it with the correct authentication
term. Keep the governance rule and the ADR#0017 reference unchanged.

Source: Linters/SAST tools

---

626-632: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Use an unambiguous hierarchy selector.

scope was explicitly retired as a placement model in Q10/Q22, but EvaluationBinding reintroduces an undefined scope selector. Define this as a hierarchy/subtree selector over opaque IDs—or rename it—so implementations do not recreate the superseded scope field inconsistently.

🤖 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/decision-record.md` around lines 626 - 632,
Clarify the EvaluationBinding selector by replacing the undefined “scope” option
with an explicitly named hierarchy/subtree selector over opaque IDs, or define
“scope” with that exact hierarchy semantics. Update the selector description
consistently so implementations do not recreate the retired placement-model
field.

---

901-905: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Link frozen decisions to canonical ADR records.

These sections cite GitHub pull-request URLs as the provenance for finalized ADRs. For reproducibility, link the canonical merged ADR/index entry and retain the immutable ADR identifier; PR URLs should be secondary references.

Also applies to: 988-995

🤖 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/decision-record.md` around lines 901 - 905,
Update the finalized ADR references in the “Q22 addendum” section and the
corresponding section around the additional cited lines to link the canonical
merged ADR/index entry and retain its immutable ADR identifier. Keep the
existing GitHub pull-request URL only as a secondary provenance reference, not
the primary decision link.

docs/research/agent-platform/products/aws-agentcore-harness.md (1)

283-287: 🔒 Security & Privacy | 🔵 Trivial

Make the root-shell bypass an explicit security boundary.

InvokeAgentRuntimeCommand runs commands as root, bypasses allowedTools, and accepts unsanitized input. State the required IAM/authorizer restrictions and that this operation must not be exposed to untrusted callers.

🤖 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/aws-agentcore-harness.md` around lines
283 - 287, Update the documentation for InvokeAgentRuntimeCommand to explicitly
identify it as a security boundary: require strict IAM permissions and
authorizer controls, and state that it must never be exposed to untrusted
callers. Preserve the existing description of root execution and allowedTools
bypass while adding the unsanitized-input restriction.

docs/research/agent-platform/products/devin.md (1)

80-93: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use source-bounded language for comparative claims.

“Industry’s loudest” is not measurable from the cited evidence, and “retraction” overstates the relationship between the two posts. Prefer “published critique” and “follow-up qualification,” or provide explicit comparative evidence.

🤖 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/devin.md` around lines 80 - 93, Revise
the Cognition comparison in the cited bullet to replace the unsupported
“industry's loudest subagent skeptic” claim with source-bounded wording such as
“published critique,” and describe the second post as a “follow-up
qualification” rather than a retraction. Preserve the cited principles and the
documented constraints on multi-agent patterns.

docs/research/agent-platform/products/cloudflare-agents.md (1)

136-141: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Scope the “no session noun” claim to the pinned SDK snapshot.

Cloudflare’s current official documentation exposes an experimental Session/SessionManager API. (developers.cloudflare.com) Verify whether it post-dates the pinned 0.17.4 commit; if so, replace “undefined by design” with “not present in the pinned snapshot” and record that exclusion.

🤖 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 136
- 141, Verify whether Cloudflare’s Session/SessionManager API was introduced
after the pinned SDK commit 0.17.4; if it post-dates that snapshot, revise the
“session is undefined by design” wording in the affected documentation to state
that sessions are not present in the pinned snapshot and record the exclusion.
Preserve the surrounding explanation of instance naming and routing.

docs/research/agent-platform/products/hermes-agent.md (2)

72-79: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick win

Clarify terminal-session versus container isolation.

“Own terminal sessions” can be read as full filesystem/process isolation, while the later text says siblings share the parent container. State explicitly which boundaries are separate: conversation context, working directory, filesystem, process namespace, and credentials.

Also applies to: 155-160

🤖 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` around lines 72 - 79,
Clarify the delegation description around delegate_task to distinguish
terminal-session separation from container isolation. Explicitly state the
isolation boundaries for conversation context, working directory, filesystem,
process namespace, and credentials, including that sibling agents share the
parent container where applicable; apply the same clarification to the
corresponding text at the additional referenced section.

---

91-101: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Separate persisted child records from live background work.

Clarify that background delegation may outlive the current turn, while its persisted session row/transcript does not make execution survive a process restart. This distinction is important for lifecycle and recovery semantics.

🤖 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` around lines 91 - 101,
Clarify the “Lifetime coupling” documentation for background delegation to
distinguish the live process-local child work from its persisted session
row/transcript: background execution may outlive the current turn but does not
survive a process restart merely because its session is persisted. Preserve the
existing guidance to use cronjob or terminal(background=True,
notify_on_complete=True) for restart-surviving work.

🤖 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/decision-record.md`:
- Line 814: Correct the grammar in the grant flow text near “GrantRequested +
escalation” by changing “the steward's grant needs become” to “the steward's
grant needs to become,” without altering the surrounding meaning.
- Around line 203-219: Update the verification identity and related
auto-activation/comparison rules in the decision record to include the resolved
model and its model source/config alongside runtime. Ensure session-level model
overrides are treated as separately verified only when that resolved combination
has verification results, or are excluded from verification-dependent decisions
when unverified.
- Around line 964-980: Define server-side precedence for changeClass so charter
dominates learned-layer whenever a proposal includes both classifications,
including mixed prompt and model or tools.required changes. Ensure every changed
field is classified, reject unknown or unclassified fields, and allow automatic
activation only when the complete typed diff is exclusively learned-layer.
- Around line 358-367: Update the pending-grants and GrantChanged flow
description to define the durable work-item/idempotency key that identifies each
pending grant request. State that delegation, event-driven retries, and
deduplication reuse this key, and that the work item remains resumable until the
grant is resolved so retries cannot create duplicate or orphaned work.

In `@docs/research/agent-platform/products/adk-a2a.md`:
- Around line 5-32: Make each version-sensitive evidence record auditable by
adding per-claim section or symbol anchors, immutable archive or snapshot URLs,
retrieval dates, and content digests, or explicitly marking unavailable
metadata. Update docs/research/agent-platform/products/adk-a2a.md (lines 5-32)
for ADK/A2A/Vertex claims;
docs/research/agent-platform/products/aws-agentcore-harness.md (lines 8-48) for
mutable AWS and secondary sources;
docs/research/agent-platform/products/bedrock-agentcore.md (lines 5-47) while
preserving operation enumeration and SDK/API evidence;
docs/research/agent-platform/products/claude-code-agent-sdk.md (lines 5-29) with
exact sections and pinned source metadata; and
docs/research/agent-platform/products/claude-managed-agents.md (lines 5-31) with
the beta API snapshot and exact skill-reference locations.
- Around line 130-138: Mark the “determinism belongs in tools, runtimes, or
external workflows, never in the agent noun” statement as an inference rather
than direct evidence. Move the design rule and related interpretation to the
document’s inference section, and add a link to the relevant ADR decision while
preserving the factual API migration evidence.

In `@docs/research/agent-platform/products/bedrock-agentcore.md`:
- Around line 279-285: Update the isolation guarantee heading and wording in the
AgentCore Tools documentation to scope it to execution sessions rather than the
entire platform. Explicitly identify Runtime, Browser, and Code Interpreter as
the covered surfaces, and avoid implying that Gateway, Memory, Registry, or
other control-plane resources receive the same guarantee.

In `@docs/research/agent-platform/products/claude-code-agent-sdk.md`:
- Around line 53-59: Clarify the persistence model across the agent-platform
documentation sections describing subagent identity, memory, transcripts, and
resumability. Distinguish the ephemeral invocation and instance identity from
durable `memory` scopes, JSONL transcript retention, and whether an invocation
can be resumed; explicitly state what survives process, session, and subagent
boundaries, resolving the later blanket claim that nothing persists except the
final message.

In `@docs/research/agent-platform/products/cloudflare-agents.md`:
- Around line 178-187: Revise the inference around the Cloudflare agent
description to preserve the definition/instance distinction: identify the
deployed class code as the deploy-time definition, while stating that Cloudflare
lacks a user-facing persisted definition or version record and combines
identity, mutable state, and intermittent process within each Durable Object
instance. Replace the absolute claims that no split exists and everything binds
at runtime, while retaining the conclusion about limited fleet governance.

In `@docs/research/agent-platform/products/crewai.md`:
- Around line 156-164: Update the lifecycle bullet in the CrewAI dossier to
avoid claiming agents have no lifecycle. Describe agent objects as ephemeral per
kickoff while stating that memory, knowledge, and flow state persist
independently; retain the existing executor and persistence details.

In `@docs/research/agent-platform/products/devin.md`:
- Around line 5-7: Make each dossier reproducible from immutable evidence: in
docs/research/agent-platform/products/devin.md lines 5-7, archive the cited
mutable documentation extracts or record content hashes with retrieval metadata;
in docs/research/agent-platform/products/jido.md lines 5-6, add the exact
repository commit, retrieval date, and line-level anchors for Jido and jido_ai.

In `@docs/research/agent-platform/products/kagent.md`:
- Around line 251-254: Revise the database/source-of-truth statement in the CRD
discussion to scope caching specifically to agent configuration: state that the
DB caches agent configuration for the HTTP API and UI, while remaining
authoritative for persisted execution state such as sessions, tasks, events, and
memory. Keep the CRDs as the source of truth for agent configuration.
- Around line 9-17: Complete provenance records for every cited excerpt: in
docs/research/agent-platform/products/kagent.md lines 9-17, add an archival URL
and digest for unversioned kagent.dev pages; in
docs/research/agent-platform/products/langgraph-platform.md lines 1-7, add
retrieval dates and stable documentation/source revision metadata; in
docs/research/agent-platform/products/netclaw.md lines 5-8, replace the mutable
dev reference with a commit or tag and record retrieval dates; in
docs/research/agent-platform/products/openai-agents-sdk.md lines 3-7, attach
direct URLs, sections, revisions, and retrieval dates to SDK/API claims; and in
docs/research/agent-platform/products/openclaw.md lines 5-9, source or remove
volatile ecosystem claims and record the repository revision.

In `@docs/research/agent-platform/products/openai-agents-sdk.md`:
- Around line 89-95: Clarify the binding distinction in the OpenAI Agents SDK
documentation: state that the agent object and its runtime behavior bind in
code, while prompt configuration binds through the server-managed, versioned
Prompt resource. Update the “Everything binds…” wording near agent versioning
without changing the surrounding versioning details.

In `@docs/research/agent-platform/products/opencomputer.md`:
- Around line 92-96: Update the session documentation around CreateSessionParams
and agentSnapshot to state that each session freezes its resolved configuration
at creation time. Clarify that agentSnapshot contains the selected model,
revision, and configuration after applying explicit session overrides, rather
than implying it always uses the agent’s active revision or model.
- Around line 3-6: Freeze the evidence references in both research dossiers: in
docs/research/agent-platform/products/opencomputer.md lines 3-6, add exact
documentation URLs, retrieval dates, and repository commit SHAs or release tags;
in docs/research/agent-platform/products/vercel.md lines 3-8, add exact
documentation URLs, retrieval dates, and package or repository versions/commit
SHAs.

In `@docs/research/agent-platform/RESEARCH_PROMPT.md`:
- Around line 85-89: Update the research output skeleton in the quote sections
to define a standard per-quote citation/evidence block, or an explicit linked
evidence-record section, containing the direct URL, document section or
repository symbol, source version or commit, retrieval date, archive or snapshot
URL when available, and content digest when available. Ensure every exact quote
is linked to its own auditable evidence record rather than relying only on
aggregate source_urls and retrieved fields.

In `@docs/research/agent-platform/synthesis.md`:
- Around line 206-217: The working definition in the opening synthesis must
distinguish revision-owned declarations from resource-owned resolved state.
Update the paragraph around the quoted agent definition to keep persona,
capability, behavior, and dependency declarations in the revision, while
describing limits, credential bindings, work contracts, resolved session
context, and observations as owned or resolved by their respective resources;
avoid presenting limits and credentials as direct agent-declaration fields.
- Around line 25-28: Qualify the universal claim in “Every platform decomposes
into the same trio” to exclude platforms such as Cloudflare that fuse identity,
state, and process. Present definition, execution, and memory as a
resource-oriented-platform pattern or proposed abstraction rather than an
industry-wide invariant, and update the corresponding convergence statement in
the divergence section.

---

Nitpick comments:
In `@docs/research/agent-platform/decision-record.md`:
- Around line 99-105: Update the fenced code block containing the
agents/code-reviewer directory tree in the decision record to include an
explicit text language identifier, preserving the existing block contents.
- Around line 1020-1025: Clarify the authentication reference in the paragraph
about principal identity and kind: if “aauth” is the intentional subsystem name,
format it consistently and define it on first use; otherwise replace it with the
correct authentication term. Keep the governance rule and the ADR#0017 reference
unchanged.
- Around line 626-632: Clarify the EvaluationBinding selector by replacing the
undefined “scope” option with an explicitly named hierarchy/subtree selector
over opaque IDs, or define “scope” with that exact hierarchy semantics. Update
the selector description consistently so implementations do not recreate the
retired placement-model field.
- Around line 901-905: Update the finalized ADR references in the “Q22 addendum”
section and the corresponding section around the additional cited lines to link
the canonical merged ADR/index entry and retain its immutable ADR identifier.
Keep the existing GitHub pull-request URL only as a secondary provenance
reference, not the primary decision link.

In `@docs/research/agent-platform/products/aws-agentcore-harness.md`:
- Around line 283-287: Update the documentation for InvokeAgentRuntimeCommand to
explicitly identify it as a security boundary: require strict IAM permissions
and authorizer controls, and state that it must never be exposed to untrusted
callers. Preserve the existing description of root execution and allowedTools
bypass while adding the unsanitized-input restriction.

In `@docs/research/agent-platform/products/cloudflare-agents.md`:
- Around line 136-141: Verify whether Cloudflare’s Session/SessionManager API
was introduced after the pinned SDK commit 0.17.4; if it post-dates that
snapshot, revise the “session is undefined by design” wording in the affected
documentation to state that sessions are not present in the pinned snapshot and
record the exclusion. Preserve the surrounding explanation of instance naming
and routing.

In `@docs/research/agent-platform/products/devin.md`:
- Around line 80-93: Revise the Cognition comparison in the cited bullet to
replace the unsupported “industry's loudest subagent skeptic” claim with
source-bounded wording such as “published critique,” and describe the second
post as a “follow-up qualification” rather than a retraction. Preserve the cited
principles and the documented constraints on multi-agent patterns.

In `@docs/research/agent-platform/products/hermes-agent.md`:
- Around line 72-79: Clarify the delegation description around delegate_task to
distinguish terminal-session separation from container isolation. Explicitly
state the isolation boundaries for conversation context, working directory,
filesystem, process namespace, and credentials, including that sibling agents
share the parent container where applicable; apply the same clarification to the
corresponding text at the additional referenced section.
- Around line 91-101: Clarify the “Lifetime coupling” documentation for
background delegation to distinguish the live process-local child work from its
persisted session row/transcript: background execution may outlive the current
turn but does not survive a process restart merely because its session is
persisted. Preserve the existing guidance to use cronjob or
terminal(background=True, notify_on_complete=True) for restart-surviving work.

🪄 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: c69be87c-1c74-49d4-a038-b102ac84046d

📥 Commits

Reviewing files that changed from the base of the PR and between b68d7a2 and ea2e4c2.

📒 Files selected for processing (21)

• docs/research/agent-platform/RESEARCH_PROMPT.md
• docs/research/agent-platform/decision-record.md
• docs/research/agent-platform/index.md
• docs/research/agent-platform/products/adk-a2a.md
• docs/research/agent-platform/products/aws-agentcore-harness.md
• docs/research/agent-platform/products/bedrock-agentcore.md
• docs/research/agent-platform/products/claude-code-agent-sdk.md
• docs/research/agent-platform/products/claude-managed-agents.md
• docs/research/agent-platform/products/cloudflare-agents.md
• docs/research/agent-platform/products/crewai.md
• docs/research/agent-platform/products/devin.md
• docs/research/agent-platform/products/hermes-agent.md
• docs/research/agent-platform/products/jido.md
• docs/research/agent-platform/products/kagent.md
• docs/research/agent-platform/products/langgraph-platform.md
• docs/research/agent-platform/products/netclaw.md
• docs/research/agent-platform/products/openai-agents-sdk.md
• docs/research/agent-platform/products/openclaw.md
• docs/research/agent-platform/products/opencomputer.md
• docs/research/agent-platform/products/vercel.md
• docs/research/agent-platform/synthesis.md

[coderabbitai]

🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Include the resolved model in verification identity.

Line 207 says verification is scoped only to runtime, but Lines 215–219 allow a session to override model without creating a revision. The same revision can therefore run on an unverified model, invalidating auto-activation and cross-session comparisons. Key verification and metric identity by at least (runtime, resolved model, model source/config), or exclude unverified model overrides from these decisions.

🤖 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/decision-record.md` around lines 203 - 219,
Update the verification identity and related auto-activation/comparison rules in
the decision record to include the resolved model and its model source/config
alongside runtime. Ensure session-level model overrides are treated as
separately verified only when that resolved combination has verification
results, or are excluded from verification-dependent decisions when unverified.

[coderabbitai]

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Show relevant section with line numbers
sed -n '320,410p' docs/research/agent-platform/decision-record.md | cat -n

# Search for related terms in the decision record
rg -n --no-heading -S 'pending-grants|escalationId|GrantChanged|idempot|work item|retry|resume|correlation|blocked session|StartSession' docs/research/agent-platform/decision-record.md

Repository: TrogonStack/trogonai

Length of output: 6989

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Read the other referenced sections with line numbers
sed -n '520,610p' docs/research/agent-platform/decision-record.md | cat -n
printf '\n----\n'
sed -n '790,830p' docs/research/agent-platform/decision-record.md | cat -n
printf '\n----\n'
sed -n '970,995p' docs/research/agent-platform/decision-record.md | cat -n

Repository: TrogonStack/trogonai

Length of output: 9816

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Search the whole document for the correlation and retry-related terms
rg -n --no-heading -S 'work item|work-item|idempotency key|idempotent|delegationId|parent ref|child session ids|GrantChanged|retry|resume|pending-grants|escalationId|session id|correlation' docs/research/agent-platform/decision-record.md

Repository: TrogonStack/trogonai

Length of output: 1355

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

sed -n '620,645p' docs/research/agent-platform/decision-record.md | cat -n
printf '\n----\n'
sed -n '1070,1095p' docs/research/agent-platform/decision-record.md | cat -n

Repository: TrogonStack/trogonai

Length of output: 2380

---

Define the durable work-item key for pending grants. pending-grants and GrantChanged cover the wait/retry flow, but the record still never says which durable work-item/idempotency key binds those retries to one pending request. Spell out the resume/dedupe contract so the same pending work can’t be duplicated or orphaned.

🤖 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/decision-record.md` around lines 358 - 367,
Update the pending-grants and GrantChanged flow description to define the
durable work-item/idempotency key that identifies each pending grant request.
State that delegation, event-driven retries, and deduplication reuse this key,
and that the work item remains resumable until the grant is resolved so retries
cannot create duplicate or orphaned work.

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Fix the grammar in the grant flow.

Change “the steward's grant needs become” to “the steward's grant needs to become.”

🧰 Tools

🪛 LanguageTool

[style] ~814-~814: The double modal “needs become” is nonstandard (only accepted in certain dialects). Consider “to be become”.
Context: ...k-to-back; the steward's grant needs become GrantRequested + escalation. 3. **Templ...

(NEEDS_FIXED)

🤖 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/decision-record.md` at line 814, Correct the
grammar in the grant flow text near “GrantRequested + escalation” by changing
“the steward's grant needs become” to “the steward's grant needs to become,”
without altering the surrounding meaning.

Source: Linters/SAST tools

[coderabbitai]

🔒 Security & Privacy | 🟠 Major | 🏗️ Heavy lift

Make mixed change classification fail closed.

The document says changeClass is derived from a typed diff but does not define precedence when one proposal changes both learned and charter fields. A prompt plus model or tools.required change must never be classified as learned and auto-activated. Derive the class server-side, make the strongest class dominate, and reject unknown or unclassified fields.

🤖 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/decision-record.md` around lines 964 - 980,
Define server-side precedence for changeClass so charter dominates learned-layer
whenever a proposal includes both classifications, including mixed prompt and
model or tools.required changes. Ensure every changed field is classified,
reject unknown or unclassified fields, and allow automatic activation only when
the complete typed diff is exclusively learned-layer.

[coderabbitai]

🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Make the corpus evidence records auditable.

The dossiers record URLs and retrieval dates, but do not consistently provide the per-quote section/symbol anchors, archive/snapshot URLs, or content digests required by RESEARCH_PROMPT.md. Add checked-in evidence metadata for each version-sensitive claim, or explicitly record which requested metadata was unavailable.

• docs/research/agent-platform/products/adk-a2a.md#L5-L32: add per-claim anchors and archival metadata for ADK/A2A/Vertex sources.
• docs/research/agent-platform/products/aws-agentcore-harness.md#L8-L48: add immutable evidence for mutable AWS documentation and secondary-source quotations.
• docs/research/agent-platform/products/bedrock-agentcore.md#L5-L47: preserve the operation enumeration and SDK/API evidence snapshot.
• docs/research/agent-platform/products/claude-code-agent-sdk.md#L5-L29: record exact documentation sections and pinned source metadata.
• docs/research/agent-platform/products/claude-managed-agents.md#L5-L31: preserve the beta API snapshot and exact skill-reference locations.

📍 Affects 5 files

• docs/research/agent-platform/products/adk-a2a.md#L5-L32 (this comment)
• docs/research/agent-platform/products/aws-agentcore-harness.md#L8-L48
• docs/research/agent-platform/products/bedrock-agentcore.md#L5-L47
• docs/research/agent-platform/products/claude-code-agent-sdk.md#L5-L29
• docs/research/agent-platform/products/claude-managed-agents.md#L5-L31

🤖 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/adk-a2a.md` around lines 5 - 32, Make
each version-sensitive evidence record auditable by adding per-claim section or
symbol anchors, immutable archive or snapshot URLs, retrieval dates, and content
digests, or explicitly marking unavailable metadata. Update
docs/research/agent-platform/products/adk-a2a.md (lines 5-32) for ADK/A2A/Vertex
claims; docs/research/agent-platform/products/aws-agentcore-harness.md (lines
8-48) for mutable AWS and secondary sources;
docs/research/agent-platform/products/bedrock-agentcore.md (lines 5-47) while
preserving operation enumeration and SDK/API evidence;
docs/research/agent-platform/products/claude-code-agent-sdk.md (lines 5-29) with
exact sections and pinned source metadata; and
docs/research/agent-platform/products/claude-managed-agents.md (lines 5-31) with
the beta API snapshot and exact skill-reference locations.

[coderabbitai]

📐 Maintainability & Code Quality | 🟠 Major | 🏗️ Heavy lift

Freeze the evidence references across both dossiers.

The corpus cites mutable documentation and source trees without immutable identifiers, so future readers cannot reliably reproduce the research snapshot.

• docs/research/agent-platform/products/opencomputer.md#L3-L6: add exact documentation URLs, retrieval dates, and repository commit SHAs or release tags.
• docs/research/agent-platform/products/vercel.md#L3-L8: add exact documentation URLs, retrieval dates, and package/repository versions or commit SHAs.

📍 Affects 2 files

• docs/research/agent-platform/products/opencomputer.md#L3-L6 (this comment)
• docs/research/agent-platform/products/vercel.md#L3-L8

🤖 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/opencomputer.md` around lines 3 - 6,
Freeze the evidence references in both research dossiers: in
docs/research/agent-platform/products/opencomputer.md lines 3-6, add exact
documentation URLs, retrieval dates, and repository commit SHAs or release tags;
in docs/research/agent-platform/products/vercel.md lines 3-8, add exact
documentation URLs, retrieval dates, and package or repository versions/commit
SHAs.

[coderabbitai]

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Clarify that sessions freeze the resolved configuration.

Because CreateSessionParams allows explicit model and revision overrides, a session may not use the agent’s active revision or its model. Describe agentSnapshot as containing the selected revision/configuration plus session overrides, and ensure that matches the underlying API semantics.

Also applies to: 131-135

🤖 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/opencomputer.md` around lines 92 - 96,
Update the session documentation around CreateSessionParams and agentSnapshot to
state that each session freezes its resolved configuration at creation time.
Clarify that agentSnapshot contains the selected model, revision, and
configuration after applying explicit session overrides, rather than implying it
always uses the agent’s active revision or model.

[coderabbitai]

🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Define where per-quote provenance is stored.

The method requires auditable metadata for every quote, but the output skeleton only defines aggregate source_urls and retrieved fields. Add a standard citation/evidence block to each quote section, or an explicit evidence-record section, covering URL, section/symbol, source version, retrieval date, archive URL, and digest.

Also applies to: 111-118

🤖 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/RESEARCH_PROMPT.md` around lines 85 - 89, Update
the research output skeleton in the quote sections to define a standard
per-quote citation/evidence block, or an explicit linked evidence-record
section, containing the direct URL, document section or repository symbol,
source version or commit, retrieval date, archive or snapshot URL when
available, and content digest when available. Ensure every exact quote is linked
to its own auditable evidence record rather than relying only on aggregate
source_urls and retrieved fields.

[coderabbitai]

🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

Qualify the “invariant” three-resource claim.

Cloudflare is listed as a durable agent, yet the divergence section says it fuses identity, state, and process rather than separating definition, execution, and memory. Either scope the convergence claim to resource-oriented platforms or describe the trio as the proposed abstraction, not a universal industry invariant.

Also applies to: 104-110

🤖 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 25 - 28, Qualify the
universal claim in “Every platform decomposes into the same trio” to exclude
platforms such as Cloudflare that fuse identity, state, and process. Present
definition, execution, and memory as a resource-oriented-platform pattern or
proposed abstraction rather than an industry-wide invariant, and update the
corresponding convergence statement in the divergence section.

[coderabbitai]

🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Reconcile the working definition with resource ownership.

The definition includes “limits” and “credentials” as agent-declaration fields, but the following paragraph says limits and credential bindings belong to other owning resources. Clarify which parts are revision data versus resolved/session-owned state before this becomes the basis for the platform schema.

🤖 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 206 - 217, The
working definition in the opening synthesis must distinguish revision-owned
declarations from resource-owned resolved state. Update the paragraph around the
quoted agent definition to keep persona, capability, behavior, and dependency
declarations in the revision, while describing limits, credential bindings, work
contracts, resolved session context, and observations as owned or resolved by
their respective resources; avoid presenting limits and credentials as direct
agent-declaration fields.