@volter/twin-xai 0.1.0

package/src/xai-conformance.ts

@@ -0,0 +1,136 @@
+// xAI twin conformance — a lightweight, offline structural check that the twin's served
+// response ENVELOPES match the documented xAI shapes. xAI publishes no first-party
+// machine-readable spec (spec-sources.json records kind:'none'), so this harness validates
+// the load-bearing envelope SHAPES directly: chat.completion (+ the streaming chunk
+// sequence + tool_calls), the flat {code, error} error envelope, the three model catalogs,
+// deferred-completion lifecycle, tokenize-text, image generations, and the Anthropic-
+// compatible /v1/messages envelope. Fully offline + deterministic (drives the local handler
+// against a temp root) so it runs in CI without an API key. Honest scope: it checks the
+// protocol envelope, NOT model output (a deterministic labeled stub by design).
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { handleXaiTwinRequest } from './xai-twin.ts';
+import type { SseEvent } from './xai-types.ts';
+
+export type ConformanceViolation = { check: string; detail: string };
+export type XaiConformanceReport = {
+  ok: boolean;
+  checksRun: number;
+  violations: ConformanceViolation[];
+};
+
+type Body = Record<string, unknown>;
+const isObj = (v: unknown): v is Body => !!v && typeof v === 'object' && !Array.isArray(v);
+
+/** Run the offline conformance checks against a fresh temp root. */
+export async function checkXaiConformance(opts: { root?: string } = {}): Promise<XaiConformanceReport> {
+  const root = opts.root ?? mkdtempSync(join(tmpdir(), 'xai-conf-'));
+  const owned = opts.root === undefined;
+  const violations: ConformanceViolation[] = [];
+  let checksRun = 0;
+  const fail = (check: string, detail: string) => violations.push({ check, detail });
+  const H = (method: string, path: string, body?: string, sseSink?: (e: SseEvent) => void) =>
+    handleXaiTwinRequest({ method, path, body, root, occurredAt: '2026-01-01T00:00:00Z', ...(sseSink ? { sseSink } : {}) });
+
+  try {
+    // 1. chat.completion response envelope (+ xAI usage detail objects).
+    checksRun++;
+    const chat = await H('POST', '/v1/chat/completions', JSON.stringify({ model: 'grok-4-0709', messages: [{ role: 'user', content: 'hi' }] }));
+    const cb = chat.body as Body;
+    if (chat.status !== 200) fail('chat.envelope', `status ${chat.status}`);
+    else {
+      for (const k of ['id', 'object', 'created', 'model', 'choices', 'usage', 'system_fingerprint']) if (!(k in cb)) fail('chat.envelope', `missing field "${k}"`);
+      if (cb.object !== 'chat.completion') fail('chat.envelope', `object is ${String(cb.object)}`);
+      const choices = cb.choices as Body[];
+      if (!Array.isArray(choices) || !isObj(choices[0]) || (choices[0]!.message as Body)?.role !== 'assistant') fail('chat.envelope', 'choices[0].message not assistant');
+      if ((choices[0]!.finish_reason) !== 'stop') fail('chat.envelope', `finish_reason is ${String(choices[0]!.finish_reason)}`);
+      const usage = cb.usage as Body;
+      if (!isObj(usage) || typeof usage.prompt_tokens !== 'number' || typeof usage.total_tokens !== 'number') fail('chat.usage', 'usage missing prompt/total tokens');
+      if (!isObj(usage?.prompt_tokens_details) || !isObj(usage?.completion_tokens_details)) fail('chat.usage', 'usage missing xAI token detail objects');
+    }
+
+    // 2. chat streaming chunk sequence (ends with done).
+    checksRun++;
+    const events: SseEvent[] = [];
+    await H('POST', '/v1/chat/completions', JSON.stringify({ model: 'grok-4-0709', stream: true, messages: [{ role: 'user', content: 'stream' }] }), (e) => events.push(e));
+    const hasRole = events.some((e) => !e.done && ((e.data!.choices as Body[])?.[0]?.delta as Body)?.role === 'assistant');
+    const hasDone = events.length > 0 && events[events.length - 1]!.done === true;
+    const firstChunkObj = events[0]?.data?.object;
+    if (!hasRole) fail('chat.stream', 'no role delta chunk');
+    if (!hasDone) fail('chat.stream', 'stream did not end with [DONE]');
+    if (firstChunkObj !== 'chat.completion.chunk') fail('chat.stream', `first chunk object is ${String(firstChunkObj)}`);
+
+    // 3. tool_calls envelope when tools provided.
+    checksRun++;
+    const tool = await H('POST', '/v1/chat/completions', JSON.stringify({ model: 'grok-4-0709', tools: [{ type: 'function', function: { name: 'get_weather', parameters: { type: 'object' } } }], messages: [{ role: 'user', content: 'weather?' }] }));
+    const tc = (tool.body as Body).choices as Body[];
+    if ((tc?.[0]?.finish_reason) !== 'tool_calls') fail('chat.tool_calls', 'finish_reason not tool_calls');
+    const calls = (tc?.[0]?.message as Body)?.tool_calls as Body[];
+    if (!Array.isArray(calls) || calls[0]?.type !== 'function') fail('chat.tool_calls', 'no function tool_call');
+
+    // 4. the flat {code, error} error envelope (xAI's gRPC-transcoded shape) + unknown model 404.
+    checksRun++;
+    const bad = await H('POST', '/v1/chat/completions', JSON.stringify({ messages: [{ role: 'user', content: 'hi' }] }));
+    const eb = bad.body as Body;
+    if (bad.status !== 400 || typeof eb.code !== 'string' || typeof eb.error !== 'string') fail('error.envelope', 'missing model did not yield the flat {code, error} 400 envelope');
+    if (isObj(eb.error)) fail('error.envelope', 'error must be a FLAT string, not a nested object (that is OpenAI\'s shape, not xAI\'s)');
+    const noModel = await H('POST', '/v1/chat/completions', JSON.stringify({ model: 'grok-nope', messages: [{ role: 'user', content: 'hi' }] }));
+    if (noModel.status !== 404 || typeof (noModel.body as Body).code !== 'string') fail('error.model_not_found', 'unknown model did not 404 with the {code, error} envelope');
+    const nf = await H('GET', '/v1/nonexistent');
+    if (nf.status !== 404 || typeof (nf.body as Body).code !== 'string') fail('error.not_found', 'unknown route did not 404');
+
+    // 5. the three model catalogs (flat + rich + image).
+    checksRun++;
+    const models = await H('GET', '/v1/models');
+    if (!Array.isArray((models.body as Body).data)) fail('models.list', 'no data array');
+    const one = await H('GET', '/v1/models/grok-4-0709');
+    if ((one.body as Body).object !== 'model') fail('models.retrieve', 'object is not a model');
+    const rich = await H('GET', '/v1/language-models');
+    const richList = (rich.body as Body).models as Body[];
+    if (!Array.isArray(richList) || !richList.some((m) => Array.isArray(m.aliases))) fail('models.language', 'no rich models array with aliases');
+    const img = await H('GET', '/v1/image-generation-models');
+    if (!Array.isArray((img.body as Body).models)) fail('models.image', 'no image-generation models array');
+
+    // 6. deferred completion lifecycle: request_id → 202 pending → 200 result → 404 after.
+    checksRun++;
+    const def = await H('POST', '/v1/chat/completions', JSON.stringify({ model: 'grok-4-0709', deferred: true, messages: [{ role: 'user', content: 'later' }] }));
+    const reqId = (def.body as Body).request_id;
+    if (def.status !== 200 || typeof reqId !== 'string') fail('deferred.create', 'no request_id');
+    else {
+      const p1 = await H('GET', `/v1/chat/deferred-completion/${reqId}`);
+      if (p1.status !== 202) fail('deferred.pending', `first poll status ${p1.status}`);
+      const p2 = await H('GET', `/v1/chat/deferred-completion/${reqId}`);
+      if (p2.status !== 200 || (p2.body as Body).object !== 'chat.completion') fail('deferred.result', 'second poll did not serve the completion');
+      const p3 = await H('GET', `/v1/chat/deferred-completion/${reqId}`);
+      if (p3.status !== 404) fail('deferred.consumed_once', 'result served more than once');
+    }
+
+    // 7. tokenize-text + api-key introspection.
+    checksRun++;
+    const tok = await H('POST', '/v1/tokenize-text', JSON.stringify({ text: 'hello twin', model: 'grok-4-0709' }));
+    const ids = (tok.body as Body).token_ids as Body[];
+    if (!Array.isArray(ids) || ids.length === 0 || typeof ids[0]?.token_id !== 'number') fail('tokenize.shape', 'no token_ids array');
+    const key = await H('GET', '/v1/api-key');
+    if (typeof (key.body as Body).redacted_api_key !== 'string' || !Array.isArray((key.body as Body).acls)) fail('api_key.shape', 'no redacted_api_key/acls');
+
+    // 8. image generations (shape + the size-rejected compatibility delta).
+    checksRun++;
+    const image = await H('POST', '/v1/images/generations', JSON.stringify({ model: 'grok-2-image', prompt: 'a cat' }));
+    const data = (image.body as Body).data as Body[];
+    if (!Array.isArray(data) || typeof data[0]?.url !== 'string') fail('images.shape', 'no data[].url');
+    const size = await H('POST', '/v1/images/generations', JSON.stringify({ model: 'grok-2-image', prompt: 'a cat', size: '1024x1024' }));
+    if (size.status !== 400) fail('images.size_rejected', 'size param was not rejected (xAI rejects OpenAI\'s size)');
+
+    // 9. Anthropic-compatible /v1/messages envelope.
+    checksRun++;
+    const msg = await H('POST', '/v1/messages', JSON.stringify({ model: 'grok-4-0709', max_tokens: 256, messages: [{ role: 'user', content: 'hi' }] }));
+    const mb = msg.body as Body;
+    if (mb.type !== 'message' || !Array.isArray(mb.content) || (mb.content as Body[])[0]?.type !== 'text') fail('messages.envelope', 'bad messages envelope');
+    const noMax = await H('POST', '/v1/messages', JSON.stringify({ model: 'grok-4-0709', messages: [{ role: 'user', content: 'hi' }] }));
+    if (noMax.status !== 400) fail('messages.max_tokens_required', 'missing max_tokens did not 400');
+  } finally {
+    if (owned) rmSync(root, { recursive: true, force: true });
+  }
+  return { ok: violations.length === 0, checksRun, violations };
+}

