opencode-ext-connector 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.7.0 - 2026-09-23
+
+- Add the opt-in `xaiOAuth.mode: "authority" | "consumer"` package subpath
+  pairing a host-side authority with a guest-side consumer; omitting
+  `xaiOAuth` disables the integration silently, while a present `xaiOAuth`
+  whose `mode` is missing or unknown is rejected at parse time
+- Ship the dedicated `./xai` consumer as a separate OpenCode plugin entry
+  that returns the xAI auth hook only with `methods: []`
+- Invoke the fixed helper at `${HOME}/.local/bin/opensandbox-xai-auth-sync`
+  with no arguments, `PATH=/usr/local/bin:/usr/bin:/bin`, `HOME` always
+  set, and `XDG_DATA_HOME` forwarded only when absolute; the helper
+  delegates projection to the OpenSandbox manager, and a non-zero exit
+  retries after `5000` ms without removing the xAI provider
+- Re-read the access file and `expires` on every outbound request and raise
+  `XaiAccessUnavailableError` before any network call on a missing file,
+  a stat that fails the closed-v1 `0600`/single-link/current-user gates,
+  a schema mismatch, a `"state": "unavailable"` record, malformed JSON,
+  or a non-future `expires`
+- Never place a refresh token inside the guest; refresh stays on the host
+  authority only
+- Keep existing Claude, Cursor, Command Code, and Ollama providers and
+  omitted-mode behavior unchanged
+
+## 0.6.0 - 2026-09-16
+
+- Add the recommended `credentialRole: "owner" | "reader"` option for shared
+  Claude logins: one Linux owner runs the existing Claude CLI authority while
+  readers consume externally managed credentials without refreshing them
+- Keep the existing low-level credential policy options available for advanced
+  control, but reject combining any of them with `credentialRole`
+- Keep omitted credential policy behavior and non-Claude providers unchanged
+
 ## 0.5.0 - 2026-09-15
 
 - Add the disabled-by-default Claude CLI credential authority for Linux

package/README.md

@@ -19,7 +19,7 @@
 
 ## Status
 
-> Independent unofficial community plugin, version **0.5.0**. Package E2E tests exercise the legacy multi-function loader with the OpenCode CLI installed in CI. `@opencode-ai/plugin@1.18.18` is the compile-time plugin API target, not a runtime pin. Source is BSD-3-Clause. This project is not affiliated with, endorsed by, sponsored by, or authorized by OpenCode or any provider. Full terms are in [License and Disclaimer](#license-and-disclaimer).
+> Independent unofficial community plugin, version **0.7.0**. Package E2E tests exercise the legacy multi-function loader with the OpenCode CLI installed in CI. `@opencode-ai/plugin@1.18.18` is the compile-time plugin API target, not a runtime pin. Source is BSD-3-Clause. This project is not affiliated with, endorsed by, sponsored by, or authorized by OpenCode or any provider. Full terms are in [License and Disclaimer](#license-and-disclaimer).
 
 Reuse the Claude, Cursor, Command Code, and Ollama sessions you already have. One `opencode.json` plugin entry publishes live catalogs into OpenCode. Claude and Cursor stay disconnected until OpenCode has a marker or OAuth record and the vendor session is present. Command Code may use an OpenCode-stored direct API key or an existing CLI session/key. Ollama requires the exact session marker plus a responsive trusted daemon.
 
@@ -55,13 +55,13 @@ OpenCode installs configured npm plugins with Bun at startup and caches them. Fo
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-ext-connector@0.5.0"]
+  "plugin": ["opencode-ext-connector@0.7.0"]
 }
 ```
 
 Fully quit and restart OpenCode after adding or changing the entry; a reload is not enough.
 
-The one package entry exposes the catalog plugin plus the Claude, Cursor, Command Code, and Ollama auth hooks. Provider ids: `claude`, `cursor`, `command-code`, `ollama`. Model ids come from each provider's live catalog, with documented fallbacks `default` (Cursor) and `Qwen/Qwen3.8-Max` (Command Code) when a live list is empty.
+The one package entry exposes the catalog plugin plus the Claude, Cursor, Command Code, and Ollama auth hooks. Provider ids: `claude`, `cursor`, `command-code`, `ollama`. Model ids come from each provider's live catalog, with documented fallbacks `default` (Cursor) and `Qwen/Qwen3.8-Max` (Command Code) when a live list is empty. The opt-in xAI consumer ships as the package subpath `opencode-ext-connector/xai`; see [Opt-in xAI OAuth authority and consumer](#opt-in-xai-oauth-authority-and-consumer-host-and-guest).
 
 ## Configuration
 
@@ -73,10 +73,12 @@ Omitted `providers` enables all four. An explicit list is a strict allow-list. E
 | --- | --- | --- |
 | `providers` | all four | Provider ids to register: `claude`, `cursor`, `command-code`, `ollama`; explicit `[]` disables all |
 | `ollamaBaseURL` | `"http://localhost:11434"` | Absolute `http` or `https` base for the trusted Ollama daemon; path prefixes are preserved |
-| `credentialManagement` | omitted | Preferred authority policy: `"connector"` authorizes refresh and writeback where an adapter supports both; `"external"` prohibits connector refresh and writeback |
+| `credentialRole` | omitted | Recommended shared-login setup: `"owner"` runs the Claude CLI authority on the one credential-owning instance; `"reader"` only reads externally managed credentials |
+| `credentialManagement` | omitted | Advanced policy: `"connector"` authorizes refresh and writeback where an adapter supports both; `"external"` prohibits connector refresh and writeback |
 | `writeBackCredentials` | `false` | **Deprecated:** accepted alone for one migration cycle; controls Claude writeback after refresh |
 | `credentialRefresh.mode` | `"auto"` | **Deprecated:** accepted alone for one migration cycle; controls Claude `"auto"` or `"never"` refresh behavior |
 | `credentialRefresh.leadMs` | `60000` | **Deprecated:** accepted alone for one migration cycle; custom lead times still require this legacy configuration |
+| `xaiOAuth.mode` | omitted | Opt-in xAI role; `"authority"` enables the host observer on the `connectorServer` entry and `"consumer"` activates the dedicated `opencode-ext-connector/xai` consumer. Omitting `xaiOAuth` disables the integration silently. A present `xaiOAuth` whose `mode` is missing or not one of `"authority" | "consumer"` is rejected at parse time. Independent of every Claude credential option. |
 | `credentialAuthority.claudeCli.enabled` | `false` | Claude-only opt-in: see [Opt-in Claude CLI authority timer](#opt-in-claude-cli-authority-timer-claude-only) |
 | `credentialAuthority.claudeCli.leadMs` | `300000` | Claude-only opt-in: milliseconds before credential expiry at which the timer invokes `claude`; non-negative integer |
 | `credentialAuthority.claudeCli.retryMs` | `300000` | Claude-only opt-in: milliseconds to wait before retrying after a non-zero exit, lock conflict, signal, or supervisor failure; positive integer |
@@ -85,6 +87,34 @@ Omitted `providers` enables all four. An explicit list is a strict allow-list. E
 | `health.initialBackoffMs` | `1000` | Health backoff after a failed snapshot |
 | `health.maximumBackoffMs` | `60000` | Health backoff cap |
 
+### Credential ownership (recommended)
+
+Choose `"owner"` on the one Linux instance that owns and refreshes the shared Claude Code login:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [["opencode-ext-connector", { "credentialRole": "owner" }]]
+}
+```
+
+Choose `"reader"` on every instance that only consumes synchronized credentials:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [["opencode-ext-connector", { "credentialRole": "reader" }]]
+}
+```
+
+`"owner"` internally selects external credential management and enables the Claude CLI authority with its default timing. `"reader"` selects external credential management without starting the CLI authority. The role describes credential ownership, not whether OpenCode runs on a physical host or in a sandbox guest.
+
+Set exactly one owner per shared Claude login. Owner mode requires Linux, util-linux `flock`, Claude Code `2.1.259` or later on `PATH`, and an authenticated Claude Code session. Each authority invocation is a real model request and may consume account usage. A revoked login still requires interactive `/login`.
+
+Do not combine `credentialRole` with `credentialManagement`, `credentialAuthority`, `credentialRefresh`, or `writeBackCredentials`. Existing low-level configurations remain supported for advanced control.
+
+### Advanced credential policy
+
 `credentialManagement: "connector"` authorizes the connector to refresh and write back credentials where a provider adapter supports both. Today only Claude has that capability, mapping to automatic refresh with a `60_000` ms lead and writeback enabled:
 
 ```jsonc
