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