| # OpenCode-Compatible Provider Integration |
|
|
| ## Goal |
|
|
| Make AbteeX SovereignCode usable from OpenCode and similar coding agents without |
| requiring those tools to understand Data Capsules directly. |
|
|
| The integration shape is: |
|
|
| ```text |
| OpenCode |
| -> OpenAI-compatible provider config |
| -> MaramaRoute gateway `/v1` |
| -> SovereignCode policy and tool broker |
| -> LumynaX model runtime |
| ``` |
|
|
| ## Current Compatibility Target |
|
|
| OpenCode supports custom OpenAI-compatible providers through |
| `@ai-sdk/openai-compatible` and a provider `baseURL`. OpenRouter exposes an |
| OpenAI-like chat endpoint at `/api/v1/chat/completions`, with normalized request |
| and response payloads. MaramaRoute should therefore expose: |
|
|
| - `GET /v1/models` |
| - `POST /v1/chat/completions` |
| - `POST /v1/route` |
| - `GET /v1/route/{decision_id}` |
|
|
| References checked on 2026-05-17: |
|
|
| - https://opencode.ai/docs/providers |
| - https://openrouter.ai/docs/api-reference/overview/ |
| - https://openrouter.ai/docs/api-reference/chat-completion |
|
|
| ## OpenCode Provider Config |
|
|
| Use `examples/opencode.marama-route.json` as the project-local provider file. |
|
|
| The important fields are: |
|
|
| | Field | Value | |
| | --- | --- | |
| | `provider.abteex-marama.npm` | `@ai-sdk/openai-compatible` | |
| | `provider.abteex-marama.options.baseURL` | Local or hosted MaramaRoute `/v1` URL | |
| | `provider.abteex-marama.options.apiKey` | Environment backed key | |
| | `provider.abteex-marama.models` | LumynaX model aliases exposed by MaramaRoute | |
|
|
| ## SovereignCode Responsibilities |
|
|
| OpenCode sends a normal chat request. SovereignCode and MaramaRoute add: |
|
|
| - capsule resolution from workspace policy files |
| - purpose and personal-detail checks before prompt assembly |
| - model routing based on residency, modality, task, and sensitivity |
| - visible approval gates before file writes, shell commands, network export, or commit |
| - audit records for policy decisions and route decisions |
|
|
| ## Workspace Files |
|
|
| A governed workspace should carry: |
|
|
| ```text |
| .sovereigncode/ |
| capsule.json |
| tenant-policy.yaml |
| approvals/ |
| audit/ |
| opencode.json |
| ``` |
|
|
| The agent can start with `capsule.json` and `opencode.json`. The full tool |
| broker can add approvals and audit persistence in the next build stage. |
|
|
| ## Minimum Viable Flow |
|
|
| 1. User opens a project in OpenCode. |
| 2. OpenCode uses the `abteex-marama` provider. |
| 3. MaramaRoute dry-runs the chat payload and selects a LumynaX model. |
| 4. SovereignCode checks the workspace Data Capsule before exposing context. |
| 5. The coding agent proposes a plan. |
| 6. File writes require a visible diff and an audit record. |
| 7. Shell, network, commit, and publish actions require explicit approval. |
|
|
| ## Similar Clients |
|
|
| Any client that can point at an OpenAI-compatible endpoint should use the same |
| gateway: |
|
|
| | Client type | Expected integration | |
| | --- | --- | |
| | OpenCode | `opencode.json` custom provider | |
| | Continue-style IDE assistant | OpenAI-compatible base URL and model ids | |
| | Aider-style terminal assistant | OpenAI-compatible base URL and key | |
| | Internal agent runner | Direct `/v1/route` and `/v1/chat/completions` calls | |
| | Browser console | Same API behind tenant auth | |
|
|
