singularity/singularity-forge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
singularity-forge/docs/plans/MISSION-A2A-ADOPTION.md

5.4 KiB
Raw Blame History

Mission: Adopt A2A as Internal Agent Communication Protocol

Metadata

  • Created: 2026-05-08
  • Status: Proposed (not started)
  • Source: Research from 4+ model consultations + codebase analysis + cross-repo pattern study
  • Plans: docs/plans/A2A_ADOPTION_PLAN.md, docs/plans/UNIFIED_DISPATCH_V2.md, docs/plans/dispatch-orchestration-architecture.md

Goal

Consolidate SF's 5 dispatch mechanisms + MessageBus into a unified dispatch architecture using A2A as the semantic communication layer, with MessageBus as the transport.

Context

Problem

SF has accumulated 5 dispatch mechanisms without a unifying abstraction:

  1. subagent tool — inline delegation, 4 tools, no project DB
  2. parallel-orchestrator — milestone-level parallelism, full tools, shared SQLite WAL
  3. slice-parallel-orchestrator — same pattern at slice scope (~80% duplicate)
  4. UOK kernel — autonomous loop controller
  5. MessageBus — SQLite-backed durable messaging (well-implemented but not wired)
  6. Cmux — surface integration (keep separate)

Evidence

  • parallel-orchestrator.js + slice-parallel-orchestrator.js share ~80% logic
  • MessageBus has zero references in parallel-orchestrator (coordination via file-based IPC)
  • @a2a-js/sdk@0.3.11 already in node_modules (transitive dep of @google/gemini-cli-core)
  • All 4 consulted models converged: merge the orchestrators first, wire MessageBus, keep subagent constraint

Constraints

  • Must preserve existing behavior throughout migration (feature-flagged rollout)
  • SF_A2A_ENABLED=0 must disable all new A2A behavior instantly
  • subagent isolation (4 tools, no project DB writes) is NOT changed
  • File-based IPC (session-status-io.js) stays as permanent crash-recovery fallback
  • DB is authoritative; A2A messages are hints

Mission Tasks

Phase 1 — A2A Type Definitions (Week 1-2)

  • Create dispatch/a2a-types.ts — A2A types + SF extensions (A2ATaskState, SFTaskExtension, MessagePriority, SFAgentCapabilities, SFAgentCard)
  • Create dispatch/a2a-task.ts — Task creation + state mapping functions
  • Create dispatch/a2a-errors.ts — DeliveryError + error codes
  • Run: npx tsc --noEmit on new types
  • Run: npx vitest run dispatch/a2a-task.test.ts

Phase 2 — AgentRegistry (Week 2-3)

  • Create dispatch/capability-registry.ts — AgentRegistry + SF_CAPABILITY_DEFINITIONS
  • Create dispatch/index.ts — barrel exports
  • Wire registry into DispatchService (opt-in via SF_A2A_ENABLED=1)
  • Run: unit tests pass
  • Run: existing tests pass with SF_A2A_ENABLED=0

Phase 3 — MessageBus Wiring (Week 3-4)

  • Create dispatch/a2a-service.ts — A2AMessageService wrapping MessageBus
  • Create dispatch/metrics.ts — A2A Prometheus metrics
  • Create dispatch/logger.ts — structured JSONL logging
  • Create dispatch/validation.ts — message body validation
  • Create dispatch/auth.ts — agent token generation + verification
  • Replace file-based IPC with MessageBus.send() for pause/resume/stop
  • Keep file-based IPC as crash-recovery fallback
  • Run: integration tests with SF_A2A_ENABLED=1
  • Run: existing tests pass with SF_A2A_ENABLED=0

Phase 4 — Subagent A2A (Week 4-5)

  • Refactor subagent/index.ts to use DispatchService
  • Remove ~600 LOC spawn management (replaced by dispatch.start())
  • Verify all 4 subagent modes work identically
  • Add optional MessageBus inbox for subagents (useMessageBus: true)
  • Run: subagent tests with SF_A2A_ENABLED=1

Phase 5 — UOK Kernel A2A (Week 5-6)

  • Register coordinator AgentCard in uok/kernel.ts
  • Replace startParallel/startSliceParallel calls with DispatchService
  • Verify sf headless autonomous works identically
  • Run: integration tests with SF_A2A_ENABLED=1

Phase 6 — A2A Default On (Week 6-7)

  • Set SF_A2A_ENABLED=1 as default in preferences
  • Monitor for 1 week
  • Promote to stable

Verification Criteria

  1. npx vitest run src/resources/extensions/sf/tests/uok-message-bus.test.mjs passes throughout
  2. SF_A2A_ENABLED=0 npm run test:unit passes throughout (legacy preserved)
  3. Pause/resume works via MessageBus with SF_A2A_ENABLED=1
  4. All 4 subagent modes work identically (parallel, debate, chain, single)
  5. sf headless autonomous works with SF_A2A_ENABLED=1
  6. Worker AgentCards visible in dashboard
  7. Panic mode activates correctly (3 consecutive delivery failures → file-based fallback)
  8. sf uok messages compact works
  9. sf dispatch agents list shows registered agents with capabilities

Key Files

File Role
src/resources/extensions/sf/uok/message-bus.js Existing MessageBus (transport)
src/resources/extensions/sf/dispatch/service.js DispatchService (A2A coordinator client)
src/resources/extensions/sf/worktree-orchestrator.js Worker spawner (A2A agent)
src/resources/extensions/sf/uok/kernel.js UOK kernel (A2A coordinator)
src/resources/extensions/subagent/index.js Subagent tool (A2A constrained agent)
docs/plans/A2A_ADOPTION_PLAN.md Full production-grade plan

Exit Criteria

Mission is complete when:

  • All 6 phases are merged to main
  • SF_A2A_ENABLED=1 is the default
  • SF_A2A_ENABLED=0 still passes all tests (legacy preserved)
  • 0 P0/P1 bugs in dispatch layer for 2 consecutive weeks
  • A2A observability dashboard shows healthy metrics (delivery latency < 500ms p99)