cleveragents/cleveragents-core

Fork 3

Proposal: update specification — fix SSE streaming event example method name in docs/reference/a2a.md #2519

New issue

Closed

opened 2026-04-03 18:44:23 +00:00 by freemo · 7 comments

freemo commented

2026-04-03 18:44:23 +00:00

Owner

Spec Update Proposal

Triggered By

PR #1841 (merged 2026-04-03): fix(a2a): reformat SseEventFormatter output to JSON-RPC 2.0 notification structure (closes #1502)

Change: SSE Streaming Event Example Method Name

What changed in the implementation

PR #1841 fixed SseEventFormatter.format() to produce JSON-RPC 2.0 notification envelopes for SSE events. The key change is that SSE events use notification-style JSON-RPC 2.0 messages (no id field) with method names like task/statusUpdate and task/artifactUpdate — not message/stream.

The message/stream method is the request method (client → server), not the notification method used in SSE data payloads.

Actual SSE data payload format (per implementation):

{
  "jsonrpc": "2.0",
  "method": "task/statusUpdate",
  "params": {
    "taskId": "plan-001",
    "status": "working"
  }
}

Event type → JSON-RPC method mapping (from SseEventFormatter._EVENT_TYPE_TO_METHOD):

TaskStatusUpdateEvent → task/statusUpdate
TaskArtifactUpdateEvent → task/artifactUpdate

What spec section needs updating

docs/reference/a2a.md — Streaming Events > Example Streaming Event:

Current (incorrect):

{
  "jsonrpc": "2.0",
  "method": "message/stream",
  "params": {
    "id": "task_01HXR...",
    "status": { "state": "working" },
    "artifacts": [{
      "parts": [{ "text": "I'll start by extracting..." }]
    }]
  }
}

Proposed (correct):

{
  "jsonrpc": "2.0",
  "method": "task/statusUpdate",
  "params": {
    "taskId": "task_01HXR...",
    "status": { "state": "working" }
  }
}

Additionally, the section should clarify:

message/stream is the request method (client → server) that initiates streaming
SSE data payloads are JSON-RPC 2.0 notifications (no id field) with method names task/statusUpdate or task/artifactUpdate
Non-spec fields (event_id, event_type, timestamp) are carried in SSE envelope headers (event: and id: lines), not in the data payload

Note: The main docs/specification.md wire format section (line 23536–23542) already shows the correct format with "method": "task/statusUpdate" — only docs/reference/a2a.md has the stale example.

Rationale

The example in docs/reference/a2a.md uses message/stream as the method name in the SSE data payload, which is incorrect. message/stream is the client request method that initiates streaming; the actual SSE data payloads use task/statusUpdate or task/artifactUpdate as the method name. This discrepancy could confuse developers implementing A2A clients.

Scope

Section	Change Type
`docs/reference/a2a.md` — Streaming Events > Example Streaming Event	Fix method name from `message/stream` to `task/statusUpdate`; add clarifying note about request vs. notification methods

Awaiting human approval before any branch or PR is created.

Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: ca-spec-updater

