@volter/twin-xai 0.1.0

package/dist/client/xai-device-auth.css

@@ -0,0 +1,246 @@
+:root {
+  color-scheme: light;
+  --xai-bg: #ffffff;
+  --xai-text: #0a0a0a;
+  --xai-muted: #777777;
+  --xai-faint: #fafafa;
+  --xai-border: #dedede;
+  --xai-error: #b42318;
+}
+
+* { box-sizing: border-box; }
+
+html, body, #root { min-height: 100%; }
+
+body {
+  margin: 0;
+  background: var(--xai-bg);
+  color: var(--xai-text);
+  font-family: Inter, ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  -webkit-font-smoothing: antialiased;
+}
+
+button, input { font: inherit; }
+
+.account-page { min-height: 100vh; }
+
+.account-header {
+  position: fixed;
+  inset: 0 0 auto;
+  z-index: 2;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  height: 88px;
+  padding: 20px 24px;
+  pointer-events: none;
+}
+
+.account-header > * { pointer-events: auto; }
+
+.account-home {
+  display: inline-flex;
+  color: var(--xai-text);
+  text-decoration: none;
+  padding: 8px 0;
+}
+
+.xai-mark {
+  display: block;
+  width: 52px;
+  height: auto;
+}
+
+.sign-out {
+  display: inline-flex;
+  align-items: center;
+  text-decoration: none;
+  min-height: 40px;
+  padding: 0 18px;
+  border: 1px solid var(--xai-border);
+  border-radius: 999px;
+  background: var(--xai-bg);
+  color: var(--xai-text);
+  cursor: pointer;
+  font-size: 14px;
+  transition: background .15s ease, border-color .15s ease;
+}
+
+.sign-out:hover { background: #f6f6f6; border-color: #c8c8c8; }
+
+.auth-shell {
+  width: min(512px, calc(100% - 40px));
+  margin: 0 auto;
+  padding: clamp(106px, 11vh, 112px) 0 72px;
+}
+
+.auth-shell-compact {
+  width: min(448px, calc(100% - 40px));
+  padding-top: clamp(240px, 35.7vh, 351px);
+}
+
+h1 {
+  margin: 0 0 32px;
+  font-size: 16px;
+  line-height: 1.3;
+  font-weight: 650;
+  letter-spacing: -0.015em;
+}
+
+.auth-shell-compact h1 {
+  margin-bottom: 16px;
+  font-size: 26px;
+  font-weight: 450;
+  letter-spacing: -0.035em;
+}
+
+.lead {
+  margin: 0 0 28px;
+  color: var(--xai-muted);
+  font-size: 17px;
+  line-height: 1.5;
+}
+
+.entry-form input {
+  width: 100%;
+  height: 42px;
+  border: 1px solid #252525;
+  border-radius: 0;
+  background: var(--xai-bg);
+  color: var(--xai-text);
+  padding: 0 16px;
+  text-align: center;
+  text-transform: uppercase;
+  letter-spacing: .08em;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 18px;
+  outline: none;
+}
+
+.entry-form input:focus { box-shadow: 0 0 0 2px #bbbbbb; }
+.device-help, .form-error {
+  margin: 14px 0 20px;
+  color: var(--xai-muted);
+  font-size: 14px;
+  line-height: 1.45;
+}
+
+.form-error { margin-bottom: -7px; color: var(--xai-error); }
+
+.primary-action, .secondary-action {
+  min-height: 40px;
+  border-radius: 999px;
+  padding: 0 24px;
+  cursor: pointer;
+  font-size: 16px;
+  transition: transform .12s ease, background .15s ease;
+}
+
+.primary-action {
+  border: 1px solid #050505;
+  background: #050505;
+  color: #ffffff;
+}
+
+.primary-action:hover { background: #252525; }
+.primary-action:disabled,
+.primary-action:disabled:hover {
+  background: #4b4b4b;
+  border-color: #4b4b4b;
+  cursor: default;
+}
+.primary-action:active, .secondary-action:active { transform: scale(.99); }
+.entry-form .primary-action { width: 100%; min-height: 50px; }
+
+.permission-list {
+  display: grid;
+  gap: 4px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.permission-list li {
+  display: flex;
+  align-items: center;
+  min-height: 44px;
+  padding: 0 16px;
+  border-radius: 13px;
+  background: var(--xai-faint);
+  font-size: 15px;
+  font-weight: 500;
+}
+
+.permission-icon {
+  flex: 0 0 auto;
+  width: 17px;
+  height: 17px;
+  margin-right: 16px;
+  color: #888888;
+}
+
+.decision-form {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 12px;
+  margin-top: 32px;
+}
+
+.secondary-action {
+  border: 1px solid var(--xai-border);
+  background: var(--xai-bg);
+  color: var(--xai-text);
+}
+
+.secondary-action:hover { background: #f7f7f7; }
+
+.result-icon {
+  display: grid;
+  place-items: center;
+  width: 48px;
+  height: 48px;
+  margin-bottom: 24px;
+  border-radius: 50%;
+  background: #f1f1f1;
+  font-size: 28px;
+  font-weight: 350;
+}
+
+.result-icon-approved { background: #050505; color: #ffffff; }
+.result-copy { margin-bottom: 6px; }
+
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+button:focus-visible, a:focus-visible, input:focus-visible {
+  outline: 2px solid #666666;
+  outline-offset: 3px;
+}
+
+@media (max-width: 640px) {
+  .account-header { height: 76px; padding: 16px 20px; }
+  .sign-out { min-height: 42px; padding: 0 17px; font-size: 15px; }
+  .auth-shell, .auth-shell-compact {
+    width: min(100% - 32px, 532px);
+    padding-top: 126px;
+  }
+  .auth-shell h1, .auth-shell-compact h1 { font-size: 27px; margin-bottom: 18px; }
+  .lead { font-size: 16px; }
+  .permission-list li { min-height: 54px; padding: 0 14px; font-size: 15px; }
+  .permission-icon { margin-right: 14px; }
+  .decision-form { grid-template-columns: 1fr; margin-top: 28px; }
+  .decision-form .primary-action { grid-row: 1; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  * { transition: none !important; }
+}

package/dist/client/xai-device-auth.d.ts

@@ -0,0 +1,19 @@
+export declare const XAI_DEVICE_PERMISSIONS: readonly ["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"];
+export type XaiDeviceAuthView = {
+    userCode: string;
+    status: 'pending' | 'approved' | 'denied' | 'connected' | 'expired' | 'unknown';
+    permissions: readonly string[];
+    error?: string;
+};
+export declare function DeviceEntryPage({ view, base }: {
+    view: XaiDeviceAuthView;
+    base?: string;
+}): import("react").JSX.Element;
+export declare function DeviceConsentPage({ view, base }: {
+    view: XaiDeviceAuthView;
+    base?: string;
+}): import("react").JSX.Element;
+export declare function DeviceDonePage({ approved, base }: {
+    approved: boolean;
+    base?: string;
+}): import("react").JSX.Element;

package/dist/client/xai-device-auth.js

@@ -0,0 +1,50 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+export const XAI_DEVICE_PERMISSIONS = [
+    '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',
+];
+function XaiMark() {
+    return (_jsxs("svg", { className: "xai-mark", viewBox: "0 0 834 318", fill: "none", "aria-hidden": "true", children: [_jsx("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", fill: "black" }), _jsx("path", { d: "M504.192 317.999H428.146L278.315 208.933C292.122 200.25 306.018 191.98 319.957 184.104L504.192 317.999Z", fill: "black" }), _jsx("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", fill: "black" }), _jsx("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", fill: "black" })] }));
+}
+// `base` is where the twin is reached (`twinPublicBase`: origin plus any served-World mount path);
+// every link and form action the pages emit is built from it, so they stay inside the World's
+// mount. Empty for an in-process render, where the paths are the vendor's own root-relative ones.
+function AccountHeader({ base, signOutReturnTo, userCode }) {
+    const signOutHref = signOutReturnTo
+        ? `${base}/sign-out?redirect=oauth2-provider&return_to=${encodeURIComponent(signOutReturnTo)}`
+        : `${base}/sign-out`;
+    return (_jsxs("header", { className: "account-header", children: [_jsx("a", { className: "account-home", href: `${base}/`, "aria-label": "SpaceXAI account home link", children: _jsx(XaiMark, {}) }), userCode ? (_jsx("a", { className: "sign-out", href: signOutHref, children: "Sign out" })) : null] }));
+}
+function AccountShell({ base, children, userCode, compact = false, result = false, signOutReturnTo }) {
+    return (_jsxs("div", { className: "account-page", children: [_jsx(AccountHeader, { base: base, userCode: userCode, signOutReturnTo: signOutReturnTo }), _jsx("main", { className: `auth-shell${compact ? ' auth-shell-compact' : ''}${result ? ' auth-shell-result' : ''}`, children: children })] }));
+}
+export function DeviceEntryPage({ view, base = '' }) {
+    const canContinue = !view.error && /^[A-Z0-9]{4}-[A-Z0-9]{4}$/u.test(view.userCode);
+    return (_jsxs(AccountShell, { base: base, compact: true, userCode: view.userCode || undefined, children: [_jsx("h1", { children: "Sign in to Grok Build" }), _jsx("p", { className: "lead", children: "Enter the code shown in your terminal." }), _jsxs("form", { className: "entry-form", method: "POST", action: `${base}/oauth2/device/continue`, children: [_jsx("label", { className: "sr-only", htmlFor: "device-code", children: "Enter device code" }), _jsx("input", { id: "device-code", name: "user_code", inputMode: "text", autoComplete: "one-time-code", autoCapitalize: "characters", spellCheck: false, defaultValue: view.userCode, placeholder: "Enter device code", "aria-describedby": view.error ? 'device-code-error device-code-help' : 'device-code-help' }), view.error ? _jsx("p", { id: "device-code-error", className: "form-error", role: "alert", children: view.error }) : null, _jsx("p", { id: "device-code-help", className: "device-help", children: "Only enter this code if you just initiated a sign-in from your device." }), _jsx("button", { className: "primary-action", type: "submit", disabled: !canContinue, children: "Continue" })] })] }));
+}
+function PermissionIcon({ index }) {
+    const paths = [
+        _jsxs(_Fragment, { children: [_jsx("circle", { cx: "12", cy: "8", r: "3" }), _jsx("path", { d: "M6.8 19c.6-3.3 2.4-5 5.2-5s4.6 1.7 5.2 5" }), _jsx("circle", { cx: "12", cy: "12", r: "9" })] }),
+        _jsxs(_Fragment, { children: [_jsx("circle", { cx: "12", cy: "8", r: "3" }), _jsx("path", { d: "M6.5 20v-1.2c0-3.2 2.2-5.3 5.5-5.3s5.5 2.1 5.5 5.3V20" })] }),
+        _jsxs(_Fragment, { children: [_jsx("rect", { x: "3.5", y: "5.5", width: "17", height: "13", rx: "1.5" }), _jsx("path", { d: "m4.5 7 7.5 6 7.5-6" })] }),
+        _jsxs(_Fragment, { children: [_jsx("circle", { cx: "12", cy: "12", r: "9" }), _jsx("path", { d: "M3 12h18M12 3c2.2 2.5 3.3 5.5 3.3 9S14.2 18.5 12 21c-2.2-2.5-3.3-5.5-3.3-9S9.8 5.5 12 3" })] }),
+        _jsx("path", { d: "m13.3 2-8 11h6l-.6 9 8-12h-6l.6-8Z" }),
+        _jsx("path", { d: "M4 5.5h16v11H9l-5 4v-15Z" }),
+    ];
+    return _jsx("svg", { className: "permission-icon", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.7", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: paths[index] });
+}
+export function DeviceConsentPage({ view, base = '' }) {
+    return (_jsxs(AccountShell, { base: base, userCode: view.userCode, signOutReturnTo: `${base}/oauth2/device/consent?user_code=${view.userCode}`, children: [_jsx("h1", { children: "Authorize Grok Build" }), _jsx("ul", { className: "permission-list", "aria-label": "Requested permissions", children: view.permissions.map((permission) => {
+                    const index = XAI_DEVICE_PERMISSIONS.indexOf(permission);
+                    return (_jsxs("li", { children: [_jsx(PermissionIcon, { index: index < 0 ? 0 : index }), _jsx("span", { children: permission })] }, permission));
+                }) }), _jsxs("form", { className: "decision-form", method: "POST", action: `${base}/oauth2/device/decision`, children: [_jsx("input", { type: "hidden", name: "user_code", value: view.userCode }), _jsx("button", { className: "secondary-action", name: "decision", value: "deny", type: "submit", children: "Deny" }), _jsx("button", { className: "primary-action", name: "decision", value: "approve", type: "submit", children: "Allow" })] })] }));
+}
+export function DeviceDonePage({ approved, base = '' }) {
+    const title = approved ? 'Device Authorized' : 'Authorization Denied';
+    const detail = approved ? 'Return to your terminal to continue.' : 'The Grok Build request was denied.';
+    return (_jsxs(AccountShell, { base: base, compact: true, result: true, children: [_jsx("div", { className: approved ? 'result-icon result-icon-approved' : 'result-icon', "aria-hidden": "true", children: approved ? '✓' : '×' }), _jsx("h1", { children: title }), _jsx("p", { className: "lead result-copy", children: detail }), _jsx("p", { className: "device-help", children: "You can close this tab." })] }));
+}

package/dist/client/xai-device-auth.tsx

@@ -0,0 +1,138 @@
+// xAI's Grok Build device-authorization surface, rendered by the Twin on the vendor paths.
+//
+// This is the ONE renderer for the device entry, consent, and terminal screens. The server
+// renders these exported components, the capability census renders these same components over
+// projected OAuth state, and the browser journey drives the forms they emit. The forms are
+// deliberately server-native: the authorization round trip works with JavaScript disabled.
+import type { ReactNode } from 'react';
+
+export const XAI_DEVICE_PERMISSIONS = [
+  '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',
+] as const;
+
+export type XaiDeviceAuthView = {
+  userCode: string;
+  status: 'pending' | 'approved' | 'denied' | 'connected' | 'expired' | 'unknown';
+  permissions: readonly string[];
+  error?: string;
+};
+
+function XaiMark() {
+  return (
+    <svg className="xai-mark" viewBox="0 0 834 318" fill="none" aria-hidden="true">
+      <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" fill="black" />
+      <path d="M504.192 317.999H428.146L278.315 208.933C292.122 200.25 306.018 191.98 319.957 184.104L504.192 317.999Z" fill="black" />
+      <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" fill="black" />
+      <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" fill="black" />
+    </svg>
+  );
+}
+
+// `base` is where the twin is reached (`twinPublicBase`: origin plus any served-World mount path);
+// every link and form action the pages emit is built from it, so they stay inside the World's
+// mount. Empty for an in-process render, where the paths are the vendor's own root-relative ones.
+function AccountHeader({ base, signOutReturnTo, userCode }: { base: string; signOutReturnTo?: string; userCode?: string }) {
+  const signOutHref = signOutReturnTo
+    ? `${base}/sign-out?redirect=oauth2-provider&return_to=${encodeURIComponent(signOutReturnTo)}`
+    : `${base}/sign-out`;
+  return (
+    <header className="account-header">
+      <a className="account-home" href={`${base}/`} aria-label="SpaceXAI account home link">
+        <XaiMark />
+      </a>
+      {userCode ? (
+        <a className="sign-out" href={signOutHref}>Sign out</a>
+      ) : null}
+    </header>
+  );
+}
+
+function AccountShell({ base, children, userCode, compact = false, result = false, signOutReturnTo }: { base: string; children: ReactNode; userCode?: string; compact?: boolean; result?: boolean; signOutReturnTo?: string }) {
+  return (
+    <div className="account-page">
+      <AccountHeader base={base} userCode={userCode} signOutReturnTo={signOutReturnTo} />
+      <main className={`auth-shell${compact ? ' auth-shell-compact' : ''}${result ? ' auth-shell-result' : ''}`}>{children}</main>
+    </div>
+  );
+}
+
+export function DeviceEntryPage({ view, base = '' }: { view: XaiDeviceAuthView; base?: string }) {
+  const canContinue = !view.error && /^[A-Z0-9]{4}-[A-Z0-9]{4}$/u.test(view.userCode);
+  return (
+    <AccountShell base={base} compact userCode={view.userCode || undefined}>
+      <h1>Sign in to Grok Build</h1>
+      <p className="lead">Enter the code shown in your terminal.</p>
+      <form className="entry-form" method="POST" action={`${base}/oauth2/device/continue`}>
+        <label className="sr-only" htmlFor="device-code">Enter device code</label>
+        <input
+          id="device-code"
+          name="user_code"
+          inputMode="text"
+          autoComplete="one-time-code"
+          autoCapitalize="characters"
+          spellCheck={false}
+          defaultValue={view.userCode}
+          placeholder="Enter device code"
+          aria-describedby={view.error ? 'device-code-error device-code-help' : 'device-code-help'}
+        />
+        {view.error ? <p id="device-code-error" className="form-error" role="alert">{view.error}</p> : null}
+        <p id="device-code-help" className="device-help">Only enter this code if you just initiated a sign-in from your device.</p>
+        <button className="primary-action" type="submit" disabled={!canContinue}>Continue</button>
+      </form>
+    </AccountShell>
+  );
+}
+
+function PermissionIcon({ index }: { index: number }) {
+  const paths = [
+    <><circle cx="12" cy="8" r="3"/><path d="M6.8 19c.6-3.3 2.4-5 5.2-5s4.6 1.7 5.2 5"/><circle cx="12" cy="12" r="9"/></>,
+    <><circle cx="12" cy="8" r="3"/><path d="M6.5 20v-1.2c0-3.2 2.2-5.3 5.5-5.3s5.5 2.1 5.5 5.3V20"/></>,
+    <><rect x="3.5" y="5.5" width="17" height="13" rx="1.5"/><path d="m4.5 7 7.5 6 7.5-6"/></>,
+    <><circle cx="12" cy="12" r="9"/><path d="M3 12h18M12 3c2.2 2.5 3.3 5.5 3.3 9S14.2 18.5 12 21c-2.2-2.5-3.3-5.5-3.3-9S9.8 5.5 12 3"/></>,
+    <path d="m13.3 2-8 11h6l-.6 9 8-12h-6l.6-8Z" />,
+    <path d="M4 5.5h16v11H9l-5 4v-15Z" />,
+  ];
+  return <svg className="permission-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.7" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">{paths[index]}</svg>;
+}
+
+export function DeviceConsentPage({ view, base = '' }: { view: XaiDeviceAuthView; base?: string }) {
+  return (
+    <AccountShell base={base} userCode={view.userCode} signOutReturnTo={`${base}/oauth2/device/consent?user_code=${view.userCode}`}>
+      <h1>Authorize Grok Build</h1>
+      <ul className="permission-list" aria-label="Requested permissions">
+        {view.permissions.map((permission) => {
+          const index = XAI_DEVICE_PERMISSIONS.indexOf(permission as typeof XAI_DEVICE_PERMISSIONS[number]);
+          return (
+          <li key={permission}>
+            <PermissionIcon index={index < 0 ? 0 : index} />
+            <span>{permission}</span>
+          </li>
+          );
+        })}
+      </ul>
+      <form className="decision-form" method="POST" action={`${base}/oauth2/device/decision`}>
+        <input type="hidden" name="user_code" value={view.userCode} />
+        <button className="secondary-action" name="decision" value="deny" type="submit">Deny</button>
+        <button className="primary-action" name="decision" value="approve" type="submit">Allow</button>
+      </form>
+    </AccountShell>
+  );
+}
+
+export function DeviceDonePage({ approved, base = '' }: { approved: boolean; base?: string }) {
+  const title = approved ? 'Device Authorized' : 'Authorization Denied';
+  const detail = approved ? 'Return to your terminal to continue.' : 'The Grok Build request was denied.';
+  return (
+    <AccountShell base={base} compact result>
+      <div className={approved ? 'result-icon result-icon-approved' : 'result-icon'} aria-hidden="true">{approved ? '✓' : '×'}</div>
+      <h1>{title}</h1>
+      <p className="lead result-copy">{detail}</p>
+      <p className="device-help">You can close this tab.</p>
+    </AccountShell>
+  );
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-xai CLI: serve the xAI/Grok API, OAuth protocol UI, or run conformance. `mirror` is an
+// alias for the SAME server because entry and consent are the vendor-owned browser leg of OAuth;
+// denial and completion are explicitly Twin-local terminal states, not a second dashboard.
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createXaiTwinServer } from "./xai-server.js";
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+const scenario = optionValue(rest, '--scenario') || undefined; // scripted completions (JSON scenario file)
+if (cmd === 'serve' || cmd === 'mirror') {
+    const s = await createXaiTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(scenario ? { scenarioPath: scenario } : {}) });
+    process.stdout.write(`xai twin (chat/completions/messages output is a deterministic stub)${readOnly ? ' [read-only]' : ''}${scenario ? ` [scenario: ${scenario}]` : ''} at http://127.0.0.1:${s.port}\n`);
+    await keepProcessAlive();
+}
+else if (cmd === 'conformance') {
+    // dev-only; lazy so the bin runs without @volter/world-tooling
+    const { checkXaiConformance } = await import("./xai-conformance.js");
+    const report = await checkXaiConformance({ ...(root ? { root } : {}) });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    if (!report.ok)
+        process.exitCode = 1;
+}
+else {
+    process.stdout.write('Usage: world-xai serve|mirror|conformance [--port N] [--root DIR] [--read-only] [--scenario FILE]\n');
+}

package/dist/src/index.d.ts

@@ -0,0 +1,17 @@
+export { handleXaiTwinRequest, streamChat, buildChatCompletion } from './xai-twin.js';
+export type { XaiRequest, XaiResponseEnvelope } from './xai-twin.js';
+export { createXaiTwinFetch, createXaiTwinServer, type XaiTwinFetchOptions } from './xai-server.js';
+export { deviceConsentPageHtml, deviceDonePageHtml, deviceEntryPageHtml, xaiDeviceAuthView, XAI_DEVICE_STYLE_PATH, } from './xai-device-auth-ui.js';
+export { XAI_MODELS, XAI_LANGUAGE_MODELS, XAI_IMAGE_GENERATION_MODELS, findModel, findLanguageModel, findImageGenerationModel, modelBehavior, canonicalModelId, } from './xai-models.js';
+export type { XaiModel, XaiLanguageModel, XaiImageGenerationModel, XaiModelBehavior } from './xai-models.js';
+export { contentToText, countPromptTokens, countPromptTokenDetails, estimateTokens, lastUserText, pseudoTokenize, stubAssistantText, stubCitations, stubJsonObject, stubReasoningText, stubToolArguments, stubToolCall, uuidFromSeed, } from './xai-stub.js';
+export type { XaiToken } from './xai-stub.js';
+export type { ChatMessageParam, ChatToolCall, ChatCompletion, ChatChoice, ChatUsage, TextCompletion, MessagesResponse, MessagesContentBlock, XaiError, SseEvent, SseSink, } from './xai-types.js';
+export { createXaiScenarioEngine, loadXaiScenarioDocument, realizeXaiRespond, xaiScenarioAdapter } from './xai-scenario.js';
+export type { ScenarioToolCall, ScriptedResult, XaiScenarioEngine, XaiScenarioRequest, XaiScenarioRespond } from './xai-scenario.js';
+export { XAI_BUDGET_CEILING, XAI_BUDGET_MAX_RETRY_AFTER_S, XAI_BUDGET_WINDOW_MS, XAI_CALL_WEIGHTS, XAI_RATE_BUDGET, XaiBudget, XaiBudgetError, xaiBudgetPath, xaiCallWeight, splitXaiPath, } from './xai-budget.js';
+export type { XaiBudgetErrorKind, XaiBudgetOptions, XaiBudgetReservation, XaiBudgetSnapshot, } from './xai-budget.js';
+export { XAI_API_BASE, liveXaiExecute, mapModel, mapLanguageModel, pullXaiModels, syncXaiFromReal, pushXaiAction, } from './xai-connector.js';
+export type { XaiExecute, LiveXaiOptions } from './xai-connector.js';
+import { type TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,70 @@
+// @volter/twin-xai — the xAI (Grok) twin (one vendor, one package), built on the shared
+// @volter/world-core kernel. The xAI API: an OpenAI-chat-compatible protocol envelope with xAI's
+// deltas modeled explicitly — the grok-4-family model catalogs (/v1/models,
+// /v1/language-models, /v1/image-generation-models), the flat {code, error} error envelope,
+// deferred completions (stateful, kernel-backed), Live Search parameters + citations,
+// reasoning_content/reasoning-token accounting, the Anthropic-compatible /v1/messages
+// endpoint, legacy /v1/completions, api-key introspection, tokenize-text, the vendor-owned Grok
+// Build device-entry/consent UI, and explicitly Twin-local terminal result states. The xAI console
+// itself remains outside this API-first pack.
+//
+// THE DETERMINISTIC STUBS ARE THE ANSWER: every inference endpoint returns a clearly-labeled
+// STUB completion, and Live Search returns deterministic labeled citations. Everything around
+// them — the wire protocol — is faithful. (Conformance + capability tooling live in @volter/world-tooling, a dev
+// dependency — NOT re-exported here, per E2.)
+export { handleXaiTwinRequest, streamChat, buildChatCompletion } from "./xai-twin.js";
+export { createXaiTwinFetch, createXaiTwinServer } from "./xai-server.js";
+export { deviceConsentPageHtml, deviceDonePageHtml, deviceEntryPageHtml, xaiDeviceAuthView, XAI_DEVICE_STYLE_PATH, } from "./xai-device-auth-ui.js";
+export { XAI_MODELS, XAI_LANGUAGE_MODELS, XAI_IMAGE_GENERATION_MODELS, findModel, findLanguageModel, findImageGenerationModel, modelBehavior, canonicalModelId, } from "./xai-models.js";
+export { contentToText, countPromptTokens, countPromptTokenDetails, estimateTokens, lastUserText, pseudoTokenize, stubAssistantText, stubCitations, stubJsonObject, stubReasoningText, stubToolArguments, stubToolCall, uuidFromSeed, } from "./xai-stub.js";
+export { createXaiScenarioEngine, loadXaiScenarioDocument, realizeXaiRespond, xaiScenarioAdapter } from "./xai-scenario.js";
+export { XAI_BUDGET_CEILING, XAI_BUDGET_MAX_RETRY_AFTER_S, XAI_BUDGET_WINDOW_MS, XAI_CALL_WEIGHTS, XAI_RATE_BUDGET, XaiBudget, XaiBudgetError, xaiBudgetPath, xaiCallWeight, splitXaiPath, } from "./xai-budget.js";
+export { XAI_API_BASE, liveXaiExecute, mapModel, mapLanguageModel, pullXaiModels, syncXaiFromReal, pushXaiAction, } from "./xai-connector.js";
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack } from '@volter/world-core';
+import { XAI_RATE_BUDGET as RATE_BUDGET } from "./xai-budget.js";
+import { performXaiAction, syncXaiFromRemote } from "./xai-connector.js";
+export const pack = {
+    // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of the real
+    // state system. Moved 2026-09-08. The xAI API has NO client-writable resource, so `perform` settles every
+    // entry with that reason and only `refresh` reads; the pack's executor is GET-only by type to say so.
+    protocol: '2',
+    refresh: { every: '30m', onDemand: { atMost: '60s' } }, // a model catalogue moves slowly
+    stateSystem: { perform: performXaiAction, refresh: syncXaiFromRemote },
+    // the round trip: a DEFERRED completion — a plain completion is answered and forgotten, but xAI's
+    // deferred mode persists the request so a caller can poll it, which is the row this twin keeps
+    roundTrip: { method: 'POST', path: '/v1/chat/completions', body: { model: 'grok-4-latest', deferred: true, messages: [{ role: 'user', content: 'round trip' }] }, headers: { authorization: 'Bearer round-trip' } },
+    parityOrigin: 'http://twin',
+    vendor: 'xai',
+    // The client-side rate budget, armed by `registerPack` as well as by importing the budget module.
+    rateBudget: RATE_BUDGET,
+    transport: 'rest',
+    archetype: 'generative',
+    bin: 'world-xai',
+    // R2 adopted-as-debt, legibly: declared types no replay can create, each with its reason.
+    resourcesUnreachable: {
+        'language_model': 'the vendor catalog',
+        'model': 'the vendor catalog',
+    },
+    resources: ['deferred_completion', 'language_model', 'model', 'oauth_account', 'oauth_device_authorization', 'oauth_usage'],
+    specSource: 'xAI (Grok) REST API + Grok Build OAuth/device and chat-proxy protocols (envelope-faithful; model output is a deterministic stub, Live Search citations are deterministic labeled stubs)',
+    description: 'xAI (Grok) twin — coherent virtual account/device OAuth/refresh/usage plus the Grok CLI proxy and OpenAI-chat-compatible API envelope; generative output is a labeled stub.',
+    // Adoption + interception, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
+    // 2026-08-31). Both credential-env spellings the vendor and its users write —
+    // XAI_* and GROK_*.
+    adoption: {
+        // xAI's official Python SDK (xai-org/xai-sdk-python). An `openai` client pointed at api.x.ai is NOT
+        // claimed here: that distribution is the openai pack's and XAI_API_BASE is what routes it.
+        pypi: ['xai-sdk'],
+        sdks: ['@ai-sdk/xai'], envStems: ['XAI', 'GROK'],
+    },
+    // Inference lives on https://api.x.ai — the pack's connector pins XAI_API_BASE =
+    // 'https://api.x.ai' (xai-connector.ts). management-api.x.ai is a separate console/
+    // administration product the pack deliberately does NOT twin (README §Management API) — left
+    // unclaimed so strict egress fails closed rather than letting a half-modeled flow through.
+    hosts: [{ host: 'api.x.ai' }],
+    // The SDK calls the same-origin '/v1/…' and loads from api.x.ai — the dev proxy forwards
+    // '/v1/' to the twin and strips the absolute host so calls come back same-origin.
+    browserRouting: { apiPathPrefix: '/v1/', loaderHost: 'https://api.x.ai' },
+};
+registerPack(pack);

package/dist/src/xai-budget.d.ts

@@ -0,0 +1,60 @@
+import { RateBudget, type RateBudgetDeclaration, type RateBudgetOptions, type RateBudgetReservation, type RateBudgetSnapshot } from '@volter/world-core';
+/** Rolling window, in ms. The fallback's, because xAI publishes no per-minute figure to match. */
+export declare const XAI_BUDGET_WINDOW_MS = 60000;
+/**
+ * Weighted units allowed inside one window. 60/60s at the default weight of 2 = 30 calls a minute —
+ * the kernel's austere fallback exactly, adopted deliberately because xAI publishes no scalar limit.
+ */
+export declare const XAI_BUDGET_CEILING = 60;
+/** Seconds. A `Retry-After` above this means the key is throttled hard — fail loudly, don't sleep. */
+export declare const XAI_BUDGET_MAX_RETRY_AFTER_S = 300;
+/**
+ * Per-call cost. FLAT by design — see the header: the execute is GET-only over read-only catalogs,
+ * so no reachable endpoint is credibly dearer than another, and inventing a ratio would be a
+ * fabricated vendor fact. `other` is the only weight, and it is never zero.
+ */
+export declare const XAI_CALL_WEIGHTS: {
+    /** Every call. xAI publishes no per-endpoint cost, and this execute reaches only catalog reads. */
+    readonly other: 2;
+};
+/**
+ * THE PACK'S DECLARATION — pure data, the only xAI-specific thing in the whole budget.
+ *
+ * `rules` is EMPTY on purpose (see the header). Also exported as `pack.rateBudget` (see index.ts),
+ * so `registerPack` arms it too.
+ */
+export declare const XAI_RATE_BUDGET: RateBudgetDeclaration;
+/** Split a connector path (which may carry its own query string) into pathname + parsed query. */
+export declare function splitXaiPath(path: string): {
+    pathname: string;
+    query: Record<string, string>;
+};
+/**
+ * Price one call. Keyed off the request the connector is ABOUT to make. With no rules declared every
+ * call takes `defaultWeight` — which is the point: an unclassified endpoint must never be free.
+ */
+export declare function xaiCallWeight(method: string, path: string): number;
+/** Where xAI's ledger lives. API-key-keyed and cwd-independent by default (the limit, whatever it
+ *  is, is per key, so a cwd-scoped ledger would hand the same key a fresh allowance in every
+ *  checkout, worktree and CI matrix leg); pass `root` to opt into world-scoped accounting instead. */
+export declare function xaiBudgetPath(opts?: {
+    root?: string;
+    token?: string;
+} | string): string;
+/** Construction options for xAI's budget. The vendor is fixed; everything else may only TIGHTEN. */
+export type XaiBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+/**
+ * xAI's budget — the shared kernel guard bound to this vendor's declaration. A real subclass, not an
+ * alias, so the guard check in `liveXaiExecute` still means "a budget that accounts against XAI's
+ * ledger under XAI's ceiling": another vendor's `RateBudget` (with its own, possibly larger,
+ * ceiling) is NOT assignable there.
+ */
+export declare class XaiBudget extends RateBudget {
+    constructor(opts?: XaiBudgetOptions);
+}
+/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
+ *  which one refused, and `err.kind` says why. */
+export { RateBudgetError as XaiBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as XaiBudgetErrorKind } from '@volter/world-core';
+export type XaiBudgetReservation = RateBudgetReservation;
+export type XaiBudgetSnapshot = RateBudgetSnapshot;