SDS-048: Platform UI Integration Service

Status: Draft
Version: 1.1
Date: 2026-01-07
Satisfies: PRD-023, ADR-033
Bounded-Context: sea-api

0. Isomorphism Declaration

Spec Section SEA-DSL Target Cardinality Verification
1. Glossary Namespace terms 1:1 Term → canonical name
2.1 API Facades Port interfaces 1:1 Method signatures match
3. Policies Policy nodes 1:1 Rule verbatim
4. Commands Flow @command 1:1 Input/output identical
5. Queries Flow @query 1:1 Input/output identical
7. Ports Interface definitions 1:1 Methods preserved

1. Domain Glossary

Term Definition Type Canonical?
UIShell External UI client that consumes SEA™ APIs Concept ✓
ZedExtension Zed IDE extension calling SEA™ endpoints Shell ✓
LibreChatClient LibreChat instance pointed at SEA™ Shell ✓
OpenAIFacade Adapter exposing OpenAI-compatible API Adapter ✓
LSPServer Language Server Protocol endpoint Adapter ✓
EditorAction SEA™ capability exposed as editor command Entity ✓
MCPServer Model Context Protocol server for tools Adapter ✓
MemoryContext Persistent context across LibreChat sessions Entity ✓
MCPTool Discoverable tool exposed via MCP Entity ✓

2. Domain Model

2.1 API Facades

Facade Purpose Protocol Endpoint Pattern
OpenAIFacade Chat-first interface for LibreChat HTTP /v1/chat/completions
LSPServer Editor integration for Zed LSP/JSON-RPC stdio or TCP
EditorActionAPI Direct HTTP for editor actions HTTP/gRPC /api/v1/actions/*

2.2 Editor Actions

Action Description Input Output
ValidateSpecs Validate spec files { paths: string[] } { valid: boolean, errors: Error[] }
GenerateCode Generate code from specs { specId: string, options: {} } { files: GeneratedFile[] }
RefactorDomain Apply refactoring { entityId: string, action: string } { changes: Change[] }
QueryKnowledge Query Knowledge Graph { sparql: string } { results: any[] }

3. Invariants & Policies

POL-ID Applies-To Rule Error Code
POL-048-001 UIShell shell.authentication = valid UNAUTHENTICATED
POL-048-002 OpenAIFacade response.format = openai_compatible INVALID_FORMAT
POL-048-003 UIShell shell.state = stateless STATEFUL_VIOLATION
POL-048-004 MCPServer tool.definition = openapi_compatible INVALID_TOOL_SCHEMA
POL-048-005 MemoryContext memory.pii_scrubbed = true PII_VIOLATION
POL-048-006 MCPTool tool.hitl_marked = true for mutations HITL_REQUIRED

4. CQRS: Commands

CMD-060: ExecuteEditorAction

Field Value
CMD-ID CMD-060
Input actionType: string, params: object, requestId: UUID
Preconditions POL-048-001 (authenticated)
State Changes Depends on action; may trigger domain commands
Emits Events EVT-060 (EditorActionExecuted)
Satisfies REQ-063

Idempotency Specification: | Idempotent? | Key Expression | Strategy | Behavior on Duplicate | |————-|—————-|———-|———————-| | yes | requestId | Request ID tracking | Return cached result |

CMD-061: ProcessChatCompletion

Field Value
CMD-ID CMD-061
Input messages: ChatMessage[], model: string, stream: boolean
Preconditions POL-048-001, POL-048-002
State Changes None (stateless)
Emits Events None
Satisfies REQ-064

Idempotency Specification: | Idempotent? | Key Expression | Strategy | Behavior on Duplicate | |————-|—————-|———-|———————-| | no | N/A | N/A | Always process (stateless) |

5. CQRS: Queries

QRY-060: GetCapabilities

Field Value    
QRY-ID QRY-060    
Input clientType: string (zed librechat generic)
Output { actions: ActionDescriptor[], models: string[] }    
Satisfies REQ-063, REQ-064    
Idempotent? yes (inherent)    

6. Domain Events

EVT-060: EditorActionExecuted

Field Value
EVT-ID EVT-060
Payload requestId, actionType, success, duration, userId
Published To sea.event.editor_action_executed.v1
Consumers Analytics, Audit
Delivery at-least-once

7. Ports

PORT-ID Port Name Direction Methods
PORT-048-001 OpenAIFacadePort inbound chatCompletion(req): Response
PORT-048-002 EditorActionPort inbound execute(action, params): Result
PORT-048-003 LSPPort inbound initialize(), hover(), completion()
PORT-048-004 SEACapabilityPort outbound validateSpecs(), generateCode(), etc.
PORT-048-005 MCPServerPort inbound registerTool(), listTools(), handleToolCall()
PORT-048-006 MemoryContextPort inbound storeContext(), retrieveContext()

8. Adapters

Category Choice Notes
HTTP Framework Hono / FastAPI Depending on runtime
Auth JWT verification Via gateway or middleware
Streaming SSE / WebSocket For chat streaming
LSP tower-lsp (Rust) If Rust-based server

9. Zed IDE Integration Details

Extension Architecture

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

┌─────────────────────────────────────────────┐
│              Zed IDE                         │
│  ┌─────────────────────────────────────┐    │
│  │      SEA™ Extension (Wasm/Rust)      │    │
│  │  - Registers actions                │    │
│  │  - Calls SEA™ endpoints              │    │
│  │  - Renders results in editor        │    │
│  └──────────────┬──────────────────────┘    │
└─────────────────┼───────────────────────────┘
                  │ HTTP/gRPC
                  ▼
┌─────────────────────────────────────────────┐
│            SEA™ API (sea-api)                │
│  - /api/v1/actions/validate                 │
│  - /api/v1/actions/generate                 │
│  - LSP server (optional)                    │
└─────────────────────────────────────────────┘
Endpoint Method Purpose
/api/v1/actions/validate POST Validate spec files
/api/v1/actions/generate POST Generate from specs
/api/v1/actions/hover POST Get hover info for symbol
/api/v1/capabilities GET List available actions

10. LibreChat Integration Details

Configuration

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# librechat.yaml
version: 1.2.8

# Memory for case context persistence
memory:
  disabled: false
  personalize: true
  tokenLimit: 4000
  validKeys:
    - "case_context"
    - "project_preferences"
    - "domain_knowledge"

# MCP Server for tool discovery
mcpServers:
  sea-forge:
    type: "sse"
    url: "${SEA_MCP_URL:-http://sea-api:8080/mcp}"

# Endpoints
endpoints:
  custom:
    - name: "SEA™"
      apiKey: "${SEA_API_KEY}"
      baseURL: "http://sea-api:8080/v1"
      models:
        default: ["sea-default", "sea-analysis", "sea-governance"]
      features:
        streaming: false
        artifacts: true

MCP Endpoints

Endpoint Method Purpose
/mcp/tools GET List all available MCP tools
/mcp/tools/{n} GET Get specific tool definition
/mcp/invoke POST Invoke a tool with parameters
/mcp/health GET MCP endpoint health check

Available MCP Tools

Tool Category Description
case_create Case Management Create new case from template
case_status Case Management Get case status by ID
case_list Case Management List active cases
case_transition Case Management Move case to next CMMN stage
spec_validate Spec Validation Validate specification files
code_generate Code Generation Generate code from specs
knowledge_query Knowledge Query Query SEA knowledge graph

OpenAI-Compatible Endpoints

Endpoint SEA™ Implementation
POST /v1/chat/completions Routes to SEA™ capabilities based on prompt
GET /v1/models Returns available SEA™ models/modes