## Spec Update Proposal ### Triggered By - **PR #1841** (merged 2026-04-03): `fix(a2a): reformat SseEventFormatter output to JSON-RPC 2.0 notification structure` (closes #1502) --- ## Change: SSE Streaming Event Example Method Name ### What changed in the implementation PR #1841 fixed `SseEventFormatter.format()` to produce JSON-RPC 2.0 **notification** envelopes for SSE events. The key change is that SSE events use **notification-style** JSON-RPC 2.0 messages (no `id` field) with method names like `task/statusUpdate` and `task/artifactUpdate` — **not** `message/stream`. The `message/stream` method is the **request** method (client → server), not the notification method used in SSE data payloads. **Actual SSE data payload format (per implementation):** ```json { "jsonrpc": "2.0", "method": "task/statusUpdate", "params": { "taskId": "plan-001", "status": "working" } } ``` **Event type → JSON-RPC method mapping (from `SseEventFormatter._EVENT_TYPE_TO_METHOD`):** - `TaskStatusUpdateEvent` → `task/statusUpdate` - `TaskArtifactUpdateEvent` → `task/artifactUpdate` ### What spec section needs updating **`docs/reference/a2a.md` — Streaming Events > Example Streaming Event:** **Current (incorrect):** ```json { "jsonrpc": "2.0", "method": "message/stream", "params": { "id": "task_01HXR...", "status": { "state": "working" }, "artifacts": [{ "parts": [{ "text": "I'll start by extracting..." }] }] } } ``` **Proposed (correct):** ```json { "jsonrpc": "2.0", "method": "task/statusUpdate", "params": { "taskId": "task_01HXR...", "status": { "state": "working" } } } ``` Additionally, the section should clarify: - `message/stream` is the **request** method (client → server) that initiates streaming - SSE data payloads are JSON-RPC 2.0 **notifications** (no `id` field) with method names `task/statusUpdate` or `task/artifactUpdate` - Non-spec fields (`event_id`, `event_type`, `timestamp`) are carried in SSE envelope headers (`event:` and `id:` lines), not in the data payload Note: The main `docs/specification.md` wire format section (line 23536–23542) already shows the correct format with `"method": "task/statusUpdate"` — only `docs/reference/a2a.md` has the stale example. ### Rationale The example in `docs/reference/a2a.md` uses `message/stream` as the method name in the SSE data payload, which is incorrect. `message/stream` is the client request method that initiates streaming; the actual SSE data payloads use `task/statusUpdate` or `task/artifactUpdate` as the method name. This discrepancy could confuse developers implementing A2A clients. --- ## Scope | Section | Change Type | |---------|-------------| | `docs/reference/a2a.md` — Streaming Events > Example Streaming Event | Fix method name from `message/stream` to `task/statusUpdate`; add clarifying note about request vs. notification methods | --- **Awaiting human approval before any branch or PR is created.** --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: ca-spec-updater

freemo added this to the v3.7.0 milestone

2026-04-03 18:44:33 +00:00

freemo referenced this issue

2026-04-03 18:45:22 +00:00

[CA-AUTO] Spec Updater — ca-spec-updater-1 — Session Tracker #2493

freemo commented

2026-04-03 18:49:05 +00:00

Author

Owner

approved

freemo referenced this issue from a commit

2026-04-03 18:53:16 +00:00

docs(a2a): fix SSE streaming event example method name

freemo referenced this issue from a pull request that will close it,

2026-04-03 18:53:35 +00:00

docs: update specification — fix SSE streaming event example method name #2557

freemo referenced this issue

2026-04-03 18:54:29 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.x — Session Tracker #2435

freemo referenced this issue

2026-04-03 19:00:56 +00:00

Task: Autonomous build progress report — v3.7.0 Production Push — 2026-04-03 #2436

freemo referenced this issue

2026-04-03 19:03:45 +00:00

[CA-AUTO] Spec Updater — ca-spec-updater-1 — Session Tracker #2493

freemo referenced this issue

2026-04-03 19:45:40 +00:00

Task: Autonomous build progress report — v3.7.0 Production Push — 2026-04-03 #2436

freemo referenced this issue

2026-04-03 20:39:56 +00:00

docs: update specification — fix SSE streaming event example method name #2557

freemo commented

2026-04-03 20:40:01 +00:00

Author

Owner

PR #2557 has been reviewed. Changes requested:

Broken link: The PR accidentally changes the SDK GitHub URL from a2aproject (correct, exists) to a2aprojects (404). This needs to be reverted.
Missing milestone: PR needs v3.7.0 milestone assigned.

The core SSE streaming event example fix is correct and aligns with the specification. Once the broken link is fixed, the PR can be approved and merged.

Automated by CleverAgents Bot
Supervisor: PR Review | Agent: ca-pr-self-reviewer

PR #2557 has been reviewed. **Changes requested:** 1. **Broken link**: The PR accidentally changes the SDK GitHub URL from `a2aproject` (correct, exists) to `a2aprojects` (404). This needs to be reverted. 2. **Missing milestone**: PR needs v3.7.0 milestone assigned. The core SSE streaming event example fix is correct and aligns with the specification. Once the broken link is fixed, the PR can be approved and merged. --- **Automated by CleverAgents Bot** Supervisor: PR Review | Agent: ca-pr-self-reviewer

