Database Layer Upgrade & OpenCode Integration - background-agent-railway Zig Port

[gHashTag]

🎯 BIG MISSING FEATURES

Agent: Full implementation of Database Layer and OpenCode Sandbox integration

Repository: gHashTag/trinity
Status: Zig port exists but requires work for production-ready

---

✅ COMPLETED IMPLEMENTATIONS

Component	Files	Status
PostgreSQL client	src/background_agent/db/client.zig	✅ DONE
Sessions CRUD	src/background_agent/db/sessions.zig	✅ DONE
HTTP Server	src/background_agent/server.zig	✅ DONE
Railway Client	src/background_agent/railway/client.zig	✅ DONE
Railway Farm	src/tri/railway_farm.zig	✅ DONE
SSH Manager	src/tri/railway_ssh.zig	✅ DONE
Circuit Breaker	src/tri/railway_circuit_breaker.zig	✅ DONE

---

❌ CRITICAL MISSING FEATURES

Priority 1: Database Layer (blocking issues)

Problems:

• ⚠️ Stub implementation: readAuthResponse() always returns success
• ⚠️ No TLS support (basic TCP without TLS)
• ⚠️ Naive query builder: buildQueryMessage() without parameter binding
• ⚠️ Missing database migrations
• ⚠️ No SQL validation (string formatting is injection-prone)

Required Implementation:

1. Full PostgreSQL wire protocol (Startup → Authentication → Query → DataRow → CommandComplete)
2. Async I/O instead of blocking reads
3. TLS support via std.crypto.tls for production
4. Prepared statements with parameter binding
5. Migration system with versioned schema
6. Migration rollback mechanism

---

Priority 2: OpenCode Sandbox Integration (core missing)

Problems:

• ❌ No OpenCode API client in Zig
• ❌ No Dockerfile for sandbox execution
• ❌ No container lifecycle management
• ❌ No file system abstraction for sandbox
• ❌ No health monitoring for containers
• ❌ No code execution proxy
• ❌ No session result retrieval
• ❌ No sandbox logs streaming

Required Implementation:

1. src/background_agent/opencode/client.zig - HTTP client for OpenCode API

   • createSession(name, image) - create sandbox session
   • executeCode(session_id, code) - execute code in session
   • getSession(session_id) - get session with logs/results
   • getSessionLogs(session_id) - stream execution logs
   • deleteSession(session_id) - terminate session

2. deploy/Dockerfile.sandbox - Multi-stage Dockerfile:

   FROM python:3.11-slim
   RUN pip install -y --no-cache-dir /root/.cache/pip
   COPY requirements.txt /app/
   RUN pip install -r /app/
   WORKDIR /app
   ENV OPENCODE_API_KEY=\${OPENCODE_API_KEY}

3. src/background_agent/container/manager.zig - Lifecycle management via Railway API:

   • createContainer(name, env_id) - via Railway client
   • deleteContainer(service_id) - via Railway client

4. Health monitoring for containers

5. Code execution service (proxy to OpenCode)

---

Priority 3: Auth & Security (blocking for production)

Problems:

• ⚠️ JWT implementation incomplete (src/background_agent/auth/jwt.zig not reviewed)
• ⚠️ No password hashing (bcrypt/argon2)
• ⚠️ No rate limiting on HTTP server

Required Implementation:

1. Complete JWT with HS256 signing and proper claims
2. Password hashing using bcrypt or argon2
3. Rate limiting middleware (token bucket algorithm)
4. API key management

---

Priority 4: Real-time Features (UX critical)

Missing:

• ❌ WebSocket server for live updates
• ❌ SSE endpoints for streaming
• ❌ Live terminal in web UI

Required Implementation:

1. src/background_agent/websocket/server.zig - WebSocket for session updates
2. Session broadcasting to connected clients
3. Web UI components for terminal view

---

Priority 5: Testing & CI/CD (quality gate)

Missing:

• ❌ No E2E tests for OpenCode integration
• ❌ No integration tests
• ❌ No GitHub Actions workflow for background-agent deployment

Required Implementation:

1. tests/background_agent/opencode/ directory
2. tests/background_agent/integration/ directory
3. .github/workflows/background-agent-deploy.yml workflow

---

Priority 6: Monitoring & Observability (production readiness)

Missing:

• ❌ No /api/metrics endpoint
• ❌ No health checks for Railway services
• ❌ No error tracking dashboard
• ❌ No audit logging system

Required Implementation:

1. Metrics collection endpoint
2. Service health monitoring
3. Error tracking with context
4. Structured logging with rotation

---

📊 TECHNICAL PROGRESS

• Railway API Client: 100% (all operations)
• Railway Farm: 100% (multi-account scheduler)
• Circuit Breaker: 100% (production-grade rate limiting)
• Database Layer: 25% (stub implementation)
• OpenCode Integration: 0% (not started)
• Web UI: 0% (React components missing)
• Auth & Security: 10% (JWT structure exists)
• Real-time: 0% (WebSocket missing)
• Testing: 0% (no tests)
• CI/CD: 0% (no workflows)
• Monitoring: 0% (no metrics)

---

Overall Progress: ~25% complete (7/9 production-ready components)

---

📋 IMMEDIATE NEXT STEPS

1. Priority 1: Upgrade PostgreSQL client from stub to full protocol

   • Implement PostgresClient.connect() with full handshake
   • Add PostgresClient.query() with prepared statements
   • Add async I/O for queries
   • Create initial migration: migrations/001_init_sessions.sql

2. Priority 2: Start OpenCode integration

   • Create src/background_agent/opencode/client.zig
   • Implement createSession/executeCode/getSession APIs
   • Create deploy/Dockerfile.sandbox

3. Priority 3: Complete auth implementation

   • Review and complete JWT implementation
   • Add password hashing with argon2
   • Implement rate limiting middleware

---

🔧 FILES TO CREATE/EDIT

src/background_agent/db/client.zig
src/background_agent/db/sessions.zig
src/background_agent/auth/jwt.zig
src/background_agent/opencode/client.zig
deploy/Dockerfile.sandbox
src/background_agent/container/manager.zig
migrations/001_init_sessions.sql