# 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:**

```http
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:**

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

or on failure:

```json
{
  "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

```bash
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:

```bash
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.