Techcle Wiki

Phase 0 Findings

5 min read

Phase 0 Research Findings

Status: ✅ COMPLETE
Started: 2026-02-14
Completed: 2026-02-16
OpenCode Version: 1.1.53
Duration: ~2 days

1. OpenCode ACP/Server Discovery

Initial Findings

OpenCode Commands Available:

  • opencode acp - start ACP (Agent Client Protocol) server
  • opencode serve - starts a headless opencode server
  • opencode web - start opencode server and open web interface
  • opencode attach <url> - attach to a running opencode server

Server Startup

opencode serve --port 3333 --hostname 127.0.0.1:

  • ✅ Starts successfully
  • ✅ Listens on http://127.0.0.1:3333
  • ⚠️ Warns: “OPENCODE_SERVER_PASSWORD is not set; server is unsecured”
  • Serves web UI on root path /
  • All routes return HTML (web UI)

opencode acp --port 3333 --hostname 127.0.0.1:

  • Started but behavior unclear
  • Did not bind to HTTP port as expected
  • May be a different protocol/connection model
  • Requires further investigation

Web UI Observations

Root endpoint / serves HTML:

<!doctype html>
<html lang="en">
  <title>OpenCode</title>
  ...
  <script type="module" src="/assets/index-CtVOE8w2.js"></script>
  <div id="root"></div>
</html>

This suggests:

  • OpenCode 1.1.53 is primarily a web-based application
  • Protocol may be WebSocket-based (not REST HTTP)
  • Need to inspect browser WebSocket connections to understand protocol

2. Next Steps for ACP Discovery

Option A: Web UI Protocol Inspection

  • Open http://localhost:3333 in browser
  • Open DevTools → Network → WS (WebSocket) tab
  • Create a session via UI
  • Document WebSocket messages exchanged
  • Reverse-engineer the protocol

Option B: Source Code Review

  • Check OpenCode GitHub repository
  • Look for ACP protocol documentation
  • Review client/server WebSocket message formats

Option C: Ask OpenCode Community

  • Check OpenCode Discord/Slack
  • Review GitHub issues/discussions
  • Look for ACP examples

Option D: Use Existing OpenCode Web Pod

Per design-questions.md Q1.3 answer:

“We already run opencode web in a separate pod (codev in the code-server ns)”

Action: Connect to existing deployment and observe its behavior

kubectl port-forward -n code-server deployment/codev 8080:8080
# Then test endpoints

3. Questions Raised

  1. Is ACP a WebSocket protocol?

    • Initial evidence suggests yes
    • opencode serve binds HTTP but serves web UI
    • Real protocol likely over WebSocket

  2. Does opencode acp work differently than opencode serve?

    • Both have same flags (—port, —hostname)
    • opencode serve succeeded, opencode acp unclear
    • May need to use opencode serve for our use case

  3. How do we programmatically create sessions?

    • If WebSocket-based, need to:
      • Establish WebSocket connection
      • Send session creation message
      • Handle responses

  4. Is there HTTP API underneath?

    • All HTTP requests return HTML
    • May need WebSocket for everything
    • Or HTTP API might be on different path (need discovery)

Immediate Priority:

  1. Inspect existing codev pod deployment to see how it’s configured
  2. Review OpenCode documentation for ACP protocol spec
  3. Web UI protocol inspection to understand WebSocket messages

Based on Findings:

  • If WebSocket-only → Implement WebSocket client in Gateway
  • If HTTP API exists → Document endpoints and use HTTP
  • If hybrid → Use appropriate protocol for each operation

5. Taskfile Builder Tasks Validation

Postponed until we understand how to start OpenCode sessions programmatically.

Once we know the protocol:

  • Create test builder: task builder:init BUILDER_NAME=test-0001 REPOS=ai-dev
  • Start OpenCode in builder
  • Validate session creation/messaging
  • Test builders:status integration

