Phase 0: Research & Discovery

Status: Not Started
Purpose: Gather critical information before implementation
Updated: 2026-02-13

Overview

Before implementing the OpenClaw-OpenCode bridge, we need to research several unknowns that will inform architectural decisions.

1. OpenCode ACP Protocol Discovery

Goal: Document OpenCode’s Agent Client Protocol (ACP) endpoints and capabilities

Setup

# Start OpenCode ACP server (if not already running)
opencode acp --port 3333
 
# Or use existing OpenCode web pod
kubectl port-forward -n code-server deployment/opencode-web 8080:8080

Discovery Tasks

Test ACP server startup

opencode acp --help
opencode acp --port 3333
# Document: startup flags, default behavior, logs

Discover HTTP endpoints

# Try common REST patterns
curl -v http://localhost:3333/
curl -v http://localhost:3333/sessions
curl -v http://localhost:3333/health
curl -v http://localhost:3333/version
 
# Try creating a session
curl -v -X POST http://localhost:3333/sessions \
  -H 'Content-Type: application/json' \
  -d '{"project": "repos/test", "model": "anthropic/claude-sonnet-4"}'

Document:

All available endpoints
Request/response formats
Status codes
Error responses

Discover WebSocket endpoints

# Install wscat: npm install -g wscat
 
# Try connecting
wscat -c ws://localhost:3333
wscat -c ws://localhost:3333/stream
wscat -c ws://localhost:3333/sessions/<ID>/stream

Document:

WebSocket endpoint paths
Connection handshake
Message format
Event types emitted

Test session lifecycle

# Create session
SESSION_ID=$(curl -s -X POST http://localhost:3333/sessions \
  -H 'Content-Type: application/json' \
  -d '{"project": "repos/test"}' | jq -r '.session_id')
 
# Send message
curl -X POST http://localhost:3333/sessions/$SESSION_ID/messages \
  -H 'Content-Type: application/json' \
  -d '{"content": "List files in the project"}'
 
# Get session status
curl http://localhost:3333/sessions/$SESSION_ID
 
# List all sessions
curl http://localhost:3333/sessions
 
# Terminate session
curl -X DELETE http://localhost:3333/sessions/$SESSION_ID

Document:

Full CRUD operations
Message sending mechanics
Status/progress endpoints
Session persistence (survive restart?)

Check authentication

# Does ACP require auth tokens?
curl http://localhost:3333/sessions
# 401/403 or unauthenticated access?
 
# Try with Authorization header
curl -H 'Authorization: Bearer fake-token' http://localhost:3333/sessions

Document:

Auth mechanism (bearer token? API key? none?)
How to obtain tokens
CORS policy

Test event streaming

# Connect WebSocket, create session, send message
# Observe what events are emitted
 
# Look for events like:
# - agent.file_opened
# - agent.file_changed
# - agent.command_run
# - agent.complete
# - agent.question
# - agent.error

Document:

All event types
Event payload format
Timing/order of events

Check session history API

# After creating session and sending messages
curl http://localhost:3333/sessions/$SESSION_ID/messages
curl http://localhost:3333/sessions/$SESSION_ID/history

Answer: Does ACP have session history endpoint?

Test session metadata

# Can we set custom metadata when creating session?
curl -X POST http://localhost:3333/sessions \
  -H 'Content-Type: application/json' \
  -d '{
    "project": "repos/test",
    "metadata": {"project_id": "0015", "category": "ai-dev"}
  }'

Answer: Does ACP support session metadata/tags?

Test event filtering

# Can we specify event filtering when creating session?
curl -X POST http://localhost:3333/sessions \
  -H 'Content-Type: application/json' \
  -d '{
    "project": "repos/test",
    "event_mode": "summary"
  }'

Answer: Can we request summary-only events?

Test multi-client attachment

# Open two WebSocket connections to same session
# Send message from one, observe events on both

Answer: Can multiple clients attach to same session?

Test session persistence

# Create session
# Restart OpenCode server
# Try to reconnect to session

Answer: Do sessions persist across server restarts?

Output: Complete acp-protocol.md with all findings

2. Taskfile Builder Tasks Validation

Goal: Verify existing builder tasks work with OpenCode sessions

Test `builder:init`

