Sea API Epic

User Journey

The sea-api bounded context serves as the protocol gateway that exposes SEA™ platform capabilities through standardized interfaces for external tooling integration. It implements a stateless shell architecture (per ADR-033) that provides two primary integration patterns: (1) Editor Actions for Zed IDE via LSP and HTTP/gRPC endpoints, and (2) OpenAI-compatible Chat Completions API for LibreChat and other LLM UIs. The gateway acts as a protocol translator with no domain logic, delegating all business operations to the SEA™ kernel through defined ports.

Jobs to be Done & EARS Requirements

Job: Execute Editor Action

User Story: As a Zed IDE user, I want to invoke editor-native actions (generate, refactor, validate) that leverage SEA™ capabilities, so that I can perform AI-assisted development tasks directly within my editor.

EARS Requirement:

• While the system is operational, when an ExecuteEditorAction command (CMD-001) is received from an EditorActionHandler with action type, payload, and optional requestId, the sea-api context shall:
  1. Validate the action payload against the action’s input schema
  2. Check authentication credentials per AuthenticationRequired policy (POL-048-001)
  3. If requestId is provided, ensure idempotent execution by checking for prior execution with that key; return cached result on duplicates (REQ-065)
  4. Translate the editor action into the appropriate SEA™ kernel command
  5. Execute the command through the defined port interface
  6. Return structured results to the editor in the expected format
  7. Emit events to the EventBus for async processing and monitoring
  8. Enforce StatelessShell policy (POL-048-003): maintain no client state between requests

Job: Process Chat Completion Request

User Story: As a LibreChat user (or any OpenAI-compatible client), I want to send chat completion requests to the SEA™ platform, so that I can leverage SEA™ capabilities through a familiar LLM interface.

EARS Requirement:

• While the system is operational, when a ProcessChatCompletion command (CMD-002) is received from an OpenAIFacade at /v1/chat/completions endpoint, the sea-api context shall:
  1. Validate the request follows OpenAI format per OpenAIFormatCompatibility policy (POL-048-002)
  2. Authenticate the request per AuthenticationRequired policy (POL-048-001)
  3. Parse ChatCompletionRequest containing model, messages, temperature, max_tokens, and stream flag
  4. Translate the OpenAI-format request into SEA™ kernel commands
  5. Process the request statelessly through the kernel port (REQ-064)
  6. If stream: false, return a complete ChatCompletionResponse with choices, usage, and finish_reason
  7. If stream: true, establish SSE connection and stream response chunks as they arrive (REQ-067)
  8. Include OpenAI-compatible metadata (id, created, model, object fields)
  9. Enforce StatelessShell policy (POL-048-003): no session state between requests

Job: Query Available Capabilities

User Story: As an external tool or UI, I want to discover available SEA™ capabilities and their input schemas, so that I can dynamically generate interfaces and validate user inputs.

EARS Requirement:

• While the system is operational, when a GetCapabilities query (QRY-001) is received from a CapabilitiesService, the sea-api context shall:
  1. Authenticate the request per AuthenticationRequired policy (POL-048-001)
  2. Retrieve the current Capabilities read model via SEA™ Kernel ports (eventual consistency)
  3. Return capabilities including:
     • Editor version and compatibility information
     • List of available editor actions with their input schemas
     • Supported models and their capabilities
     • Feature flags and enabled functionality
  4. Provide structured schema definitions for each capability (REQ-066)
  5. Support capability filtering by type (editor, chat, system)
  6. Return results in JSON format for client consumption

Domain Entities Summary

The sea-api shell contains no domain logic; entities listed here are kernel references or protocol artifacts.

Kernel Domain Entities (Referenced)

• EditorAction: Kernel-defined entity representing editor-native operations (generate, refactor, validate)
• ChatCompletionRequest/Response: Kernel-defined OpenAI-compatible structures for chat interactions
• Capabilities: Kernel-defined capability model with editor version, supported models, and input schemas

Adapter/Protocol Artifacts

• ChatMessage: Individual message in a chat conversation with role, content, and optional name
• OpenAIFacade: Adapter/facade for OpenAI API integration with base URL and API key reference
• EditorActionHandler: Service/handler for editor actions with handler name and active status
• CapabilitiesService: Service for managing capabilities with name and status
• EventBus: Infrastructure pub/sub event bus with topic and subscribers

Policy Rules

• AuthenticationRequired (POL-048-001): All requests must be authenticated
• OpenAIFormatCompatibility (POL-048-002): Enforce OpenAI format for chat endpoints
• StatelessShell (POL-048-003): Gateway must remain stateless

Integration Points

• SEA™ Kernel (libs/sea/*): Delegates all business logic through defined ports; contains no domain logic itself
• Zed IDE: LSP server + HTTP/gRPC endpoints for editor action integration
• LibreChat: OpenAI-compatible /v1/chat/completions API facade
• LLM Provider Context: Integrates for actual LLM model execution
• Message Bus: NATS for event-driven communication and outbox pattern
• Database: PostgreSQL used by SEA™ Kernel for persistence/outbox (shell has no direct DB access) No, the sea-api shell does not have direct DB access; all persistence and outbox work is delegated to the SEA™ Kernel (ADR-033).

Architecture Constraints (per ADR-033)

• Kernel-Shell Separation: Shells contain only composition + configuration; no domain logic
• Stateless Operation: No client state maintained between requests
• Protocol Translation: Acts as pure adapter layer with no business rules
• Independence: Kernel remains runnable without any shells; each shell has own release cadence
• Boundary Enforcement: Nx module boundaries prevent illegal imports between kernel and shells