ACP Gateway Integration Architecture

Explanation: Deep dive into how the ACP Gateway integrates SEA-Forge™ with Zed IDE and external services.

Overview

The ACP (Agent Communication Protocol) Gateway is SEA-Forge™’s bridge between Zed IDE and the semantic execution stack. It implements a JSON-RPC 2.0 server that exposes SEA™ capabilities as IDE-native tools.

Architecture Location: Integration Adapter Layer (per AGENTS.md §Integration Adapter Exception)

Specification References:

SDS-048: Platform UI Integration
SDS-049: LLM Provider Service
SDS-003: Knowledge Graph Service
SDS-002: Semantic Core & DSL Management
SDS-021: Delivery Pipeline Service

Component Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Zed IDE                                  │
│  (sends JSON-RPC requests via stdio)                            │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ JSON-RPC 2.0 (stdio)
                             │
┌────────────────────────────▼────────────────────────────────────┐
│                      ACP Gateway                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │   Message    │  │  Tool        │  │  Capability  │          │
│  │   Handler    │  │  Executor    │  │  Registry    │          │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘          │
│         │                 │                 │                   │
│         └─────────────────┴─────────────────┘                   │
│                           │                                      │
└───────────────────────────┼──────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
        ▼                   ▼                   ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ LLM Provider │  │  Knowledge   │  │  Validation  │
│   Service    │  │    Graph     │  │  + Pipeline  │
│  (HTTP API)  │  │ (Oxigraph/   │  │  (subprocess)│
│              │  │   rdflib)    │  │              │
└──────────────┘  └──────────────┘  └──────────────┘
  SDS-049           SDS-003           SDS-002/021

Key Design Decisions

1. Graceful Degradation

Problem: External services may not be running (LLM, Oxigraph).

Solution: Multi-tier fallback strategy for each capability.

Example - Chat Completion:

1. Try: HTTP call to LLM service (localhost:8000)
   ↓ fails
2. Try: Return informative echo message
   ↓ always succeeds
3. Result: User gets response + guidance to start service

Example - Knowledge Graph:

1. Try: HTTP call to Oxigraph (localhost:7878)
   ↓ fails
2. Try: In-memory RDF via rdflib + .snapshot.json files
   ↓ fails
3. Try: Return empty results + error message
   ↓ always succeeds

2. Optional Dependencies

Problem: Not all users need all integrations.

Solution: Conditional imports with runtime checks.

try:
    import httpx
except ImportError:
    httpx = None  # type: ignore

# Later in code
if httpx is None:
    return {"error": "Install httpx: pip install httpx"}

Benefits:

Core functionality works without optional deps
Clear error messages guide installation
Testing doesn’t require full stack

3. Interface Preservation

Problem: Zed IDE expects consistent JSON-RPC responses.

Solution: Wrapper pattern maintains contract even when services fail.

# Always returns valid JSON-RPC response
{
    "success": bool,
    "result": {...} | None,
    "error": str | None
}

Invariant: No exceptions escape to Zed IDE (caught and converted to error responses).

Integration Points

1. LLM Provider Service (SDS-049)

Endpoint: POST http://localhost:8000/v1/chat/completions

Request:

{
  "messages": [
    {"role": "user", "content": "Validate specs in docs/specs/orders/"}
  ],
  "model": "ollama/llama3.2",
  "temperature": 0.7,
  "max_tokens": 500
}

Response:

{
  "id": "chatcmpl-...",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "I'll validate the specifications..."
      },
      "finish_reason": "stop"
    }
  ]
}

Implementation:

async with httpx.AsyncClient(timeout=30.0) as client:
    response = await client.post(
        f"{llm_service_url}/v1/chat/completions",
        json={"messages": messages, "model": model}
    )

Fallback: Echo response with service start instructions.

2. Knowledge Graph Service (SDS-003)

Oxigraph Endpoint: POST http://localhost:7878/query

Request:

POST /query HTTP/1.1
Accept: application/sparql-results+json
Content-Type: application/x-www-form-urlencoded

query=SELECT ?entity WHERE { ?entity rdf:type sea:Entity }

Response:

{
  "results": {
    "bindings": [
      {"entity": {"type": "uri", "value": "http://sea-forge.com/concept/orders/Entity/Order"}}
    ]
  }
}

Fallback - In-Memory RDF:

graph = rdflib.Graph()
for snapshot_file in glob.glob(f"docs/specs/{context}/*.snapshot.json"):
    snapshot = json.load(open(snapshot_file))
    turtle_rdf = snapshot["rdf_turtle"]
    graph.parse(data=turtle_rdf, format="turtle")

results = graph.query(sparql)  # Execute locally

Fallback Chain:

Oxigraph HTTP (distributed, persistent)
rdflib in-memory (local, ephemeral)
Error message (no SPARQL capability)

3. Validation Service (SDS-002)

Subprocess Call: python tools/validate_sds.py <file>

Implementation:

result = subprocess.run(
    [sys.executable, "tools/validate_sds.py", path],
    capture_output=True,
    text=True,
    timeout=30
)

if result.returncode != 0:
    errors.append(result.stderr.strip())

Why Subprocess?

Validation is synchronous, file-based operation
No need for HTTP overhead
Reuses existing CLI tool
Natural isolation (separate process)

4. Pipeline Service (SDS-021)

Just Command: just pipeline <context>

Implementation:

result = subprocess.run(
    ["just", "pipeline", spec_id],
    cwd=repo_root,
    capture_output=True,
    timeout=120
)

# Parse generated files from output
output_lines = result.stdout.strip().split('\n')
generated_files = [
    line for line in output_lines
    if 'generated' in line.lower()
]

Why Just Command?

Pipeline is complex multi-stage process
Just recipe orchestrates: AST → IR → Manifest → Codegen
Ensures consistent execution environment
120s timeout for large generations

Error Handling Strategy

Principle: Fail Gracefully, Guide Users

Every integration point follows this pattern:

try:
    # Primary: Attempt service call
    result = await call_service(...)
    if result.status_code == 200:
        return success_response(result)
    else:
        # Service returned error
        return error_response_with_guidance(result)
except ConnectionError:
    # Service not running
    return {"error": "Service unavailable. Start with: uvicorn ..."}
except TimeoutError:
    # Service too slow
    return {"error": "Service timeout. Check service health."}
except ImportError:
    # Dependency missing
    return {"error": "Install dependency: pip install httpx"}
except Exception as e:
    # Unexpected error
    return {"error": f"Unexpected error: {str(e)}"}

Never:

Let exceptions propagate to Zed IDE
Return malformed JSON-RPC responses
Hang indefinitely (always use timeouts)

Always:

Provide actionable error messages
Include service start instructions
Log errors for debugging
Maintain JSON-RPC contract

Performance Considerations

Timeouts

Service	Timeout	Rationale
LLM	30s	Chat completion typically < 10s
Validation	30s	File I/O + schema validation
Pipeline	120s	Large contexts may generate 50+ files
Oxigraph	10s	SPARQL queries are fast or hanging

Caching Strategy

Current: No caching (stateless gateway)

Future Optimization:

Cache validation results (invalidate on file change)
Cache SPARQL query results (TTL: 5 minutes)
Connection pooling for HTTP clients

Concurrency

Current: Serial execution per request (simple, correct)

Future Optimization:

Parallel execution for independent tools
Connection pooling (httpx AsyncClient reuse)
Background task queue for long-running pipeline

Testing Strategy

Unit Tests

Located in tests/acp/test_acp_gateway.py:

async def test_handle_send_message():
    gateway = ACPGateway()
    result = await gateway._handle_send_message({
        "message": {"role": "user", "content": "hello"}
    })
    assert "response" in result
    assert result["response"]["role"] == "agent"

Coverage:

✅ Gateway initialization
✅ JSON-RPC request/response parsing
✅ Handler routing
✅ Error response formatting

Not Covered (integration tests):

Actual service calls (mocked)
Timeout behavior
Service failover logic

Integration Tests

Recommended: Add tests/acp/test_integration.py

@pytest.mark.integration
async def test_llm_service_integration():
    """Test with real LLM service running."""
    gateway = ACPGateway()

    # Start LLM service in background
    proc = subprocess.Popen(["uvicorn", "services.llm-provider.main:app"])
    await asyncio.sleep(2)  # Wait for startup

    try:
        result = await gateway._handle_send_message({
            "message": {"role": "user", "content": "hello"}
        })
        assert result["response"]["content"] != "Service unavailable"
    finally:
        proc.kill()

Deployment

Local Development

# Terminal 1: Start LLM service
cd services/llm-provider
uvicorn main:app --reload