package/src/xai-connector.ts

@@ -0,0 +1,212 @@
+// xAI CONNECTOR — the live-vendor pull path that lets the xAI twin mirror real account state.
+//
+// PULL  (real → twin):  fetch the real model catalogs (GET /v1/models + /v1/language-models),
+//                       map them → SyncResource[], fold into the event log via syncPull
+//                       (shadow-diff dedup, so re-pulling identical state appends nothing).
+//                       The twin's served /v1/models and /v1/language-models MERGE these
+//                       observed rows over the static catalog.
+// PUSH  (twin → real):  THE xAI API HAS NO CLIENT-WRITABLE RESOURCES — every endpoint is
+//                       inference or read-only catalog/introspection. The twin's only local
+//                       writes are its own deferred-completion lifecycle rows, which are twin
+//                       inference state, not vendor resources. So push REFUSES LOUDLY for
+//                       every operation rather than silently dropping (or fabricating) a
+//                       write — the same fail-loud rule the other connectors apply to
+//                       unmodeled op types, applied to the whole (empty) push surface.
+//
+// The vendor I/O is an INJECTED executor (B3 auth boundary): the kernel + this pack hold NO
+// xAI key and import NO SDK at runtime. Tests pass a fake executor; live runs pass
+// `liveXaiExecute(apiKey)`. Same code path either way — fully exercisable offline.
+import { assertBudgetGuardIntact, observeResources } from '@volter/world-core';
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { XaiBudget, XaiBudgetError, xaiCallWeight, type XaiBudgetOptions } from './xai-budget.ts';
+
+const SERVICE = 'xai';
+
+/** The real xAI API host. The ONLY place this pack names it as a target. */
+export const XAI_API_BASE = 'https://api.x.ai';
+
+/** Construction options for the live executor. There is deliberately no way to disable the guard. */
+export type LiveXaiOptions = {
+  /** Injected transport. Tests pass a counting fake; production passes nothing. */
+  fetchImpl?: typeof fetch;
+  /** An existing budget to share across executes. Omit and one is constructed. Cannot be null. */
+  budget?: XaiBudget;
+  /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+  budgetOptions?: XaiBudgetOptions;
+};
+
+/**
+ * The injected real-xAI boundary. `request` issues ONE xAI REST call:
+ *   method  — 'GET' (the pull surface is read-only)
+ *   path    — e.g. '/v1/models' or '/v1/language-models'
+ * Returns the parsed JSON (a `{ data }` / `{ models }` list, or a `{ code, error }` envelope).
+ */
+export type XaiExecute = (
+  method: 'GET',
+  path: string,
+) => Promise<{ data?: any; models?: any; code?: string; error?: string; [k: string]: unknown }>;
+
+/**
+ * THE CHOKE POINT — the one place this pack builds an `XaiExecute` that really reaches api.x.ai, and
+ * therefore the one place the rate budget has to be enforced. Sends the required
+ * `Authorization: Bearer` header. Never imported by the pack's own code path — only constructed by a
+ * caller that opts into real I/O.
+ *
+ * EVERY request is guarded: the budget is charged BEFORE it goes out (`checkBudget`, which THROWS
+ * instead of returning once the ceiling or a persisted cooldown says stop) and the response is fed
+ * back (`recordCall`) so a `Retry-After` / 429 / rate-limit-exhaustion signal becomes a persisted
+ * cooldown that makes every later call fail fast WITHOUT touching xAI. There is deliberately NO
+ * option to disable the guard. See `xai-budget.ts` for the numbers — and for why they are the
+ * kernel's austere fallback rather than a model of a published limit (xAI publishes none at all).
+ *
+ * No vendor SDK is imported: real-transport `fetch` keeps the SDK a dev-only dependency, which the
+ * architecture guardrail requires.
+ */
+export function liveXaiExecute(
+  apiKey: string,
+  base = XAI_API_BASE,
+  opts: LiveXaiOptions = {},
+): XaiExecute {
+  const doFetch = opts.fetchImpl ?? fetch;
+  // ONE expression decides which budget is used, so there is no second, weaker test that could
+  // disagree with the first. `null`/`undefined` (or omitting it) build the default; anything else
+  // must be an UNMODIFIED `XaiBudget` — a duck-typed stand-in, a SUBCLASS overriding `checkBudget`,
+  // and a Proxy trapping it are ALL refused, because each is a one-liner that would otherwise hand
+  // back a client with no ceiling. What this cannot stop is deliberate sabotage from inside the
+  // process (an injected clock, a throwaway ledger path); the kernel's header states that limit
+  // rather than pretending otherwise.
+  //
+  // The default ledger is keyed by a hash of THIS key — the limit is per key, so a cwd-scoped ledger
+  // would hand the same key a fresh allowance per checkout/worktree/CI leg.
+  const budget = opts.budget !== undefined && opts.budget !== null
+    ? assertBudgetGuardIntact(opts.budget, XaiBudget, 'liveXaiExecute')
+    : new XaiBudget({ token: apiKey, ...(opts.budgetOptions ?? {}) });
+  return async (method, path) => {
+    const weight = xaiCallWeight(method, path);
+    // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+    const reservation = budget.checkBudget(weight);
+    const res = await doFetch(`${base}${path}`, { method, headers: { authorization: `Bearer ${apiKey}` } });
+    const resHeaders: Record<string, string> = {};
+    res.headers.forEach((v: string, k: string) => { resHeaders[k.toLowerCase()] = v; });
+    const parsed = (await res.json()) as { data?: any; models?: any; code?: string; error?: string };
+    // Settles the reservation and, on a back-off signal, arms the cooldown. May itself throw (a
+    // `Retry-After` beyond the cap is not something to sleep off) — the cooldown is persisted first
+    // either way, so the refusal survives the throw.
+    // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+    // call that louder refusal wins; an answer xAI ACCEPTED is kept, so a write that landed is
+    // never recorded as failed and performed again on retry.
+    try {
+      budget.recordCall(weight, resHeaders, { status: res.status, reservation });
+    } catch (error) {
+      if (!(error instanceof XaiBudgetError) || !res.ok) throw error;
+    }
+    return parsed;
+  };
+}
+
+function throwIfError(res: { code?: string; error?: string }, ctx: string): void {
+  // xAI's error envelope is FLAT: { code, error } strings (no nested error object).
+  if (typeof res.error === 'string' && res.error) throw new Error(`xai ${ctx} failed: ${res.error}`);
+}
+
+// ── PULL ────────────────────────────────────────────────────────────────────
+
+/** Map a real-xAI flat model object (GET /v1/models) → a twin sync resource. */
+export function mapModel(m: Record<string, unknown>): SyncResource {
+  return {
+    type: 'model',
+    id: String(m.id),
+    fields: {
+      object: 'model',
+      created: (m.created as number) ?? 0,
+      owned_by: (m.owned_by as string) ?? 'xai',
+    },
+  };
+}
+
+/** Map a real-xAI rich language-model object (GET /v1/language-models) → a twin sync resource. */
+export function mapLanguageModel(m: Record<string, unknown>): SyncResource {
+  return {
+    type: 'language_model',
+    id: String(m.id),
+    fields: {
+      object: 'model',
+      created: (m.created as number) ?? 0,
+      owned_by: (m.owned_by as string) ?? 'xai',
+      version: (m.version as string) ?? null,
+      fingerprint: (m.fingerprint as string) ?? null,
+      input_modalities: Array.isArray(m.input_modalities) ? m.input_modalities : [],
+      output_modalities: Array.isArray(m.output_modalities) ? m.output_modalities : [],
+      aliases: Array.isArray(m.aliases) ? m.aliases : [],
+      prompt_text_token_price: (m.prompt_text_token_price as number) ?? null,
+      completion_text_token_price: (m.completion_text_token_price as number) ?? null,
+    },
+  };
+}
+
+/** Pull the real model catalogs via the executor and map them to twin sync resources. */
+export async function pullXaiModels(execute: XaiExecute): Promise<SyncResource[]> {
+  const out: SyncResource[] = [];
+  const flat = await execute('GET', '/v1/models');
+  throwIfError(flat, 'pull /v1/models');
+  for (const item of Array.isArray(flat.data) ? flat.data : []) out.push(mapModel(item));
+  const rich = await execute('GET', '/v1/language-models');
+  throwIfError(rich, 'pull /v1/language-models');
+  for (const item of Array.isArray(rich.models) ? rich.models : []) out.push(mapLanguageModel(item));
+  return out;
+}
+
+/**
+ * Pull from real xAI and fold into the twin (mirror seeding). syncPull's shadow-diff makes a
+ * re-pull of identical state a no-op.
+ */
+export async function syncXaiFromReal(
+  execute: XaiExecute,
+  opts: { root?: string; occurredAt: string },
+): Promise<{ observed: number; deltasAppended: number }> {
+  const resources = await pullXaiModels(execute);
+  // protocol 2: the observation lands on the head through the kernel's fold — one batch, one instant
+  const result = observeResources(SERVICE, resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), { ...(opts.root !== undefined ? { root: opts.root } : {}), at: opts.occurredAt, batch: `obs:${SERVICE}:${opts.occurredAt}` });
+  return { observed: result.observed, deltasAppended: result.appended };
+}
+
+// ── PUSH (refuses loudly — the vendor has no writable surface) ──────────────
+
+/**
+ * Push ONE local action to real xAI. The xAI API exposes NO client-writable resources, so
+ * EVERY operation refuses loudly BEFORE any client dispatch — pushing a twin-local row (e.g.
+ * a deferred-completion lifecycle write) to the vendor would fabricate a write that cannot
+ * exist. Silent dropping is exactly the failure mode this refusal prevents.
+ */
+export async function pushXaiAction(
+  _execute: XaiExecute,
+  action: Pick<TwinAction, 'operation' | 'subject'>,
+): Promise<never> {
+  const op = action.operation ?? `${action.subject.type}.update`;
+  throw new Error(`xai push: unsupported operation '${op}' — the xAI API has no client-writable resources; refusing to silently drop a local write`);
+}
+
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+/** The pack's executor over the kernel's. */
+export function xaiExecuteOver(execute: RemoteExecute): XaiExecute {
+  // the pack's executor is READ-ONLY by type (GET), which is the same fact `perform` states: xAI has no
+  // client-writable resource, so there is nothing for this boundary to send
+  return async (method: 'GET', path: string) => {
+    const res = await execute({ method, path, headers: { accept: 'application/json', authorization: 'Bearer twin' } });
+    if (res.status < 200 || res.status >= 300) throw new Error(`xai GET ${path} refused: HTTP ${res.status} ${res.body.slice(0, 200)}`);
+    return JSON.parse(res.body || '{}') as Awaited<ReturnType<XaiExecute>>;
+  };
+}
+/** The refresh adapter: pull the account's model catalog and keys through the executor. */
+export async function syncXaiFromRemote(execute: RemoteExecute, opts: { root?: string; origin?: string; occurredAt?: string } = {}): Promise<{ observed: number; deltasAppended: number }> {
+  return syncXaiFromReal(xaiExecuteOver(execute), {
+    ...(opts.root !== undefined ? { root: opts.root } : {}),
+    occurredAt: opts.occurredAt ?? new Date().toISOString(),
+  });
+}
+/** The perform adapter — and the honest answer is that nothing can cross: the xAI API has NO
+ *  client-writable resource. A completion is a call already answered, not a row the vendor keeps for you.
+ *  Each entry settles with that reason rather than being marked across or silently dropped. */
+export async function performXaiAction(_execute: RemoteExecute, action: TwinAction, _ctx: PerformContext): Promise<PushOutcome> {
+  return { externalId: action.subject.id, data: { performed: false, reason: `${action.operation ?? action.subject.type}: the xAI API has no client-writable resources — nothing to perform` } };
+}