@@ -143,17 +173,17 @@ With all credential-policy options omitted, refreshed Claude tokens stay in memo
 
 Anthropic rotates the refresh token on every refresh and invalidates the previous one. Two copies of `~/.claude/.credentials.json` that both refresh will therefore break each other. Copying the file works only if exactly one machine refreshes and every other machine receives the result before its own copy expires:
 
-- **Refresh authority** (where you log in): choose exactly one refresh path. Use `credentialManagement: "connector"`, or on Linux use `credentialManagement: "external"` with the opt-in [Claude CLI authority timer](#opt-in-claude-cli-authority-timer-claude-only). The parser rejects enabling the CLI timer in connector mode. If you need a custom publication window for connector mode, use the deprecated legacy options alone for this migration cycle, for example `writeBackCredentials: true` with `credentialRefresh: { mode: "auto", leadMs: 1800000 }`.
-- **External-authority machines**: `credentialManagement: "external"`. They never contact the OAuth endpoint; when a request returns 401 they re-read externally managed credentials and retry once.
+- **Credential owner** (where you log in): use `credentialRole: "owner"` on one Linux instance. For advanced control, use `credentialManagement: "connector"`, or combine `credentialManagement: "external"` with the opt-in [Claude CLI authority timer](#opt-in-claude-cli-authority-timer-claude-only).
+- **Credential readers**: use `credentialRole: "reader"`. They never contact the OAuth endpoint; when a request returns 401 they re-read externally managed credentials and retry once.
 - Synchronize the externally managed credential material from the refresh-authority machine whenever it changes. The option itself does not synchronize machines or require file storage; if you copy `~/.claude/.credentials.json`, OpenCode's own `auth.json` only needs the `anthropic` record once and its other providers should remain untouched.
 
 Machines that refresh on their own — including a Claude Code install that is used interactively — must not share the file. Log in separately there.
 
 ### Opt-in Claude CLI authority timer (Claude-only)
 
-This Linux-only option lets one host use an existing Claude Code login as the refresh authority for an externally managed credential file. It is disabled by default, does not log in or mint tokens, and requires `credentialManagement: "external"`.
+This is the advanced form of `credentialRole: "owner"`, useful when custom `leadMs` or `retryMs` values are required. It is disabled by default, does not log in or mint tokens, and requires `credentialManagement: "external"`.
 
-Minimal configuration:
+Low-level equivalent:
 
 ```jsonc
 {
@@ -182,6 +212,58 @@ Each invocation is a real model request and can count against the account's subs
 
 If the timer does not run, check `flock --version`, `claude --version`, the state directory permissions, and both required configuration values. Repeated warnings indicate that the CLI failed, was signalled, or could not be started. To disable the timer, remove `credentialAuthority` or set `enabled` to `false`, then fully restart OpenCode.
 
+### Opt-in xAI OAuth authority and consumer (host and guest)
+
+This connector ships an opt-in xAI path that pairs a host-side **authority** with a guest-side **consumer**. The roles are independent of `credentialRole`, `credentialManagement`, `credentialAuthority`, `credentialRefresh`, and `writeBackCredentials`, and never modify or replace any Claude policy. Omitting `xaiOAuth` disables the integration silently. A present `xaiOAuth` whose `mode` is missing or not one of `"authority" | "consumer"` is rejected at parse time.
+
+Configure the two roles in separate OpenCode environments. On the host:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [["opencode-ext-connector", { "xaiOAuth": { "mode": "authority" } }]]
+}
+```
+
+In the guest:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [["opencode-ext-connector/xai", { "xaiOAuth": { "mode": "consumer" } }]]
+}
+```
+
+**Authority (host).** Set `xaiOAuth.mode: "authority"` on the host `connectorServer` entry. The observer reads `${XDG_DATA_HOME}/opencode/auth.json` when `XDG_DATA_HOME` is set and absolute, or `${HOME}/.local/share/opencode/auth.json` on Linux only when `XDG_DATA_HOME` is unset or empty. A relative `XDG_DATA_HOME` (set but not absolute) disables the authority: it neither reads `auth.json` nor invokes the helper. When enabled, the observer inspects **only** the `xai` record. When that record's serialized fingerprint changes, the observer invokes the fixed, no-argument helper at `${HOME}/.local/bin/opensandbox-xai-auth-sync` with `PATH` set to `/usr/local/bin:/usr/bin:/bin`, `HOME` always set, and `XDG_DATA_HOME` forwarded when absolute. The helper delegates projection to the OpenSandbox manager; the connector never writes the guest access file, mints or refreshes xAI OAuth, ships tokens across machines, or places a refresh token inside the guest. A non-zero helper exit is treated as transient and retried after `5000` ms without removing the xAI provider.
+
+**Consumer (guest).** Load the consumer as a separate OpenCode plugin entry as the tuple `["opencode-ext-connector/xai", { "xaiOAuth": { "mode": "consumer" } }]`. The mode is required: a subpath entry without it returns an empty hook and the xAI provider stays disconnected. With mode `"consumer"` the connector returns the xAI auth hook and exposes no `/connect` methods — `methods: []` is part of the public contract. The consumer requires the exact marker
+
+```jsonc
+{ "type": "api", "key": "cli-session:xai" }
+```
+
+in the OpenCode auth record for the `xai` provider. The connector does not place this marker; provisioning it is the operator's responsibility. Any other shape means the loader returns no auth. As a sentinel, the loader returns a placeholder `apiKey` plus a wrapped `fetch`; the real bearer is sourced from the access file on every outbound request.
+
+**Access file.** The consumer re-reads the access file on **every** request and never trusts an in-memory token:
+
+- Path: `${XDG_DATA_HOME}/opencode/xai-access.json` when `XDG_DATA_HOME` is set and absolute, or `${HOME}/.local/share/opencode/xai-access.json` on Linux when `XDG_DATA_HOME` is unset or empty. A relative `XDG_DATA_HOME` fails closed without inspecting the HOME fallback.
+- File gates: regular file, mode `0600`, link count `1`, owned by the current user. A missing file, a non-conforming stat, a symlink, a multi-link file, the wrong owner, or the wrong mode all return the unavailable state.
+- Schema (closed v1):
+
+```jsonc
+{
+  "schema_version": 1,
+  "provider": "xai",
+  "state": "ready",
+  "access": "<bearer-token>",
+  "expires": 1735689600000
+}
+```
+
+A `"state": "unavailable"` record, malformed JSON, a schema mismatch, an absent file, a failed stat, or an `expires` not strictly greater than the current time all fail **before** any network call, raising `XaiAccessUnavailableError` for the request. The bearer token never enters plugin arguments, connector stdout/stderr diagnostics, or request URLs.
+
+**Out of scope.** Ordinary xAI API keys stored directly in OpenCode auth (the built-in `XAI_API_KEY`-style path) follow OpenCode's built-in `xai` provider, not this authority/consumer pair. The connector never imports, mirrors, or proxies such keys. The helper must be idempotent; running a developer Claude Code session in the same guest does not give it authority over the projected access file.
+
 ## Host/Guest Sandbox Setup
 
 When OpenCode runs in a container, VM, or another sandbox, treat that runtime as the **guest** and the machine that owns the vendor logins and Ollama daemon as the **host**. The guest has its own `localhost`, home directory, environment, keychains, filesystem permissions, and network namespace. Host sessions are not visible unless you mount their files or inject their environment values explicitly.
@@ -190,10 +272,11 @@ The safest shared-session layout keeps each vendor login owned and refreshed by
 
 | Provider | Host | Guest |
 | --- | --- | --- |
-| Claude | Own and refresh the Claude Code login | Mount the Claude credential directory read-only, set `CLAUDE_CONFIG_DIR` to that guest path, and use `credentialManagement: "external"`; a host macOS Keychain is not available inside a Linux guest; resolve the client version with `ANTHROPIC_CLI_VERSION`, an installed `claude` binary, or npm registry access |
+| Claude | Own and refresh the Claude Code login | Mount the Claude credential directory read-only, set `CLAUDE_CONFIG_DIR` to that guest path, and use `credentialRole: "reader"`; a host macOS Keychain is not available inside a Linux guest; resolve the client version with `ANTHROPIC_CLI_VERSION`, an installed `claude` binary, or npm registry access |
 | Cursor | Own the Cursor CLI login | Mount the credential file at the guest's `${HOME}/.config/cursor/auth.json` read-only, or inject `CURSOR_ACCESS_TOKEN` through the sandbox's secret mechanism; install Node.js 22 or later in the guest |
 | Command Code | Own the CLI login or API key | Mount `${HOME}/.commandcode/auth.json` read-only, or inject `COMMAND_CODE_API_KEY`; resolve the client version with `COMMAND_CODE_CLI_VERSION`, an installed `command-code` binary, or npm registry access |
 | Ollama | Run the trusted daemon and run `ollama signin` there when Cloud access is needed | Copy no Ollama credential; connect only to the daemon selected by `ollamaBaseURL` |
+| xAI | Host authority invokes `~/.local/bin/opensandbox-xai-auth-sync`; the OpenSandbox manager projects access-only guest state | Use the manager-projected `{"type":"api","key":"cli-session:xai"}` marker and `${XDG_DATA_HOME}/opencode/xai-access.json` (or the HOME fallback when XDG is unset or empty), then load `opencode-ext-connector/xai` with `xaiOAuth.mode: "consumer"`; never copy or mount a refresh token |
 
 For example, a Linux guest can use these paths and optional secret/version overrides; adapt the mount source and destination to the sandbox runtime:
 
@@ -220,7 +303,7 @@ Use this complete guest `opencode.json` when all four providers are enabled and
       {
         "providers": ["claude", "cursor", "command-code", "ollama"],
         "ollamaBaseURL": "http://host.docker.internal:11434",
-        "credentialManagement": "external",
+        "credentialRole": "reader",
         "catalogReloadMs": 300000,
         "snapshotTimeoutMs": 30000,
         "health": {
@@ -233,7 +316,7 @@ Use this complete guest `opencode.json` when all four providers are enabled and
 }
 ```
 
-`ollamaBaseURL` is a flat connector option in the package tuple, not an OpenCode provider option. The numeric values above are the connector defaults; `credentialManagement: "external"` and the host daemon URL are deliberate overrides for read-only host-owned credentials. Do not put vendor tokens in `opencode.json`; pass them through read-only mounts or the sandbox's secret injection mechanism.
+`ollamaBaseURL` is a flat connector option in the package tuple, not an OpenCode provider option. The numeric values above are the connector defaults; `credentialRole: "reader"` and the host daemon URL are deliberate overrides for read-only host-owned credentials. Do not put vendor tokens in `opencode.json`; pass them through read-only mounts or the sandbox's secret injection mechanism.
 
 For Docker Desktop, `host.docker.internal` normally resolves to the host. A Linux Docker bridge may also need `--add-host=host.docker.internal:host-gateway` or the Compose equivalent:
 
@@ -244,7 +327,7 @@ extra_hosts:
 
 Ollama normally listens on host loopback. For bridge networking, the host may need to start it with `OLLAMA_HOST=0.0.0.0:11434`; restrict the exposed port with host firewall and sandbox network policy. `OLLAMA_HOST` configures the host daemon, while `ollamaBaseURL` configures this connector in the guest. Host networking makes guest `localhost` reach the host but reduces isolation and should be an explicit choice. Other sandbox runtimes need an equivalent host route and must allow outbound access to each enabled provider; allow `registry.npmjs.org` only when Claude or Command Code cannot resolve its client version from an environment value or installed binary.
 
-Alternatively, the guest can own its vendor logins in persistent guest storage. In that mode, run vendor login flows in the guest instead of mounting host credentials. A guest that is the sole Claude refresh owner may use `credentialManagement: "connector"`. Never let the host and guest independently refresh credentials descended from the same Claude refresh token.
+Alternatively, the guest can own its vendor logins in persistent guest storage. In that mode, run vendor login flows in the guest instead of mounting host credentials. A Linux guest that is the sole Claude refresh owner may use `credentialRole: "owner"`; low-level `credentialManagement: "connector"` remains available for connector-managed OAuth refresh and writeback. Never let the host and guest independently refresh credentials descended from the same Claude refresh token.
 
 ## Update and Remove
 
@@ -278,15 +361,18 @@ Ollama `/connect` probes the configured daemon and stores the exact session mark
 
 | Provider | What it does |
 | --- | --- |
-| **Claude** | Reuses existing Claude Code credentials. Does not mint OAuth. Compatibility fetch sends CLI-compatible request metadata and streams Anthropic SSE on the built-in `anthropic` path. `credentialManagement: "connector"` maps to auto-refresh with a `60_000` ms lead and writeback; `"external"` maps to never-refresh/no-write with a credential re-read after 401. On Linux only, `credentialManagement: "external"` plus the opt-in `credentialAuthority.claudeCli.enabled: true` timer (see [Opt-in Claude CLI authority timer](#opt-in-claude-cli-authority-timer-claude-only)) can keep an externally managed credential file current by invoking the local `claude` CLI; the timer is off by default and does not log in or extend the underlying session lifetime. Omitting all credential-policy options preserves legacy auto/`60_000` behavior without writeback; if only `credentialManagement` is omitted, supplied deprecated options still control behavior. |
+| **Claude** | Reuses existing Claude Code credentials. Does not mint OAuth. Compatibility fetch sends CLI-compatible request metadata and streams Anthropic SSE on the built-in `anthropic` path. For shared logins, `credentialRole: "owner"` enables the Linux-only Claude CLI authority on one instance, while `"reader"` keeps every other instance read-only with a credential re-read after 401. Low-level `credentialManagement: "connector"` maps to auto-refresh with a `60_000` ms lead and writeback; `"external"` maps to never-refresh/no-write. Omitting all credential-policy options preserves legacy auto/`60_000` behavior without writeback; if only `credentialManagement` is omitted, supplied deprecated options still control behavior. |
 | **Cursor** | Calls Cursor's unpublished client protocol (`api2.cursor.sh` `AgentService`, Connect+protobuf over HTTP/2) with the CLI access token. Credentials remain read-only under both credential-management modes. Direct generation may re-read a changed, non-null credential and retry once only on an exact HTTP 401 before output or effects; this is not refresh or writeback. Legacy/compatibility generation remains one-shot. A plugin-owned Node child communicates over private stdio, keeps tool results on the same bidi Run, never replays parked calls, opens no user-facing daemon, and never spawns `cursor-agent` for generation. Unofficial; not a public Cursor API. After protocol drift there is no implicit fallback — that provider fails. Requires Node.js 22 or later. Live catalog ids are used when present; otherwise the documented fallback is `default`. |
 | **Command Code** | Calls `/alpha/generate` with CLI-compatible request metadata and streams provider-local NDJSON text and tool events. Credentials remain read-only under both credential-management modes. On an exact HTTP 401 before output or effects, it may re-read a changed, non-null credential and retry once only; this is not refresh or writeback. The client version comes from `COMMAND_CODE_CLI_VERSION`, an installed `command-code` binary, or the npm registry. Request metadata includes Node.js version, platform, architecture, and the absolute working directory. Live catalog ids are used when present; otherwise the documented fallback is `Qwen/Qwen3.8-Max`. |
 | **Ollama** | Unaffected by `credentialManagement`. Uses the trusted daemon selected by `ollamaBaseURL` (default `http://localhost:11434`) with `/api/tags`, `/api/pull`, and `/api/chat`; path prefixes are preserved. Publishes models already pulled there, plus exact Cloud tags discovered anonymously from Ollama's official Cloud search and library pages, without connector-supplied credentials. Local entries win exact duplicates. Incomplete Cloud refreshes retain the last complete list. Selecting an absent authorized Cloud tag pulls its lightweight remote reference on first use; concurrent pulls of the same tag and normalized base share one in-flight request, and a failed pull can be retried later. The daemon may then proxy Cloud-tag prompts under the user's Ollama Cloud subscription. The connector never uses an Ollama API key, the usage-billed direct Cloud API, `OLLAMA_HOST`, credentials, custom headers, cookies, or a direct Cloud generation endpoint. |
+| **xAI** | Opt-in OAuth consumer loaded only through the package subpath `opencode-ext-connector/xai`. The access file is re-read on every request, exposes no `/connect` methods, and never mints or refreshes xAI OAuth. Independent of Claude `credentialRole` and credential policy. See [Opt-in xAI OAuth authority and consumer](#opt-in-xai-oauth-authority-and-consumer-host-and-guest). |
 
 Provider health is isolated: one provider failing does not remove the others.
 
 The standalone SDK entry is `opencode-ext-connector/ollama`; pass `{ ollamaBaseURL }` to select the same trusted daemon. It can generate with models already present there; connector-managed Cloud auto-pull requires an active Ollama catalog lease for that normalized base.
 
+The dedicated consumer entry is `opencode-ext-connector/xai`; pass `{ xaiOAuth: { mode: "consumer" } }` to register the xAI auth hook without registering any model providers, models, or `/connect` methods.
+
 ## Troubleshooting
 
 | Symptom | What to check |
@@ -294,12 +380,14 @@ The standalone SDK entry is `opencode-ext-connector/ollama`; pass `{ ollamaBaseU
 | `/connect` methods missing | Confirm `plugin` contains `"opencode-ext-connector"` or an exact published `"opencode-ext-connector@<version>"` spec, then fully restart OpenCode. |
 | Provider enabled but no models | Omitted `providers` enables all four; an explicit list is a strict allow-list. Claude and Cursor need a marker or OAuth record plus the vendor session; Command Code may use an OpenCode-stored API key or a CLI session/key; Ollama needs the exact marker plus a responsive configured daemon. Fully restart after `/connect` so instance reconstruction picks up new membership. |
 | Claude works until the next start | Omitting all credential-policy options preserves legacy in-memory refresh without writeback. A rotated refresh token can then fail on the next process start; use `credentialManagement: "connector"` when the connector should refresh and write back. If only `credentialManagement` is omitted, check supplied deprecated refresh/writeback options instead. |
-| Claude reports `invalid_grant` on shared credentials | Another machine with the same login already refreshed and rotated the refresh token. Every refresher counts: `credentialManagement: "connector"` refreshes through the OAuth endpoint, and the opt-in `credentialAuthority.claudeCli.enabled` timer refreshes through the local `claude` CLI. Pick exactly one authority: either connector mode, or external mode with the CLI timer on one Linux machine. Keep every other machine on `"external"` with the timer disabled, or log in separately. |
-| Configuration rejects credential options | Do not combine the new and legacy options; the exact error is: `` `credentialManagement` cannot be combined with deprecated `credentialRefresh` or `writeBackCredentials` ``. Legacy options remain accepted alone for one migration cycle. |
+| Claude reports `invalid_grant` on shared credentials | Another machine with the same login already refreshed and rotated the refresh token. Set `credentialRole: "owner"` on exactly one Linux instance and `"reader"` everywhere else, or use exactly one documented low-level authority path. Every refresher counts, including connector OAuth refresh and the Claude CLI timer. |
+| Configuration rejects credential options | Do not combine `credentialRole` with any low-level credential option. The exact role-conflict error is: `` `credentialRole` cannot be combined with `credentialManagement`, `credentialAuthority`, `credentialRefresh`, or `writeBackCredentials` ``. Low-level options remain accepted alone; `credentialManagement` still cannot be combined with deprecated refresh/writeback options. |
 | `Claude Code client version is unavailable` | No `ANTHROPIC_CLI_VERSION`, no `claude` binary, and `registry.npmjs.org` was unreachable. Set the variable or allow registry access. |
 | Cursor generation fails | Node.js 22 or later is required. Generation uses the unpublished protocol through a private Node child, not `cursor-agent`. Protocol drift fails that provider; there is no implicit fallback. |
 | Command Code generation fails | The client version could not be resolved: set `COMMAND_CODE_CLI_VERSION`, install `command-code`, or allow access to `registry.npmjs.org`. Request metadata includes Node.js version, platform, architecture, and the absolute working directory. |
 | Ollama missing from `opencode models ollama` | Start a daemon you trust at `ollamaBaseURL` (or the default `localhost:11434`), then `/connect` so the exact session marker can be stored. Confirm any path prefix reaches Ollama's `/api/*` routes. Cloud tags are anonymous catalog entries; `OLLAMA_HOST`, API keys, credential headers, redirects, and direct Cloud generation are not used. |
+| Per-request xAI calls fail with `XaiAccessUnavailableError` | Confirm `xaiOAuth.mode` is `"authority"` on the host `connectorServer` entry and `"consumer"` on the `opencode-ext-connector/xai` subpath entry, the OpenCode auth record holds exactly `{"type":"api","key":"cli-session:xai"}`, and the access file at `${XDG_DATA_HOME}/opencode/xai-access.json` (or `${HOME}/.local/share/opencode/xai-access.json` on Linux when `XDG_DATA_HOME` is unset or empty) is a current-user regular single-link file with mode `0600`, valid closed v1, and a future `expires`. The error is raised before any network call. |
+| Host xAI authority helper never runs | Verify `${HOME}/.local/bin/opensandbox-xai-auth-sync` exists, is executable, and exits `0` on success. The observer treats every non-zero exit as transient and retries after `5000` ms without removing the xAI provider. The helper delegates projection to the OpenSandbox manager. A relative `XDG_DATA_HOME` (set but not absolute) disables the authority without reading or invoking. |
 | Host credentials exist but the guest provider is disconnected | Check the mount target and permissions, the guest's `HOME`, `CLAUDE_CONFIG_DIR`, injected secret environment, writable guest OpenCode `auth.json`, and whether `/connect` completed inside the guest. |
 | Ollama works on the host but not in the guest | Guest `localhost` is usually not the host. Check `host.docker.internal` resolution, Linux `host-gateway` mapping, the daemon bind address, firewall and sandbox egress, and whether any base path prefix reaches Ollama's `/api/*` routes. |
 | One provider is down | Failures are isolated. Transient snapshot failures keep the last-known catalog; an unavailable snapshot removes only that connector-owned provider. |

package/dist/core/options.d.ts

@@ -2,6 +2,11 @@ import { z } from "zod";
 import type { HealthPolicy } from "./health.js";
 export type CredentialRefreshMode = "auto" | "never";
 export type CredentialManagement = "connector" | "external";
+export type CredentialRole = "owner" | "reader";
+export type XaiOAuthMode = "authority" | "consumer";
+export type XaiOAuthOptions = {
+    readonly mode: XaiOAuthMode;
+};
 export type CredentialRefreshPolicy = {
     readonly mode: CredentialRefreshMode;
     readonly leadMs: number;
@@ -17,6 +22,8 @@ export type CredentialAuthority = {
 export type ConnectorOptionsInput = {
     readonly providers?: readonly ("claude" | "cursor" | "command-code" | "ollama")[] | undefined;
     readonly snapshotTimeoutMs?: number | undefined;
+    readonly credentialRole?: CredentialRole | undefined;
+    readonly xaiOAuth?: XaiOAuthOptions | undefined;
     readonly credentialManagement?: CredentialManagement | undefined;
     readonly credentialAuthority?: {
         readonly claudeCli: {
@@ -44,6 +51,7 @@ export type ConnectorOptions = {
     readonly writeBackCredentials: boolean;
     readonly credentialRefresh: CredentialRefreshPolicy;
     readonly credentialAuthority: CredentialAuthority;
+    readonly xaiOAuth: XaiOAuthOptions | null;
     readonly catalogReloadMs: number;
     readonly health: HealthPolicy;
 };

package/dist/core/options.js

@@ -5,6 +5,11 @@ const NonNegativeSafeIntegerSchema = z.number().int().nonnegative().max(MaximumT
 const ProviderSchema = z.enum(["claude", "cursor", "command-code", "ollama"]);
 const CredentialRefreshModeSchema = z.enum(["auto", "never"]);
 const CredentialManagementSchema = z.enum(["connector", "external"]);
+const CredentialRoleSchema = z.enum(["owner", "reader"]);
+const XaiOAuthSchema = z
+    .object({ mode: z.enum(["authority", "consumer"]) })
+    .strict()
+    .readonly();
 const SafeIntegerSchema = z.number().int().safe();
 const DefaultProviders = [
     "claude",
@@ -26,7 +31,8 @@ const CredentialAuthorityInputSchema = z
     .strict()
     .readonly();
 function resolveCredentialOptions(input) {
-    switch (input.credentialManagement) {
+    const credentialManagement = input.credentialRole === undefined ? input.credentialManagement : "external";
+    switch (credentialManagement) {
         case undefined:
             return {
                 credentialRefresh: Object.freeze({
@@ -51,6 +57,8 @@ const ConnectorOptionsInputSchema = z
     .object({
     providers: z.array(ProviderSchema).optional(),
     snapshotTimeoutMs: PositiveSafeIntegerSchema.optional(),
+    credentialRole: CredentialRoleSchema.optional(),
+    xaiOAuth: XaiOAuthSchema.optional(),
     credentialManagement: CredentialManagementSchema.optional(),
     credentialAuthority: CredentialAuthorityInputSchema.optional(),
     writeBackCredentials: z.boolean().optional(),
@@ -72,6 +80,17 @@ const ConnectorOptionsInputSchema = z
 })
     .strict()
     .superRefine((input, context) => {
+    if (input.credentialRole !== undefined &&
+        (input.credentialManagement !== undefined ||
+            input.credentialAuthority !== undefined ||
+            input.credentialRefresh !== undefined ||
+            input.writeBackCredentials !== undefined)) {
+        context.addIssue({
+            code: "custom",
+            path: ["credentialRole"],
+            message: "`credentialRole` cannot be combined with `credentialManagement`, `credentialAuthority`, `credentialRefresh`, or `writeBackCredentials`",
+        });
+    }
     if (input.credentialManagement !== undefined &&
         (input.credentialRefresh !== undefined || input.writeBackCredentials !== undefined)) {
         context.addIssue({
@@ -89,6 +108,14 @@ const ConnectorOptionsInputSchema = z
             message: "Claude CLI credential authority requires external credential management and the Claude provider",
         });
     }
+    if (input.credentialRole === "owner" &&
+        !(input.providers ?? DefaultProviders).includes("claude")) {
+        context.addIssue({
+            code: "custom",
+            path: ["credentialRole"],
+            message: "Credential owner role requires the Claude provider",
+        });
+    }
     const initialBackoffMs = input.health?.initialBackoffMs ?? 1_000;
     const maximumBackoffMs = input.health?.maximumBackoffMs ?? 60_000;
     if (initialBackoffMs > maximumBackoffMs) {
@@ -103,17 +130,21 @@ export const ConnectorOptionsSchema = ConnectorOptionsInputSchema.transform((inp
     const credentialOptions = resolveCredentialOptions(input);
     const credentialAuthority = Object.freeze({
         claudeCli: Object.freeze({
-            enabled: input.credentialAuthority?.claudeCli.enabled ?? false,
+            enabled: input.credentialRole === "owner"
+                ? true
+                : (input.credentialAuthority?.claudeCli.enabled ?? false),
             leadMs: input.credentialAuthority?.claudeCli.leadMs ?? 300_000,
             retryMs: input.credentialAuthority?.claudeCli.retryMs ?? 300_000,
         }),
     });
+    const xaiOAuth = input.xaiOAuth === undefined ? null : Object.freeze(input.xaiOAuth);
     return Object.freeze({
         providers: Object.freeze(input.providers ?? DefaultProviders),
         snapshotTimeoutMs: input.snapshotTimeoutMs ?? 30_000,
         writeBackCredentials: credentialOptions.writeBackCredentials,
         credentialRefresh: credentialOptions.credentialRefresh,
         credentialAuthority,
+        xaiOAuth,
         catalogReloadMs: input.catalogReloadMs ?? 300_000,
         health,
     });

package/dist/core/process.d.ts

@@ -3,6 +3,7 @@ export type ProcessCommand = {
     readonly executable: string;
     readonly arguments: readonly string[];
     readonly cwd: string | null;
+    readonly environment?: Readonly<Record<string, string>>;
 };
 export type ProcessExit = {
     readonly kind: "code";

package/dist/index.d.ts

@@ -4,3 +4,4 @@ export declare const claudeAuthServer: V1Plugin;
 export declare const cursorAuthServer: V1Plugin;
 export declare const commandCodeAuthServer: V1Plugin;
 export declare const ollamaAuthServer: V1Plugin;
+export declare const xaiAuthServer: V1Plugin;

package/dist/index.js

@@ -3,3 +3,4 @@ export const claudeAuthServer = async (input, options) => (await import("./serve
 export const cursorAuthServer = async (input, options) => (await import("./server.js")).cursorAuthServer(input, options);
 export const commandCodeAuthServer = async (input, options) => (await import("./server.js")).commandCodeAuthServer(input, options);
 export const ollamaAuthServer = async (input, options) => (await import("./server.js")).ollamaAuthServer(input, options);
+export const xaiAuthServer = async (input, options) => (await import("./server.js")).xaiAuthServer(input, options);

package/dist/opencode/host-options.d.ts

@@ -1,8 +1,10 @@
 import type { ConnectorOptionsInput } from "../core/options.js";
-type HostConnectorOptionsInput = Omit<ConnectorOptionsInput, "credentialAuthority" | "credentialManagement" | "credentialRefresh" | "writeBackCredentials"> & {
+type HostConnectorOptionsInput = Omit<ConnectorOptionsInput, "credentialAuthority" | "credentialManagement" | "credentialRefresh" | "credentialRole" | "xaiOAuth" | "writeBackCredentials"> & {
     readonly credentialAuthority?: unknown;
     readonly credentialManagement?: unknown;
     readonly credentialRefresh?: unknown;
+    readonly credentialRole?: unknown;
+    readonly xaiOAuth?: unknown;
     readonly writeBackCredentials?: unknown;
 };
 export declare function pickConnectorOptionsInput(input: unknown): HostConnectorOptionsInput;

package/dist/opencode/host-options.js

@@ -28,8 +28,10 @@ export function pickConnectorOptionsInput(input) {
     if (typeof input !== "object" || input === null) {
         return {};
     }
-    const preservesCredentialPolicy = "credentialManagement" in input &&
-        (input.credentialManagement === "connector" || input.credentialManagement === "external");
+    const preservesCredentialPolicy = ("credentialManagement" in input &&
+        (input.credentialManagement === "connector" || input.credentialManagement === "external")) ||
+        ("credentialRole" in input &&
+            (input.credentialRole === "owner" || input.credentialRole === "reader"));
     const writeBackCredentials = "writeBackCredentials" in input && input.writeBackCredentials !== undefined
         ? preservesCredentialPolicy
             ? input.writeBackCredentials
@@ -51,9 +53,13 @@ export function pickConnectorOptionsInput(input) {
             : undefined,
         snapshotTimeoutMs: "snapshotTimeoutMs" in input ? positiveInteger(input.snapshotTimeoutMs) : undefined,
         ...(writeBackCredentials === undefined ? {} : { writeBackCredentials }),
+        ...(!("credentialRole" in input) || input.credentialRole === undefined
+            ? {}
+            : { credentialRole: input.credentialRole }),
         ...(!("credentialManagement" in input) || input.credentialManagement === undefined
             ? {}
             : { credentialManagement: input.credentialManagement }),
+        ...(!("xaiOAuth" in input) || input.xaiOAuth === undefined ? {} : { xaiOAuth: input.xaiOAuth }),
         ...(!("credentialAuthority" in input) || input.credentialAuthority === undefined
             ? {}
             : { credentialAuthority: input.credentialAuthority }),

package/dist/process/production-supervisor.d.ts

@@ -3,6 +3,7 @@ export type ProcessSpawnOptions = {
     readonly shell: false;
     readonly stdio: "ignore";
     readonly windowsHide: true;
+    readonly env?: Readonly<Record<string, string>>;
 };
 export interface SpawnedChild {
     readonly exitCode: number | null;

package/dist/process/production-supervisor.js

@@ -12,6 +12,7 @@ function spawnNodeChild(command, options) {
         shell: options.shell,
         stdio: options.stdio,
         windowsHide: options.windowsHide,
+        ...(options.env === undefined ? {} : { env: options.env }),
     });
     return {
         get exitCode() {
@@ -136,7 +137,9 @@ export function createProductionProcessSupervisor(options = {}) {
             throw new ResourceDisposedError("process-supervisor");
         let child;
         try {
-            child = spawnProcess(command, spawnOptions);
+            child = spawnProcess(command, command.environment === undefined
+                ? spawnOptions
+                : { ...spawnOptions, env: command.environment });
         }
         catch (error) {
             throw processFailure("spawn", error);

package/dist/providers/xai/access-state.d.ts

@@ -0,0 +1,25 @@
+export type XaiAccessState = {
+    readonly kind: "ready";
+    readonly access: string;
+    readonly expires: number;
+} | {
+    readonly kind: "unavailable";
+};
+export type XaiAccessFileMetadata = {
+    readonly regular: boolean;
+    readonly links: number;
+    readonly mode: number;
+    readonly ownerUid: number;
+};
+export interface XaiAccessFile {
+    stat(): Promise<XaiAccessFileMetadata>;
+    readText(): Promise<string>;
+    close(): Promise<void>;
+}
+export type XaiAccessStateOptions = {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly currentUid?: () => number | undefined;
+    readonly openFile?: (path: string) => Promise<XaiAccessFile>;
+};
+export declare function resolveXaiAccessPath(env: Readonly<Record<string, string | undefined>>): string | null;
+export declare function readXaiAccessState(options: XaiAccessStateOptions): Promise<XaiAccessState>;