@volter/twin-xai 0.1.0

package/dist/src/xai-models.js

@@ -0,0 +1,102 @@
+// xAI model catalog — the static model-listing surface. xAI serves THREE catalogs:
+//   • GET /v1/models                    — OpenAI-compatible ({ id, object:'model', created, owned_by })
+//   • GET /v1/language-models           — xAI-native rich objects ({ models: [...] } with modalities,
+//                                         per-token prices, aliases, fingerprint)
+//   • GET /v1/image-generation-models   — same rich shape for the image models
+// The twin returns a faithful, deterministic slice of the published grok catalog so
+// `models.list()` / alias resolution round-trip like the vendor. This is a STATIC surface (the
+// registry doesn't change at runtime), so it is a plain data table rather than kernel state —
+// the connector can additionally fold OBSERVED real models into the served list (xai-twin.ts).
+//
+// Price fields follow the vendor's integer per-token price representation; the values here are
+// deterministic representative constants, not a live price sheet (see README ## Coverage).
+// The grok-4-family + supporting catalog (ids are the exact vendor strings; aliases resolve for
+// inference AND retrieval, like the vendor).
+const LANGUAGE_CATALOG = [
+    {
+        id: 'grok-4-0709', fingerprint: 'fp_twin_grok4', created: 1752019200, object: 'model', owned_by: 'xai',
+        version: '1.0.0', input_modalities: ['text', 'image'], output_modalities: ['text'],
+        prompt_text_token_price: 30000, cached_prompt_text_token_price: 7500, prompt_image_token_price: 30000,
+        completion_text_token_price: 150000, search_price: 250000, aliases: ['grok-4', 'grok-4-latest'],
+        behavior: { supportsReasoningEffort: false, isReasoningModel: true },
+    },
+    {
+        id: 'grok-4-fast-reasoning', fingerprint: 'fp_twin_grok4fr', created: 1758240000, object: 'model', owned_by: 'xai',
+        version: '1.0.0', input_modalities: ['text', 'image'], output_modalities: ['text'],
+        prompt_text_token_price: 2000, cached_prompt_text_token_price: 500, prompt_image_token_price: 2000,
+        completion_text_token_price: 5000, search_price: 250000, aliases: ['grok-4-fast', 'grok-4-fast-latest'],
+        behavior: { supportsReasoningEffort: false, isReasoningModel: true },
+    },
+    {
+        id: 'grok-4-fast-non-reasoning', fingerprint: 'fp_twin_grok4fnr', created: 1758240000, object: 'model', owned_by: 'xai',
+        version: '1.0.0', input_modalities: ['text', 'image'], output_modalities: ['text'],
+        prompt_text_token_price: 2000, cached_prompt_text_token_price: 500, prompt_image_token_price: 2000,
+        completion_text_token_price: 5000, search_price: 250000, aliases: [],
+        behavior: { supportsReasoningEffort: false, isReasoningModel: false },
+    },
+    {
+        id: 'grok-code-fast-1', fingerprint: 'fp_twin_grokcode', created: 1756166400, object: 'model', owned_by: 'xai',
+        version: '1.0.0', input_modalities: ['text'], output_modalities: ['text'],
+        prompt_text_token_price: 2000, cached_prompt_text_token_price: 200, prompt_image_token_price: 0,
+        completion_text_token_price: 15000, search_price: 0, aliases: ['grok-build'],
+        behavior: { supportsReasoningEffort: false, isReasoningModel: true },
+    },
+    {
+        id: 'grok-3', fingerprint: 'fp_twin_grok3', created: 1743724800, object: 'model', owned_by: 'xai',
+        version: '1.0.0', input_modalities: ['text'], output_modalities: ['text'],
+        prompt_text_token_price: 30000, cached_prompt_text_token_price: 7500, prompt_image_token_price: 0,
+        completion_text_token_price: 150000, search_price: 250000, aliases: ['grok-3-latest', 'grok-3-beta'],
+        behavior: { supportsReasoningEffort: false, isReasoningModel: false },
+    },
+    {
+        id: 'grok-3-mini', fingerprint: 'fp_twin_grok3mini', created: 1743724800, object: 'model', owned_by: 'xai',
+        version: '1.0.0', input_modalities: ['text'], output_modalities: ['text'],
+        prompt_text_token_price: 3000, cached_prompt_text_token_price: 750, prompt_image_token_price: 0,
+        completion_text_token_price: 5000, search_price: 250000, aliases: ['grok-3-mini-latest', 'grok-3-mini-beta'],
+        behavior: { supportsReasoningEffort: true, isReasoningModel: true },
+    },
+];
+export const XAI_IMAGE_GENERATION_MODELS = [
+    {
+        id: 'grok-2-image-1212', fingerprint: 'fp_twin_grok2img', created: 1734307200, object: 'model', owned_by: 'xai',
+        version: '1.0.0', input_modalities: ['text'], output_modalities: ['image'],
+        image_price: 70000, aliases: ['grok-2-image', 'grok-2-image-latest'],
+    },
+];
+export const XAI_LANGUAGE_MODELS = LANGUAGE_CATALOG.map(({ behavior: _b, ...m }) => m);
+/** The OpenAI-compatible /v1/models view (language + image-generation models, flat). */
+export const XAI_MODELS = [
+    ...LANGUAGE_CATALOG.map((m) => ({ id: m.id, object: 'model', created: m.created, owned_by: 'xai' })),
+    ...XAI_IMAGE_GENERATION_MODELS.map((m) => ({ id: m.id, object: 'model', created: m.created, owned_by: 'xai' })),
+];
+/** Resolve a model id OR one of its aliases to the canonical language-model entry. */
+export function findLanguageModel(id) {
+    const hit = LANGUAGE_CATALOG.find((m) => m.id === id || m.aliases.includes(id));
+    if (!hit)
+        return undefined;
+    const { behavior: _b, ...m } = hit;
+    return m;
+}
+/** Resolve a model id/alias to the flat OpenAI-compatible model object. */
+export function findModel(id) {
+    const lm = LANGUAGE_CATALOG.find((m) => m.id === id || m.aliases.includes(id));
+    if (lm)
+        return { id: lm.id, object: 'model', created: lm.created, owned_by: 'xai' };
+    const im = XAI_IMAGE_GENERATION_MODELS.find((m) => m.id === id || m.aliases.includes(id));
+    if (im)
+        return { id: im.id, object: 'model', created: im.created, owned_by: 'xai' };
+    return undefined;
+}
+export function findImageGenerationModel(id) {
+    return XAI_IMAGE_GENERATION_MODELS.find((m) => m.id === id || m.aliases.includes(id));
+}
+/** Twin-internal: behavior flags for an INFERENCE model id/alias (undefined for unknown ids
+ *  and for image models, which cannot chat). */
+export function modelBehavior(id) {
+    return LANGUAGE_CATALOG.find((m) => m.id === id || m.aliases.includes(id))?.behavior;
+}
+/** Canonical id for a model id/alias (the vendor echoes the CANONICAL id in responses). */
+export function canonicalModelId(id) {
+    return LANGUAGE_CATALOG.find((m) => m.id === id || m.aliases.includes(id))?.id
+        ?? XAI_IMAGE_GENERATION_MODELS.find((m) => m.id === id || m.aliases.includes(id))?.id;
+}

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

