Implementation Plan: Platform UI Integration

Implement blackbox UI shells (Zed IDE, LibreChat) with multi-protocol support: OpenAI-compatible endpoints, LSP, ACP (Agent Client Protocol), and A2A (Agent-to-Agent) integration. Leverages Semantic Kernel for AI orchestration and integrates seamlessly with the Agent Society runtime.

Provenance & Traceability

Architectural Decisions (ADRs)

Product Requirements (PRDs)

Software Design Specifications (SDS)

Architecture and Design

Multi-Protocol Integration Strategy

graph TB
    subgraph "UI Shells (Blackbox)"
        ZED[Zed IDE<br/>ACP Protocol]
        LIBRE[LibreChat<br/>OpenAI API]
        VSCODE[VS Code<br/>LSP/MCP]
    end

    subgraph "SEA™ Protocol Layer"
        ACP_GW[ACP Gateway]
        A2A_SRV[A2A Server]
        OPENAI[OpenAI Facade]
        LSP[LSP Server]
    end

    subgraph "SEA™ Core"
        SK[Semantic Kernel]
        AGENTS[Agent Society<br/>Registry + HITL]
        ROUTER[Task Router]
    end

    ZED --> ACP_GW
    LIBRE --> OPENAI
    VSCODE --> LSP

    ACP_GW --> ROUTER
    A2A_SRV --> ROUTER
    OPENAI --> SK
    LSP --> SK

    ROUTER --> SK
    ROUTER --> AGENTS
    SK --> AGENTS

Protocol Responsibilities

Agent Society Synergy (P015)

Integration with the Agent Society Runtime enables:

1. Agent Registry - All IDE-connected agents registered in .github/agents/**
2. HITL Escalation - Privileged IDE actions require human approval (SDS-031)
3. Audit Trail - All agent actions logged with correlation IDs
4. Tool Surface Control - Deny-by-default tool exposure (SDS-052)

Design Principles Applied

• Isomorphism: UI shells map to explicit commands/queries in SDS-048.
• Invariants: Shells remain stateless; kernel remains authoritative (ADR-033).
• Idempotency: Command endpoints include request IDs (CMD-060).

Dependency Justification

8.1 Cognitive Artifact Rendering

8.2 Protocol Integration

Proposed Cycles

Task Breakdown

Wave 1: OpenAI Facade & Editor Actions (Parallel)

• C1A: Implement OpenAI-compatible facade endpoints
  • Implements: /v1/chat/completions, /v1/models
  • Satisfies: PRD-023 REQ-064
  • Backend: Route to Semantic Kernel for completion
• C1B: Implement editor action endpoints
  • Implements: /api/v1/actions/* (validate/generate/hover)
  • Satisfies: PRD-023 REQ-063

Wave 2: ACP & A2A Integration (Depends on Wave 1)

• C2A: Implement ACP Gateway for Zed IDE
  • Implements: ACP JSON-RPC over stdio (Zed agent panel)
  • Satisfies: Agent-to-editor communication
  • Files: libs/sea/adapters/acp/src/acp_gateway.py
• C2B: Connect A2A server to UI protocols
  • Implements: Route editor requests through A2A Task → SK execution
  • Leverages: P027 A2A Server, Task Router, SK integration
  • Files: Bridge in services/a2a/

Wave 3: LibreChat & Agent Society (Depends on Wave 2)

• C3A: LibreChat shell with Semantic Kernel backend
  • Implements: CopilotKit integration with SK plugins
  • Satisfies: Chat-based AI interaction
  • Dependencies: CopilotKit, SK
• C3B: Wire Agent Society registry and HITL
  • Implements: IDE agents registered in .github/agents/**
  • Leverages: P015 Agent Society (SDS-031, SDS-045)
  • HITL: Privileged IDE actions require approval

Validation & Verification

Spec Validation

• Endpoint contracts match SDS-048 definitions
• ACP messages conform to Zed’s ACP specification
• A2A endpoints pass interoperability tests

Implementation Validation

• LibreChat can call /v1/chat/completions with no UI changes
• Zed IDE agent panel shows SEA™ agent via ACP
• External agents can discover SEA™ via /.well-known/agent.json
• HITL approvals required for write operations

Open Questions

1. Which HTTP framework is canonical for sea-api? → FastAPI (per P027)
2. Is LSP a separate process? → LSP handler in API
3. NEW: What ACP version does Zed require? → Research needed

Risks & Mitigation

Related Documents

Future Synergy: P023 (Case Management) will enable case-based routing of IDE tasks, allowing agent interactions to create/update cases and leverage case context for richer completions.