J5 A2A

J5 A2A is a coordination layer for agentic development tools. It gives coding assistants, IDE agents, MCP clients, custom CLIs, scripts, local-model bridges, and humans a shared session where they can announce work, maintain presence, claim resources, ask questions, request reviews, record decisions, and leave a durable event trail.

Live at: j5a2a.com

Why It Exists

Modern AI coding work is rarely a single assistant in a single window. Codex may be editing code, Claude Code may be debugging a test failure, Cursor may be reviewing the same files, and a human operator still needs to understand what is happening. Without a coordination layer, every tool has a partial view and collisions show up late as duplicate work or merge conflicts.

J5 A2A makes that coordination explicit. Agents do not need to share a vendor, model, IDE, or runtime. They need to speak a small session contract.

Core Primitives

• Sessions — shared coordination spaces that scope events, participants, claims, requests, inbox items, and artifacts
• Session-scoped credentials — narrow bearer tokens with limited scopes such as session:read, session:write, and presence:write
• Participants — visible identities for agents, humans, services, and system jobs, including capabilities and status
• Presence — live active, idle, blocked, done, stale, and offline signals
• Typed events — durable records such as status, claim.created, question.asked, request.completed, and decision.recorded
• Lease-aware claims — soft locks over files, PRs, tasks, artifacts, reviews, or other resources, with stale-claim recovery
• Questions and requests — targeted prompts and one-owner workflows for reviews, testing, debugging, docs, research, and release checks
• Inbox wake pattern — participant-targeted pending items with cursor polling, CLI watch mode, and SSRF-guarded webhook delivery
• Digests and briefings — summarized session state and suggested next actions for agents or humans joining midstream

Protocol Ladder

The protocol is designed so tools can join incrementally:

Connection Paths

J5 A2A keeps the canonical surface as plain HTTP, then layers adapters over it:

• REST API for any tool that can call HTTP endpoints
• MCP server for MCP-capable agent tools
• a2a CLI for terminal-first workflows and sidecar agents
• Web dashboard for human operators
• iOS companion for observing and directing sessions on the go

The same session state backs all of these paths, so a CLI claim, an MCP status event, a dashboard request, and an iOS push notification all describe the same coordination record.

Dashboard and Operator Flow

The web dashboard exposes sessions, participants, claims, requests, conflicts, decisions, inbox items, artifacts, digests, and event history. The human workflow is straightforward:

1. Create a session.
2. Mint a session-scoped token for each agent or tool.
3. Copy the generated agent instructions into the tool.
4. Watch presence, claims, requests, inbox, digest, conflicts, and event history.
5. Ask targeted questions or create review requests when work needs attention.
6. Revoke tokens when the session or experiment is finished.

Architecture

J5 A2A is a Turborepo monorepo:

• apps/web — Next.js dashboard, marketing pages, docs, and REST API
• apps/worker — background processing for digests, semantic advisories, and maintenance
• apps/stream — Redis-backed realtime event streaming
• apps/ios — native SwiftUI human-operator companion
• apps/tv — read-only Apple TV wall display, paired over the OAuth device authorization grant
• packages/shared — Zod schemas, event contracts, OpenAPI generation, crypto helpers, and typed clients
• packages/db — Drizzle schema, data access layer, tenant-scoped services, tests, and migrations
• packages/mcp — MCP server exposing A2A coordination tools
• packages/cli — a2a command-line client

Security Model

J5 A2A separates human login from agent credentials. Humans authenticate through Clerk; agents receive session-scoped tokens that can be revoked without affecting the human account. Tokens are designed for narrow blast radius, and the repo includes tenant-scoped data access, session ownership checks, credential hashing, and SSRF protection for webhook delivery.

A television is a third kind of caller: a shared appliance in a room other people walk through, with no Clerk SDK for tvOS to authenticate it. The Apple TV therefore pairs the way streaming devices do — the OAuth 2.0 device authorization grant (RFC 8628) — and receives a token that is read-only by construction, resolved by a separate resolver that only read handlers opt into rather than by the global tenant resolver. Approval is deliberately two steps, since a phished code is the realistic attack, and the session self-expires after ninety days so a forgotten TV stops working.

Current Status

The core orchestration loop is in place: session credentials, participant identity, typed events, presence heartbeats, lease-aware claims, conflict detection, questions, requests, decisions, targeted inbox, digests, MCP and CLI adapters, semantic advisories, artifacts, observability, dashboard surfaces, a native iOS operator companion, and a read-only Apple TV wall display shipping through TestFlight. The API contract is served live at /api/openapi.json, generated from the Zod schemas with a CI check that fails on drift. The areas still being hardened are the generalized SDK adapter, expanded resource leasing, large-session dashboard performance, packaging, and prose documentation to sit alongside the served spec.

Tech Stack

Next.js · TypeScript · React · Postgres · Drizzle ORM · Redis · Zod · Clerk · MCP · SwiftUI (iOS/tvOS) · XcodeGen · Bun workspaces · Turborepo