@@ -0,0 +1,30 @@
+export type XaiOauthResult = {
+    status: number;
+    body: Record<string, unknown>;
+};
+export declare function startXaiTwinDeviceAuthorization(input: {
+    body: URLSearchParams;
+    occurredAt?: string;
+    origin: string;
+    root?: string;
+}): Promise<XaiOauthResult>;
+export declare function decideXaiTwinDeviceAuthorization(input: {
+    approved: boolean;
+    occurredAt?: string;
+    root?: string;
+    userCode: string;
+}): Promise<XaiOauthResult>;
+export declare function inspectXaiTwinDeviceAuthorization(userCode: string, root?: string): Record<string, unknown> | undefined;
+export declare function exchangeXaiTwinToken(input: {
+    body: URLSearchParams;
+    occurredAt?: string;
+    root?: string;
+}): Promise<XaiOauthResult>;
+export declare function isCurrentXaiTwinAccessToken(accessToken: string, root?: string, occurredAt?: string): boolean;
+export declare function recordXaiTwinUsage(input: {
+    completionTokens: number;
+    occurredAt?: string;
+    promptTokens: number;
+    requestId: string;
+    root?: string;
+}): Promise<void>;

package/dist/src/xai-oauth.js

@@ -0,0 +1,279 @@
+import { applyTwinWrite, applyTwinWriteAtomic, projectResources } from '@volter/world-core';
+const SERVICE = 'xai';
+const ACCOUNT_ID = 'acct_twin_grok';
+const DEFAULT_SCOPE = 'openid profile email offline_access grok-cli:access api:access conversations:read conversations:write workspaces:read workspaces:write';
+const ACCESS_TTL_SECONDS = 3_600;
+const DEVICE_TTL_SECONDS = 900;
+function at(occurredAt) {
+    return new Date(occurredAt ?? new Date().toISOString());
+}
+/** FNV-1a over the seed, widened by re-hashing with a round counter until `n` hex chars exist. */
+function stableHex(seed, n) {
+    let out = '';
+    for (let round = 0; out.length < n; round += 1) {
+        let h = 0x811c9dc5;
+        const s = `${round}:${seed}`;
+        for (let i = 0; i < s.length; i += 1) {
+            h ^= s.charCodeAt(i);
+            h = Math.imul(h, 0x01000193) >>> 0;
+        }
+        out += h.toString(16).padStart(8, '0');
+    }
+    return out.slice(0, n);
+}
+// Device codes, user codes and OAuth tokens are STATE (stored on the device-authorization row
+// and served straight back), so they are DETERMINISTIC (R9): a stable hash over the world
+// instant plus the ordinal the write takes, never randomUUID. The shapes are unchanged — 32 hex
+// characters after the prefix, exactly what `randomUUID().replaceAll('-','')` produced. Every
+// mint happens INSIDE the actions lock, from the row count read under that lock, so two
+// identical requests in one millisecond still take different ordinals and both land.
+function token(prefix, seed) {
+    return `${prefix}_${stableHex(seed, 32)}`;
+}
+function deviceRows(resources) {
+    return resources.filter((resource) => resource.type === 'oauth_device_authorization');
+}
+function oauthError(status, error, description) {
+    return { status, body: { error, error_description: description } };
+}
+function accountClaims() {
+    return {
+        email: 'grok-builder@twin.invalid',
+        name: 'Grok Builder (Twin)',
+        preferred_username: 'grok-builder-twin',
+        sub: 'xai_twin_user_grok_builder',
+    };
+}
+function idToken() {
+    const header = Buffer.from(JSON.stringify({ alg: 'none', typ: 'JWT' })).toString('base64url');
+    const payload = Buffer.from(JSON.stringify({ ...accountClaims(), aud: 'grok-build', iss: 'xai-twin' })).toString('base64url');
+    return `${header}.${payload}.`;
+}
+async function ensureAccount(root, occurredAt) {
+    // ENSURE means "make sure one exists", not "write one per request". Every other ensure* in the
+    // catalog checks first; this one wrote unconditionally and was only ever one row because the
+    // kernel used to collapse identical writes — a local vendor write is now an OCCURRENCE, so
+    // without this check every device-authorization start appended a pending oauth_account.ensure
+    // (2026-09-04, in review).
+    if (projectResources(SERVICE, root).some((r) => r.type === 'oauth_account' && r.id === ACCOUNT_ID))
+        return;
+    await applyTwinWrite(SERVICE, {
+        operation: 'oauth_account.ensure',
+        subjectType: 'oauth_account',
+        subjectId: ACCOUNT_ID,
+        fields: { ...accountClaims(), status: 'active' },
+        ...(occurredAt ? { occurredAt } : {}),
+        actor: { kind: 'system' },
+    }, root);
+}
+export async function startXaiTwinDeviceAuthorization(input) {
+    const clientId = input.body.get('client_id')?.trim() ?? '';
+    const scope = input.body.get('scope')?.trim() || DEFAULT_SCOPE;
+    if (!clientId)
+        return oauthError(400, 'invalid_request', 'client_id is required');
+    if (!new Set(scope.split(/\s+/u)).has('grok-cli:access')) {
+        return oauthError(400, 'invalid_scope', 'grok-cli:access is required');
+    }
+    await ensureAccount(input.root, input.occurredAt);
+    const now = at(input.occurredAt);
+    const expiresAt = new Date(now.getTime() + DEVICE_TTL_SECONDS * 1_000).toISOString();
+    // The ordinal is read INSIDE the lock, so two identical device-authorization requests at the
+    // same instant mint different codes and both land — what `uniqueness: randomUUID()` bought
+    // before, now without randomness in served content.
+    const minted = await applyTwinWriteAtomic(SERVICE, (resources) => {
+        const seed = `oauth_device_authorization:${input.occurredAt ?? ''}:${deviceRows(resources).length}:${clientId}`;
+        const deviceCode = token('xai_twin_device', seed);
+        const userCode = stableHex(`user_code:${seed}`, 8).toUpperCase().replace(/(.{4})/u, '$1-');
+        return {
+            kind: 'write',
+            value: { deviceCode, userCode },
+            write: {
+                operation: 'oauth_device_authorization.create',
+                subjectType: 'oauth_device_authorization',
+                subjectId: deviceCode,
+                fields: {
+                    account_id: ACCOUNT_ID,
+                    client_id: clientId,
+                    expires_at: expiresAt,
+                    scope,
+                    status: 'pending',
+                    user_code: userCode,
+                },
+                ...(input.occurredAt ? { occurredAt: input.occurredAt } : {}),
+                actor: { kind: 'agent' },
+                uniqueness: deviceCode,
+            },
+        };
+    }, input.root);
+    const { deviceCode, userCode } = minted.value;
+    const base = input.origin.replace(/\/+$/, '');
+    const verificationUri = `${base}/oauth2/device`;
+    const verificationUriComplete = `${base}/oauth2/device?user_code=${encodeURIComponent(userCode)}`;
+    return {
+        status: 200,
+        body: {
+            device_code: deviceCode,
+            user_code: userCode,
+            verification_uri: verificationUri,
+            verification_uri_complete: verificationUriComplete,
+            expires_in: DEVICE_TTL_SECONDS,
+            interval: 1,
+        },
+    };
+}
+export async function decideXaiTwinDeviceAuthorization(input) {
+    const now = at(input.occurredAt);
+    const decision = await applyTwinWriteAtomic(SERVICE, (resources) => {
+        const device = deviceRows(resources).find((resource) => resource.user_code === input.userCode);
+        if (!device)
+            return { kind: 'skip', value: oauthError(404, 'invalid_user_code', 'The device code is unknown.') };
+        if (Date.parse(String(device.expires_at)) <= now.getTime()) {
+            return { kind: 'skip', value: oauthError(400, 'expired_token', 'The device code expired.') };
+        }
+        if (device.status !== 'pending') {
+            return { kind: 'skip', value: oauthError(409, 'invalid_request', 'The device authorization was already decided.') };
+        }
+        const status = input.approved ? 'approved' : 'denied';
+        return {
+            kind: 'write',
+            value: { status: 200, body: { approved: input.approved, status, user_code: input.userCode } },
+            write: {
+                operation: input.approved ? 'oauth_device_authorization.approve' : 'oauth_device_authorization.deny',
+                subjectType: 'oauth_device_authorization',
+                subjectId: device.id,
+                fields: { decided_at: now.toISOString(), status },
+                ...(input.occurredAt ? { occurredAt: input.occurredAt } : {}),
+                actor: { kind: 'human', id: ACCOUNT_ID },
+            },
+        };
+    }, input.root);
+    return decision.value;
+}
+export function inspectXaiTwinDeviceAuthorization(userCode, root) {
+    const resources = projectResources(SERVICE, root);
+    const device = resources.find((resource) => resource.type === 'oauth_device_authorization' && resource.user_code === userCode);
+    if (!device)
+        return undefined;
+    const account = resources.find((resource) => resource.type === 'oauth_account' && resource.id === device.account_id);
+    return {
+        account: account ? { email: account.email, id: account.id, name: account.name } : undefined,
+        expiresAt: device.expires_at,
+        scope: device.scope,
+        status: device.status,
+        userCode: device.user_code,
+    };
+}
+export async function exchangeXaiTwinToken(input) {
+    const grantType = input.body.get('grant_type') ?? '';
+    const now = at(input.occurredAt);
+    if (grantType === 'urn:ietf:params:oauth:grant-type:device_code') {
+        const clientId = input.body.get('client_id')?.trim() ?? '';
+        const deviceCode = input.body.get('device_code') ?? '';
+        const result = await applyTwinWriteAtomic(SERVICE, (resources) => {
+            const device = deviceRows(resources).find((resource) => resource.id === deviceCode);
+            // Minted under the lock off the row this exchange consumes plus its token generation, so a
+            // re-issue against the same device code at the same instant is still a distinct token.
+            const accessToken = token('xai_twin_access', `access_token:${input.occurredAt ?? ''}:${deviceCode}:1`);
+            const refreshToken = token('xai_twin_refresh', `refresh_token:${input.occurredAt ?? ''}:${deviceCode}:1`);
+            if (!device)
+                return { kind: 'skip', value: oauthError(400, 'invalid_grant', 'The device code is invalid.') };
+            if (!clientId || clientId !== device.client_id)
+                return { kind: 'skip', value: oauthError(400, 'invalid_grant', 'The device code was not issued to this client.') };
+            if (Date.parse(String(device.expires_at)) <= now.getTime())
+                return { kind: 'skip', value: oauthError(400, 'expired_token', 'The device code expired.') };
+            if (device.status === 'pending')
+                return { kind: 'skip', value: oauthError(400, 'authorization_pending', 'Authorization is pending.') };
+            if (device.status === 'denied')
+                return { kind: 'skip', value: oauthError(400, 'access_denied', 'Authorization was denied.') };
+            if (device.status !== 'approved')
+                return { kind: 'skip', value: oauthError(400, 'invalid_grant', 'The device code was already consumed.') };
+            const scope = String(device.scope ?? DEFAULT_SCOPE);
+            return {
+                kind: 'write',
+                value: { status: 200, body: { access_token: accessToken, expires_in: ACCESS_TTL_SECONDS, id_token: idToken(), refresh_token: refreshToken, scope, token_type: 'Bearer' } },
+                write: {
+                    operation: 'oauth_device_authorization.exchange',
+                    subjectType: 'oauth_device_authorization',
+                    subjectId: device.id,
+                    fields: {
+                        access_expires_at: new Date(now.getTime() + ACCESS_TTL_SECONDS * 1_000).toISOString(),
+                        access_token: accessToken,
+                        refresh_token: refreshToken,
+                        status: 'connected',
+                        token_generation: 1,
+                    },
+                    ...(input.occurredAt ? { occurredAt: input.occurredAt } : {}),
+                    actor: { kind: 'agent' },
+                },
+            };
+        }, input.root);
+        return result.value;
+    }
+    if (grantType === 'refresh_token') {
+        const clientId = input.body.get('client_id')?.trim() ?? '';
+        const presentedRefresh = input.body.get('refresh_token') ?? '';
+        const result = await applyTwinWriteAtomic(SERVICE, (resources) => {
+            const device = deviceRows(resources).find((resource) => resource.refresh_token === presentedRefresh && resource.status === 'connected');
+            if (!device)
+                return { kind: 'skip', value: oauthError(400, 'invalid_grant', 'The refresh token is invalid or revoked.') };
+            if (!clientId || clientId !== device.client_id)
+                return { kind: 'skip', value: oauthError(400, 'invalid_grant', 'The refresh token was not issued to this client.') };
+            const scope = String(device.scope ?? DEFAULT_SCOPE);
+            // The NEXT generation is the discriminator: each refresh of the same row mints a new pair.
+            const generation = Number(device.token_generation ?? 1) + 1;
+            const accessToken = token('xai_twin_access', `access_token:${input.occurredAt ?? ''}:${String(device.id)}:${generation}`);
+            const refreshToken = token('xai_twin_refresh', `refresh_token:${input.occurredAt ?? ''}:${String(device.id)}:${generation}`);
+            return {
+                kind: 'write',
+                value: { status: 200, body: { access_token: accessToken, expires_in: ACCESS_TTL_SECONDS, id_token: idToken(), refresh_token: refreshToken, scope, token_type: 'Bearer' } },
+                write: {
+                    operation: 'oauth_token.refresh',
+                    subjectType: 'oauth_device_authorization',
+                    subjectId: device.id,
+                    fields: {
+                        access_expires_at: new Date(now.getTime() + ACCESS_TTL_SECONDS * 1_000).toISOString(),
+                        access_token: accessToken,
+                        refresh_token: refreshToken,
+                        token_generation: generation,
+                    },
+                    ...(input.occurredAt ? { occurredAt: input.occurredAt } : {}),
+                    actor: { kind: 'agent' },
+                },
+            };
+        }, input.root);
+        return result.value;
+    }
+    return oauthError(400, 'unsupported_grant_type', 'The requested OAuth grant is unsupported.');
+}
+export function isCurrentXaiTwinAccessToken(accessToken, root, occurredAt) {
+    const now = at(occurredAt).getTime();
+    return projectResources(SERVICE, root).some((resource) => resource.type === 'oauth_device_authorization'
+        && resource.status === 'connected'
+        && resource.access_token === accessToken
+        && Date.parse(String(resource.access_expires_at)) > now);
+}
+export async function recordXaiTwinUsage(input) {
+    await applyTwinWriteAtomic(SERVICE, (resources) => {
+        const prior = resources.find((resource) => resource.type === 'oauth_usage' && resource.id === ACCOUNT_ID);
+        return {
+            kind: 'write',
+            value: undefined,
+            write: {
+                operation: 'oauth_usage.spend',
+                subjectType: 'oauth_usage',
+                subjectId: ACCOUNT_ID,
+                fields: {
+                    account_id: ACCOUNT_ID,
+                    completion_tokens: Number(prior?.completion_tokens ?? 0) + input.completionTokens,
+                    prompt_tokens: Number(prior?.prompt_tokens ?? 0) + input.promptTokens,
+                    requests: Number(prior?.requests ?? 0) + 1,
+                    total_tokens: Number(prior?.total_tokens ?? 0) + input.promptTokens + input.completionTokens,
+                },
+                ...(input.occurredAt ? { occurredAt: input.occurredAt } : {}),
+                actor: { kind: 'agent' },
+                correlationId: input.requestId,
+                uniqueness: input.requestId,
+            },
+        };
+    }, input.root);
+}

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

