67225a39fa
Config policies (16 files): alert_routing, architecture_pressure, backlog, cost_weights, data_governance, incident_escalation, incident_intelligence, network_allowlist, nodes_registry, observability_sources, rbac_tools_matrix, release_gate, risk_attribution, risk_policy, slo_policy, tool_limits, tools_rollout Ops (22 files): Caddyfile, calendar compose, grafana voice dashboard, deployments/incidents logs, runbooks for alerts/audit/backlog/incidents/sofiia/voice, cron jobs, scripts (alert_triage, audit_cleanup, migrate_*, governance, schedule), task_registry, voice alerts/ha/latency/policy Docs (30+ files): HUMANIZED_STEPAN v2.7-v3 changelogs and runbooks, NODA1/NODA2 status and setup, audit index and traces, backlog, incident, supervisor, tools, voice, opencode, release, risk, aistalk, spacebot Made-with: Cursor
140 lines
3.8 KiB
Markdown
140 lines
3.8 KiB
Markdown
# 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.
|