package/src/xai-device-auth-css.gen.ts

@@ -0,0 +1,6 @@
+// GENERATED by scripts/text-modules.ts — do not hand-edit; text-modules.test.ts fails on drift.
+// A VERBATIM copy of packages/twin/xai/client/xai-device-auth.css as committed text, so the serve path imports it instead of
+// reading it off disk (runtime contract R12b workerd-clean: no node:fs, no import.meta.dir on a
+// fetch closure). The .css file remains the source of truth — edit THAT, then run
+// `bun scripts/text-modules.ts` and commit this module alongside it.
+export const XAI_DEVICE_AUTH_CSS = ":root {\n  color-scheme: light;\n  --xai-bg: #ffffff;\n  --xai-text: #0a0a0a;\n  --xai-muted: #777777;\n  --xai-faint: #fafafa;\n  --xai-border: #dedede;\n  --xai-error: #b42318;\n}\n\n* { box-sizing: border-box; }\n\nhtml, body, #root { min-height: 100%; }\n\nbody {\n  margin: 0;\n  background: var(--xai-bg);\n  color: var(--xai-text);\n  font-family: Inter, ui-sans-serif, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif;\n  -webkit-font-smoothing: antialiased;\n}\n\nbutton, input { font: inherit; }\n\n.account-page { min-height: 100vh; }\n\n.account-header {\n  position: fixed;\n  inset: 0 0 auto;\n  z-index: 2;\n  display: flex;\n  align-items: center;\n  justify-content: space-between;\n  height: 88px;\n  padding: 20px 24px;\n  pointer-events: none;\n}\n\n.account-header > * { pointer-events: auto; }\n\n.account-home {\n  display: inline-flex;\n  color: var(--xai-text);\n  text-decoration: none;\n  padding: 8px 0;\n}\n\n.xai-mark {\n  display: block;\n  width: 52px;\n  height: auto;\n}\n\n.sign-out {\n  display: inline-flex;\n  align-items: center;\n  text-decoration: none;\n  min-height: 40px;\n  padding: 0 18px;\n  border: 1px solid var(--xai-border);\n  border-radius: 999px;\n  background: var(--xai-bg);\n  color: var(--xai-text);\n  cursor: pointer;\n  font-size: 14px;\n  transition: background .15s ease, border-color .15s ease;\n}\n\n.sign-out:hover { background: #f6f6f6; border-color: #c8c8c8; }\n\n.auth-shell {\n  width: min(512px, calc(100% - 40px));\n  margin: 0 auto;\n  padding: clamp(106px, 11vh, 112px) 0 72px;\n}\n\n.auth-shell-compact {\n  width: min(448px, calc(100% - 40px));\n  padding-top: clamp(240px, 35.7vh, 351px);\n}\n\nh1 {\n  margin: 0 0 32px;\n  font-size: 16px;\n  line-height: 1.3;\n  font-weight: 650;\n  letter-spacing: -0.015em;\n}\n\n.auth-shell-compact h1 {\n  margin-bottom: 16px;\n  font-size: 26px;\n  font-weight: 450;\n  letter-spacing: -0.035em;\n}\n\n.lead {\n  margin: 0 0 28px;\n  color: var(--xai-muted);\n  font-size: 17px;\n  line-height: 1.5;\n}\n\n.entry-form input {\n  width: 100%;\n  height: 42px;\n  border: 1px solid #252525;\n  border-radius: 0;\n  background: var(--xai-bg);\n  color: var(--xai-text);\n  padding: 0 16px;\n  text-align: center;\n  text-transform: uppercase;\n  letter-spacing: .08em;\n  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;\n  font-size: 18px;\n  outline: none;\n}\n\n.entry-form input:focus { box-shadow: 0 0 0 2px #bbbbbb; }\n.device-help, .form-error {\n  margin: 14px 0 20px;\n  color: var(--xai-muted);\n  font-size: 14px;\n  line-height: 1.45;\n}\n\n.form-error { margin-bottom: -7px; color: var(--xai-error); }\n\n.primary-action, .secondary-action {\n  min-height: 40px;\n  border-radius: 999px;\n  padding: 0 24px;\n  cursor: pointer;\n  font-size: 16px;\n  transition: transform .12s ease, background .15s ease;\n}\n\n.primary-action {\n  border: 1px solid #050505;\n  background: #050505;\n  color: #ffffff;\n}\n\n.primary-action:hover { background: #252525; }\n.primary-action:disabled,\n.primary-action:disabled:hover {\n  background: #4b4b4b;\n  border-color: #4b4b4b;\n  cursor: default;\n}\n.primary-action:active, .secondary-action:active { transform: scale(.99); }\n.entry-form .primary-action { width: 100%; min-height: 50px; }\n\n.permission-list {\n  display: grid;\n  gap: 4px;\n  margin: 0;\n  padding: 0;\n  list-style: none;\n}\n\n.permission-list li {\n  display: flex;\n  align-items: center;\n  min-height: 44px;\n  padding: 0 16px;\n  border-radius: 13px;\n  background: var(--xai-faint);\n  font-size: 15px;\n  font-weight: 500;\n}\n\n.permission-icon {\n  flex: 0 0 auto;\n  width: 17px;\n  height: 17px;\n  margin-right: 16px;\n  color: #888888;\n}\n\n.decision-form {\n  display: grid;\n  grid-template-columns: 1fr 1fr;\n  gap: 12px;\n  margin-top: 32px;\n}\n\n.secondary-action {\n  border: 1px solid var(--xai-border);\n  background: var(--xai-bg);\n  color: var(--xai-text);\n}\n\n.secondary-action:hover { background: #f7f7f7; }\n\n.result-icon {\n  display: grid;\n  place-items: center;\n  width: 48px;\n  height: 48px;\n  margin-bottom: 24px;\n  border-radius: 50%;\n  background: #f1f1f1;\n  font-size: 28px;\n  font-weight: 350;\n}\n\n.result-icon-approved { background: #050505; color: #ffffff; }\n.result-copy { margin-bottom: 6px; }\n\n.sr-only {\n  position: absolute;\n  width: 1px;\n  height: 1px;\n  padding: 0;\n  margin: -1px;\n  overflow: hidden;\n  clip: rect(0, 0, 0, 0);\n  white-space: nowrap;\n  border: 0;\n}\n\nbutton:focus-visible, a:focus-visible, input:focus-visible {\n  outline: 2px solid #666666;\n  outline-offset: 3px;\n}\n\n@media (max-width: 640px) {\n  .account-header { height: 76px; padding: 16px 20px; }\n  .sign-out { min-height: 42px; padding: 0 17px; font-size: 15px; }\n  .auth-shell, .auth-shell-compact {\n    width: min(100% - 32px, 532px);\n    padding-top: 126px;\n  }\n  .auth-shell h1, .auth-shell-compact h1 { font-size: 27px; margin-bottom: 18px; }\n  .lead { font-size: 16px; }\n  .permission-list li { min-height: 54px; padding: 0 14px; font-size: 15px; }\n  .permission-icon { margin-right: 14px; }\n  .decision-form { grid-template-columns: 1fr; margin-top: 28px; }\n  .decision-form .primary-action { grid-row: 1; }\n}\n\n@media (prefers-reduced-motion: reduce) {\n  * { transition: none !important; }\n}\n";

