xworkmate-bridge/docs/api-reference.md

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:

./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
• internal/acp/server.go
• 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
• 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:

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

Response shape:

{
  "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:

{
  "sessionId": "session-1"
}

Typical request:

{
  "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:

{
  "sessionId": "session-1"
}

Typical request:

{
  "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:

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

Response:

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

3.5 session.close

Request:

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

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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
• 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:

{
  "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
• docs/gemini-acp-adapter.md
• docs/architecture/acp-forwarding-topology.md

8. Suggested Maintenance Rule

If a new externally callable method is added to:

• internal/acp/server.go
• internal/geminiadapter/server.go

then this document should be updated in the same change.