@@ -0,0 +1,33 @@
+import { type PackScenarioAdapter, type ScenarioDocument, ScenarioEngine } from '@volter/world-core';
+import type { ChatMessageParam, ChatToolCall } from './xai-types.js';
+export type XaiScenarioRequest = {
+    model: string;
+    messages: ChatMessageParam[];
+    tools?: unknown;
+};
+export type XaiScenarioEngine = ScenarioEngine<XaiScenarioRequest>;
+/** A scripted tool call — the full arguments object is emitted verbatim (JSON-encoded on the
+ *  wire, and streamed as delta.tool_calls on the streaming path). */
+export type ScenarioToolCall = {
+    name: string;
+    arguments: Record<string, unknown>;
+    id?: string;
+};
+/** What the assistant says when a handler fires: text and/or one-or-more tool calls. */
+export type XaiScenarioRespond = {
+    text?: string;
+    toolCalls?: ScenarioToolCall | ScenarioToolCall[];
+    /** Defaults to 'tool_calls' when any tool call is present, else 'stop'. */
+    finishReason?: 'stop' | 'length' | 'tool_calls' | 'content_filter';
+};
+/** What a fired handler yields — assistant text/tool_calls + finish_reason for the envelope. */
+export type ScriptedResult = {
+    text: string | null;
+    toolCalls: ChatToolCall[];
+    finishReason: 'stop' | 'length' | 'tool_calls' | 'content_filter';
+};
+export declare const xaiScenarioAdapter: PackScenarioAdapter<XaiScenarioRequest>;
+export declare function loadXaiScenarioDocument(path: string): ScenarioDocument;
+export declare function createXaiScenarioEngine(document?: ScenarioDocument): XaiScenarioEngine;
+/** Realize a fired handler's respond into the envelope builder's scripted-turn shape. */
+export declare function realizeXaiRespond(respond: XaiScenarioRespond): ScriptedResult;

