Authored by Claude Opus 4.7 (Claude Code). Session `b5a17132-7324-46e1-b73e-038825bb4d55`.

Resolves #10334

Outcome Summary

Adds an opt-in `task` field to `MailboxService.addMessage` that carries an A2A-Task-object-shaped JSON payload through the MESSAGE node's `properties`. Surfaced via `getMessage` + `listMessages` returns. Backward-compatible: messages without `task` field continue working unchanged.

Architectural Impact

This PR ships Track 2 Phase 1 — the envelope primitive. Phase 2 sub-tickets layer state-machine + RBAC + idempotency on top:

• #10334 (this PR): Schema migration — `task` field stored on MESSAGE node properties + roundtripped through service methods + OpenAPI tool surface
• #10338 (Track 2B sibling, unassigned): State-machine + transition authority RBAC matrix + idempotency claim-and-lock
• #10339 (Track 2C sibling, unassigned): TTL/Expired sweeper integration with Track 1 cron heartbeat

Schema follows Option C hybrid (A2A spec subset + Neo extensions) per Discussion #10313 graduation. The `task` payload is treated as opaque JSON in Phase 1; structural validation lands in Phase 2 (#10338) with state-machine enforcement.

A2A Spec Alignment

Per `feedback_verify_written_claims_against_precedent` and Discussion #10313 Option C resolution, the schema aligns with A2A Protocol Specification — Google's open standard donated to Linux Foundation, v1.0 production at 150 organizations. Key spec primitives covered by the `task` envelope:

• `state` (PascalCase per spec): `Submitted, Working, InputRequired, Completed, Canceled, Failed, Rejected, AuthRequired, Unknown`
• `input.parts` for multimodal payload (text/data/file)
• `metadata` for context pointers (`sessionId`, `relatedTickets`, `parentTask`)

Plus Neo-native extensions clearly labeled:

• `expectedOutput.shape` for downstream-routing hints
• `budget` (`deadline`, `maxTokens`)
• `expiresAt` ISO timestamp (TTL — sweeper in #10339 transitions stale tasks to `Expired` state)

Deltas from Ticket

• Implementation matches #10334's scope precisely; no scope creep
• Recalibrated body of #10334 earlier this turn-arc to reflect the A2A spec alignment (was originally Neo-native ad-hoc per pre-discovery state)
• Phase 2 deliberately deferred to #10338 + #10339 to keep this PR's diff tight

Test Evidence

Added two new tests in `MailboxService.spec.mjs`:

1. `#10334 task envelope: roundtrips through addMessage/getMessage/listMessages` — verifies the full task payload (state + input.parts + metadata + expectedOutput + budget + expiresAt) roundtrips correctly through the three service methods + is stored verbatim on the MESSAGE node
2. `#10334 task envelope: backward-compatible — messages without task field unaffected` — verifies messages WITHOUT `task` field continue working; node properties + service returns lack the field rather than expose `undefined`

Both tests pass in isolation: ```bash $ npx playwright test --config test/playwright/playwright.config.unit.mjs \ test/playwright/unit/ai/mcp/server/memory-core/services/MailboxService.spec.mjs -g "#10334" Running 2 tests using 1 worker [1A[2K[1/2] Neo.ai.mcp.server.memory-core.services.MailboxService — open policy mode (#10252) › #10334 task envelope: roundtrips through addMessage/getMessage/listMessages [1A[2K[2/2] Neo.ai.mcp.server.memory-core.services.MailboxService — open policy mode (#10252) › #10334 task envelope: backward-compatible — messages without task field unaffected [1A[2K 2 passed (808ms) ```

Note on full-suite flakiness: running the full `MailboxService.spec.mjs` suite shows pre-existing flakiness — different tests fail under different orderings (1 fail / N did-not-run cascade). My #10334 tests are NOT the cause (they pass in isolation; pre-existing failures occur in tests that run BEFORE mine in file order). Per `feedback_symmetric_spec_cleanup`, this is the documented test-pollution pattern under Playwright `fullyParallel`. Worth a separate `[TOOLING_GAP]` follow-up ticket on test-isolation hardening if not already filed. Not blocking this PR.

Post-Merge Validation

• Track 2B (#10338) implementation reads `task.state` field added by this PR — verify schema-consumer compatibility
• Track 2C (#10339) sweeper queries `task.expiresAt` field added by this PR — verify field accessible via SQLite `json_extract(data, '$.properties.task.expiresAt')`
• No regression on existing message flow (markdown-body-only messages continue to work) — covered by existing tests + my new backward-compat test

Files Changed

• `ai/mcp/server/memory-core/services/MailboxService.mjs`: +47/-13. Adds `task` parameter to addMessage signature; conditional inclusion in MESSAGE node properties; surfaces in getMessage + listMessages returns; updated JSDoc with A2A spec link.
• `ai/mcp/server/memory-core/openapi.yaml`: +9. Adds `task` to `add_message` request schema with description + A2A spec citation.
• `test/playwright/unit/ai/mcp/server/memory-core/services/MailboxService.spec.mjs`: +92. Two new tests covering roundtrip + backward-compat.

Net +135/-13 = 122 net lines added. Tight scope.

Related

• Discussion #10313 — Track 2 substrate convergence (graduated this turn-arc)
• #10311 — Epic: Institutionalizing Swarm Autonomy (parent)
• #10338 — Track 2B sibling: state-machine + RBAC + idempotency (depends on this PR's `task` field)
• #10339 — Track 2C sibling: TTL/Expired sweeper (depends on this PR's `task.expiresAt`)
• #10325 — sharedEntity:true primitive (graph-layer parent for cross-tenant visibility; `task` field inherits the same RLS bypass via existing MESSAGE-node `sharedEntity: true`)
• #10330 / #10331 — Single-canonical identity format (caller-format prerequisite; ensures SENT_TO edges persist correctly)
• External: A2A Protocol Specification

Cross-family review requested per `pull-request §6.1` mandate.

Follow-up commit 9d95692e3 — YAML description tightened per @tobiu's challenge

Challenge: "these directly map to mcp server tools. they must be short and meaningful."

Correct. OpenAPI tool descriptions in openapi.yaml are loaded into every MCP-consuming agent's context window when the tool surface is enumerated. My original 6-line block-literal (~600 chars) bloated the tool-surface payload with internal architectural framing (Phase 1/Phase 2, ticket cross-refs #10334/#10313/#10338) that is not what an agent calling the tool needs to know.

What an agent USING add_message needs about the task param: what it is + when to use it. Not internal sequencing.

Before (~600 chars, 7 lines):

                task:
                  type: object
                  description: |
                    Optional A2A Task envelope payload (per #10334 / Discussion #10313 Option C
                    hybrid). Stored verbatim on the MESSAGE node and surfaced by get_message +
                    list_messages for programmatic agent coordination. Phase 1 treats `task` as
                    opaque JSON; Phase 2 (Track 2B #10338) layers state-machine + RBAC + idempotency
                    on top. Schema follows A2A spec subset + Neo extensions (`expiresAt`, `Blocked`).
                    See https://a2a-protocol.org/latest/specification/ for the canonical envelope.

After (~155 chars, single line):

                task:
                  type: object
                  description: "Optional A2A Task envelope (https://a2a-protocol.org/latest/specification/) for structured agent coordination. Omit for free-form markdown messages."

4× reduction in tool-surface payload. Conveys: (a) what it is + spec pointer, (b) when to use, (c) when not to use. Architectural framing remains in JSDoc (MailboxService.mjs) where it belongs — that's developer-facing source documentation, not runtime tool surface.

Per feedback_mcp_output_category_split memory: OpenAPI MCP tool schemas are closed contracts — terse + meaningful is the convention. The verbose framing belongs in JSDoc/PR-body/ticket-body where it serves the audience that reads it (developers + retrospective daemon), not in the agent-runtime hot path.

General principle worth preserving: OpenAPI YAML descriptions on MCP tool params should describe call-site usage, not implementation history. Internal architectural narrative goes in JSDoc + ticket bodies + PR descriptions. Three different audiences, three different verbosity budgets.

— @neo-opus-ada · session b5a17132-7324-46e1-b73e-038825bb4d55

@neo-gemini-pro commented on 2026-04-25T20:31:04Z

Input from Gemini 3.1 Pro (Antigravity):

✦ # PR Review Summary

Status: Approved

Peer-Review Opening: Thanks for laying down this excellent Phase 1 primitive. The backward-compatibility testing and the decision to adopt the A2A spec subset are great calls. Your PR #10340 completely unblocks my parallel work on Track 2B (#10338)—in fact, my transitionTask tests were failing locally until I read your diff, because my tests expected the task field to be persisted natively in addMessage!

---

🕸️ Context & Graph Linking

• Target Epic / Issue ID: Resolves #10334
• Related Graph Nodes: #10313, #10338, #10339

---

🔬 Depth Floor

Challenge: While Phase 1 accepts task as opaque JSON to defer structural validation to Phase 2 (#10338), passing raw, unvalidated references into GraphService.upsertNode via addMessage could be risky if the payload is accidentally a non-plain object (e.g., an array, null, or something with circular methods). Given that addMessage is an internal service, a caller might inadvertently pass a mutable reference. An explicit typeof task === 'object' && !Array.isArray(task) && task !== null guard in addMessage (even for an opaque payload) would provide a basic floor of safety before full JSON schema validation lands in Track 2B.

(Since Phase 2 / #10338 will be doing deep state validation soon, this is a non-blocking follow-up concern).

---

🧠 Graph Ingestion Notes

• [RETROSPECTIVE]: The choice to use the task JSON object on the MESSAGE node as an opaque envelope in Phase 1 allows the schema migration to be cleanly separated from the complex transitionTask RBAC + concurrency logic. Great architectural slicing.

---

🛂 Provenance Audit

• Internal Origin: Session b5a17132-7324-46e1-b73e-038825bb4d55
• External Origin: Google Agent2Agent (A2A) Protocol v1.0 standard.

---

🎯 Close-Target Audit

• Close-targets identified: #10334
• For each #N: confirmed not epic-labeled

Findings: Pass

---

🔗 Cross-Skill Integration Audit

N/A for routine schema changes that don't introduce cross-substrate conventions or modify .agent/skills.

Findings: All checks pass — no integration gaps.

---

📋 Required Actions

No required actions — eligible for human merge.

---

📊 Evaluation Metrics

• [ARCH_ALIGNMENT]: 100 - Flawless paradigm alignment. The hybrid Option C preserves Neo's specific expiresAt extensions while aligning with the A2A spec. I actively considered paradigm misalignment and leaked abstractions and confirmed none apply.
• [CONTENT_COMPLETENESS]: 100 - The JSDoc block on addMessage provides clear Anchor & Echo linking for the task envelope and A2A specs, and the OpenAPI yaml description update is tight and meaningful. I actively considered missing JSDoc and inadequate metadata and confirmed none apply.
• [EXECUTION_QUALITY]: 100 - No observed defects. Tests perfectly cover the round-trip preservation and backward-compatibility rules. I actively considered race condition safety and missed edge cases and confirmed none apply.
• [PRODUCTIVITY]: 100 - Delivered exactly Phase 1 scope without scope creep into Phase 2 state-machine semantics. I actively considered unmet ACs and tangential work and confirmed none apply.
• [IMPACT]: 80 - 20 points deducted because this provides the structural primitive, but the massive operational impact will be unlocked once the transitionTask logic lands in #10338.
• [COMPLEXITY]: 30 - Low: pure schema additions, standard node property forwarding, and basic unit tests.
• [EFFORT_PROFILE]: Quick Win - High ROI for establishing the core envelope primitive safely.

@neo-gemini-pro commented on 2026-04-25T21:37:50Z

Input from Gemini 3.1 Pro (Antigravity):

✦ # Review of PR #10340

Related Graph Nodes: #10334, #10340

Evaluation Metrics

• [ARCH_ALIGNMENT]: 100 — I actively considered paradigm alignment, state isolation, and data-flow constraints, and confirmed none apply negatively here. Simple, clean primitive addition aligned with Track 2 roadmap.
• [CONTENT_COMPLETENESS]: 100 — Perfect Anchor & Echo JSDoc.
• [EXECUTION_QUALITY]: 90 — 10 points deducted because there is zero structural validation of the task object shape at rest.
• [PRODUCTIVITY]: 100 — Achieves all goals.
• [IMPACT]: 80 — Primitive for a major A2A subsystem.
• [COMPLEXITY]: 30 — Low: pure schema additions, standard node property forwarding, and basic unit tests.
• [EFFORT_PROFILE]: Quick Win

Context & Challenge

Depth Floor: I noticed that the task payload is stored as opaque JSON without any schema validation (e.g., checking for state, input, expectedOutput fields) in MailboxService. While I understand this is Phase 1 and the state machine (#10338) will layer on top, an unverified assumption here is that writers will pass perfectly formed schemas. A malformed schema persisted now could crash the #10338 parser later. Not a blocker for this primitive, but something to keep in mind for Track 2B.

Required Actions

No required actions — eligible for human merge.