freemo commented

2026-04-04 15:21:35 +00:00

Author

Owner

Label compliance fix applied:

Removed conflicting labels: State/Unverified, State/Verified
Kept: State/In progress (most advanced state)
Reason: Issue had 3 conflicting State/* labels simultaneously. Per CONTRIBUTING.md, only one State/* label is permitted. State/In progress is the most advanced state and was retained.

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

Label compliance fix applied: - Removed conflicting labels: `State/Unverified`, `State/Verified` - Kept: `State/In progress` (most advanced state) - Reason: Issue had 3 conflicting `State/*` labels simultaneously. Per CONTRIBUTING.md, only one `State/*` label is permitted. `State/In progress` is the most advanced state and was retained. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

freemo referenced this issue

2026-04-04 15:24:49 +00:00

[CA-GROOMER] Backlog Groomer — Session State (groomer-1) #2386

freemo commented

2026-04-04 19:09:46 +00:00

Author

Owner

Label compliance fix applied:

Added missing label: State/Unverified
Added missing label: Type/Task
Added missing label: Priority/Backlog
Reason: Issue was missing all required labels (State/, Type/, Priority/*) per CONTRIBUTING.md. Applied defaults: State/Unverified (new issues default), Type/Task (spec update proposal), Priority/Backlog (default per CONTRIBUTING.md).

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

Label compliance fix applied: - Added missing label: `State/Unverified` - Added missing label: `Type/Task` - Added missing label: `Priority/Backlog` - Reason: Issue was missing all required labels (State/*, Type/*, Priority/*) per CONTRIBUTING.md. Applied defaults: `State/Unverified` (new issues default), `Type/Task` (spec update proposal), `Priority/Backlog` (default per CONTRIBUTING.md). --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

freemo referenced this issue

2026-04-04 19:15:15 +00:00

docs: update specification — fix SSE streaming event example method name #2557

freemo commented

2026-04-04 19:15:19 +00:00

Author

Owner

PR #2557 Review Update

PR #2557 has been reviewed independently. Changes requested before it can be approved and merged:

🔴 Broken SDK link: Line 12 of docs/reference/a2a.md accidentally changes a2aproject to a2aprojects (404). Must be reverted.
⚠️ Missing milestone: PR needs v3.7.0 milestone assigned.
CI failing: lint, unit_tests, integration_tests, and e2e_tests are all failing on the PR commit.

The core SSE streaming event fix (message/stream → task/statusUpdate) is correct and aligns with docs/specification.md. Once the above issues are addressed, the PR can be approved and merged.

Automated by CleverAgents Bot
Supervisor: PR Review | Agent: ca-pr-self-reviewer

## PR #2557 Review Update PR #2557 has been reviewed independently. **Changes requested** before it can be approved and merged: 1. **🔴 Broken SDK link**: Line 12 of `docs/reference/a2a.md` accidentally changes `a2aproject` to `a2aprojects` (404). Must be reverted. 2. **⚠️ Missing milestone**: PR needs v3.7.0 milestone assigned. 3. **CI failing**: lint, unit_tests, integration_tests, and e2e_tests are all failing on the PR commit. The core SSE streaming event fix (`message/stream` → `task/statusUpdate`) is **correct** and aligns with `docs/specification.md`. Once the above issues are addressed, the PR can be approved and merged. --- **Automated by CleverAgents Bot** Supervisor: PR Review | Agent: ca-pr-self-reviewer

freemo referenced this issue

2026-04-04 19:21:49 +00:00

[CA-AUTO] Backlog Groomer — groomer-1 — Session Tracker #2771

freemo added the

MoSCoW

Could have

label

2026-04-04 20:49:54 +00:00

freemo referenced this issue

2026-04-04 20:50:23 +00:00

[CA-AUTO] Project Owner — project-owner-1 — Session Tracker #2793

freemo referenced this issue

2026-04-05 02:34:56 +00:00

docs: update specification — fix SSE streaming event example method name #2557

freemo commented

2026-04-05 02:35:11 +00:00

Author

Owner

PR #2557 has been reviewed and changes requested (third review cycle).

Blocking issue: The PR accidentally changes the SDK link from a2aproject/a2a-python to a2aprojects/a2a-python (adds an 's'), which results in a 404 broken link. This needs to be reverted.

Minor issue: PR is missing the v3.7.0 milestone (required by CONTRIBUTING.md).

The core SSE streaming event fix (message/stream → task/statusUpdate) is correct and aligns with docs/specification.md. Once the broken link is reverted and milestone assigned, the PR can be approved.

Automated by CleverAgents Bot
Supervisor: PR Review | Agent: ca-pr-self-reviewer

PR #2557 has been reviewed and **changes requested** (third review cycle). **Blocking issue:** The PR accidentally changes the SDK link from `a2aproject/a2a-python` to `a2aprojects/a2a-python` (adds an 's'), which results in a 404 broken link. This needs to be reverted. **Minor issue:** PR is missing the v3.7.0 milestone (required by CONTRIBUTING.md). The core SSE streaming event fix (`message/stream` → `task/statusUpdate`) is correct and aligns with `docs/specification.md`. Once the broken link is reverted and milestone assigned, the PR can be approved. --- **Automated by CleverAgents Bot** Supervisor: PR Review | Agent: ca-pr-self-reviewer

freemo referenced this issue

2026-04-05 07:12:04 +00:00

docs: update specification — fix SSE streaming event example method name #2557

freemo commented

2026-04-05 07:13:26 +00:00

Author

Owner

PR #2557 Review Update: Changes Requested

PR #2557 has been reviewed and changes are requested before it can be approved and merged.

Critical Issues Found

Massive undisclosed scope: The PR claims to be a docs-only fix for docs/reference/a2a.md, but the actual commit touches 112 files with 4,330 deletions including production source code, database migrations, tests, benchmarks, CI pipeline config, and agent behavior specifications. This violates CONTRIBUTING.md's atomic commit requirement.
Broken SDK link (flagged for the 4th time): Line 12 of docs/reference/a2a.md introduces a 404 link (a2aprojects should be a2aproject).
CI failures: lint, unit_tests, integration_tests, e2e_tests all failing.
Missing milestone: PR needs v3.7.0 milestone assigned.

What's Correct

The core a2a.md changes (fixing message/stream → task/statusUpdate, adding clarifying note, adding task/artifactUpdate example) are accurate and well-aligned with docs/specification.md.

Next Steps

The PR needs to be split into separate atomic PRs, the broken link fixed, milestone assigned, and CI passing before re-review.

Automated by CleverAgents Bot
Supervisor: PR Review | Agent: ca-pr-self-reviewer

## PR #2557 Review Update: Changes Requested PR #2557 has been reviewed and **changes are requested** before it can be approved and merged. ### Critical Issues Found 1. **Massive undisclosed scope**: The PR claims to be a docs-only fix for `docs/reference/a2a.md`, but the actual commit touches **112 files** with **4,330 deletions** including production source code, database migrations, tests, benchmarks, CI pipeline config, and agent behavior specifications. This violates CONTRIBUTING.md's atomic commit requirement. 2. **Broken SDK link** (flagged for the 4th time): Line 12 of `docs/reference/a2a.md` introduces a 404 link (`a2aprojects` should be `a2aproject`). 3. **CI failures**: lint, unit_tests, integration_tests, e2e_tests all failing. 4. **Missing milestone**: PR needs v3.7.0 milestone assigned. ### What's Correct The core a2a.md changes (fixing `message/stream` → `task/statusUpdate`, adding clarifying note, adding `task/artifactUpdate` example) are accurate and well-aligned with `docs/specification.md`. ### Next Steps The PR needs to be split into separate atomic PRs, the broken link fixed, milestone assigned, and CI passing before re-review. --- **Automated by CleverAgents Bot** Supervisor: PR Review | Agent: ca-pr-self-reviewer

freemo referenced this issue

2026-04-05 16:40:34 +00:00

docs: update specification — fix SSE streaming event example method name #2557