# Terminal 2: Start Oxigraph
docker run -p 7878:7878 oxigraph/oxigraph serve

# Terminal 3: Run ACP Gateway
python -m libs.sea.adapters.acp.src.main

Production (Kubernetes)

# deployment.yaml
apiVersion: v1
kind: Service
metadata:
  name: acp-gateway
spec:
  selector:
    app: acp-gateway
  ports:
    - port: 8080
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: acp-gateway
spec:
  replicas: 2
  template:
    spec:
      containers:
      - name: acp-gateway
        image: sea-forge/acp-gateway:latest
        env:
        - name: LLM_PROVIDER_URL
          value: "http://llm-provider:8000"
        - name: OXIGRAPH_URL
          value: "http://oxigraph:7878"

Monitoring

OpenTelemetry Spans

Future: Add OTel instrumentation per SDS-030

from opentelemetry import trace

tracer = trace.get_tracer("acp-gateway")

async def _handle_send_message(self, params):
    with tracer.start_as_current_span("acp.send_message") as span:
        span.set_attribute("message.role", params["message"]["role"])
        # ... implementation

Metrics

Recommended:

acp_requests_total{method, status} - Counter
acp_request_duration_seconds{method} - Histogram
acp_service_errors_total{service} - Counter

Security Considerations

1. No Authentication (Current)

Status: ACP Gateway runs on stdio (local process)

Threat Model: Zed IDE is trusted (user’s local machine)

Future: If exposing via HTTP, add JWT authentication

2. No Authorization

Status: All capabilities exposed to Zed IDE

Mitigation: Capabilities are read-only or sandbox-safe

Validation: reads files, no writes
Pipeline: writes to **/src/gen/** only (per codegen rules)
SPARQL: read-only queries

3. Command Injection

Risk: User-controlled strings in subprocess calls

Mitigation:

# BAD: Shell injection risk
subprocess.run(f"just pipeline {user_input}", shell=True)

# GOOD: Array args (no shell)
subprocess.run(["just", "pipeline", user_input], shell=False)

4. Dependency Security

httpx: Pinned to 0.28.1, audit for CVEs rdflib: Pinned to 7.5.0, audit for CVEs

Policy: Update dependencies monthly via Dependabot

Future Enhancements

Phase 1: Performance

Connection pooling for HTTP clients
Cache validation results (5 min TTL)
Parallel tool execution

Phase 2: Observability

OpenTelemetry spans (SDS-030)
Prometheus metrics endpoint
Structured logging (JSON)

Phase 3: Resilience

Circuit breaker for failing services
Exponential backoff retries
Health check endpoint

Phase 4: Features

Streaming responses for chat
Batch validation (multiple files)
Pipeline progress updates

ACP Types - JSON-RPC data models
SDS-048 - Platform UI Integration
SDS-049 - LLM Provider Service
AGENTS.md - Integration Adapter Exception rules
Test Suite - Unit tests

Summary

The ACP Gateway demonstrates SEA-Forge™’s graceful degradation philosophy:

Primary: Use production services (LLM, Oxigraph) when available
Fallback: Use local alternatives (echo, in-memory RDF) when not
Guidance: Always provide actionable error messages

This design enables:

✅ Development without full stack running
✅ Progressive enhancement as services come online
✅ Clear error messages guide troubleshooting
✅ Zero assumptions about deployment environment

Result: Zed IDE integration works out-of-the-box, scales to production.

ACP Gateway Integration Architecture

Overview

Component Architecture

Key Design Decisions

1. Graceful Degradation

2. Optional Dependencies

3. Interface Preservation

Integration Points

1. LLM Provider Service (SDS-049)

2. Knowledge Graph Service (SDS-003)

3. Validation Service (SDS-002)

4. Pipeline Service (SDS-021)

Error Handling Strategy

Principle: Fail Gracefully, Guide Users

Performance Considerations

Timeouts

Caching Strategy

Concurrency

Testing Strategy

Unit Tests

Integration Tests

Deployment

Local Development

Production (Kubernetes)

Monitoring

OpenTelemetry Spans

Metrics

Security Considerations

1. No Authentication (Current)

2. No Authorization

3. Command Injection

4. Dependency Security

Future Enhancements

Phase 1: Performance

Phase 2: Observability

Phase 3: Resilience

Phase 4: Features

Related Documentation

Summary