Skip to main content

OpenCode Integration

This page describes how OpenCode (the agent coding tool) integrates with the Yabanin gateway — i.e., the gateway-side contract: which models OpenCode is routed to, how subscription executors are delegated, and how an OpenCode-driven session is governed (budgets, task tagging, guard hooks).

Local development, stand-up, and credential handling are covered in the Development Guide. This page does not repeat that setup; it documents the integration surface itself.

Model routing for the yabanin agent​

The yabanin OpenCode agent talks to the gateway's OpenAI-compatible endpoint (POST /v1/chat/completions). The gateway routes each request by task shape, so the agent's "thinking model" and its "fast coder" can be different providers under one key. The routing decision is exposed on the X-Yabanin-Decision response header (see Agent Governance — Decision header) so a session can log why a given response used a given model.

Agent wiring (make opencode-remote-wire, the public stand at https://yabanin.ai/gw) routes the OpenCode agents through Yabanin gateway models and routes by task shape:

RouteModelUsed for
Primary agent yabaninthe configured planning modelSession leading, planning, complex reasoning.
Subagent reasonthe configured analysis modelDeep analysis, architecture, trade-offs, research synthesis.
Subagent codethe configured local coderClear, well-specified code edits — templates, tests, docs, instruction-driven refactors.
Subagent complex-codethe configured flash model (with fallback)Heavy algorithmic codegen.

The concrete model names are deployment configuration (registry / org routing settings), not part of the gateway contract. What the contract guarantees: a request is routed deterministically by class, the decision is logged, and cache / cost / tier accounting all apply exactly as they do for any API-key client.

Subscription delegation (tr_delegate)​

For hard coding tasks, OpenCode can delegate to a Codex or Cursor subscription executor through the local MCP tool tr_delegate:

  • tr_delegate { mode: "analyze" | "implement", task: "…", provider?: "auto" | "codex" | "cursor" }
  • analyze is read-only review; implement writes to the workspace.
  • provider: auto picks the available executor; codex / cursor force one.
  • tr_delegation_status reports whether each executor is configured (it does not return credentials).

Delegation is off by default and enabled with YABANIN_DELEGATION_ENABLED=true. Credentials stay on the machine (Codex from ~/.codex/auth.json, Cursor from official agent login); the gateway never sees them. Delegation is a sidecar concern (services/subscription-bridge/); the gateway only handles the OpenAI-compatible chat/tool traffic.

Delegate only when the in-agent routes above are not enough — the leading model should use its native tools for ordinary work.

Governing an OpenCode session​

Because an OpenCode-driven session is just a gateway client, the full agent governance surface applies. The practical recommendations:

  • Task tag every logical unit of work. Send X-Yabanin-Task per task (e.g. stand-opencode/feature-42). This makes the session's spend attributable in CTOR / task analytics and lets you cap it with YABANIN_TASK_TOKEN_BUDGET.
  • Cap runaway sessions. Set YABANIN_TASK_TOKEN_BUDGET (recommended 500000) and/or YABANIN_SESSION_TOKEN_BUDGET (recommended 200000). At ≥80% the gateway sets X-Yabanin-Budget-Warning; at 100% it returns a 429 the client can back off on.
  • Route cheap work to cheap hours. Enable YABANIN_TIME_ROUTING with a YABANIN_TIME_CHEAP_WINDOW (default 22:00-07:00); batch work (X-Yabanin-Batch: true) is always downgraded, interactive work can opt out with X-Yabanin-Priority: high.
  • Screen egress. For sessions that may emit sensitive data, run YABANIN_GUARD_MODE=log (observe) and tighten to redact / deny once the false-positive profile is known. See the guard-hook FP caveat.
  • Verify the lineage. After a run, yb lineage verify --org <org> confirms the per-request attestation chain is intact, and yb lineage export … --s3 … --lock-compliance produces a WORM evidence copy. See Lineage — hash chain + export.

Evaluation before shipping routing changes​

Because OpenCode traffic is the real load on the router, regression-test routing and guard changes with the offline suites before they reach a stand:

make evaluate-routing
make evaluate-guards

See Evaluation Suites.