Create test builder
```
task builder:init BUILDER_NAME=test-0001-validation REPOS=ai-dev
```
Verify:
- .builders/test-0001-validation/ created
- workspace-root worktree exists
- repos/ai-dev/ worktree exists
- All have branch builder/test-0001-validation
Start OpenCode in builder
```
cd .builders/test-0001-validation
opencode acp --cwd . --session test-0001
```
Verify:
- OpenCode starts successfully
- Can see workspace-root files
- Can see ai-dev repo files
- Session accessible via ACP
Test orchestrator access
```
# From workspace root
opencode acp --cwd . --session orchestrator
```
Verify:
- Orchestrator can see all repos
- Orchestrator can see .ai/projectlist.md
- Orchestrator can see .builders/

Test `builder:cleanup`

Cleanup with uncommitted changes (should fail)

cd .builders/test-0001-validation
echo "test" > test.txt
cd ../..
task builder:cleanup BUILDER_NAME=test-0001-validation

Verify:

Cleanup fails with error message
Builder directory NOT deleted

Cleanup clean builder (should succeed)

cd .builders/test-0001-validation
git add test.txt && git commit -m "test"
cd ../..
task builder:cleanup BUILDER_NAME=test-0001-validation

Verify:

Cleanup succeeds
Builder directory deleted
Worktrees removed
Branch deleted

Test `builders:status`

Create builder and check status

task builder:init BUILDER_NAME=test-0002-status REPOS=ai-dev,domain-apis
cd .builders/test-0002-status/repos/ai-dev
echo "test" > test.txt
git add test.txt
cd ../../..
task builders:status

Verify:

Shows builder name
Shows branch for workspace-root
Shows branch for each repo
Shows uncommitted changes (staged in ai-dev)
Shows last commit

Output: Document any issues found, update tasks if needed

3. OpenClaw Event Filtering Capabilities

Goal: Determine how to implement event filtering without AI processing

Research OpenClaw Gateway Architecture

Find OpenClaw gateway code

# Locate gateway implementation
find . -name "*gateway*" -o -name "*openclaw*" | grep -v node_modules

Review event handling
- How does gateway currently handle WebSocket events?
- Can we add hardcoded filtering rules?
- Where would filter logic live?
Check existing filtering patterns
- Are there other tools with event filtering?
- How is it implemented?

Questions to Answer:

Can we add TypeScript/JavaScript filter functions in gateway code?
Can we configure filters without AI processing?
Where should filter configuration live (gateway config vs hardcoded)?
Can we store full event history without AI processing?

Output: Document filtering approach in architecture.md

4. Personal Assistant → Orchestrator Communication

Goal: Determine best way for Personal Assistant to invoke orchestrator

Research OpenClaw Tool System

Review existing tools
```
# Find tool implementations
find . -path "*/openclaw/tools/*" -o -path "*/tools/*"
```
Study:
- How are tools registered?
- How do tools make HTTP calls?
- How do tools handle responses?

Check for ACP client libraries

# Look for existing ACP/OpenCode clients
grep -r "opencode" --include="*.ts" --include="*.js"
grep -r "acp" --include="*.ts" --include="*.js"

Design Options

Option A: Direct ACP calls
- Personal Assistant makes HTTP POST to orchestrator session
- No tool wrapper needed
- Simpler, but less abstraction
Option B: OpenClaw tool wrapper
- Create orchestrator tool that wraps ACP calls
- Personal Assistant calls: orchestrator(action='create_builder', ...)
- More abstraction, consistent with other tools

Decision Criteria:

Does OpenClaw have HTTP client utilities?
Are there similar tools that make API calls?
What’s more maintainable long-term?

Output: Recommend approach in design-questions.md

5. Session History Storage

Goal: Determine where/how to store full event history

Options to Evaluate

Option A: File-based in builder
```
# Test writing events to file
echo '{"type": "agent.complete", "content": "test"}' >> \
  .builders/test-0001/.session-history.jsonl
```
Pros:
- Simple, no dependencies
- History stays with builder
- Easy to inspect/debug
Cons:
- Lost if builder cleaned up
- Not queryable
- Manual management
Option B: ACP session history API
- Use ACP’s built-in history (if exists)
- Query via: GET /sessions/:id/messages
Pros:
- No duplicate storage
- OpenCode manages it
Cons:
- Depends on ACP capability
- Lost if session terminated

Option C: Project metadata

