@jini-ai/http-kit 0.2.1

package/dist/xai.js

@@ -0,0 +1,668 @@
+/**
+ * @module xai
+ *
+ * `POST /api/xai/oauth/start`, `POST /api/xai/oauth/complete`, `POST /api/xai/oauth/cancel`,
+ * `GET /api/xai/auth/status`, `POST /api/xai/oauth/disconnect`, `POST /api/xai/search` — ported
+ * from OD's real `apps/daemon/src/routes/xai.ts` (read directly in the sibling
+ * `/Users/la/Desktop/Programming/OSS-Repos/open-design` checkout on this machine, per this repo's
+ * "verify against the real source, don't guess" convention), and from that same file's own
+ * `packages/http/source-map.md` routes-classification row #27 ("MIXED, OD-leaning... the OAuth
+ * start/complete/status/cancel/disconnect shape is a recognizable generic pattern, but this file is
+ * fused to a transitional xAI PoC arrangement"). Deliberately left out of the 2026-07-22
+ * azure/google/ollama/connectors/health/research route-parity pass pending a product decision on
+ * whether to build xAI OAuth support at all — approved after that pass landed; this is that build.
+ *
+ * **Reused `@jini-ai/agent-runtime`'s existing generic OAuth+PKCE machinery instead of building a
+ * second OAuth stack.** `packages/agent-runtime/src/providers/{pkce,oauth-provider,oauth-callback-
+ * server,oauth-tokens,oauth-credentials}.ts` (all ported 2026-07-18, see that package's
+ * `source-map.md` "providers/ — LLM-provider integrations" section) already generalized this exact
+ * origin file's OAuth sibling files — OD's `integrations/xai-oauth.ts` → `oauth-provider.ts`
+ * (`beginOAuthPkce`/`completeOAuthPkce`/`refreshOAuthPkceToken`, config-driven via
+ * `OAuthPkceProviderConfig`, with `XAI_OAUTH_PROVIDER_CONFIG` kept as the concrete xAI preset the
+ * origin actually shipped), `integrations/xai-oauth-server.ts` → `oauth-callback-server.ts`
+ * (`startOAuthCallbackListener`, de-branded, `host`/`port`/`path` now caller-supplied instead of
+ * xAI-hardcoded constants), `integrations/xai-tokens.ts` → `oauth-tokens.ts`
+ * (`getStoredOAuthToken`/`setStoredOAuthToken`/`clearStoredOAuthToken`, filename now a parameter),
+ * `integrations/xai-credentials.ts` → `oauth-credentials.ts` (`resolveOAuthBearer`, refresh-on-read).
+ * That prior port had **no HTTP route consumer anywhere** — this file is the first one. Nothing new
+ * was built for PKCE/callback-listener/token-storage/refresh; this module supplies only the pieces
+ * that machinery doesn't already have an opinion on: xAI's concrete `providerConfig`/callback
+ * host-port-path defaults (still overridable — see `XaiHttpDeps`), the HTTP wire shapes
+ * (`RouteInputContext` parsing, `Result`/`ApiError` responses, `requireSameOrigin`), and the
+ * `x_search` Responses-API call itself (genuinely xAI-specific, no existing home in
+ * `@jini-ai/agent-runtime`).
+ *
+ * **The one genuinely xAI-specific quirk carried over verbatim: the fixed loopback port.** xAI's
+ * PoC `client_id` (`XAI_OAUTH_PROVIDER_CONFIG.clientId`, reused from NousResearch/hermes-agent —
+ * xAI does not yet publish a public client-registration flow) has its `redirect_uri` locked to
+ * `http://127.0.0.1:56121/callback` server-side; a daemon can't register its own. `oauth-callback-
+ * server.ts` already made `host`/`port`/`path` generic parameters rather than hardcoded constants,
+ * so this file just supplies xAI's fixed values as `XaiHttpDeps`' (overridable, for tests) default
+ * (`XAI_OAUTH_REDIRECT_HOST`/`_PORT`/`_PATH`, all from `@jini-ai/agent-runtime`) — no new
+ * listener-mechanics code needed.
+ *
+ * **Dropped: OD's "SuperGrok subscription" gate.** The origin's `POST /api/xai/search` resolved
+ * credentials through OD's own multi-source cascade (`resolveProviderConfig(..., 'grok')`:
+ * OD-native OAuth token → a separate "Hermes" tool's `auth.json` → `OD_GROK_API_KEY` env var →
+ * `XAI_API_KEY` env var) and returned a 401 with product-specific copy
+ * ("sign in with your SuperGrok subscription...") when nothing resolved. Both are OD product/billing
+ * decisions, not generic engine concerns — a SuperGrok subscription is an OD-specific entitlement
+ * concept `@jini-ai/http-kit` has no business modeling. This port checks only "is an xAI OAuth account
+ * connected" (via `resolveOAuthBearer` against this file's own token store) and returns a clean
+ * `NOT_CONFIGURED` (503) when it isn't; if a connected account isn't actually entitled to
+ * `x_search`, xAI's own `/responses` endpoint returns its own real error, which this route surfaces
+ * through the same SEC-005 `INTERNAL_ERROR` path as any other upstream failure — no hardcoded
+ * pre-flight entitlement check is layered on top of xAI's own answer.
+ *
+ * **Wire shapes changed from OD's snake_case request body to this package's established camelCase
+ * convention** (`allowedXHandles`/`excludedXHandles`/`fromDate`/`toDate`/
+ * `enableImageUnderstanding`/`enableVideoUnderstanding`, matching `media.ts`/`connectors.ts`'s own
+ * camelCase JSON surfaces) — converted to xAI's real snake_case (`allowed_x_handles`, ...) only when
+ * building the actual upstream `x_search` tool payload, the same "camelCase API surface, vendor
+ * snake_case is an internal implementation detail" split `research.ts` already applies to Tavily's
+ * `search_depth`/`max_results`.
+ *
+ * **State sharing across requests, resolved once, not per-call.** Unlike `research.ts`'s
+ * `resolveCredentials` (stateless — a fresh default is harmless every call) or `connectors.ts`'s
+ * per-capability `deps.auth`/`deps.storage` (genuinely-optional-forever, not defaulted at all), this
+ * file's `pending` (`PendingAuthCache`) and `listenerRef` (the in-flight loopback listener slot) are
+ * mutable state that must be the *same instance* across `oauth/start` → `oauth/complete`/
+ * `oauth/cancel`/`oauth/disconnect` calls for the dance to work at all — a fresh `PendingAuthCache`
+ * minted independently on every request would mean `start` and `complete` never see each other's
+ * state. `registerXaiRoutes` resolves every optional default exactly once (`resolveXaiHttpDeps`)
+ * and hands that single resolved object to every mounted route, so a zero-config
+ * `registerXaiRoutes(app, {}, adapter)` call still shares one cache/listener-slot across the whole
+ * mounted lifetime. Each route's own `handle` also calls `resolveXaiHttpDeps` at its top (a
+ * defensive, idempotent pass-through when deps are already concrete) purely so individual routes
+ * stay directly unit-testable without going through `registerXaiRoutes` first, matching every other
+ * route pack in this package's own test convention — a test exercising a multi-call flow (e.g.
+ * start then complete) must pass the same concrete `pending`/`listenerRef` across both calls, the
+ * same way a real mounted server does.
+ *
+ * **SEC-005 throughout**: every thrown error (listener bind failure, token-exchange/refresh
+ * failure, token read/write failure, the `x_search` upstream call) is converted to a redacted,
+ * correlation-id-bearing generic `INTERNAL_ERROR` before reaching the caller — the HTTP *response*
+ * never carries the raw error regardless of source. For the two paths that actually touch an
+ * untrusted upstream response body — token exchange/refresh (`handleListenerCallback`/
+ * `xaiOauthCompleteRoute`) and `callXaiSearch` (which sends this file's own just-issued bearer
+ * token as a header, the highest-risk path) — `redactSecrets` (reused from `@jini-ai/agent-runtime`'s
+ * `connection-guard.ts`, already this package's `research.ts` precedent) additionally strips any
+ * Bearer/api-key-shaped text out of the message before it is even logged to the host's own sink
+ * (`redactError`/`callXaiSearch`'s own inline redaction), belt-and-braces beyond the generic-message
+ * substitution the caller already gets. Purely local failures (a listener-bind `EADDRINUSE`, an
+ * `fs` read/write error) carry no upstream text and are passed through to the sink unredacted — the
+ * generic response substitution alone already satisfies SEC-005 for those. The one deliberate
+ * exception: `completeOAuthPkce`'s own "state not found or expired" / "state mismatch" validation
+ * errors (thrown before any network call, carrying no secret) are surfaced verbatim as
+ * `BAD_REQUEST` — a legitimate client-correctable error, not an internal failure to redact.
+ *
+ * **Two known, deliberate, non-functional divergences from OD's exact wire text, both confirmed
+ * against the real OD daemon (2026-07-22 live-parity pass) and left as-is:**
+ * 1. `GET /api/xai/auth/status` when disconnected: OD's real handler (`routes/xai.ts:205-207`)
+ *    returns only `{ connected: false, listening }` — `expiresAt`/`scope`/`savedAt` are *omitted*
+ *    entirely, confirmed live (`{"connected":false,"listening":false}`, no other keys). This file's
+ *    `XaiAuthStatusResponse` always includes those three keys, set to `null` when disconnected —
+ *    a deliberate stable-typed-envelope choice (avoids an `expiresAt?: number` optional-vs-null split
+ *    for callers) consistent with this package's established camelCase/typed-shape departures from
+ *    OD elsewhere in this same file; not changed to avoid weakening the typed response contract.
+ * 2. The "state not found or expired" / "state mismatch" `BAD_REQUEST` text
+ *    (`@jini-ai/agent-runtime`'s `oauth-provider.ts`) reads `xai OAuth state ...` (lowercase, from the
+ *    generic `providerId: 'xai'` config field shared across providers), where OD's real, hardcoded
+ *    string (`integrations/xai-oauth.ts:131,134-136`) reads `xAI OAuth state ...` (mixed-case, a
+ *    literal specific to that one file). Confirmed live (`{"error":"xAI OAuth state not found or
+ *    expired"}` from the real daemon). Purely cosmetic — same meaning, same `BAD_REQUEST` classifi-
+ *    cation either way (`xaiOauthCompleteRoute`'s own prefix check uses the same `providerId` for
+ *    both generation and matching, so it's internally self-consistent) — and the casing lives in
+ *    `@jini-ai/agent-runtime`'s already-shipped generic module, outside this file's own scope to alter
+ *    without special-casing one provider's capitalization inside otherwise-generic code.
+ */
+import { randomUUID } from 'node:crypto';
+import { beginOAuthPkce, clearStoredOAuthToken, completeOAuthPkce, getStoredOAuthToken, PendingAuthCache, redactSecrets, resolveOAuthBearer, setStoredOAuthToken, startOAuthCallbackListener, validateBaseUrl, XAI_OAUTH_PROVIDER_CONFIG, XAI_OAUTH_REDIRECT_HOST, XAI_OAUTH_REDIRECT_PATH, XAI_OAUTH_REDIRECT_PORT, } from '@jini-ai/agent-runtime';
+import { createApiError } from '@jini-ai/protocol';
+import { defineJsonRoute, mountJsonRoute } from './adapter.js';
+import { validationError } from './request.js';
+import { err, ok } from './types.js';
+const DEFAULT_TOKEN_FILE_NAME = 'xai-oauth-token.json';
+/** Matches the loopback listener's own 30-minute self-close timeout (OD's real comment: keeps the
+ * PKCE state, the open socket, and any paste-back UI expiring together). */
+const DEFAULT_PENDING_AUTH_TTL_MS = 30 * 60 * 1000;
+const DEFAULT_SEARCH_BASE_URL = 'https://api.x.ai/v1';
+/** xAI's real Responses-API model id for `x_search`, per OD's origin `X_SEARCH_DEFAULT_MODEL`. */
+const DEFAULT_SEARCH_MODEL = 'grok-4.20-reasoning';
+/** Deadline for one xAI search request, covering the response body as well as the request. Matches `research.ts`'s `DEFAULT_TAVILY_TIMEOUT_MS` — the two outbound-provider paths in this package should not disagree about how long a stalled upstream may pin a handler. */
+const DEFAULT_SEARCH_TIMEOUT_MS = 30_000;
+function defaultInternalErrorSink(context) {
+    // eslint-disable-next-line no-console
+    console.error(`[@jini-ai/http-kit] internal error (xai/${context.source}, correlationId=${context.correlationId})`, context.error);
+}
+/** Resolves every optional `XaiHttpDeps` field to a concrete value. Idempotent — calling this again on an already-resolved object (e.g. `registerXaiRoutes`'s own single resolution, passed through to each route's `handle`) is a harmless pass-through. See module doc on why stateful fields (`pending`/`listenerRef`) must be resolved once per registration, not once per request. */
+function resolveXaiHttpDeps(deps) {
+    return {
+        dataDir: deps.dataDir ?? process.cwd(),
+        tokenFileName: deps.tokenFileName ?? DEFAULT_TOKEN_FILE_NAME,
+        providerConfig: deps.providerConfig ?? XAI_OAUTH_PROVIDER_CONFIG,
+        callbackHost: deps.callbackHost ?? XAI_OAUTH_REDIRECT_HOST,
+        callbackPort: deps.callbackPort ?? XAI_OAUTH_REDIRECT_PORT,
+        callbackPath: deps.callbackPath ?? XAI_OAUTH_REDIRECT_PATH,
+        pending: deps.pending ?? new PendingAuthCache(DEFAULT_PENDING_AUTH_TTL_MS),
+        listenerRef: deps.listenerRef ?? { current: null },
+        startCallbackListener: deps.startCallbackListener ?? startOAuthCallbackListener,
+        searchBaseUrl: deps.searchBaseUrl ?? DEFAULT_SEARCH_BASE_URL,
+        searchDefaultModel: deps.searchDefaultModel ?? DEFAULT_SEARCH_MODEL,
+        fetchImpl: deps.fetchImpl ?? fetch,
+        searchTimeoutMs: deps.searchTimeoutMs ?? DEFAULT_SEARCH_TIMEOUT_MS,
+        onInternalError: deps.onInternalError ?? defaultInternalErrorSink,
+    };
+}
+function xaiRedirectUri(resolved) {
+    return `http://${resolved.callbackHost}:${resolved.callbackPort}${resolved.callbackPath}`;
+}
+/** Stops (best-effort) and clears the in-flight loopback listener, if any. Never throws — the listener self-closes on completion/timeout anyway, matching OD's origin `stopActiveListener`. */
+async function stopListener(listenerRef) {
+    const current = listenerRef.current;
+    listenerRef.current = null;
+    if (!current)
+        return;
+    try {
+        await current.stop();
+    }
+    catch {
+        // Best-effort only — see this function's own doc.
+    }
+}
+/**
+ * Serializes OAuth starts that share one `listenerRef`, keyed by the ref object itself (a
+ * `WeakMap`, so a host that discards a registration's deps does not leak an entry here).
+ *
+ * The loopback callback port is a singleton, and `oauth/start` both checks and claims it
+ * (`listenerRef.current`) across two `await`s (`beginOAuthPkce` then `startCallbackListener`).
+ * Without serializing, two concurrent starts could both observe `listenerRef.current === null`
+ * before either claimed it, both proceed to open a listener, and the second's write would
+ * silently clobber the first's — the first caller would already have been handed an
+ * `authorizeUrl` whose callback endpoint just died, with no error ever surfaced to it. That is
+ * the exact race `xaiOauthStartRoute`'s own `OAUTH_FLOW_IN_PROGRESS` conflict check exists to
+ * reject instead of silently losing. Serializing makes "check the slot, then claim it" the single
+ * indivisible step it always needed to be, so that check can never race with itself.
+ */
+const oauthStartQueues = new WeakMap();
+function serializeOauthStart(key, task) {
+    const previous = oauthStartQueues.get(key) ?? Promise.resolve();
+    // `then(task, task)` so a rejected predecessor still lets the next start run — this is a mutex,
+    // not a dependency chain.
+    const next = previous.then(task, task);
+    // The stored link must never reject, or an unhandled rejection escapes and every later start
+    // inherits it. Only the returned promise carries the outcome.
+    oauthStartQueues.set(key, next.then(() => undefined, () => undefined));
+    return next;
+}
+/** Redacts any Bearer/api-key/`key=`-shaped secret out of a thrown value's message before it reaches the internal-error sink — belt-and-braces even on paths (token exchange/refresh) that don't send a bearer header of our own, since the upstream error body is otherwise passed through verbatim. Matches `callXaiSearch`'s own redaction; kept as a separate helper since those two paths have no exact-secret value in common to pass as `redactSecrets`' second argument. */
+function redactError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return new Error(redactSecrets(message));
+}
+async function persistToken(resolved, tokenResp) {
+    const stored = {
+        accessToken: tokenResp.access_token,
+        tokenType: tokenResp.token_type ?? 'Bearer',
+        savedAt: Date.now(),
+    };
+    if (tokenResp.refresh_token)
+        stored.refreshToken = tokenResp.refresh_token;
+    if (tokenResp.scope)
+        stored.scope = tokenResp.scope;
+    if (typeof tokenResp.expires_in === 'number') {
+        stored.expiresAt = Date.now() + tokenResp.expires_in * 1000;
+    }
+    await setStoredOAuthToken(resolved.dataDir, resolved.tokenFileName, stored);
+}
+/** Invoked when the loopback listener actually receives xAI's redirect (the real-browser path, as opposed to `oauth/complete`'s manual paste-back path — xAI's own docs note the loopback redirect commonly shows the user a code to paste rather than following the redirect). No HTTP response to write here; failures are only reported through the internal-error sink. */
+async function handleListenerCallback(resolved, outcome) {
+    resolved.listenerRef.current = null;
+    if (outcome.kind !== 'ok') {
+        resolved.onInternalError({
+            source: 'oauth-start',
+            correlationId: randomUUID(),
+            error: new Error(`xAI OAuth callback failed: ${outcome.error}`),
+        });
+        return;
+    }
+    try {
+        const tokenResp = await completeOAuthPkce({
+            config: resolved.providerConfig,
+            pending: resolved.pending,
+            state: outcome.state,
+            code: outcome.code,
+            fetchImpl: resolved.fetchImpl,
+        });
+        await persistToken(resolved, tokenResp);
+    }
+    catch (error) {
+        resolved.onInternalError({ source: 'oauth-start', correlationId: randomUUID(), error: redactError(error) });
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Trims before checking/returning — matches OD's real route handlers, which trim `state`/`code`
+ * (`routes/xai.ts:154-157`) and `query` (`routes/xai.ts:258`) before ever using them, so a
+ * paste-back value with incidental leading/trailing whitespace (the common case for xAI's own
+ * loopback-redirect UX, which shows the user a code to copy rather than following a redirect — see
+ * this file's own `xaiOauthCompleteRoute` doc) still matches the exact state string the pending-auth
+ * cache stored it under. Live-verified against the real OD daemon (2026-07-22 live-parity pass):
+ * `POST /oauth/complete` with a state padded in extra spaces around a real, still-pending state
+ * proceeded straight to the token exchange (reaching `auth.x.ai`'s real "invalid_grant" response)
+ * instead of failing with "state not found or expired" — proving OD's server-side trim, not just its
+ * request-body parsing, is load-bearing. This file's own three `nonEmptyString` call sites
+ * (`state`/`code` in `parseXaiOauthComplete`, `query` in `parseXaiSearch`) are exactly OD's three
+ * trimmed fields — `fromDate`/`toDate`/`model` deliberately go through `parseOptionalString` instead,
+ * which does not trim, matching OD's own untrimmed `from_date`/`to_date`/`model` handling. */
+function nonEmptyString(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function parseOptionalString(body, key) {
+    const value = body[key];
+    if (value === undefined)
+        return ok(undefined);
+    if (typeof value !== 'string')
+        return err(validationError(`${key} must be a string when provided`));
+    return ok(value);
+}
+function parseOptionalBoolean(body, key) {
+    const value = body[key];
+    if (value === undefined)
+        return ok(undefined);
+    if (typeof value !== 'boolean')
+        return err(validationError(`${key} must be a boolean when provided`));
+    return ok(value);
+}
+function parseOptionalStringArray(body, key) {
+    const value = body[key];
+    if (value === undefined)
+        return ok(undefined);
+    if (!Array.isArray(value) || !value.every((v) => typeof v === 'string')) {
+        return err(validationError(`${key} must be an array of strings when provided`));
+    }
+    return ok(value);
+}
+export const xaiOauthStartRoute = defineJsonRoute({
+    method: 'post',
+    path: '/api/xai/oauth/start',
+    requireSameOrigin: true,
+    parse: () => ok(undefined),
+    handle: async (_input, deps) => {
+        const resolved = resolveXaiHttpDeps(deps);
+        // Only one OAuth dance can be in flight at a time — the loopback port is a singleton. A
+        // second `start` arriving while a listener from a prior `start` is still bound/waiting used
+        // to silently stop that listener and open a new one: the first caller's already-returned
+        // `authorizeUrl` would point at a now-dead callback endpoint with no error ever surfaced to
+        // it. Fail loud instead: reject with a conflict and require the caller to finish
+        // (`oauth/complete`) or explicitly cancel (`POST /api/xai/oauth/cancel`) the in-flight flow
+        // first. The check-then-claim runs under `serializeOauthStart` so two concurrent starts can't
+        // both observe an empty slot — see that function's doc.
+        return serializeOauthStart(resolved.listenerRef, async () => {
+            if (resolved.listenerRef.current !== null) {
+                return err(createApiError('OAUTH_FLOW_IN_PROGRESS', 'an xAI OAuth flow is already in progress — complete it, or cancel it via POST /api/xai/oauth/cancel, before starting a new one'));
+            }
+            try {
+                const { authorizeUrl, state } = beginOAuthPkce({
+                    config: resolved.providerConfig,
+                    pending: resolved.pending,
+                    redirectUri: xaiRedirectUri(resolved),
+                });
+                const listener = await resolved.startCallbackListener({
+                    host: resolved.callbackHost,
+                    port: resolved.callbackPort,
+                    path: resolved.callbackPath,
+                    expectedState: state,
+                    onCallback: (outcome) => handleListenerCallback(resolved, outcome),
+                });
+                resolved.listenerRef.current = listener;
+                return ok({
+                    authorizeUrl,
+                    state,
+                    callback: { host: listener.address.host, port: listener.address.port },
+                });
+            }
+            catch (error) {
+                await stopListener(resolved.listenerRef);
+                const correlationId = randomUUID();
+                resolved.onInternalError({ source: 'oauth-start', correlationId, error });
+                return err(createApiError('INTERNAL_ERROR', 'an internal error occurred', { requestId: correlationId }));
+            }
+        });
+    },
+});
+function parseXaiOauthComplete(input) {
+    if (!isRecord(input.body))
+        return err(validationError('body must be a JSON object'));
+    const state = nonEmptyString(input.body.state);
+    if (!state)
+        return err(validationError('state must be a non-empty string', [{ path: 'state', message: 'required non-empty string' }]));
+    const code = nonEmptyString(input.body.code);
+    if (!code)
+        return err(validationError('code must be a non-empty string', [{ path: 'code', message: 'required non-empty string' }]));
+    return ok({ state, code });
+}
+export const xaiOauthCompleteRoute = defineJsonRoute({
+    method: 'post',
+    path: '/api/xai/oauth/complete',
+    requireSameOrigin: true,
+    parse: parseXaiOauthComplete,
+    handle: async ({ state, code }, deps) => {
+        const resolved = resolveXaiHttpDeps(deps);
+        try {
+            const tokenResp = await completeOAuthPkce({
+                config: resolved.providerConfig,
+                pending: resolved.pending,
+                state,
+                code,
+                fetchImpl: resolved.fetchImpl,
+            });
+            await persistToken(resolved, tokenResp);
+            // We won the race against the loopback listener (or it was never going to resolve in the
+            // first place); shut it down so the next `oauth/start` has a clean slate — matching OD's
+            // origin behavior on a successful manual paste-back.
+            await stopListener(resolved.listenerRef);
+            return ok({ ok: true });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            // `completeOAuthPkce`'s own pre-network validation errors ("state not found or expired",
+            // "state mismatch...") carry no secret and are a legitimate client-correctable failure —
+            // surfaced verbatim as BAD_REQUEST rather than folded into the SEC-005 INTERNAL_ERROR path
+            // below (see module doc's "SEC-005 throughout" section). Exact-prefix match, not substring:
+            // pkce.ts#tokenRequest's upstream-error message ("token endpoint rejected request: ...")
+            // can legitimately contain the substring "OAuth state" inside an attacker-influenced token
+            // endpoint error body, which must never be reflected raw to the caller.
+            if (message.startsWith(`${resolved.providerConfig.providerId} OAuth state`)) {
+                return err(validationError(message));
+            }
+            const correlationId = randomUUID();
+            resolved.onInternalError({ source: 'oauth-complete', correlationId, error: redactError(error) });
+            return err(createApiError('INTERNAL_ERROR', 'an internal error occurred', { requestId: correlationId }));
+        }
+    },
+});
+// ---------------------------------------------------------------------------
+// POST /api/xai/oauth/cancel
+// ---------------------------------------------------------------------------
+export const xaiOauthCancelRoute = defineJsonRoute({
+    method: 'post',
+    path: '/api/xai/oauth/cancel',
+    requireSameOrigin: true,
+    parse: () => ok(undefined),
+    handle: async (_input, deps) => {
+        const resolved = resolveXaiHttpDeps(deps);
+        // Cancel only stops the in-flight loopback listener; it must never wipe a stored token — a
+        // user clicking Cancel mid-reconnect would otherwise lose their existing grant. Disconnect
+        // (below) is the destructive path. Matches OD's origin `oauth/cancel` handler exactly.
+        await stopListener(resolved.listenerRef);
+        return ok({ ok: true });
+    },
+});
+export const xaiAuthStatusRoute = defineJsonRoute({
+    method: 'get',
+    path: '/api/xai/auth/status',
+    requireSameOrigin: true,
+    parse: () => ok(undefined),
+    handle: async (_input, deps) => {
+        const resolved = resolveXaiHttpDeps(deps);
+        try {
+            const token = await getStoredOAuthToken(resolved.dataDir, resolved.tokenFileName);
+            const listening = resolved.listenerRef.current !== null;
+            if (!token)
+                return ok({ connected: false, expiresAt: null, scope: null, savedAt: null, listening });
+            return ok({
+                connected: true,
+                expiresAt: token.expiresAt ?? null,
+                scope: token.scope ?? null,
+                savedAt: token.savedAt,
+                listening,
+            });
+        }
+        catch (error) {
+            const correlationId = randomUUID();
+            resolved.onInternalError({ source: 'auth-status', correlationId, error });
+            return err(createApiError('INTERNAL_ERROR', 'an internal error occurred', { requestId: correlationId }));
+        }
+    },
+});
+// ---------------------------------------------------------------------------
+// POST /api/xai/oauth/disconnect
+// ---------------------------------------------------------------------------
+export const xaiOauthDisconnectRoute = defineJsonRoute({
+    method: 'post',
+    path: '/api/xai/oauth/disconnect',
+    requireSameOrigin: true,
+    parse: () => ok(undefined),
+    handle: async (_input, deps) => {
+        const resolved = resolveXaiHttpDeps(deps);
+        try {
+            await stopListener(resolved.listenerRef);
+            await clearStoredOAuthToken(resolved.dataDir, resolved.tokenFileName);
+            return ok({ ok: true });
+        }
+        catch (error) {
+            const correlationId = randomUUID();
+            resolved.onInternalError({ source: 'oauth-disconnect', correlationId, error });
+            return err(createApiError('INTERNAL_ERROR', 'an internal error occurred', { requestId: correlationId }));
+        }
+    },
+});
+function parseXaiSearch(input) {
+    if (!isRecord(input.body))
+        return err(validationError('body must be a JSON object'));
+    const body = input.body;
+    const query = nonEmptyString(body.query);
+    if (!query)
+        return err(validationError('query must be a non-empty string', [{ path: 'query', message: 'required non-empty string' }]));
+    const allowedXHandles = parseOptionalStringArray(body, 'allowedXHandles');
+    if (!allowedXHandles.ok)
+        return allowedXHandles;
+    const excludedXHandles = parseOptionalStringArray(body, 'excludedXHandles');
+    if (!excludedXHandles.ok)
+        return excludedXHandles;
+    const fromDate = parseOptionalString(body, 'fromDate');
+    if (!fromDate.ok)
+        return fromDate;
+    const toDate = parseOptionalString(body, 'toDate');
+    if (!toDate.ok)
+        return toDate;
+    const enableImageUnderstanding = parseOptionalBoolean(body, 'enableImageUnderstanding');
+    if (!enableImageUnderstanding.ok)
+        return enableImageUnderstanding;
+    const enableVideoUnderstanding = parseOptionalBoolean(body, 'enableVideoUnderstanding');
+    if (!enableVideoUnderstanding.ok)
+        return enableVideoUnderstanding;
+    const model = parseOptionalString(body, 'model');
+    if (!model.ok)
+        return model;
+    return ok({
+        query,
+        ...(allowedXHandles.value?.length ? { allowedXHandles: allowedXHandles.value } : {}),
+        ...(excludedXHandles.value?.length ? { excludedXHandles: excludedXHandles.value } : {}),
+        ...(fromDate.value ? { fromDate: fromDate.value } : {}),
+        ...(toDate.value ? { toDate: toDate.value } : {}),
+        ...(enableImageUnderstanding.value !== undefined ? { enableImageUnderstanding: enableImageUnderstanding.value } : {}),
+        ...(enableVideoUnderstanding.value !== undefined ? { enableVideoUnderstanding: enableVideoUnderstanding.value } : {}),
+        ...(model.value ? { model: model.value } : {}),
+    });
+}
+/** Pulls the assistant's main text out of an xAI Responses-API payload — the convenience `output_text` field, or the structured `output[].content[].text` form. Ported verbatim from OD's `extractAnswerText`. */
+function extractAnswerText(data) {
+    if (!isRecord(data))
+        return '';
+    const direct = data.output_text;
+    if (typeof direct === 'string' && direct.trim())
+        return direct;
+    const output = data.output;
+    if (!Array.isArray(output))
+        return '';
+    const chunks = [];
+    for (const item of output) {
+        if (!isRecord(item))
+            continue;
+        const content = item.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const block of content) {
+            if (!isRecord(block))
+                continue;
+            const t = block.text;
+            if (typeof t === 'string' && t)
+                chunks.push(t);
+        }
+    }
+    return chunks.join('\n').trim();
+}
+/** Walks every annotation in the Responses-API output and returns the unique URL citations (`type: 'url_citation'`). Ported verbatim from OD's `extractUrlCitations`. */
+function extractUrlCitations(data) {
+    if (!isRecord(data))
+        return [];
+    const output = data.output;
+    if (!Array.isArray(output))
+        return [];
+    const urls = new Set();
+    for (const item of output) {
+        if (!isRecord(item))
+            continue;
+        const content = item.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const block of content) {
+            if (!isRecord(block))
+                continue;
+            const annotations = block.annotations;
+            if (!Array.isArray(annotations))
+                continue;
+            for (const ann of annotations) {
+                if (!isRecord(ann))
+                    continue;
+                if (ann.type !== 'url_citation')
+                    continue;
+                const url = typeof ann.url === 'string' ? ann.url.trim() : '';
+                if (url)
+                    urls.add(url);
+            }
+        }
+    }
+    return [...urls];
+}
+/** Calls xAI's real `POST {searchBaseUrl}/responses` endpoint with the `x_search` native tool, using `accessToken` as the bearer credential. Throws (never a `Result`) on any failure — `xaiSearchRoute.handle` is the one place that converts a thrown error into this package's SEC-005 response shape. Any thrown message is pre-redacted of `accessToken` here so the sink never even logs it unredacted. */
+async function callXaiSearch(resolved, accessToken, request) {
+    const baseUrlCheck = validateBaseUrl(resolved.searchBaseUrl);
+    if (baseUrlCheck.error)
+        throw new Error(baseUrlCheck.error);
+    const base = resolved.searchBaseUrl.replace(/\/+$/, '');
+    const model = request.model ?? resolved.searchDefaultModel;
+    const xSearchTool = { type: 'x_search' };
+    if (request.allowedXHandles?.length)
+        xSearchTool.allowed_x_handles = request.allowedXHandles;
+    if (request.excludedXHandles?.length)
+        xSearchTool.excluded_x_handles = request.excludedXHandles;
+    if (request.fromDate)
+        xSearchTool.from_date = request.fromDate;
+    if (request.toDate)
+        xSearchTool.to_date = request.toDate;
+    if (request.enableImageUnderstanding === true)
+        xSearchTool.enable_image_understanding = true;
+    if (request.enableVideoUnderstanding === true)
+        xSearchTool.enable_video_understanding = true;
+    const requestBody = {
+        model,
+        input: [{ role: 'user', content: request.query }],
+        tools: [xSearchTool],
+        store: false,
+    };
+    // One deadline covering the request *and* the body read, mirroring `research.ts`'s Tavily call.
+    // Arming it only around `fetch` would leave the far more common stall unbounded: an upstream that
+    // returns headers promptly and then never finishes the body still pins this handler, its socket
+    // and the caller's connection forever. The timer is cleared in a `finally` so a fast response
+    // does not leave one armed.
+    const timeoutController = new AbortController();
+    const timeoutHandle = setTimeout(() => timeoutController.abort(), resolved.searchTimeoutMs);
+    const timedOutMessage = `xAI request timed out after ${resolved.searchTimeoutMs}ms`;
+    try {
+        let response;
+        try {
+            response = await resolved.fetchImpl(`${base}/responses`, {
+                method: 'POST',
+                headers: { authorization: `Bearer ${accessToken}`, 'content-type': 'application/json' },
+                body: JSON.stringify(requestBody),
+                signal: timeoutController.signal,
+            });
+        }
+        catch (error) {
+            if (timeoutController.signal.aborted)
+                throw new Error(timedOutMessage);
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(redactSecrets(`xAI request failed: ${message}`, [accessToken]));
+        }
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            throw new Error(redactSecrets(`xAI ${response.status}: ${text.slice(0, 240) || 'no body'}`, [accessToken]));
+        }
+        let data;
+        try {
+            data = await response.json();
+        }
+        catch (error) {
+            if (timeoutController.signal.aborted)
+                throw new Error(timedOutMessage);
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(redactSecrets(`xAI response could not be read: ${message}`, [accessToken]));
+        }
+        return { answer: extractAnswerText(data), citations: extractUrlCitations(data), model };
+    }
+    finally {
+        clearTimeout(timeoutHandle);
+    }
+}
+export const xaiSearchRoute = defineJsonRoute({
+    method: 'post',
+    path: '/api/xai/search',
+    requireSameOrigin: true,
+    parse: parseXaiSearch,
+    handle: async (request, deps) => {
+        const resolved = resolveXaiHttpDeps(deps);
+        let credential;
+        try {
+            credential = await resolveOAuthBearer(resolved.providerConfig, resolved.tokenFileName, resolved.dataDir, resolved.fetchImpl);
+        }
+        catch (error) {
+            const correlationId = randomUUID();
+            resolved.onInternalError({ source: 'search', correlationId, error });
+            return err(createApiError('INTERNAL_ERROR', 'an internal error occurred', { requestId: correlationId }));
+        }
+        if (!credential) {
+            // No entitlement gate here — see module doc's "Dropped: OD's SuperGrok subscription gate"
+            // section. This is only "no connected/refreshable xAI account," an honest, non-exceptional
+            // NOT_CONFIGURED (503), matching `research.ts`'s "capability exists, reachable, inert until
+            // configured" shape.
+            return err(createApiError('NOT_CONFIGURED', 'no xAI account connected — sign in via /api/xai/oauth/start first'));
+        }
+        try {
+            const result = await callXaiSearch(resolved, credential.accessToken, request);
+            return ok(result);
+        }
+        catch (error) {
+            const correlationId = randomUUID();
+            resolved.onInternalError({ source: 'search', correlationId, error });
+            return err(createApiError('INTERNAL_ERROR', 'an internal error occurred', { requestId: correlationId }));
+        }
+    },
+});
+/** Mounts every xAI route on `app`. A pack's `http(app, services)` calls this directly. */
+export function registerXaiRoutes(app, deps, adapter) {
+    const resolved = resolveXaiHttpDeps(deps);
+    mountJsonRoute(app, xaiOauthStartRoute, resolved, adapter);
+    mountJsonRoute(app, xaiOauthCompleteRoute, resolved, adapter);
+    mountJsonRoute(app, xaiOauthCancelRoute, resolved, adapter);
+    mountJsonRoute(app, xaiAuthStatusRoute, resolved, adapter);
+    mountJsonRoute(app, xaiOauthDisconnectRoute, resolved, adapter);
+    mountJsonRoute(app, xaiSearchRoute, resolved, adapter);
+}
+//# sourceMappingURL=xai.js.map