LearnNewsExamplesServices
Frontmatter
id15269
titleFleet read adapter: per-agent A2A mailbox mirror — read-only, viewer-admitted, paginated (S1 Brain half, D#15249)
stateClosed
labels
enhancementai
assigneesneo-opus-vega
createdAtJul 16, 2026, 5:06 PM
updatedAtJul 16, 2026, 11:18 PM
githubUrlhttps://github.com/neomjs/neo/issues/15269
authorneo-fable
commentsCount0
parentIssue13015
subIssues[]
subIssuesCompleted0
subIssuesTotal0
contentTrust
projected
quarantined0
signals[]
blockedBy[]
blocking[ ] 15270 FM cockpit per-agent mailbox pane — read-only AgentDetail tab (S1 view half, D#15249)
closedAtJul 16, 2026, 11:18 PM

Fleet read adapter: per-agent A2A mailbox mirror — read-only, viewer-admitted, paginated (S1 Brain half, D#15249)

Closed Backlog/active-chunk-6 enhancementai
neo-fable
neo-fable commented on Jul 16, 2026, 5:06 PM

Context

The Brain half of surface S1 from the graduated FM design-first record (D#15249, closed RESOLVED → #15254 Surface Registry). The operator reads raw A2A mailbox traffic by hand today; the cockpit's detail view has no communication surface. The cockpit pane (sibling leaf under #14560) consumes THIS adapter — blocked-by edge set.

The Problem

Cross-inbox reads are identity-bound: an operator/control-plane viewer reading agent X's mailbox is not agent X. No Fleet-side surface exposes a mailbox mirror with viewer admission today; the cockpit cannot render one honestly without it.

The Architectural Reality

  • MailboxService already discovers bounded pagination (limit, offset) and thread metadata (partOfThread); its public summary must carry that discovered thread fact so the adapter can project the real service contract rather than an enriched test double.
  • The graduated record's binding boundary ACs (verbatim authority): read-only Body→Brain adapter; explicit operator/control-plane viewer admission (CAN_READ_INBOX_OF + audit policy); canonical identity mapping (viewer, subject-agent); bounded pagination; no markRead exposure on the adapter surface — operator-side mark-read would mutate the agent's own turn-start signal and silently swallow peer handoffs (the record's MUST-NOT, a correctness rule).
  • Admission authority is the server-stamped request identity used by MailboxService. A viewerIdentity field is an audit fact only: wiring must derive or verify it against that same trusted request binding; caller text never grants access. This surface accepts one direct Agent subject, not the AGENT:* broadcast sentinel.
  • Default view = active/non-archived inbox (archive stays opt-in per the mailbox contract); archive browsing is out of v13.2 scope unless explicitly specced later.
  • Any subject or diagnostic projected toward the Body is bounded and secret-safe, including bearer and PAT-shaped credentials.

Acceptance Criteria

  • A Fleet-side read adapter exposes a per-agent mailbox mirror: {viewerIdentity, subjectAgentId, limit, offset} → immutable message rows (timestamped facts) + thread metadata, active/non-archived by default.
  • Viewer admission enforced fail-closed: no CAN_READ_INBOX_OF grant → no rows, an honest admission error (never an empty-success); admission checks are auditable and tied to the same trusted request identity that enforced the read.
  • The adapter surface carries NO markRead/mutation verbs — structurally absent, not merely unused.
  • Canonical identity mapping documented and tested (viewer ≠ subject; direct Agent subject only; agent-reading-own-inbox stays on the existing path, untouched).
  • Unit coverage: admission fail-closed, trusted viewer/subject validation, pagination bounds, active-vs-archived default, real MailboxService thread metadata pass-through, and secret-safe projected text.

Contract Ledger

Target Surface Source of Authority Proposed Behavior Fallback Docs Evidence
readFleetMailboxMirror(options) D#15249 S1 boundary ACs + Surface Registry #15254 Request-bound read of one direct Agent's active inbox → frozen snapshot Named degraded snapshot; never fabricated rows Module JSDoc Adapter contract suite
Viewer admission + admission audit fact RequestContext-bound MailboxService + CAN_READ_INBOX_OF Enforcement uses the server-stamped request identity; viewer audit identity is derived/verified from the same binding; direct-Agent subject only Explicit denied only for the named capability failure; other failures are unavailable Module JSDoc Grant, denial, sentinel, malformed-input, and viewer-mismatch witnesses
Mailbox summary → mirror row thread fact MailboxService listMessages() summary contract Service returns its discovered partOfThread; adapter projects it without invention Missing fact stays null, never guessed Service + adapter JSDoc Real producer-contract regression + adapter pass-through witness
Body-facing subject/reason text Brain→Body secret boundary Bounded summaries redact assignment, GitHub/GitLab PAT, and bearer forms Safe generic reason Module JSDoc Raw-token non-observability witnesses
Mutation verbs D#15249 MUST-NOT; adjacent evidence #15253 Structurally absent — read/projection exports only n/a Module JSDoc Export-surface witness
Archive exposure Ticket active/non-archived default Adapter does not expose or forward includeArchived Service default governs Module JSDoc Exact forwarded-key witness

Out of Scope

The cockpit pane rendering this (sibling leaf, blocked on this one) · reply-as-operator (deferred v13.3 per the record — needs the operator-as-sender authority contract) · archive browsing.

Related

Epic #13015 (parent — the C-lane services home per the D#15209 placement default) · D#15249 (graduated record, S1 resolution tokens + boundary ACs) · #15254 / PR #15255 (Surface Registry citation target) · #15253 (the markRead divergence bug — adjacent evidence for the MUST-NOT).

Sweeps: latest-open checked 2026-07-16T15:05Z (latest #15267) — no equivalent; the fleet service tree carries no mailbox read adapter (grep-verified during the D#15249 STEP_BACK). A2A herd-window clean.

Origin Session ID: b42c5667-db78-4a0c-83a0-ce66c95ee0d9 Retrieval Hint: "fleet mailbox read adapter viewer admission CAN_READ_INBOX_OF S1"

tobiu referenced in commit 8ed6f0c - "feat(fleet): viewer-admitted per-agent mailbox mirror adapter — the S1 Brain half (#15269) (#15285) on Jul 16, 2026, 11:18 PM
tobiu closed this issue on Jul 16, 2026, 11:18 PM