microdao-daarion/docs/opencode/sofiia_setup.md

OpenCode ↔ Sofiia Integration

Sofiia (CTO agent) is exposed to OpenCode via the DAARION router tool execution endpoint. No extra adapter service is required for basic tool calls.

---

1. Environment variables

Variable	Description	Example
ROUTER_URL	Base URL of the DAARION router	http://localhost:8000 or http://router:8000
SUPERVISOR_API_KEY	Optional. If set, router requires Authorization: Bearer <key> on /v1/tools/execute	(secret)

Set these in your OpenCode environment or in the config that invokes Sofiia.

---

2. Agent endpoint (for OpenCode “invoke agent”)

• Tool execution (primary):
  POST {ROUTER_URL}/v1/tools/execute

• Chat / inference:
  POST {ROUTER_URL}/v1/agents/sofiia/infer

OpenCode can treat Sofiia as an agent whose “tools” are executed by POSTing to /v1/tools/execute with a JSON body (see below). There is no separate “invoke” URL; tool execution is the invocation.

---

3. Tool execution contract

Request:

POST /v1/tools/execute
Content-Type: application/json
Authorization: Bearer <SUPERVISOR_API_KEY>   # optional

{
  "tool": "risk_engine_tool",
  "action": "service",
  "agent_id": "sofiia",
  "env": "prod",
  "service": "gateway"
}

Response:

{
  "status": "succeeded",
  "data": { ... },
  "error": null
}

or on failure:

{
  "status": "failed",
  "data": null,
  "error": {
    "code": "tool_error",
    "message": "...",
    "retryable": false
  }
}

All parameters beyond tool, action, and agent_id are passed as the tool’s arguments (e.g. env, service, task_id, inputs).

---

4. Hello-world: one tool call

export ROUTER_URL="http://localhost:8000"
# Optional: export SUPERVISOR_API_KEY="your-key"

curl -s -X POST "$ROUTER_URL/v1/tools/execute" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SUPERVISOR_API_KEY" \
  -d '{
    "tool": "backlog_tool",
    "action": "dashboard",
    "agent_id": "sofiia",
    "env": "prod"
  }'

Expected: "status": "succeeded" and "data" with backlog summary.

---

5. How to verify (one command)

From the repo root:

python3 ops/scripts/verify_sofiia_stack.py --router-url "$ROUTER_URL"

This checks:

• Router /healthz (or /health)
• Dry-run tool calls: risk_engine_tool.service, architecture_pressure_tool.service, backlog_tool.dashboard
• Presence of governance cron entries in ops/cron/jobs.cron
• Optional: supervisor health if SUPERVISOR_URL is set

Exit code 0 = all checks PASS.

---

6. Typical tools for OpenCode-driven flows

Tool	Action	Typical use
risk_engine_tool	service, dashboard	Risk score / dashboard
architecture_pressure_tool	service, dashboard, digest	Pressure index, weekly digest
backlog_tool	dashboard, list, create, auto_generate_weekly	Backlog ops
job_orchestrator_tool	start_task	e.g. task_id: "release_check" for release gates
oncall_tool	incident_create, list	Incidents
incident_intelligence_tool	correlate, recurrence, weekly_digest	Intelligence

OpenCode can “Ask Sofiia to run release_check” by calling /v1/tools/execute with tool: "job_orchestrator_tool", action: "start_task", task_id: "release_check", inputs: { "gate_profile": "staging" }.

---

7. Sofiia Control Console (optional)

A minimal web UI for chat + ops + nodes is provided by sofiia-console (NODA2 primary):

• Chat: proxy to POST /v1/agents/sofiia/infer
• Ops: Risk/Pressure/Backlog/Release check via POST /v1/tools/execute
• Nodes: dashboard from config/nodes_registry.yml

See services/sofiia-console/ and runbook for deployment. OpenCode integration does not depend on the console; the console is for human operators.