# API Interface Reference

This document organizes the current API surface of `xworkmate-bridge` based on the actual code paths in this repository.

It focuses on:

- the ACP Bridge exposed by `xworkmate-go-core serve`
- the Gemini ACP adapter exposed by `xworkmate-go-core gemini-acp-adapter`
- auxiliary HTTP handlers that exist in code but are not currently mounted by `main.go`

## 1. Runtime Entry Points

The binary currently exposes these runtime modes:

```bash
./build/bin/xworkmate-go-core serve
./build/bin/xworkmate-go-core acp-stdio
./build/bin/xworkmate-go-core gemini-acp-adapter
```

Relevant source:

- [main.go](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/main.go)
- [internal/acp/server.go](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/internal/acp/server.go)
- [internal/geminiadapter/server.go](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/internal/geminiadapter/server.go)

## 2. ACP Bridge HTTP / WebSocket API

### 2.1 Default listen address

`serve` mode reads:

- `ACP_LISTEN_ADDR`, default `127.0.0.1:8787`

### 2.2 Exposed routes

When running `xworkmate-go-core serve`, only these two routes are mounted:

| Path | Protocol | Purpose |
| --- | --- | --- |
| `/acp/rpc` | HTTP POST | JSON-RPC entrypoint |
| `/acp` | WebSocket | ACP over WebSocket |

Any other path returns `404`.

### 2.3 Auth and CORS

Bridge auth is bearer-token based:

- Environment variable: `ACP_AUTH_TOKEN`
- Required header: `Authorization: Bearer <token>`

Origin allowlist comes from:

- `ACP_ALLOWED_ORIGINS`
- default: `https://xworkmate.svc.plus,http://localhost:*,http://127.0.0.1:*`

Behavior summary:

- missing or invalid bearer token: HTTP `401`, JSON-RPC error code `-32001`
- disallowed origin: HTTP `403`, JSON-RPC error code `-32003`
- `OPTIONS /acp/rpc` is supported for CORS preflight

Relevant source:

- [internal/acp/server.go](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/internal/acp/server.go)
- [internal/acp/web_contract.go](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/internal/acp/web_contract.go)

### 2.4 Content negotiation

For `POST /acp/rpc`:

- normal JSON-RPC response: `Content-Type: application/json`
- if `Accept` contains `text/event-stream`, the server streams notifications as SSE and sends the final JSON-RPC result through SSE as well

### 2.5 JSON-RPC methods exposed by the bridge

The bridge currently handles these methods:

| Method | Description |
| --- | --- |
| `acp.capabilities` | Return current bridge capability summary |
| `session.start` | Start a task session |
| `session.message` | Continue an existing session |
| `session.cancel` | Cancel an active session |
| `session.close` | Close session state |
| `xworkmate.dispatch.resolve` | Resolve provider choice from candidate providers and requirements |
| `xworkmate.routing.resolve` | Resolve execution target / provider / skills from routing metadata |
| `xworkmate.providers.sync` | Sync external single-agent provider catalog into the bridge |
| `xworkmate.mounts.reconcile` | Reconcile managed MCP configuration and mount-related settings |
| `xworkmate.gateway.connect` | Connect bridge runtime to gateway |
| `xworkmate.gateway.request` | Send a request to the connected gateway runtime |
| `xworkmate.gateway.disconnect` | Disconnect gateway runtime |

Unknown methods return JSON-RPC error code `-32601`.

## 3. Bridge Method Details

### 3.1 `acp.capabilities`

Request:

```json
{
  "jsonrpc": "2.0",
  "id": "cap-1",
  "method": "acp.capabilities"
}
```

Response shape:

```json
{
  "jsonrpc": "2.0",
  "id": "cap-1",
  "result": {
    "singleAgent": true,
    "multiAgent": true,
    "providers": ["codex", "gemini", "opencode"],
    "capabilities": {
      "single_agent": true,
      "multi_agent": true,
      "providers": ["codex", "gemini", "opencode"]
    }
  }
}
```

Notes:

- `providers` is the union of:
  - synced external providers from `xworkmate.providers.sync`
  - locally detected ACP providers from `shared.DetectACPProviders()`
- `multiAgent` is controlled by `ACP_MULTI_AGENT_ENABLED`, default `true`

### 3.2 `session.start`

Starts a session and resets any existing state with the same `sessionId`.

Minimum required params:

```json
{
  "sessionId": "session-1"
}
```

Typical request:

```json
{
  "jsonrpc": "2.0",
  "id": "task-1",
  "method": "session.start",
  "params": {
    "sessionId": "session-1",
    "threadId": "thread-1",
    "taskPrompt": "Reply with exactly pong",
    "workingDirectory": "/tmp/demo",
    "routing": {
      "routingMode": "explicit",
      "explicitExecutionTarget": "singleAgent",
      "explicitProviderId": "opencode"
    }
  }
}
```

