Skip to content

A2A: let callers poll tasks returned by SendMessage - #202

Open
harshsaver wants to merge 3 commits into
mainfrom
feat/189-a2a-gettask
Open

harshsaver wants to merge 3 commits into
mainfrom
feat/189-a2a-gettask

Conversation

@harshsaver

Copy link
Copy Markdown
Member

Implements GetTask on the A2A ingress handler using the existing publication authorization, A2A-Version checks, and a new principal-scoped history read (Store/Runtime A2ATaskHistory) that pairs each correlated Bus request with its agent reply.

Mapping and bounds (documented in docs/architecture/a2a-bridge.md):

  • Bus states map one-to-one onto A2A task states; status timestamp is the task update time.
  • History holds one user message per turn in acceptance order (caller's messageId), each followed by its agent reply (durable Bus response id) when present; single plain-text part each.
  • historyLength limits to the most recent N messages (0 = none, omitted = full); negative rejected. Replies surface in history only; no artifacts, no duplicate status message.

Isolation: unknown and other-principal tasks report task-not-found; revoked credentials and disabled publications stay denied via the same in-transaction fencing as acceptance.

Tests (existing harness, bus package):

  • submit → deliver → reply → poll across submitted/working/completed, plus restart durability
  • historyLength selection incl. 0/oversized/negative
  • state mapping for input-required/failed/canceled/rejected
  • foreign-task indistinguishability, rotation/disable paths, version and param errors

Streaming, task listing, cancellation, push notifications, and new content types stay out of scope.

Fixes #189

harshsaver and others added 3 commits November 12, 2026 17:17
Implement GetTask on the A2A ingress handler using the existing publication authorization, version checks, and a new principal-scoped history read that pairs each correlated Bus request with its agent reply. Unknown and other-principal tasks report task-not-found; revoked credentials and disabled publications stay denied. Documents the state/history mapping and bounds in the A2A guide and shows polling in the client example.
…task lookup

Update spec/0.1 to describe the task read, drop the test-only A2ATask
lookup in favour of A2ATaskHistory, remove unused history timestamps,
and correct the GetTask client example.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@harshsaver harshsaver added the agentbox: ready to merge Audited by Claude and Codex; Harsh can merge label Nov 13, 2026
@harshsaver

Copy link
Copy Markdown
Member Author

🤖 Agentbox PR audit: small fixes applied, then ready to merge

What this PR changes

  • What it does: An outside system that hands work to a published agent can now ask how its task is doing and retrieve the agent's reply.
  • What changes in the product: Nothing visible in the workspace UI. Integrators can use the standard task lookup instead of receiving an unsupported-operation error.
  • Why it exists: Issue A2A: let callers poll tasks returned by SendMessage #189. Callers could submit work and receive a task ID but had no standard way to check progress or read the answer.
  • Why merge (or why not yet): The intended flow is implemented, caller isolation is preserved, and all 11 CI checks pass on this commit. The public specification still denies support for task reads, and the implementation leaves two copies of the lookup behind.
  • What to expect after merging: Callers read replies from conversation history. Clients that only inspect output artifacts will not see the answer. Polling has no separate per-caller rate limit, so tight polling loops deserve monitoring. The new tests exercise SQLite; PostgreSQL execution of this read remains untested.
Full audit (Claude (fable, xhigh) × Codex (gpt-6-astra, xhigh), 2 turns, commit e57da46)

PR audit: #202 — A2A: let callers poll tasks returned by SendMessage

Head: d7e168c

Sign-off

  • Claude (fable, xhigh): ❌ not satisfied — the feature is correct and CI is green, but the versioned spec still says task reads are unsupported and a duplicate lookup path is left behind; both are small fixes we can apply.
  • Codex (gpt-6-astra, xhigh): ✅ satisfied — independently verified the blockers and exact fix plan; no material changes are needed to the audit.

Decision

fix — the polling path works as intended; update the stale public spec and remove the duplicate lookup, with the small documentation and unused-field fixes below.

What changes (plain language)

  • What it does: An outside system that hands work to a published agent can now ask how its task is doing and retrieve the agent's reply.
  • What changes in the product: Nothing visible in the workspace UI. Integrators can use the standard task lookup instead of receiving an unsupported-operation error.
  • Why it exists: Issue A2A: let callers poll tasks returned by SendMessage #189. Callers could submit work and receive a task ID but had no standard way to check progress or read the answer.
  • Why merge (or why not yet): The intended flow is implemented, caller isolation is preserved, and all 11 CI checks pass on this commit. The public specification still denies support for task reads, and the implementation leaves two copies of the lookup behind.
  • What to expect after merging: Callers read replies from conversation history. Clients that only inspect output artifacts will not see the answer. Polling has no separate per-caller rate limit, so tight polling loops deserve monitoring. The new tests exercise SQLite; PostgreSQL execution of this read remains untested.

Findings

Blocking

  1. The versioned spec now contradicts the shipped behaviour.
    • spec/0.1/README.md:208 still lists "task-read" among operations the binding does not accept.
    • spec/0.1/http.md:111 has no route row for the task read; only message:send is listed.
    • spec/0.1/http.md:169 describes SendMessage only and says other A2A operations return protocol errors.
    • Rule: CONTRIBUTING.md:38 ("Protocol behavior belongs in the versioned specification"), CONTRIBUTING.md:49, and spec/README.md:21-23 (a protocol change includes the specification update).
    • The PR updated docs/architecture/a2a-bridge.md and docs/clients.md but not spec/0.1/. The existing specification tests do not detect this contradiction.
  2. A duplicate, test-only lookup path is left behind (ruleset: remove obsolete paths; simplest implementation). This is not a demonstrated runtime bug.
    • Store.A2ATaskHistory (bus/a2a_tasks.go:362-407) repeats Store.A2ATask (bus/a2a_tasks.go:228-248): begin transaction, requireCurrentA2APrincipal, expireMessages, loadA2ATask, commit. It then adds message bodies. Runtime.A2ATaskHistory (:409-418) likewise repeats Runtime.A2ATask (:347-356).
    • A2ATask has no production caller outside its own wrapper. Its callers are bus/a2a_tasks_test.go:43,61,68,106 and bus/hardening_test.go:98, yet it stays on the storage interface (bus/storage_backend.go:95). It was already test-only on the base; this PR adds the duplicate rather than replacing that prepared lookup.
    • Consequence: the store-level credential-rotation fence test (bus/hardening_test.go:98) covers the old method, not the production read. The new HTTP rotation/disable tests are rejected earlier in authorize (bus/a2a_ingress.go:44-47), so they do not exercise the rejection at bus/a2a_tasks.go:368.
    • The production transaction does contain the correct fence. Removing the old method and redirecting the existing test closes the coverage gap without another abstraction. Issue A2A: let callers poll tasks returned by SendMessage #189 explicitly points to the existing principal-scoped lookup.

Non-blocking

In the fix plan (same lines are already being touched):

  • Unused fields. A2ATaskHistoryEntry.RequestCreatedAt and ResponseCreatedAt (bus/protocol.go:133,136) are filled at bus/a2a_tasks.go:392,396 and never read. taskHistoryToA2A (bus/a2a_ingress.go:146-168) ignores them, and the pinned SDK's a2a.Message has no timestamp field. Speculative per the ruleset.
  • Docs example does not match the SDK. docs/clients.md:67 shows a2aClient.GetTask(ctx, taskID). The pinned SDK signature is GetTask(ctx, *a2a.GetTaskRequest) (a2aclient/client.go:72 in a2a-go v2.7.0). docs/clients.md:64 also says to poll "until its state is completed"; that fails to stop on failed, canceled or rejected.

Not in the fix plan (optional follow-ups):

  • Unreachable fallbacks. bus/a2a_tasks.go:384-388 silently skips a turn whose request row is missing, and :397 silently drops a missing reply. Both columns are foreign keys to messages (bus/schema.go:156-157; deploy/hosted/migrations/001_runtime.sql:155-156), and retention prunes tasks and messages together (bus/retention_a2a.go:8-9; bus/storage.go:314). These branches mask broken invariants; they are not needed for normal retention.
  • Query shape and history limits. bus/a2a_tasks.go:379-400 issues up to two body queries per turn. All bodies are loaded even for historyLength=0; trimming happens afterward at bus/a2a_ingress.go:161. A join could reduce round trips. Impact is small for the current HTTP product: accepting another turn requires input-required (bus/a2a_tasks.go:188), and only the test-used SetA2ATaskState sets that state.
  • Multi-turn ordering caveat. The new documentation promises acceptance order (docs/architecture/a2a-bridge.md:38), but the reused query orders by millisecond created_at and then caller-controlled client_message_id (bus/a2a_tasks.go:36,151,208; bus/store.go:156). Two turns accepted in the same millisecond can therefore be reversed, affecting which messages a history limit selects. The new test uses already-sorted IDs turn-1 and turn-2 (bus/a2a_gettask_test.go:127,137). This is a pre-existing ordering limitation in the currently test-only multi-turn path, not a blocker for today's single-turn polling flow.
  • Error wording. mapBusA2AError (bus/a2a_ingress.go:173,187) reports internal failures as "The message could not be accepted", which now also appears on a read. Cosmetic.
  • Stale pin row (pre-existing). docs/architecture/a2a-bridge.md:14 says the A2A Go SDK is v2.5.0; go.mod:8 pins v2.7.0. Not caused by this PR.
  • Negative historyLength. Rejected with invalid params (bus/a2a_ingress.go:207-209); the pinned SDK's default handler instead returns empty history (a2asrv/handler.go:297). The pinned specification defines unset, zero and positive values, leaving negatives unspecified. Rejecting them is documented and tested. Pinned A2A specification, §3.2.4.
  • Reply placement is a documented interoperability limitation. Replies appear in history only (bus/a2a_ingress.go:154-166; docs/architecture/a2a-bridge.md:40), matching issue A2A: let callers poll tasks returned by SendMessage #189's request for correlated request/reply history. The pinned specification recommends artifacts for task outputs and says clients cannot generally assume important messages are persisted. That recommendation deserves acknowledgement; this bridge explicitly documents its history guarantee, so it does not require expanding this PR. Pinned A2A specification, §3.7.
  • Coverage. The new tests use the SQLite harness (bus/runtime_test.go:39-46). The hosted CI job selects Test(Postgres|Hosted) (.github/workflows/ci.yml:152) and does not execute these tests. PostgreSQL uses the same Store (bus/postgres.go:41) and portable SQL wrapper (bus/sql_database.go:113), so compilation is covered but execution of the new read is not.
  • Polling cost. No per-principal read limit, unlike output streams (bus/output_streams.go:21,310). Each poll takes a transaction and runs scope-wide expiry (bus/a2a_tasks.go:363-371), including a per-scope PostgreSQL lock (bus/scope_authority.go:38-45). The general 256-request concurrency cap remains (bus/capacity.go:10; bus/server.go:232-248). The expiry-on-read pattern already exists in Store.Receipt (bus/store.go:945-955).

Checked and found correct:

  • Authorization and the A2A-Version check precede task lookup (bus/a2a_ingress.go:199). The SDK may reject malformed query syntax before entering this handler, but that does not look up a task.
  • Foreign and unknown tasks return the same task-not-found error through the principal filter (bus/a2a_tasks.go:29-31; bus/a2a_ingress.go:180-181).
  • Credential generation, grants and publication enabled state are rechecked in the protected transaction (bus/a2a_principals.go:211-222). PostgreSQL scope serialization also prevents retention or reply writes from interleaving with the history read.
  • historyLength unset, zero, positive and oversized values select the expected history; zero omits history through the SDK's omitempty tag (a2a/core.go:364).
  • State mapping and the status timestamp preserve the existing taskToA2A behaviour (bus/a2a_ingress.go:114-137,164-166).
  • The documented 64 KiB body bound matches bus/a2a_tasks.go:336, bus/runtime.go:685 and the byte-length check in bus/validation.go:32.

Fix plan

Line numbers refer to the reviewed head. These are proposed changes for the fix phase; no tracked source files were changed during this audit.

  1. spec/0.1/README.md:208 — replace the paragraph with:

    The reference HTTP+JSON binding accepts authenticated A2A SendMessage requests containing plain text parts. It joins multiple parts in order with a newline, creates a durable Bus request, and returns the correlated A2A Task. It also accepts A2A GetTask, which returns the calling principal's task with its current state and its correlated request and response history as plain text messages. Unknown tasks and tasks of another principal return the same task-not-found error. The first binding does not accept file, URL, data, extension, referenced-task, streaming, push-notification, task-list, or cancellation operations. Rejected requests do not create Bus work. If an A2A-Version header is present, it MUST contain exactly 1.0.

  2. spec/0.1/http.md — after line 111 add:
    | `GET` | `/a2a/agents/{publicationId}/tasks/{taskId}` | Scoped A2A | Durable A2A Task with correlated history |
  3. spec/0.1/http.md:169 — replace the paragraph with:

    POST /a2a/agents/{publicationId}/message:send implements A2A 1.0 HTTP+JSON SendMessage. It accepts user messages made only of plain text parts and returns a durable A2A Task. GET /a2a/agents/{publicationId}/tasks/{taskId} implements A2A 1.0 GetTask for the calling principal's own tasks. It returns the task state and a history of each accepted user message followed by the agent's response when one exists. The optional historyLength query parameter keeps only that many of the most recent messages; 0 returns none and a negative value is rejected. Unknown tasks and tasks owned by another principal return the same A2A task-not-found error. On both routes the bearer credential must belong to the requested publication and the optional A2A-Version header must contain exactly 1.0. Other A2A operations and content types return A2A protocol errors.

  4. bus/a2a_tasks.go — delete func (s *Store) A2ATask (lines 228-248) and func (r *Runtime) A2ATask (lines 347-356).
  5. bus/storage_backend.go — delete line 95 (the A2ATask(...) interface entry).
  6. bus/a2a_tasks_test.go — switch the four callers to the remaining method:
    • line 43: stored, _, err := restarted.A2ATaskHistory(ctx, issued.Credential, publication.ID, task.ID)
    • line 61: working, _, err := agents.runtime.A2ATaskHistory(ctx, issued.Credential, publication.ID, task.ID)
    • line 68: completed, _, err := agents.runtime.A2ATaskHistory(ctx, issued.Credential, publication.ID, task.ID)
    • line 106: _, _, err = agents.runtime.A2ATaskHistory(ctx, other.Credential, publication.ID, task.ID)
  7. bus/hardening_test.go:98 — _, _, err = s.A2ATaskHistory(ctx, p, task.ID).
  8. bus/protocol.go — delete the RequestCreatedAt (line 133) and ResponseCreatedAt (line 136) fields.
  9. bus/a2a_tasks.go (inside Store.A2ATaskHistory):
    • delete var created int64;
    • in both queries change SELECT body,created_at to SELECT body and .Scan(&body, &created) to .Scan(&body);
    • change the request assignment to entry.RequestBody = body;
    • change the response assignment to entry.ResponseMessageID, entry.ResponseBody = correlation.BusResponseMessageID, body.
  10. docs/clients.md:
    • line 64: change "until its state is completed" to "until its state is terminal (completed, failed, canceled or rejected)";
    • line 67: change the call to task, err := a2aClient.GetTask(ctx, &a2a.GetTaskRequest{ID: taskID}) // bearer credential, A2A-Version 1.0.

After applying, run gofmt -l bus (no output expected) and the checks under Verification.

Message to the developer

n/a

Questions for Harsh

n/a

Verification

  • Audit only: no dependency installation, build, typecheck, vet, lint or tests were run. Review used code, the complete eight-file diff, history, documentation and read-only GitHub requests. Only the untracked audit document was written.
  • PR and issue: the prescribed gh pr view --comments command failed because this installed CLI requests retired Projects Classic fields. Explicit JSON fields and the REST API supplied the full PR body, issue A2A: let callers poll tasks returned by SendMessage #189 body, comments, reviews and inline discussion. All discussion lists were empty. Issue A2A: let callers poll tasks returned by SendMessage #189's five acceptance items are implemented, subject to the documentation/cleanup findings above.
  • Head/base: the checkout and live PR head both equal d7e168cbaca75dcdb9ca7ca4e6a43638412f16a8. The live base and local origin/main both equal 85d411e77a1c866295f33ed3462cd4d364b2c107; git log HEAD..origin/main is empty. GitHub reports MERGEABLE and BLOCKED. No rebase is needed.
  • Diff hygiene: git diff --check 85d411e77a1c866295f33ed3462cd4d364b2c107...HEAD was clean.
  • CI: all 11 checks passed. Run 43390538155 reports the exact reviewed head SHA. These are existing CI results, not checks rerun during the audit.
  • Independent code review: read the full diff and both handler/store implementations; traced authorization, credential rotation, delivery and reply transitions, retention, SQLite connection serialization, PostgreSQL scope locking and SQL adaptation. Rechecked every proposed deletion and all five affected test callers. Reviewed the new tests, existing A2A tests, the rotation regression, retention tests, specification policy, changed docs and CI selections.
  • Pinned library: inspected a2a-go v2.7.0 in the existing module cache, including REST routing/query parsing/error encoding, client signatures, default GetTask, task/message types and generated proto comments. No dependency was downloaded.
  • Resolved Turn 1's source gap: retrieved the exact pinned A2A specification at 173695755607e884aa9acf8ce4feed90e32727a1 and read §§3.1.3, 3.2.4 and 3.7. This confirms the history-length assessment and adds the artifact recommendation caveat.
  • Checks that matter after the fix: gofmt -l bus; go vet ./...; go build ./...; go test -race -count=1 ./bus ./spec ./conformance, especially TestA2AGetTask*, TestA2ATask*, TestA2ARotationFencesRetryReadAndStateChanges and TestA2ASendMessage*.
  • Remaining CI validation: run the hosted job with its disposable PostgreSQL configuration (go test -race -count=1 ./bus ./cmd/agentintercom ./conformance -run 'Test(Postgres|Hosted)') and the TypeScript interoperability job. The hosted job exercises existing PostgreSQL paths; it does not by itself add execution coverage for GetTask. Final required CI must pass on the fixed commit.

Audit log

  • Turn 1 (Claude (fable, xhigh)): Audited from scratch at d7e168c (same head as my interrupted earlier pass; no new commits or comments). Verified auth, isolation, historyLength, state mapping, retention and the SDK's REST handling. Raised two blocking items (stale spec/0.1 text; duplicate test-only A2ATask lookup) and wrote an exact fix plan of about 50 lines. Decision: fix.
  • Turn 2 (Codex (gpt-6-astra, xhigh)): Independently verified both blockers and every fix-plan edit against the same head, full issue and pinned SDK. Confirmed transaction fencing and retention; fetched the pinned specification; clarified the pre-existing test-only lookup, artifact recommendation, history-limit cost and multi-turn timestamp ties. No new blocker and no change to the decision or fix plan. Agree; no material changes.

Fixes applied by the audit

  • Applied the fix plan exactly in local commit e57da46 (8 files, +14/-50, not pushed): spec/0.1 README and http.md now describe the GetTask task read; removed the duplicate Store/Runtime A2ATask lookup and its storage-interface entry, pointing the 5 test callers at A2ATaskHistory; dropped the two unused history timestamp fields; corrected the docs/clients.md GetTask example and stop condition. Nothing was built or run.
  • Reviewed by Codex (gpt-6-astra, xhigh): All ten agreed fixes are implemented exactly, follow the ruleset, and add no scope; no correctness issues found. Installs, builds and tests were not run.

Final checks (run once, after both agents agreed)

Reviewed fixed commit e57da46 on Linux arm64 with Go 1.27 and Node 24.
go mod download — PASS.
npm ci (sdk/typescript) — PASS.
gofmt -l bus — PASS; no formatting changes needed.
git diff --check 85d411e..HEAD — PASS.
go vet ./... — PASS.
go build ./... — PASS.
go test -json -race -count=1 ./... — unavailable: ThreadSanitizer reports unsupported VMA range, Found 47 / Supported 48; identical failure on base 85d411e, excluded as a platform limitation.
Hosted suite with -race — same platform limitation on both head and base; requires a supported runner.
go test -json -count=1 ./... — PASS: 589 tests passed, including all new A2A tests; 43 database tests deferred to hosted suite.
go test -json -count=1 ./bus ./cmd/agentintercom ./conformance -run 'Test(Postgres|Hosted)' — PASS against disposable PostgreSQL 17: 49 tests passed, covering all 43 deferred tests.
Supabase identity lifecycle script — PASS; temporary dump redirected under HOME without modifying tracked files.
npm run typecheck — PASS.
npm run build — PASS.
npm run test:errors — PASS: 19 tests.
npm run test:release — PASS: 33 tests and compatibility metadata validation.
npm run build:native — PASS for Linux arm64.
npm run pack:distribution — PASS.
npm run test:distribution — PASS, including installation, CLI invocation and demo.
npm run test:integration — PASS against the freshly built CLI.
npm audit --audit-level=high — PASS; zero vulnerabilities.
Final repository check — tracked files unchanged; disposable PostgreSQL stopped.
Logs: /home/harshsaver/pr202-checks-e57da46-jJJXcdct/logs

Automated review by Harsh's agentbox: two AI reviewers audited this PR against the project ruleset and agreed on it.

@harshsaver

Copy link
Copy Markdown
Member Author

Verified the audit fix at head e57da46 (pushed before the audit's reviewed head d7e168c): all 10 fix-plan items are in — spec README + http.md route row and paragraph, both test-only A2ATask methods and the interface entry deleted, all five test callers switched to A2ATaskHistory, timestamp fields and SELECT body cleanup, and the corrected GetTask docs example. gofmt -l bus clean, CI 11/11 green at this head. No further push.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agentbox: ready to merge Audited by Claude and Codex; Harsh can merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

A2A: let callers poll tasks returned by SendMessage

1 participant