# Store in project directory
mkdir -p .ai/projects/ai-dev/project-0015/session-history
echo '...' > .ai/projects/ai-dev/project-0015/session-history/2026-02-13.jsonl

Pros:

Persists with project
Not tied to builder lifecycle

Cons:

Manual syncing needed
Potentially large files

Output: Recommend storage strategy

6. Integration with `.ai/projectlist.md`

Goal: Validate projectlist schema supports our needs

Review Current Schema

Read projectlist.md
```
cat .ai/projectlist.md
```
Check existing projects
- Do they have repos field? (No, needs to be added)
- Do they have chat_binding field? (No, needs to be added)
- Is files field consistent?

Schema Updates Needed

Add repos field

- id: "0015"
  repos: [ai-dev, domain-apis]  # NEW FIELD

Add chat_binding field (optional)

- id: "0015"
  chat_binding:                # NEW FIELD
    platform: whatsapp
    group_name: "Dev Team"
    trigger: all_messages

Test orchestrator can parse

# Write simple Python script to read projectlist
python3 -c "
import yaml
with open('.ai/projectlist.md') as f:
    content = f.read()
    # Find YAML block
    start = content.find('projects:')
    yaml_content = content[start:]
    data = yaml.safe_load(yaml_content)
    print(data['projects'][0])
"

Output: Document schema additions needed

7. Existing OpenCode Web Pod

Goal: Understand current OpenCode deployment

Check Current Deployment

Inspect OpenCode pod
```
kubectl get pods -n code-server | grep opencode
kubectl describe pod -n code-server <opencode-pod>
```
Questions:
- Is OpenCode web already running?
- What version?
- What port?
- What’s the startup command?

Check if orchestrator session exists

# Port-forward and query
kubectl port-forward -n code-server deployment/opencode-web 8080:8080
curl http://localhost:8080/sessions

Questions:

Can we access ACP endpoints?
Are there existing sessions?
How was it deployed?

Review deployment manifests

find repos/k8s-lab -name "*opencode*"
cat repos/k8s-lab/.../opencode-deployment.yaml

Output: Document current state, required changes

Success Criteria

Phase 0 is complete when:

✅ ACP protocol documented in acp-protocol.md
✅ Builder tasks validated with OpenCode sessions
✅ Event filtering approach decided
✅ Personal Assistant → Orchestrator communication pattern chosen
✅ Session history storage strategy decided
✅ projectlist.md schema updates documented
✅ Current OpenCode deployment understood

Estimated Time: 2-3 days

Next Steps After Phase 0

Once research is complete:

Update architecture documents with findings
Update design-questions.md with answers
Begin Phase 1 implementation (Core Pattern)

Techcle Wiki

Explorer

Phase 0 Research

Phase 0: Research & Discovery

Overview

1. OpenCode ACP Protocol Discovery

Setup

Discovery Tasks

2. Taskfile Builder Tasks Validation

Test `builder:init`

Test `builder:cleanup`

Test `builders:status`

3. OpenClaw Event Filtering Capabilities

Research OpenClaw Gateway Architecture

4. Personal Assistant → Orchestrator Communication

Research OpenClaw Tool System

Design Options

5. Session History Storage

Options to Evaluate

6. Integration with `.ai/projectlist.md`

Review Current Schema

Schema Updates Needed

7. Existing OpenCode Web Pod

Check Current Deployment

Success Criteria

Next Steps After Phase 0

Graph View

Table of Contents

Techcle Wiki

Explorer

Phase 0 Research

Phase 0: Research & Discovery

Overview

1. OpenCode ACP Protocol Discovery

Setup

Discovery Tasks

2. Taskfile Builder Tasks Validation

Test builder:init

Test builder:cleanup

Test builders:status

3. OpenClaw Event Filtering Capabilities

Research OpenClaw Gateway Architecture

4. Personal Assistant → Orchestrator Communication

Research OpenClaw Tool System

Design Options

5. Session History Storage

Options to Evaluate

6. Integration with .ai/projectlist.md

Review Current Schema

Schema Updates Needed

7. Existing OpenCode Web Pod

Check Current Deployment

Success Criteria

Next Steps After Phase 0

Graph View

Table of Contents

Test `builder:init`

Test `builder:cleanup`

Test `builders:status`

6. Integration with `.ai/projectlist.md`