package/src/xai-device-auth-ui.ts

@@ -0,0 +1,90 @@
+// Server half of xAI's Grok Build device-authorization UI. This is protocol UI, not an
+// invented dashboard: it is served on the OAuth paths and coupled directly to the pending
+// device authorization projected from the Twin kernel.
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import {
+  DeviceConsentPage,
+  DeviceDonePage,
+  DeviceEntryPage,
+  type XaiDeviceAuthView,
+  XAI_DEVICE_PERMISSIONS,
+} from '../client/xai-device-auth.tsx';
+import { inspectXaiTwinDeviceAuthorization } from './xai-oauth.ts';
+import { XAI_DEVICE_AUTH_CSS } from './xai-device-auth-css.gen.ts';
+
+export type { XaiDeviceAuthView } from '../client/xai-device-auth.tsx';
+export { XAI_DEVICE_PERMISSIONS } from '../client/xai-device-auth.tsx';
+
+export const XAI_DEVICE_STYLE_PATH = '/_twin/assets/xai-device-auth.css';
+export const XAI_DEVICE_SCRIPT_PATH = '/_twin/assets/xai-device-auth.js';
+export const XAI_DEVICE_FAVICON_PATH = '/_twin/assets/xai-favicon.svg';
+// The stylesheet is COMMITTED TEXT (scripts/text-modules.ts, the `xai` entry), beside the
+// favicon and script constants below: the serve path answers this route from a constant and
+// never opens a file (R12b workerd-clean). `client/xai-device-auth.css` stays the source of
+// truth — edit THAT, run `bun scripts/text-modules.ts`, and text-modules.test.ts fails on drift.
+
+const SYMBOL_PATHS = `<path d="M832.565 0.590983C736.633 8.41256 359.563 55.1598 98.1057 317.999H1.08203L11.9228 307.195C66.6371 254.336 308.741 30.3127 832.565 0.299805V0.590983Z"/><path d="M504.192 317.999H428.146L278.315 208.933C292.122 200.25 306.018 191.98 319.957 184.104L504.192 317.999Z"/><path d="M382.659 318H306.648L283.589 301.228H154.852C163.915 293.18 173.091 285.368 182.362 277.784H251.322L215.636 251.826C228.392 242.335 241.288 233.244 254.287 224.535L382.659 318Z"/><path d="M105.997 116.89L164.612 159.488C150.024 168.078 136.37 176.58 123.626 184.897L30.0522 116.854L105.997 116.89Z"/>`;
+const FAVICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 834 318" fill="#000">${SYMBOL_PATHS}</svg>`;
+const DEVICE_SCRIPT = `(()=>{const i=document.getElementById('device-code');const b=document.querySelector('.entry-form button[type="submit"]');if(!(i instanceof HTMLInputElement)||!(b instanceof HTMLButtonElement))return;const sync=()=>{i.value=i.value.toUpperCase();b.disabled=!/^[A-Z0-9]{4}-[A-Z0-9]{4}$/.test(i.value.trim())};i.addEventListener('input',sync);sync()})();`;
+
+function escapeHtml(value: string): string {
+  return value.replace(/&/gu, '&amp;').replace(/</gu, '&lt;').replace(/>/gu, '&gt;').replace(/"/gu, '&quot;');
+}
+
+/** `base` is where the twin is reached (`twinPublicBase`: origin plus any served-World mount
+ *  path), so the page's assets resolve inside the World's mount; empty for an in-process render. */
+function page(title: string, markup: string, base: string): string {
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<meta name="color-scheme" content="light"><title>${escapeHtml(title)} | SpaceXAI Accounts</title>
+<link rel="icon" href="${base}${XAI_DEVICE_FAVICON_PATH}" type="image/svg+xml">
+<link rel="stylesheet" href="${base}${XAI_DEVICE_STYLE_PATH}"><script src="${base}${XAI_DEVICE_SCRIPT_PATH}" defer></script></head><body><div id="root">${markup}</div></body></html>`;
+}
+
+export function xaiDeviceAuthView(userCode: string, root?: string, error?: string, nowAt?: string): XaiDeviceAuthView {
+  const normalized = userCode.trim().toUpperCase().replace(/[^A-Z0-9-]/gu, '');
+  const state = inspectXaiTwinDeviceAuthorization(normalized, root);
+  let status = typeof state?.status === 'string' ? state.status : 'unknown';
+  if (state?.expiresAt && Date.parse(String(state.expiresAt)) <= Date.parse(nowAt ?? new Date().toISOString()) && status === 'pending') status = 'expired';
+  const supported = new Set<XaiDeviceAuthView['status']>(['pending', 'approved', 'denied', 'connected', 'expired', 'unknown']);
+  const scopes = new Set(String(state?.scope ?? '').split(/\s+/u).filter(Boolean));
+  const permissions = XAI_DEVICE_PERMISSIONS.filter((_, index) => [
+    scopes.has('openid'),
+    scopes.has('profile'),
+    scopes.has('email'),
+    scopes.has('offline_access'),
+    scopes.has('api:access') || scopes.has('grok-cli:access'),
+    scopes.has('conversations:read') || scopes.has('conversations:write') || scopes.has('workspaces:read') || scopes.has('workspaces:write'),
+  ][index]);
+  return {
+    userCode: normalized,
+    status: supported.has(status as XaiDeviceAuthView['status']) ? status as XaiDeviceAuthView['status'] : 'unknown',
+    permissions,
+    ...(error ? { error } : {}),
+  };
+}
+
+export function deviceEntryPageHtml(view: XaiDeviceAuthView, base = ''): string {
+  return page('Device Sign-in', renderToStaticMarkup(createElement(DeviceEntryPage, { view, base })), base);
+}
+
+export function deviceConsentPageHtml(view: XaiDeviceAuthView, base = ''): string {
+  return page('Authorize Grok Build', renderToStaticMarkup(createElement(DeviceConsentPage, { view, base })), base);
+}
+
+export function deviceDonePageHtml(approved: boolean, base = ''): string {
+  return page(approved ? 'Device Authorized' : 'Authorization Denied', renderToStaticMarkup(createElement(DeviceDonePage, { approved, base })), base);
+}
+
+export function xaiDeviceStylesheet(): string {
+  return XAI_DEVICE_AUTH_CSS;
+}
+
+export function xaiDeviceFavicon(): string {
+  return FAVICON_SVG;
+}
+
+export function xaiDeviceScript(): string {
+  return DEVICE_SCRIPT;
+}

package/src/xai-journey.uitest.ts

@@ -0,0 +1,155 @@
+// Grok Build device-auth UI journey. The browser is the protocol participant: it enters the
+// issued code, reviews the projected permission surface, and approves or denies. The approved
+// journey then redeems and USES the bearer, closing the same virtual-account loop the CLI uses.
+import { describe, expect, test } from 'bun:test';
+import { atPath, requireBrowser, runUiJourney, visible, JOURNEY_TIMEOUT_MS } from '@volter/world-tooling';
+import { createXaiTwinServer } from './xai-server.ts';
+
+const JOURNEY_LABEL = 'xAI Grok Build device authorization UI journey';
+type DeviceReply = { device_code: string; user_code: string; verification_uri_complete: string };
+
+async function startDevice(origin: string): Promise<DeviceReply> {
+  const response = await fetch(`${origin}/oauth2/device/code`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      client_id: 'grok-build',
+      scope: 'openid profile email offline_access grok-cli:access api:access conversations:read conversations:write workspaces:read workspaces:write',
+    }),
+  });
+  expect(response.status).toBe(200);
+  return response.json() as Promise<DeviceReply>;
+}
+
+describe('xAI Grok Build device authorization UI journey', () => {
+  test('code entry → consent → Allow → token exchange → Grok CLI request', async () => {
+    if (!(await requireBrowser(JOURNEY_LABEL))) return;
+    let origin = '';
+    let device: DeviceReply | null = null;
+
+    await runUiJourney({
+      label: 'xai device authorization approved round trip',
+      seed: async () => {},
+      serve: async (root) => {
+        const server = await createXaiTwinServer({ root, port: 0 });
+        origin = `http://127.0.0.1:${server.port}`;
+        device = await startDevice(origin);
+        return { url: device.verification_uri_complete, stop: () => server.stop() };
+      },
+      journey: async (page) => {
+        const issued = device!;
+        await visible(page, 'Sign in to Grok Build');
+        expect(await page.getByRole('textbox', { name: 'Enter device code' }).inputValue()).toBe(issued.user_code);
+        await page.getByRole('button', { name: 'Continue' }).click();
+        await atPath(page, '/oauth2/device/consent');
+        await visible(page, 'Authorize Grok Build');
+        for (const permission of [
+          'Verify your identity',
+          'Read your profile (name, avatar)',
+          'Read your email address',
+          "Maintain access when you're not present",
+          'Use the xAI API',
+          'Read and write access Grok.com',
+        ]) await visible(page, permission);
+        await page.getByRole('button', { name: 'Allow' }).click();
+        await atPath(page, '/oauth2/device/done');
+        await visible(page, 'Device Authorized');
+
+        const exchange = await fetch(`${origin}/oauth2/token`, {
+          method: 'POST',
+          headers: { 'content-type': 'application/x-www-form-urlencoded' },
+          body: new URLSearchParams({ client_id: 'grok-build', device_code: issued.device_code, grant_type: 'urn:ietf:params:oauth:grant-type:device_code' }),
+        });
+        expect(exchange.status).toBe(200);
+        const credential = await exchange.json() as { access_token: string };
+        const use = await fetch(`${origin}/v1/chat/completions`, {
+          method: 'POST',
+          headers: {
+            authorization: `Bearer ${credential.access_token}`,
+            'content-type': 'application/json',
+            'x-grok-model-override': 'grok-build',
+            'x-xai-token-auth': 'xai-grok-cli',
+          },
+          body: JSON.stringify({ model: 'grok-build', messages: [{ role: 'user', content: 'journey ping' }] }),
+        });
+        expect(use.status).toBe(200);
+        expect((await use.json() as { model: string }).model).toBe('grok-code-fast-1');
+      },
+    });
+  }, JOURNEY_TIMEOUT_MS);
+
+  test('Deny leaves token exchange at access_denied', async () => {
+    if (!(await requireBrowser(JOURNEY_LABEL))) return;
+    let origin = '';
+    let device: DeviceReply | null = null;
+
+    await runUiJourney({
+      label: 'xai device authorization denied round trip',
+      seed: async () => {},
+      serve: async (root) => {
+        const server = await createXaiTwinServer({ root, port: 0 });
+        origin = `http://127.0.0.1:${server.port}`;
+        device = await startDevice(origin);
+        return { url: device.verification_uri_complete, stop: () => server.stop() };
+      },
+      journey: async (page) => {
+        const issued = device!;
+        await page.getByRole('button', { name: 'Continue' }).click();
+        await atPath(page, '/oauth2/device/consent');
+        await page.getByRole('button', { name: 'Deny' }).click();
+        await atPath(page, '/oauth2/device/done');
+        await visible(page, 'Authorization Denied');
+        const exchange = await fetch(`${origin}/oauth2/token`, {
+          method: 'POST',
+          headers: { 'content-type': 'application/x-www-form-urlencoded' },
+          body: new URLSearchParams({ client_id: 'grok-build', device_code: issued.device_code, grant_type: 'urn:ietf:params:oauth:grant-type:device_code' }),
+        });
+        expect(exchange.status).toBe(400);
+        expect((await exchange.json() as { error: string }).error).toBe('access_denied');
+      },
+    });
+  }, JOURNEY_TIMEOUT_MS);
+
+  test('blank entry → invalid PRG → consent sign-out preserves the pending grant', async () => {
+    if (!(await requireBrowser(JOURNEY_LABEL))) return;
+    let origin = '';
+    let device: DeviceReply | null = null;
+
+    await runUiJourney({
+      label: 'xai device entry error and account sign out',
+      seed: async () => {},
+      serve: async (root) => {
+        const server = await createXaiTwinServer({ root, port: 0 });
+        origin = `http://127.0.0.1:${server.port}`;
+        device = await startDevice(origin);
+        return { url: `${origin}/oauth2/device`, stop: () => server.stop() };
+      },
+      journey: async (page) => {
+        const issued = device!;
+        await visible(page, 'Sign in to Grok Build');
+        const entry = page.getByRole('textbox', { name: 'Enter device code' });
+        const proceed = page.getByRole('button', { name: 'Continue' });
+        expect(await proceed.isDisabled()).toBe(true);
+        await entry.fill('NOPE-0000');
+        expect(await proceed.isEnabled()).toBe(true);
+        await proceed.click();
+        await atPath(page, '/oauth2/device');
+        await visible(page, 'Invalid or expired code. Please try again.');
+        expect(await entry.inputValue()).toBe('');
+        expect(await proceed.isDisabled()).toBe(true);
+
+        await page.goto(issued.verification_uri_complete);
+        await page.getByRole('button', { name: 'Continue' }).click();
+        await atPath(page, '/oauth2/device/consent');
+        await page.getByRole('link', { name: 'Sign out' }).click();
+        await atPath(page, '/oauth2/device');
+        const pending = await fetch(`${origin}/oauth2/token`, {
+          method: 'POST',
+          headers: { 'content-type': 'application/x-www-form-urlencoded' },
+          body: new URLSearchParams({ client_id: 'grok-build', device_code: issued.device_code, grant_type: 'urn:ietf:params:oauth:grant-type:device_code' }),
+        });
+        expect((await pending.json() as { error: string }).error).toBe('authorization_pending');
+      },
+    });
+  }, JOURNEY_TIMEOUT_MS);
+});