Rules:

- `sessionId` is required, otherwise `-32602`
- `threadId` defaults to `sessionId`
- work is queued per `threadId`
- for public single-agent multi-turn usage, `routing` should be resent on later turns

### 3.3 `session.message`

Continues an existing session.

Minimum required params:

```json
{
  "sessionId": "session-1"
}
```

Typical request:

```json
{
  "jsonrpc": "2.0",
  "id": "task-2",
  "method": "session.message",
  "params": {
    "sessionId": "session-1",
    "threadId": "thread-1",
    "taskPrompt": "Continue the previous task",
    "workingDirectory": "/tmp/demo",
    "routing": {
      "routingMode": "explicit",
      "explicitExecutionTarget": "singleAgent",
      "explicitProviderId": "opencode"
    }
  }
}
```

### 3.4 `session.cancel`

Request:

```json
{
  "jsonrpc": "2.0",
  "id": "cancel-1",
  "method": "session.cancel",
  "params": {
    "sessionId": "session-1"
  }
}
```

Response:

```json
{
  "accepted": true,
  "cancelled": true
}
```

### 3.5 `session.close`

Request:

```json
{
  "jsonrpc": "2.0",
  "id": "close-1",
  "method": "session.close",
  "params": {
    "sessionId": "session-1"
  }
}
```

Response:

```json
{
  "accepted": true,
  "closed": true
}
```

### 3.6 `xworkmate.dispatch.resolve`

Purpose:

- choose a provider from a list of candidates
- apply preferred provider and capability constraints
- optionally consider node state and node info

Key params:

- `providers`: array of provider definitions
- `preferredProviderId`
- `requiredCapabilities`
- `nodeState`
- `nodeInfo`

Provider item shape:

```json
{
  "id": "codex",
  "name": "Codex",
  "defaultArgs": ["app-server"],
  "capabilities": ["singleAgent", "tools"]
}
```

### 3.7 `xworkmate.routing.resolve`

Purpose:

- resolve routing metadata into:
  - execution target
  - endpoint target
  - provider
  - model
  - selected skills
  - install suggestion / unavailable state

Key input fields:

- `taskPrompt`
- `workingDirectory`
- `routing.routingMode`
- `routing.preferredGatewayTarget`
- `routing.explicitExecutionTarget`
- `routing.explicitProviderId`
- `routing.explicitModel`
- `routing.explicitSkills`
- `routing.allowSkillInstall`
- `routing.installApproval`
- `routing.availableSkills`
- `aiGatewayBaseUrl`
- `aiGatewayApiKey`

Representative response fields:

- `resolvedExecutionTarget`
- `resolvedEndpointTarget`
- `resolvedProviderId`
- `resolvedModel`
- `resolvedSkills`
- `skillResolutionSource`
- `needsSkillInstall`
- `unavailable`
- `unavailableCode`
- `unavailableMessage`
- `skillInstallRequestId`
- `skillCandidates`
- `memorySources`

### 3.8 `xworkmate.providers.sync`

Purpose:

- register external ACP single-agent providers into the bridge

Request example:

```json
{
  "jsonrpc": "2.0",
  "id": "sync-1",
  "method": "xworkmate.providers.sync",
  "params": {
    "providers": [
      {
        "providerId": "opencode",
        "label": "OpenCode",
        "endpoint": "https://acp-server.svc.plus/opencode/acp/rpc",
        "authorizationHeader": "Bearer ${OPENCODE_AUTH_TOKEN}",
        "enabled": true
      }
    ]
  }
}
```

Provider fields:

- `providerId`
- `label`
- `endpoint`
- `authorizationHeader`
- `enabled`

Response shape:

```json
{
  "ok": true,
  "providers": [
    {
      "providerId": "opencode",
      "label": "OpenCode",
      "endpoint": "https://acp-server.svc.plus/opencode/acp/rpc",
      "enabled": true
    }
  ]
}
```

### 3.9 `xworkmate.mounts.reconcile`

Purpose:

- reconcile managed MCP server config for supported local tools and homes

Key params:

- `config.autoSync`
- `config.usesAris`
- `config.managedMcpServers`
- `aiGatewayUrl`
- `configuredCodexCliPath`
- `codexHome`
- `opencodeHome`
- `openclawHome`
- `aris`

Managed MCP server item shape:

```json
{
  "id": "xworkmate_server",
  "command": "xworkmate-mcp",
  "args": ["--port", "7777"],
  "enabled": true
}
```

### 3.10 Gateway runtime methods

#### `xworkmate.gateway.connect`

Purpose:

- connect a bridge runtime session to the gateway runtime

Key params:

- `runtimeId`
- `mode`
- `clientId`
- `locale`
- `userAgent`
- `connectAuthMode`
- `connectAuthFields`
- `connectAuthSources`
- `hasSharedAuth`
- `hasDeviceToken`
- `endpoint.host`
- `endpoint.port`
- `endpoint.tls`
- `packageInfo`
- `deviceInfo`
- `identity`
- `auth`