package/dist/src/xai-scenario.js

@@ -0,0 +1,139 @@
+// The xai pack's HALF of the scenario system on the kernel's ONE engine (@volter/world-core
+// scenario.ts): the chat-completions vocabulary + the scripted-turn respond shape the
+// envelope builder consumes. The handler FILE (handlers/xai.json in a world dir) is the only
+// write surface. Deferred chat calls answer { request_id } before this machinery runs and are
+// never counted.
+import { getActiveWorldStore, parseScenarioDocument, ScenarioError, ScenarioEngine } from '@volter/world-core';
+import { contentToText, lastUserText } from "./xai-stub.js";
+const RESPOND_KEYS = new Set(['text', 'toolCalls', 'finishReason']);
+const FINISH_REASONS = new Set(['stop', 'length', 'tool_calls', 'content_filter']);
+const nonEmptyString = (cond) => typeof cond === 'string' && cond.length > 0;
+/** The function NAMES a tool-role last message answers: resolve its tool_call_id against the
+ *  tool_calls of earlier assistant turns. */
+function lastToolResultNames(messages) {
+    const names = new Set();
+    const last = messages[messages.length - 1];
+    if (!last || last.role !== 'tool')
+        return names;
+    const idToName = new Map();
+    for (const m of messages) {
+        if (m.role !== 'assistant')
+            continue;
+        for (const tc of m.tool_calls ?? [])
+            idToName.set(tc.id, tc.function.name);
+    }
+    if (typeof last.tool_call_id === 'string') {
+        const name = idToName.get(last.tool_call_id);
+        if (name)
+            names.add(name);
+    }
+    return names;
+}
+function toolNames(tools) {
+    if (!Array.isArray(tools))
+        return [];
+    return tools.map((t) => typeof t?.function?.name === 'string' ? t.function.name : typeof t?.name === 'string' ? t.name : null).filter((n) => n !== null);
+}
+export const xaiScenarioAdapter = {
+    vendor: 'xai',
+    features: (req) => ({
+        model: req.model,
+        lastUserText: lastUserText(req.messages).slice(0, 300),
+        tools: toolNames(req.tools),
+        lastMessageIsToolResult: req.messages[req.messages.length - 1]?.role === 'tool',
+        toolResultFor: [...lastToolResultNames(req.messages)],
+    }),
+    matchers: {
+        modelEquals: (req, cond) => nonEmptyString(cond) && req.model === cond,
+        userTextIncludes: (req, cond) => nonEmptyString(cond) && lastUserText(req.messages).toLowerCase().includes(cond.toLowerCase()),
+        anyTextIncludes: (req, cond) => nonEmptyString(cond) && req.messages.map((m) => contentToText(m.content)).join('\n').toLowerCase().includes(cond.toLowerCase()),
+        lastMessageIsToolResult: (req, cond) => typeof cond === 'boolean' && (req.messages[req.messages.length - 1]?.role === 'tool') === cond,
+        toolResultFor: (req, cond) => nonEmptyString(cond) && lastToolResultNames(req.messages).has(cond),
+        hasTool: (req, cond) => nonEmptyString(cond) && toolNames(req.tools).includes(cond),
+    },
+    text: (req) => req.messages.map((m) => contentToText(m.content)).join('\n'),
+    validateOn: (on) => {
+        for (const k of ['modelEquals', 'userTextIncludes', 'anyTextIncludes', 'toolResultFor', 'hasTool'])
+            if (on[k] !== undefined && (typeof on[k] !== 'string' || !on[k]))
+                return `on.${k} is a non-empty string`;
+        for (const k of ['lastMessageIsToolResult'])
+            if (on[k] !== undefined && typeof on[k] !== 'boolean')
+                return `on.${k} is a boolean`;
+        return null;
+    },
+    validateRespond: (respond) => {
+        if (typeof respond !== 'object' || respond === null || Array.isArray(respond))
+            return 'respond is an object { text?, toolCalls?, finishReason? }';
+        const r = respond;
+        for (const k of Object.keys(r))
+            if (!RESPOND_KEYS.has(k))
+                return `respond: unknown key "${k}" (valid: ${[...RESPOND_KEYS].join(', ')})`;
+        if (r.text !== undefined && typeof r.text !== 'string')
+            return 'respond.text is a string';
+        if (r.finishReason !== undefined && (typeof r.finishReason !== 'string' || !FINISH_REASONS.has(r.finishReason)))
+            return `respond.finishReason is one of ${[...FINISH_REASONS].join(', ')}`;
+        if (r.toolCalls !== undefined) {
+            for (const tc of Array.isArray(r.toolCalls) ? r.toolCalls : [r.toolCalls]) {
+                const t = tc;
+                if (!t || typeof t !== 'object' || Array.isArray(t))
+                    return 'respond.toolCalls entries are objects';
+                if (typeof t.name !== 'string' || !t.name)
+                    return 'respond.toolCalls[].name is a non-empty string';
+                if (!t.arguments || typeof t.arguments !== 'object' || Array.isArray(t.arguments))
+                    return 'respond.toolCalls[].arguments is an object';
+                if (t.id !== undefined && typeof t.id !== 'string')
+                    return 'respond.toolCalls[].id is a string';
+            }
+        }
+        if (r.text === undefined && r.toolCalls === undefined)
+            return 'respond needs text or toolCalls';
+        return null;
+    },
+};
+export function loadXaiScenarioDocument(path) {
+    let parsed;
+    try {
+        // Read through the ACTIVE WorldStore, never the filesystem directly (runtime contract
+        // R12b): the handlers document is WORLD STATE, so a MemoryWorldStore / DO-backed world
+        // serves ITS OWN scenario instead of whatever happens to sit on the host disk — and the
+        // serve path stays workerd-clean. A missing document keeps the historical ENOENT wording,
+        // so the loud load-time failure reads byte-identically to the read it replaces.
+        const raw = getActiveWorldStore().read(path);
+        if (raw === null)
+            throw new Error(`ENOENT: no such file or directory, open '${path}'`);
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new ScenarioError(`xai scenario: cannot read/parse ${path}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    return parseScenarioDocument(parsed, xaiScenarioAdapter);
+}
+export function createXaiScenarioEngine(document) {
+    return new ScenarioEngine(xaiScenarioAdapter, document);
+}
+// Scripted tool_call ids are unique per run and deterministic for a given request sequence.
+/** A scripted tool call's id, DERIVED from the call itself — never a process counter, so two identical
+ *  worlds answer the same request with the same ids (protocol 2, R9). */
+function scriptedCallId(name, args, seq) {
+    let h = 0x811c9dc5;
+    const seed = `${name}|${JSON.stringify(args)}|${seq}`;
+    for (let i = 0; i < seed.length; i += 1) {
+        h ^= seed.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return `call_scripted_${h.toString(16).padStart(8, '0')}`;
+}
+/** Realize a fired handler's respond into the envelope builder's scripted-turn shape. */
+export function realizeXaiRespond(respond) {
+    const toolCalls = [];
+    let seq = 0; // this response's own ordinal, not the process's
+    for (const tc of respond.toolCalls ? (Array.isArray(respond.toolCalls) ? respond.toolCalls : [respond.toolCalls]) : []) {
+        seq += 1;
+        toolCalls.push({ id: tc.id ?? scriptedCallId(tc.name, tc.arguments, seq), type: 'function', function: { name: tc.name, arguments: JSON.stringify(tc.arguments) } });
+    }
+    return {
+        text: respond.text ?? (toolCalls.length ? null : ''),
+        toolCalls,
+        finishReason: respond.finishReason ?? (toolCalls.length ? 'tool_calls' : 'stop'),
+    };
+}

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

@@ -0,0 +1,36 @@
+/** Options every xAI-twin HTTP surface needs, independent of who owns the socket. */
+export interface XaiTwinFetchOptions {
+    root?: string;
+    readOnly?: boolean;
+    scenarioPath?: string;
+}
+/**
+ * The pack's whole HTTP surface as a plain `fetch` — Request in, Response out, no listener.
+ *
+ * This is the composable form (runtime contract R12b): a Worker / Durable Object entry has NO
+ * loopback ports, so it must mount a pack's handler IN-PROCESS. `createXaiTwinServer` is
+ * nothing but `Bun.serve` wrapped around this closure, so the standalone (R1) and hosted
+ * surfaces are the SAME code — there is no second HTTP adaptation to drift. openai is the
+ * reference for this shape; xai is its generative sibling.
+ *
+ * WHAT IT SERVES IS UNCHANGED (R9): xai is a GENERATIVE pack, so chat completions answer a
+ * labeled deterministic stub or a scripted scenario — never a model. The only wall-clock-shaped
+ * call on this path is `worldNow()`, the world's frozen instant, and GET /twin is built from
+ * constants plus the scenario engine's own counters, so replaying it on identical state is
+ * byte-identical.
+ *
+ * NOTHING ON THIS PATH TOUCHES A FILESYSTEM. The scenario document is read through the ACTIVE
+ * WORLD STORE (xai-scenario.ts), once, when the factory is called; the device-authorization
+ * stylesheet, script and favicon are all served from committed constants
+ * (xai-device-auth-ui.ts), so the OAuth protocol UI is workerd-servable too.
+ */
+export declare function createXaiTwinFetch(options?: XaiTwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createXaiTwinServer(options: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+    scenarioPath?: string;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;