opencode-ext-connector 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # 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

package/README.md

@@ -19,7 +19,7 @@
 
 ## Status
 
-> Independent unofficial community plugin, version **0.6.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.6.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
 
@@ -78,6 +78,7 @@ Omitted `providers` enables all four. An explicit list is a strict allow-list. E
 | `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 |
@@ -211,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.
@@ -223,6 +276,7 @@ The safest shared-session layout keeps each vendor login owned and refreshed by
 | 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:
 
@@ -311,11 +365,14 @@ Ollama `/connect` probes the configured daemon and stores the exact session mark
 | **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 |
@@ -329,6 +386,8 @@ The standalone SDK entry is `opencode-ext-connector/ollama`; pass `{ ollamaBaseU
 | 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

@@ -3,6 +3,10 @@ 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;
@@ -19,6 +23,7 @@ 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: {
@@ -46,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

@@ -6,6 +6,10 @@ 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",
@@ -54,6 +58,7 @@ const ConnectorOptionsInputSchema = z
     providers: z.array(ProviderSchema).optional(),
     snapshotTimeoutMs: PositiveSafeIntegerSchema.optional(),
     credentialRole: CredentialRoleSchema.optional(),
+    xaiOAuth: XaiOAuthSchema.optional(),
     credentialManagement: CredentialManagementSchema.optional(),
     credentialAuthority: CredentialAuthorityInputSchema.optional(),
     writeBackCredentials: z.boolean().optional(),
@@ -132,12 +137,14 @@ export const ConnectorOptionsSchema = ConnectorOptionsInputSchema.transform((inp
             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,9 +1,10 @@
 import type { ConnectorOptionsInput } from "../core/options.js";
-type HostConnectorOptionsInput = Omit<ConnectorOptionsInput, "credentialAuthority" | "credentialManagement" | "credentialRefresh" | "credentialRole" | "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

@@ -59,6 +59,7 @@ export function pickConnectorOptionsInput(input) {
         ...(!("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>;

package/dist/providers/xai/access-state.js

@@ -0,0 +1,118 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { z } from "zod";
+const XaiAccessRecordSchema = z.discriminatedUnion("state", [
+    z
+        .object({
+        schema_version: z.literal(1),
+        provider: z.literal("xai"),
+        state: z.literal("ready"),
+        access: z.string().min(1),
+        expires: z.number().int().nonnegative(),
+    })
+        .strict()
+        .readonly(),
+    z
+        .object({
+        schema_version: z.literal(1),
+        provider: z.literal("xai"),
+        state: z.literal("unavailable"),
+    })
+        .strict()
+        .readonly(),
+]);
+const UnavailableState = Object.freeze({ kind: "unavailable" });
+class XaiAccessStateInvariantError extends Error {
+    name = "XaiAccessStateInvariantError";
+    constructor() {
+        super("unexpected xAI access state");
+    }
+}
+function assertNeverAccessState(_state) {
+    throw new XaiAccessStateInvariantError();
+}
+function currentProcessUid() {
+    return typeof process.getuid === "function" ? process.getuid() : undefined;
+}
+async function openAccessFile(path) {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    return {
+        stat: async () => {
+            const metadata = await handle.stat();
+            return {
+                regular: metadata.isFile(),
+                links: metadata.nlink,
+                mode: metadata.mode & 0o7777,
+                ownerUid: metadata.uid,
+            };
+        },
+        readText: () => handle.readFile("utf8"),
+        close: () => handle.close(),
+    };
+}
+export function resolveXaiAccessPath(env) {
+    const dataHome = env["XDG_DATA_HOME"];
+    if (dataHome !== undefined && dataHome.length > 0) {
+        return isAbsolute(dataHome) ? join(dataHome, "opencode", "xai-access.json") : null;
+    }
+    const home = env["HOME"];
+    return home !== undefined && home.length > 0 && isAbsolute(home)
+        ? join(home, ".local", "share", "opencode", "xai-access.json")
+        : null;
+}
+function parsedState(raw) {
+    const parsedJson = JSON.parse(raw);
+    const record = XaiAccessRecordSchema.safeParse(parsedJson);
+    if (!record.success)
+        return UnavailableState;
+    switch (record.data.state) {
+        case "ready":
+            return Object.freeze({
+                kind: "ready",
+                access: record.data.access,
+                expires: record.data.expires,
+            });
+        case "unavailable":
+            return UnavailableState;
+        default:
+            return assertNeverAccessState(record.data);
+    }
+}
+export async function readXaiAccessState(options) {
+    const path = resolveXaiAccessPath(options.env);
+    if (path === null)
+        return UnavailableState;
+    const openFile = options.openFile ?? openAccessFile;
+    let file;
+    try {
+        file = await openFile(path);
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return UnavailableState;
+        throw error;
+    }
+    let state = UnavailableState;
+    try {
+        const metadata = await file.stat();
+        const runtimeUid = (options.currentUid ?? currentProcessUid)();
+        const ownerMatches = runtimeUid === undefined || metadata.ownerUid === runtimeUid;
+        if (metadata.regular && metadata.links === 1 && metadata.mode === 0o600 && ownerMatches) {
+            state = parsedState(await file.readText());
+        }
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+    }
+    try {
+        await file.close();
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return UnavailableState;
+        throw error;
+    }
+    return state;
+}

package/dist/providers/xai/authority-observer.d.ts

@@ -0,0 +1,13 @@
+import type { Clock } from "../../core/clock.js";
+import { type AsyncDisposableHandle } from "../../core/lifecycle.js";
+import type { ProcessSupervisor } from "../../core/process.js";
+export type XaiAuthorityObserverOptions = {
+    readonly enabled: boolean;
+    readonly clock: Clock;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly processSupervisor: ProcessSupervisor;
+    readonly pollMs?: number;
+    readonly retryMs?: number;
+    readonly readAuthFile?: (path: string) => Promise<string>;
+};
+export declare function createXaiAuthorityObserver(options: XaiAuthorityObserverOptions): AsyncDisposableHandle;

package/dist/providers/xai/authority-observer.js

@@ -0,0 +1,165 @@
+import { readFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { z } from "zod";
+import { InvalidArgumentError, OperationCancelledError } from "../../core/errors.js";
+import { createAsyncDisposable } from "../../core/lifecycle.js";
+import { opencodeAuthJsonPaths } from "../../opencode/auth-store.js";
+const AUTH_SYNC_HELPER = "opensandbox-xai-auth-sync";
+const AUTH_SYNC_PATH = "/usr/local/bin:/usr/bin:/bin";
+const AuthRootSchema = z.record(z.string(), z.unknown());
+function errorCode(error) {
+    return "code" in error ? Reflect.get(error, "code") : undefined;
+}
+function commandEnvironment(env, home) {
+    const dataHome = env["XDG_DATA_HOME"];
+    return dataHome === undefined || dataHome.length === 0 || !isAbsolute(dataHome)
+        ? Object.freeze({ HOME: home, PATH: AUTH_SYNC_PATH })
+        : Object.freeze({ HOME: home, PATH: AUTH_SYNC_PATH, XDG_DATA_HOME: dataHome });
+}
+class XaiAuthorityInvariantError extends Error {
+    name = "XaiAuthorityInvariantError";
+    constructor() {
+        super("unexpected xAI authority state");
+    }
+}
+function assertNeverAuthorityState(_state) {
+    throw new XaiAuthorityInvariantError();
+}
+export function createXaiAuthorityObserver(options) {
+    const pollMs = options.pollMs ?? 1_000;
+    const retryMs = options.retryMs ?? 5_000;
+    if (!Number.isSafeInteger(pollMs) || pollMs <= 0)
+        throw new InvalidArgumentError("pollMs");
+    if (!Number.isSafeInteger(retryMs) || retryMs <= 0)
+        throw new InvalidArgumentError("retryMs");
+    if (!options.enabled)
+        return createAsyncDisposable(() => undefined);
+    const home = options.env["HOME"];
+    if (home === undefined || home.length === 0 || !isAbsolute(home)) {
+        return createAsyncDisposable(() => undefined);
+    }
+    const dataHome = options.env["XDG_DATA_HOME"];
+    if (dataHome !== undefined && dataHome.length > 0 && !isAbsolute(dataHome)) {
+        return createAsyncDisposable(() => undefined);
+    }
+    const [authPath] = opencodeAuthJsonPaths(options.env);
+    if (authPath === undefined || !isAbsolute(authPath))
+        return createAsyncDisposable(() => undefined);
+    const helper = join(home, ".local", "bin", AUTH_SYNC_HELPER);
+    const environment = commandEnvironment(options.env, home);
+    const loadAuth = options.readAuthFile ?? ((path) => readFile(path, "utf8"));
+    const controller = new AbortController();
+    let scheduled;
+    let activeProcess;
+    let activeEvaluation;
+    let synchronizedFingerprint;
+    let disposalStarted = false;
+    const arm = (delayMs) => {
+        if (disposalStarted)
+            return;
+        scheduled?.cancel();
+        scheduled = options.clock.schedule(delayMs, () => {
+            scheduled = undefined;
+            startEvaluation();
+        });
+    };
+    const observe = async () => {
+        let raw;
+        try {
+            raw = await loadAuth(authPath);
+        }
+        catch (error) {
+            if (error instanceof Error && errorCode(error) === "ENOENT") {
+                return { kind: "ready", fingerprint: "null" };
+            }
+            if (error instanceof Error)
+                return { kind: "retry" };
+            throw error;
+        }
+        try {
+            const parsedJson = JSON.parse(raw);
+            const root = AuthRootSchema.safeParse(parsedJson);
+            return root.success
+                ? { kind: "ready", fingerprint: JSON.stringify(root.data["xai"] ?? null) }
+                : { kind: "retry" };
+        }
+        catch (error) {
+            if (error instanceof SyntaxError)
+                return { kind: "retry" };
+            throw error;
+        }
+    };
+    const invoke = async () => {
+        const process = await options.processSupervisor.start({ executable: helper, arguments: [], cwd: null, environment }, controller.signal);
+        activeProcess = process;
+        try {
+            const exit = await process.wait(controller.signal);
+            switch (exit.kind) {
+                case "code":
+                    return exit.code === 0;
+                case "signal":
+                    return false;
+                default:
+                    return assertNeverAuthorityState(exit);
+            }
+        }
+        finally {
+            activeProcess = undefined;
+            await process.dispose();
+        }
+    };
+    const evaluate = async () => {
+        const observation = await observe();
+        if (disposalStarted)
+            return;
+        switch (observation.kind) {
+            case "retry":
+                arm(retryMs);
+                return;
+            case "ready":
+                if (observation.fingerprint === synchronizedFingerprint) {
+                    arm(pollMs);
+                    return;
+                }
+                if (await invoke())
+                    synchronizedFingerprint = observation.fingerprint;
+                if (!disposalStarted) {
+                    arm(observation.fingerprint === synchronizedFingerprint ? pollMs : retryMs);
+                }
+                return;
+            default:
+                return assertNeverAuthorityState(observation);
+        }
+    };
+    const startEvaluation = () => {
+        if (disposalStarted || activeEvaluation !== undefined)
+            return;
+        const operation = evaluate().catch((error) => {
+            if (error instanceof OperationCancelledError && disposalStarted)
+                return;
+            if (error instanceof Error) {
+                arm(retryMs);
+                return;
+            }
+            throw error;
+        });
+        activeEvaluation = operation;
+        void operation.then(() => {
+            if (activeEvaluation === operation)
+                activeEvaluation = undefined;
+        }, () => {
+            if (activeEvaluation === operation)
+                activeEvaluation = undefined;
+        });
+    };
+    const disposal = createAsyncDisposable(async () => {
+        disposalStarted = true;
+        scheduled?.cancel();
+        scheduled = undefined;
+        controller.abort();
+        await activeProcess?.terminate();
+        await activeEvaluation;
+    });
+    startEvaluation();
+    return { dispose: disposal.dispose, [Symbol.asyncDispose]: disposal[Symbol.asyncDispose] };
+}

package/dist/providers/xai/consumer-auth.d.ts

@@ -0,0 +1,23 @@
+import type { Clock } from "../../core/clock.js";
+export type NetworkFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export type XaiConsumerAuthOptions = {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly clock: Clock;
+    readonly networkFetch: NetworkFetch;
+};
+export type XaiConsumerAuthHook = {
+    readonly provider: "xai";
+    readonly loader: (getAuth: () => Promise<unknown>) => Promise<{
+        readonly apiKey: string;
+        readonly fetch: NetworkFetch;
+    } | {
+        readonly apiKey?: never;
+        readonly fetch?: never;
+    }>;
+    readonly methods: [];
+};
+export declare class XaiAccessUnavailableError extends Error {
+    readonly name = "XaiAccessUnavailableError";
+    constructor();
+}
+export declare function createXaiConsumerAuth(options: XaiConsumerAuthOptions): XaiConsumerAuthHook;

package/dist/providers/xai/consumer-auth.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { readXaiAccessState } from "./access-state.js";
+const XAI_CONSUMER_MARKER = "cli-session:xai";
+const XAI_DUMMY_API_KEY = "xai-access-file";
+const XaiConsumerMarkerSchema = z
+    .object({ type: z.literal("api"), key: z.literal(XAI_CONSUMER_MARKER) })
+    .strict();
+export class XaiAccessUnavailableError extends Error {
+    name = "XaiAccessUnavailableError";
+    constructor() {
+        super("xAI consumer access is unavailable");
+    }
+}
+function assertNeverAccessState(_state) {
+    throw new XaiAccessUnavailableError();
+}
+function createConsumerFetch(options) {
+    return async (input, init) => {
+        const state = await readXaiAccessState({ env: options.env });
+        let access;
+        switch (state.kind) {
+            case "ready":
+                if (state.expires <= options.clock.nowMs())
+                    throw new XaiAccessUnavailableError();
+                access = state.access;
+                break;
+            case "unavailable":
+                throw new XaiAccessUnavailableError();
+            default:
+                return assertNeverAccessState(state);
+        }
+        const headers = new Headers(input instanceof Request ? input.headers : undefined);
+        const initHeaders = new Headers(init?.headers);
+        initHeaders.forEach((value, key) => {
+            headers.set(key, value);
+        });
+        headers.set("authorization", `Bearer ${access}`);
+        return options.networkFetch(input, init === undefined ? { headers } : { ...init, headers });
+    };
+}
+export function createXaiConsumerAuth(options) {
+    return {
+        provider: "xai",
+        loader: async (getAuth) => {
+            const marker = XaiConsumerMarkerSchema.safeParse(await getAuth());
+            return marker.success
+                ? { apiKey: XAI_DUMMY_API_KEY, fetch: createConsumerFetch(options) }
+                : {};
+        },
+        methods: [],
+    };
+}

package/dist/server.d.ts

@@ -4,6 +4,7 @@ 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;
 export type ConnectorPluginModule = {
     readonly id: "opencode-ext-connector";
     readonly server: V1Plugin;

package/dist/server.js

@@ -14,6 +14,8 @@ import { createProductionProcessSupervisor } from "./process/production-supervis
 import { createClaudeCredentialAuthorityScheduler } from "./providers/claude/credential-authority-scheduler.js";
 import { writeClaudeCredentials } from "./providers/claude/writeback.js";
 import { productionOllamaFetch } from "./providers/ollama/http.js";
+import { createXaiAuthorityObserver } from "./providers/xai/authority-observer.js";
+import { createXaiConsumerAuth } from "./providers/xai/consumer-auth.js";
 const env = process.env;
 const transport = createFetchHttpTransport();
 const authStore = createOpenCodeAuthStore({ env });
@@ -86,10 +88,17 @@ export const connectorServer = async (input, options) => {
         processSupervisor,
         logger,
     });
+    const xaiAuthority = createXaiAuthorityObserver({
+        enabled: connectorOptions.xaiOAuth?.mode === "authority",
+        clock,
+        env,
+        processSupervisor,
+    });
     const dispose = hooks.dispose;
     const disposal = createAsyncDisposable(async () => {
         const results = await Promise.allSettled([
             Promise.resolve().then(() => credentialAuthority.dispose()),
+            Promise.resolve().then(() => xaiAuthority.dispose()),
             Promise.resolve().then(() => processSupervisor.dispose()),
             Promise.resolve().then(() => dispose?.()),
             Promise.resolve().then(disposeV1LanguageRuntime),
@@ -129,6 +138,12 @@ export const ollamaAuthServer = async (_input, options) => {
     }).find((candidate) => candidate.id === "ollama");
     return entry === undefined ? {} : buildV1AuthHooks(entry, providerDeps, options);
 };
+export const xaiAuthServer = async (_input, options) => {
+    const connectorOptions = parseConnectorOptions(pickConnectorOptionsInput(options));
+    return connectorOptions.xaiOAuth?.mode === "consumer"
+        ? { auth: createXaiConsumerAuth({ env, clock, networkFetch: globalThis.fetch }) }
+        : {};
+};
 export const plugin = {
     id: "opencode-ext-connector",
     server: connectorServer,

package/dist/xai.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin as V1Plugin } from "@opencode-ai/plugin";
+export declare const xaiAuthServer: V1Plugin;

package/dist/xai.js

@@ -0,0 +1 @@
+export const xaiAuthServer = async (input, options) => (await import("./server.js")).xaiAuthServer(input, options);

package/docs/README.ko.md

@@ -19,7 +19,7 @@
 
 ## 상태
 
-> 독립적인 비공식 커뮤니티 플러그인, 버전 **0.6.0**. CI에 설치된 OpenCode CLI를 대상으로 legacy multi-function 로더를 패키지 E2E 테스트로 검증합니다. `@opencode-ai/plugin@1.18.18`은 컴파일 시 사용하는 플러그인 API 대상이며 OpenCode 런타임 버전 고정이 아닙니다. 소스는 BSD-3-Clause입니다. 이 프로젝트는 OpenCode 또는 어떤 프로바이더와도 제휴, 보증, 후원, 승인 관계가 없습니다. 전체 조건은 [라이선스 및 면책 조항](#라이선스-및-면책-조항)에 있습니다.
+> 독립적인 비공식 커뮤니티 플러그인, 버전 **0.7.0**. CI에 설치된 OpenCode CLI를 대상으로 legacy multi-function 로더를 패키지 E2E 테스트로 검증합니다. `@opencode-ai/plugin@1.18.18`은 컴파일 시 사용하는 플러그인 API 대상이며 OpenCode 런타임 버전 고정이 아닙니다. 소스는 BSD-3-Clause입니다. 이 프로젝트는 OpenCode 또는 어떤 프로바이더와도 제휴, 보증, 후원, 승인 관계가 없습니다. 전체 조건은 [라이선스 및 면책 조항](#라이선스-및-면책-조항)에 있습니다.
 
 이미 가지고 있는 Claude, Cursor, Command Code, Ollama 세션을 재사용합니다. `opencode.json` 플러그인 항목 하나가 라이브 카탈로그를 OpenCode에 공개합니다. Claude와 Cursor는 OpenCode에 마커 또는 OAuth 레코드가 있고 벤더 세션이 있을 때까지 연결되지 않은 상태로 유지됩니다. Command Code는 OpenCode에 저장된 직접 API 키 또는 기존 CLI 세션/키를 사용할 수 있습니다. Ollama는 정확한 세션 마커와 응답하는 신뢰된 데몬이 필요합니다.
 
@@ -55,13 +55,13 @@ OpenCode는 시작 시 Bun으로 설정된 npm 플러그인을 설치하고 캐
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-ext-connector@0.6.0"]
+  "plugin": ["opencode-ext-connector@0.7.0"]
 }
 ```
 
 항목을 추가하거나 변경한 뒤 OpenCode를 완전히 종료하고 다시 시작하십시오. 리로드만으로는 충분하지 않습니다.
 
-패키지 항목 하나가 카탈로그 플러그인과 Claude, Cursor, Command Code, Ollama 인증 hook을 노출합니다. 프로바이더 id: `claude`, `cursor`, `command-code`, `ollama`. 모델 id는 각 프로바이더의 라이브 카탈로그에서 가져오며, 라이브 목록이 비어 있으면 문서화된 fallback은 Cursor의 `default`와 Command Code의 `Qwen/Qwen3.8-Max`입니다.
+패키지 항목 하나가 카탈로그 플러그인과 Claude, Cursor, Command Code, Ollama 인증 hook을 노출합니다. 프로바이더 id: `claude`, `cursor`, `command-code`, `ollama`. 모델 id는 각 프로바이더의 라이브 카탈로그에서 가져오며, 라이브 목록이 비어 있으면 문서화된 fallback은 Cursor의 `default`와 Command Code의 `Qwen/Qwen3.8-Max`입니다. 옵트인 xAI 컨슈머는 패키지 subpath `opencode-ext-connector/xai`로 노출됩니다. [옵트인 xAI OAuth 권한과 컨슈머](#옵트인-xai-oauth-권한과-컨슈머-호스트와-게스트)를 참조하십시오.
 
 ## 설정
 
@@ -78,6 +78,7 @@ OpenCode는 플러그인 옵션을 두 요소 튜플의 두 번째 항목으로
 | `writeBackCredentials` | `false` | **사용 중단 예정:** 한 번의 마이그레이션 주기 동안 단독 사용 시 허용되며, 갱신 후 Claude writeback을 제어 |
 | `credentialRefresh.mode` | `"auto"` | **사용 중단 예정:** 한 번의 마이그레이션 주기 동안 단독 사용 시 허용되며, Claude의 `"auto"` 또는 `"never"` 갱신 동작을 제어 |
 | `credentialRefresh.leadMs` | `60000` | **사용 중단 예정:** 한 번의 마이그레이션 주기 동안 단독 사용 시 허용되며, 사용자 지정 리드 타임에는 여전히 이 레거시 설정이 필요 |
+| `xaiOAuth.mode` | 생략 | 옵트인 xAI 역할. `"authority"`는 호스트 `connectorServer` 항목에서 호스트 옵저버를 활성화하고, `"consumer"`는 전용 `opencode-ext-connector/xai` 컨슈머를 활성화합니다. `xaiOAuth`를 생략하면 통합은 조용히 비활성화됩니다. `xaiOAuth`가 존재하지만 `mode`가 없거나 `"authority" | "consumer"` 중 하나가 아니면 파싱 시점에 거부됩니다. 모든 Claude 자격 증명 옵션과 독립적입니다. |
 | `credentialAuthority.claudeCli.enabled` | `false` | Claude 전용 옵트인: [옵트인 Claude CLI 권한 타이머](#옵트인-claude-cli-권한-타이머-claude-전용) 참조 |
 | `credentialAuthority.claudeCli.leadMs` | `300000` | Claude 전용 옵트인: 자격 증명 만료 전 이 밀리초만큼 남았을 때 타이머가 `claude`를 호출; 음수가 아닌 정수 |
 | `credentialAuthority.claudeCli.retryMs` | `300000` | Claude 전용 옵트인: 0이 아닌 종료, 잠금 충돌, 시그널, supervisor 실패 후 재시도까지의 밀리초; 양의 정수 |
@@ -211,6 +212,58 @@ Anthropic은 갱신할 때마다 refresh 토큰을 회전시키고 이전 토큰
 
 타이머가 실행되지 않으면 `flock --version`, `claude --version`, 상태 디렉터리 권한, 두 필수 설정값을 확인하십시오. 반복 경고는 CLI 실행 실패, 시그널 종료, 또는 시작 실패를 뜻합니다. 비활성화하려면 `credentialAuthority`를 제거하거나 `enabled`를 `false`로 설정한 뒤 OpenCode를 완전히 재시작하십시오.
 
+### 옵트인 xAI OAuth 권한과 컨슈머 (호스트와 게스트)
+
+이 커넥터는 옵트인 xAI 경로를 호스트 측 **authority**와 게스트 측 **consumer** 쌍으로 제공합니다. 두 역할은 `credentialRole`, `credentialManagement`, `credentialAuthority`, `credentialRefresh`, `writeBackCredentials`와 독립적이며 어떤 Claude 정책도 변경하거나 대체하지 않습니다. `xaiOAuth`를 생략하면 통합은 조용히 비활성화됩니다. `xaiOAuth`가 존재하지만 `mode`가 없거나 `"authority" | "consumer"` 중 하나가 아니면 파싱 시점에 거부됩니다.
+
+두 역할은 서로 다른 OpenCode 환경에 설정하십시오. 호스트에서는:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [["opencode-ext-connector", { "xaiOAuth": { "mode": "authority" } }]]
+}
+```
+
+게스트에서는:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [["opencode-ext-connector/xai", { "xaiOAuth": { "mode": "consumer" } }]]
+}
+```
+
+**Authority (호스트).** 호스트 `connectorServer` 항목에 `xaiOAuth.mode: "authority"`를 설정하십시오. 옵저버는 `XDG_DATA_HOME`이 설정되어 절대 경로일 때 `${XDG_DATA_HOME}/opencode/auth.json`을 읽고, Linux에서 `XDG_DATA_HOME`이 미설정 또는 빈 문자열일 때만 `${HOME}/.local/share/opencode/auth.json`으로 fallback합니다. 상대 경로의 `XDG_DATA_HOME`(설정되었지만 절대 경로가 아님)은 권한을 비활성화합니다 — `auth.json`을 읽지 않고 헬퍼도 호출하지 않습니다. 활성화된 경우 옵저버는 **오직** `xai` 레코드만 검사합니다. 그 레코드의 직렬화 fingerprint가 바뀌면 `${HOME}/.local/bin/opensandbox-xai-auth-sync` 고정 헬퍼를 인자 없이, `PATH`는 `/usr/local/bin:/usr/bin:/bin`, `HOME`은 항상 설정하고 `XDG_DATA_HOME`은 절대 경로일 때만 전달하여 호출합니다. 헬퍼는 OpenSandbox manager에 projection을 위임합니다. 커넥터는 게스트 접근 파일을 기록하거나 xAI OAuth를 발급·갱신하지 않고, 머신 간에 토큰을 전송하거나 refresh 토큰을 게스트에 두지 않습니다. 0이 아닌 종료는 일시적 사례로 처리되어 xAI 프로바이더를 제거하지 않은 채 `5000` ms 후 재시도됩니다.
+
+**Consumer (게스트).** 별도의 OpenCode 플러그인 항목으로 `["opencode-ext-connector/xai", { "xaiOAuth": { "mode": "consumer" } }]` 튜플을 로드하십시오. mode는 필수입니다. subpath 항목에 mode가 없으면 빈 hook을 반환하고 xAI 프로바이더는 연결되지 않은 상태로 유지됩니다. `"consumer"` 모드에서 커넥터는 xAI auth hook을 반환하며 `/connect` 메서드를 노출하지 않습니다 — `methods: []`가 공개 계약의 일부입니다. 컨슈머는 `xai` 프로바이더의 OpenCode auth 레코드에 다음 정확한 마커를 요구합니다:
+
+```jsonc
+{ "type": "api", "key": "cli-session:xai" }
+```
+
+커넥터는 이 마커를 기록하지 않으며 마커 배치는 운영자의 책임입니다. 다른 형태면 loader는 auth를 반환하지 않습니다. 센티널로 loader는 자리 표시자 `apiKey`와 래핑된 `fetch`를 반환합니다. 실제 bearer는 모든 외부 요청마다 접근 파일에서 가져옵니다.
+
+**접근 파일.** 컨슈머는 **모든** 요청마다 접근 파일을 다시 읽으며 메모리 내 토큰을 신뢰하지 않습니다:
+
+- 경로: `XDG_DATA_HOME`이 설정되어 절대 경로일 때 `${XDG_DATA_HOME}/opencode/xai-access.json`, Linux에서 `XDG_DATA_HOME`이 미설정 또는 빈 문자열일 때만 `${HOME}/.local/share/opencode/xai-access.json`. 상대 경로의 `XDG_DATA_HOME`은 HOME fallback을 검사하지 않고 fail-closed합니다.
+- 파일 게이트: 정규 파일, mode `0600`, link 수 `1`, 현재 사용자 소유. 파일 부재, 부적합한 stat, 심볼릭 링크, 다중 링크 파일, 잘못된 소유자, 잘못된 mode는 모두 unavailable 상태를 반환합니다.
+- 스키마 (closed v1):
+
+```jsonc
+{
+  "schema_version": 1,
+  "provider": "xai",
+  "state": "ready",
+  "access": "<bearer-token>",
+  "expires": 1735689600000
+}
+```
+
+`"state": "unavailable"` 레코드, malformed JSON, 스키마 불일치, 파일 부재, stat 실패, 또는 `expires`가 현재 시각 이후가 아닌 경우 모두 **모든** 네트워크 호출 **이전**에 실패하며 해당 요청에 대해 `XaiAccessUnavailableError`를 던집니다. bearer 토큰은 플러그인 인수, 커넥터 stdout/stderr 진단, 또는 요청 URL에 들어가지 않습니다.
+
+**범위 밖.** OpenCode auth에 직접 저장된 일반 xAI API 키(내장 `XAI_API_KEY` 방식 경로)는 이 권한/컨슈머 쌍이 아니라 OpenCode의 내장 `xai` 프로바이더를 따릅니다. 커넥터는 그러한 키를 가져오거나, 미러링하거나, 프록시하지 않습니다. 헬퍼는 idempotent해야 합니다. 같은 게스트에서 개발자 Claude Code 세션을 실행해도 projected 접근 파일에 대한 권한을 갖지 않습니다.
+
 ## 호스트/게스트 샌드박스 설정
 
 OpenCode가 컨테이너, VM 또는 다른 샌드박스에서 실행될 때 그 런타임을 **게스트**, 벤더 로그인과 Ollama 데몬을 소유한 머신을 **호스트**로 봅니다. 게스트에는 자체 `localhost`, 홈 디렉터리, 환경, keychain, 파일 권한, 네트워크 namespace가 있습니다. 파일을 mount하거나 환경 값을 명시적으로 주입하지 않으면 호스트 세션은 게스트에 보이지 않습니다.
@@ -223,6 +276,7 @@ OpenCode가 컨테이너, VM 또는 다른 샌드박스에서 실행될 때 그
 | Cursor | Cursor CLI 로그인을 소유 | 자격 증명 파일을 게스트의 `${HOME}/.config/cursor/auth.json`에 read-only로 mount하거나 샌드박스 secret 기능으로 `CURSOR_ACCESS_TOKEN` 주입; 게스트에 Node.js 22 이상 설치 |
 | Command Code | CLI 로그인 또는 API 키를 소유 | `${HOME}/.commandcode/auth.json`을 read-only로 mount하거나 `COMMAND_CODE_API_KEY` 주입; `COMMAND_CODE_CLI_VERSION`, 설치된 `command-code` 바이너리 또는 npm registry 접근으로 클라이언트 버전 확인 |
 | Ollama | 신뢰하는 데몬을 실행하고 Cloud 접근이 필요하면 그곳에서 `ollama signin` 실행 | Ollama 자격 증명을 복사하지 않고 `ollamaBaseURL`로 선택한 데몬에만 연결 |
+| xAI | 호스트 권한이 `~/.local/bin/opensandbox-xai-auth-sync`을 호출하고 OpenSandbox manager가 access-only 게스트 상태를 projection | manager가 projection한 `{"type":"api","key":"cli-session:xai"}` 마커와 `${XDG_DATA_HOME}/opencode/xai-access.json`(또는 XDG가 미설정 또는 빈 문자열일 때 HOME fallback)을 사용하고, `xaiOAuth.mode: "consumer"`로 `opencode-ext-connector/xai`를 로드; refresh 토큰은 절대 복사하거나 mount하지 않음 |
 
 예를 들어 Linux 게스트는 다음 경로와 선택적인 secret/version override를 사용할 수 있습니다. Mount source와 destination은 샌드박스 런타임에 맞게 조정하십시오:
 
@@ -311,11 +365,14 @@ Ollama `/connect`는 설정된 데몬을 조사하고 정확한 세션 마커를
 | **Cursor** | CLI 액세스 토큰으로 Cursor의 미공개 클라이언트 프로토콜(`api2.cursor.sh` `AgentService`, HTTP/2 위의 Connect+protobuf)을 호출합니다. 두 자격 증명 관리 모드 모두 자격 증명은 읽기 전용입니다. direct 생성은 정확한 HTTP 401이 출력이나 효과 전에 발생할 때만 null이 아니며 변경된 자격 증명을 다시 읽고 한 번 재시도할 수 있으며, 이는 갱신이나 writeback이 아닙니다. legacy/compatibility 생성은 한 번만 시도합니다. 플러그인이 소유한 Node 자식 프로세스가 private stdio로 통신하고, 툴 결과를 같은 bidi Run에 유지하며, parked call을 절대 재실행하지 않고, 사용자 대면 데몬을 열지 않으며, 생성에 `cursor-agent`를 절대 spawn하지 않습니다. 비공식이며 공개 Cursor API가 아닙니다. 프로토콜이 어긋난 뒤에는 암시적 fallback이 없습니다 — 해당 프로바이더가 실패합니다. Node.js 22 이상이 필요합니다. 라이브 카탈로그 id가 있으면 그것을 쓰고, 없으면 문서화된 fallback은 `default`입니다. |
 | **Command Code** | CLI 호환 요청 메타데이터와 함께 `/alpha/generate`를 호출하고, 프로바이더 로컬 NDJSON 텍스트와 툴 이벤트를 스트림합니다. 두 자격 증명 관리 모드 모두 자격 증명은 읽기 전용입니다. 정확한 HTTP 401이 출력이나 효과 전에 발생하면 null이 아니며 변경된 자격 증명을 다시 읽고 한 번만 재시도할 수 있으며, 이는 갱신이나 writeback이 아닙니다. 클라이언트 버전은 `COMMAND_CODE_CLI_VERSION`, 설치된 `command-code` 바이너리, 또는 npm registry에서 가져옵니다. 요청 메타데이터에는 Node.js 버전, 플랫폼, 아키텍처, 절대 작업 디렉터리가 포함됩니다. 라이브 카탈로그 id가 있으면 그것을 쓰고, 없으면 문서화된 fallback은 `Qwen/Qwen3.8-Max`입니다. |
 | **Ollama** | `credentialManagement`의 영향을 받지 않습니다. `ollamaBaseURL`로 선택한 신뢰된 데몬(기본값 `http://localhost:11434`)의 `/api/tags`, `/api/pull`, `/api/chat`을 사용하며 경로 prefix를 보존합니다. 이미 pull된 모델과, 커넥터 자격 증명 없이 Ollama 공식 Cloud 검색 및 library 페이지에서 익명으로 발견한 정확한 Cloud 태그를 공개합니다. 정확히 중복되는 항목은 로컬이 이깁니다. 불완전한 Cloud 갱신은 마지막 완전한 목록을 유지합니다. 없는 인가된 Cloud 태그를 선택하면 최초 사용 시 lightweight remote reference를 pull합니다. 같은 정규화 base와 태그의 동시 pull은 하나의 in-flight 요청을 공유하며 실패한 pull은 재시도할 수 있습니다. 데몬은 사용자의 Ollama Cloud 구독으로 Cloud 태그 프롬프트를 proxy할 수 있습니다. 커넥터는 Ollama API 키, 사용량 과금 direct Cloud API, `OLLAMA_HOST`, 자격 증명/custom header, cookie, direct Cloud 생성 endpoint를 사용하지 않습니다. |
+| **xAI** | 패키지 subpath `opencode-ext-connector/xai`로만 로드되는 옵트인 OAuth 컨슈머입니다. 접근 파일은 모든 요청마다 다시 읽고, `/connect` 메서드를 노출하지 않으며, xAI OAuth를 발급하거나 갱신하지 않습니다. Claude `credentialRole`과 자격 증명 정책에서 독립적입니다. [옵트인 xAI OAuth 권한과 컨슈머](#옵트인-xai-oauth-권한과-컨슈머-호스트와-게스트) 참조. |
 
 프로바이더 health는 격리됩니다. 한 프로바이더가 실패해도 나머지는 제거되지 않습니다.
 
 독립 SDK entry는 `opencode-ext-connector/ollama`입니다. `{ ollamaBaseURL }`을 전달해 같은 신뢰된 데몬을 선택할 수 있습니다. 해당 데몬에 이미 있는 모델로 생성할 수 있으며, 커넥터가 관리하는 Cloud 자동 pull은 그 정규화 base의 활성 Ollama 카탈로그 lease가 필요합니다.
 
+전용 컨슈머 entry는 `opencode-ext-connector/xai`입니다. `{ xaiOAuth: { mode: "consumer" } }`을 전달해 모델 프로바이더, 모델, `/connect` 메서드를 등록하지 않고 xAI auth hook만 등록합니다.
+
 ## 문제 해결
 
 | 증상 | 확인할 것 |
@@ -329,6 +386,8 @@ Ollama `/connect`는 설정된 데몬을 조사하고 정확한 세션 마커를
 | Cursor 생성이 실패함 | Node.js 22 이상이 필요합니다. 생성은 `cursor-agent`가 아니라 private Node 자식 프로세스를 통한 미공개 프로토콜을 사용합니다. 프로토콜이 어긋나면 해당 프로바이더가 실패하며, 암시적 fallback은 없습니다. |
 | Command Code 생성이 실패함 | 클라이언트 버전을 확인할 수 없었습니다: `COMMAND_CODE_CLI_VERSION`을 설정하거나, `command-code`를 설치하거나, `registry.npmjs.org` 접근을 허용하십시오. 요청 메타데이터에는 Node.js 버전, 플랫폼, 아키텍처, 절대 작업 디렉터리가 포함됩니다. |
 | `opencode models ollama`에 Ollama가 없음 | `ollamaBaseURL`(또는 기본 `localhost:11434`)에서 신뢰하는 데몬을 시작한 뒤 `/connect`하십시오. 경로 prefix가 Ollama `/api/*` route에 도달하는지 확인하십시오. Cloud 태그는 익명 catalog 항목이며 `OLLAMA_HOST`, API 키, credential header, redirect, direct Cloud 생성은 사용하지 않습니다. |
+| xAI 요청이 `XaiAccessUnavailableError`로 실패함 | 호스트 `connectorServer` 항목의 `xaiOAuth.mode`가 `"authority"`인지, `opencode-ext-connector/xai` subpath 항목의 `xaiOAuth.mode`가 `"consumer"`인지, OpenCode auth 레코드가 정확히 `{"type":"api","key":"cli-session:xai"}`를 담고 있는지, 접근 파일이 `${XDG_DATA_HOME}/opencode/xai-access.json`(또는 Linux에서 `XDG_DATA_HOME`이 미설정 또는 빈 문자열일 때 `${HOME}/.local/share/opencode/xai-access.json`)에 현재 사용자 소유의 정규 단일 링크 mode `0600` 파일로 존재하고 유효한 closed v1 스키마와 미래의 `expires`를 가지는지 확인하십시오. 상대 경로의 `XDG_DATA_HOME`은 HOME fallback 없이 fail-closed합니다. 오류는 모든 네트워크 호출 전에 발생합니다. |
+| 호스트 xAI 권한 헬퍼가 실행되지 않음 | `${HOME}/.local/bin/opensandbox-xai-auth-sync`이 존재하고 실행 가능하며 성공 시 `0`으로 종료하는지 확인하십시오. 옵저버는 모든 0이 아닌 종료를 일시적 사례로 처리해 `5000` ms 후 재시도하며 xAI 프로바이더를 제거하지 않습니다. 헬퍼는 OpenSandbox manager에 projection을 위임합니다. 상대 경로의 `XDG_DATA_HOME`(설정되었지만 절대 경로가 아님)은 읽기와 호출 없이 권한을 비활성화합니다. |
 | 호스트 자격 증명이 있지만 게스트 프로바이더가 연결되지 않음 | mount 대상과 권한, 게스트의 `HOME`, `CLAUDE_CONFIG_DIR`, 주입한 secret 환경, writable 게스트 OpenCode `auth.json`, 게스트 안에서 `/connect`가 완료됐는지 확인하십시오. |
 | Ollama가 호스트에서는 동작하지만 게스트에서는 동작하지 않음 | 게스트 `localhost`는 보통 호스트가 아닙니다. `host.docker.internal` resolve, Linux `host-gateway` mapping, 데몬 bind 주소, firewall과 샌드박스 egress, base path prefix가 Ollama `/api/*` route에 도달하는지 확인하십시오. |
 | 한 프로바이더가 다운됨 | 실패는 격리됩니다. 일시적 스냅샷 실패는 마지막으로 알려진 카탈로그를 유지하고, unavailable 스냅샷은 해당 커넥터 소유 프로바이더만 제거합니다. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-ext-connector",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "External provider connector for OpenCode",
   "type": "module",
   "license": "BSD-3-Clause",
@@ -20,6 +20,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./xai": {
+      "types": "./dist/xai.d.ts",
+      "import": "./dist/xai.js"
+    },
     "./command-code": {
       "types": "./dist/sdk/command-code.d.ts",
       "import": "./dist/sdk/command-code.js"