Response fields:

- `ok`
- `snapshot`
- `auth`
- `returnedDeviceToken`
- `error`

#### `xworkmate.gateway.request`

Purpose:

- send a gateway runtime RPC-like request through an existing runtime connection

Params:

- `runtimeId`
- `method`
- `params`
- `timeoutMs`

Response fields:

- `ok`
- `payload`
- `error`

#### `xworkmate.gateway.disconnect`

Params:

- `runtimeId`

Response:

```json
{
  "accepted": true
}
```

## 4. WebSocket Contract

`/acp` accepts the same JSON-RPC method set as `/acp/rpc`.

Differences from HTTP:

- each inbound message is a JSON-RPC request frame
- notifications are written back as WebSocket JSON messages
- result envelopes and error envelopes are also written as WebSocket JSON messages

## 5. Gemini ACP Adapter API

### 5.1 Default listen address

`gemini-acp-adapter` reads:

- `GEMINI_ADAPTER_LISTEN_ADDR`, default `127.0.0.1:8791`

### 5.2 Exposed routes

When running `xworkmate-go-core gemini-acp-adapter`, only these routes are mounted:

| Path | Protocol | Purpose |
| --- | --- | --- |
| `/acp/rpc` | HTTP POST | Adapter JSON-RPC entrypoint |
| `/acp` | WebSocket | Adapter WebSocket JSON-RPC entrypoint |

### 5.3 Auth and CORS

Adapter auth is separate from bridge auth:

- Environment variable: `GEMINI_ADAPTER_AUTH_TOKEN`
- Required header: `Authorization: Bearer <token>`

Allowed origins come from:

- `GEMINI_ADAPTER_ALLOWED_ORIGINS`
- default: `https://xworkmate.svc.plus,http://localhost:*,http://127.0.0.1:*`

### 5.4 Adapter JSON-RPC methods

| Method | Description |
| --- | --- |
| `acp.capabilities` | Synthesized Gemini single-agent capability response |
| `session.start` | Start adapter-local Gemini session |
| `session.message` | Continue adapter-local Gemini session |
| `session.cancel` | Accept cancel request, currently returns `cancelled: false` |
| `session.close` | Close adapter-local session |
| `gemini.initialize` | Return upstream initialize result |
| `gemini.raw` | Forward raw Gemini-facing payload handling |

Unsupported methods return:

```json
{
  "success": false,
  "error": "unsupported method: <method>"
}
```

### 5.5 Core adapter env vars

- `GEMINI_ADAPTER_LISTEN_ADDR`
- `GEMINI_ADAPTER_BIN`
- `GEMINI_ADAPTER_ARGS`
- `GEMINI_ADAPTER_PROTOCOL_VERSION`
- `GEMINI_ADAPTER_AUTH_TOKEN`
- `GEMINI_ADAPTER_PROVIDER_ID`
- `GEMINI_ADAPTER_PROVIDER_LABEL`
- `GEMINI_ADAPTER_ALLOWED_ORIGINS`
- `GEMINI_ADAPTER_UPSTREAM_METHOD`
- `ACP_GEMINI_BIN`

## 6. Auxiliary HTTP Handlers Present in Code

The repository also contains two plain HTTP handlers:

- [internal/handler/auth_handler.go](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/internal/handler/auth_handler.go)
- [internal/handler/token_auth_handler.go](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/internal/handler/token_auth_handler.go)

These handlers are currently not mounted by `main.go`, so they are not part of the live binary HTTP routing surface unless another embedding program wires them in.

### 6.1 Username/password auth handler

Request body:

```json
{
  "username": "demo",
  "password": "secret"
}
```

Behavior:

- invalid JSON -> `400 invalid json`
- auth failure -> `401 <error message>`
- success -> `200 {"status":"ok"}`

### 6.2 Bearer token auth handler

Behavior:

- no service -> `503 service unavailable`
- invalid bearer token -> `401 unauthorized`
- success -> `200 {"ok":true}`

## 7. Public Deployment Notes

Existing project docs already record the current public ingress convention:

- Bridge-facing public ACP HTTP JSON-RPC path: `.../acp/rpc`
- WebSocket ACP path: `.../acp`

Reference docs:

- [docs/acp-public-validation-2026-04-09.md](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/docs/acp-public-validation-2026-04-09.md)
- [docs/gemini-acp-adapter.md](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/docs/gemini-acp-adapter.md)
- [docs/architecture/acp-forwarding-topology.md](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/docs/architecture/acp-forwarding-topology.md)

## 8. Suggested Maintenance Rule

If a new externally callable method is added to:

- [internal/acp/server.go](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/internal/acp/server.go)
- [internal/geminiadapter/server.go](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/internal/geminiadapter/server.go)

then this document should be updated in the same change.