6. Current OpenCode Deployment

Local Installation

  • ✅ OpenCode 1.1.53 installed at /home/coder/.opencode/bin/opencode
  • ✅ Can start server with opencode serve

K8s Deployment

Need to check:

kubectl get pods -n code-server | grep -i codev
kubectl describe pod -n code-server <codev-pod>
kubectl exec -n code-server <codev-pod> -- opencode --version

7. Blocking Issues

CRITICAL: ACP Protocol Unknown

Cannot proceed with implementation until we understand:

  • How to create sessions programmatically
  • What messages to send/receive
  • WebSocket vs HTTP API
  • Session management operations

Recommended Action:

  1. Review OpenCode source code / documentation
  2. Inspect existing codev deployment
  3. Web UI protocol inspection
  4. Consult OpenCode community if needed

8. Updated Timeline

Original estimate: Phase 0 = 2-3 days

Current status:

  • Day 1: Initial discovery (OpenCode is WebSocket-based, not REST)
  • Need: Protocol documentation or reverse engineering
  • Estimate: +1-2 days for protocol discovery

Revised estimate: 3-5 days for complete Phase 0

Final Results ✅

What We Discovered

Two Protocols Available:

  1. ACP (JSON-RPC over stdio) - For editor integrations (VSCode, Cursor)
    • Not suitable for OpenClaw
  2. HTTP REST + SSE - For programmatic access ✅
    • Perfect for OpenClaw Gateway integration

HTTP REST API Endpoints:

  • ✅ GET /project - List all projects/workspaces
  • ✅ POST /session - Create session
  • ✅ GET /session - List all sessions (workspace-specific!)
  • ✅ GET /session/:id - Get session details
  • ✅ GET /session/:id/message - Get all messages
  • ✅ POST /session/:id/message - Send message (tested end-to-end!)
  • ✅ GET /global/event - SSE event stream
  • ✅ GET /global/health - Health check

Critical Discovery - Workspace Isolation:

  • ⚠️ Server is workspace-specific: Must start opencode web from the target workspace directory
  • Sessions/messages are scoped to the workspace where the server started
  • For multiple builders, need multiple OpenCode servers (one per workspace)
  • /project endpoint lists all available workspaces

Session Storage:

  • Location: ~/.local/share/opencode/storage/session/<project-id>/
  • Format: JSON files per session
  • Includes: ID, title, directory, permissions, timestamps, summary

Authentication:

  • Optional: OPENCODE_SERVER_PASSWORD environment variable
  • Default: Unsecured (warning on startup)

Documentation Created

  1. opencode-protocol-discovered.md - Complete HTTP API documentation
  2. phase-0-findings.md - Research journey and discoveries
  3. Updated phase-0-research.md - Original research plan

Blocking Issues Resolved

✅ All critical blocking questions answered ✅ Full API documented and tested end-to-end ✅ Workspace isolation understood: Server must start from target workspace ✅ Multi-workspace strategy: Run multiple OpenCode servers (one per builder) ✅ Ready for Phase 1 implementation

End-to-End Test Results

Test performed (2026-02-16):

  1. ✅ Started opencode web from /home/coder/src
  2. ✅ Listed sessions via GET /session - confirmed orchestrator session visible
  3. ✅ Sent message via POST /session/ses_3ae187259ffeMdIpeZbzA5R4ZU/message
  4. ✅ Received response from Claude via this session
  5. ✅ Retrieved messages via GET /session/:id/message

Conclusion: Full OpenCode HTTP API integration is viable and tested.

Next Phase

Phase 1: Core Pattern

  • Build OpenCode HTTP client library (TypeScript/Node.js)
  • Handle workspace isolation (multiple server instances)
  • Implement Gateway integration
  • Implement event filtering (hardcoded rules, no AI)
  • Test with real builder workspaces
  • Integrate with Orchestrator pattern

Estimated Time: 2-3 days

Graph View