@volter/twin-xai 0.1.0

package/dist/src/xai-twin.js

@@ -0,0 +1,883 @@
+// xAI (Grok) twin REQUEST HANDLER — the canonical xAI API surface for the twin.
+// Contract: handleXaiTwinRequest({method, path, body}) -> {status, body}. It is the faithful
+// xAI API the real `@ai-sdk/xai` provider / any OpenAI-compatible client (pointed at this
+// baseURL) talks to UNMODIFIED.
+//
+// THE HONEST DESIGN: the twin cannot run Grok, so POST /v1/chat/completions, /v1/completions,
+// and /v1/messages return a DETERMINISTIC STUB completion (xai-stub.ts) clearly labeled a twin
+// stub — it NEVER pretends to be real model output. Live Search returns deterministic labeled
+// citations (never real retrieval). But the ENTIRE PROTOCOL ENVELOPE is vendor-faithful:
+// response shapes, streaming SSE chunks, tool_calls, finish_reason, reasoning_content /
+// reasoning-token accounting, deterministic usage, and xAI's flat {code, error} error
+// envelope. The genuinely stateful + static surface is real, not stubbed:
+//   • GET /v1/models (+ /:id)                        — static catalog + connector-observed models
+//   • GET /v1/language-models (+ /:id)               — xAI-native rich catalog
+//   • GET /v1/image-generation-models (+ /:id)       — image-model catalog
+//   • deferred completions                           — stateful (kernel action log): create →
+//     202-pending poll → 200 result, consumed exactly once
+//   • GET /v1/api-key                                — deterministic key introspection
+//   • POST /v1/tokenize-text                         — deterministic pseudo-tokenizer
+//
+// State lives in the kernel action log (D1): deferred completions are local actions projected
+// on read. No real xAI is ever called from this path (D4). Streaming uses an INJECTED sink —
+// no real sockets / setTimeout (D5 verify is offline + deterministic).
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { canonicalModelId, findImageGenerationModel, findLanguageModel, findModel, modelBehavior, XAI_IMAGE_GENERATION_MODELS, XAI_LANGUAGE_MODELS, XAI_MODELS, } from "./xai-models.js";
+import { realizeXaiRespond } from "./xai-scenario.js";
+import { decideXaiTwinDeviceAuthorization, exchangeXaiTwinToken, isCurrentXaiTwinAccessToken, recordXaiTwinUsage, startXaiTwinDeviceAuthorization, } from "./xai-oauth.js";
+import { countPromptTokenDetails, estimateTokens, fnv1a, lastUserText, pseudoTokenize, stubAssistantText, stubCitations, stubJsonObject, stubReasoningText, stubToolArguments, stubToolCall, uuidFromSeed, } from "./xai-stub.js";
+const SERVICE = 'xai';
+// ── vendor-shaped errors: xAI's gRPC-transcoded FLAT {code, error} envelope ──────────────
+function errBody(code, error) {
+    return { code, error };
+}
+function invalidArgument(message) {
+    return { status: 400, body: errBody('Client specified an invalid argument', message) };
+}
+function notFoundEntity(message) {
+    return { status: 404, body: errBody('Some requested entity was not found', message) };
+}
+function modelNotFound(model) {
+    return notFoundEntity(`The model ${model} does not exist or your team has no access to it. Consult https://docs.x.ai for available models.`);
+}
+function authError(message) {
+    // gRPC transcode of 401 is UNAUTHENTICATED — its canonical description, matching the
+    // convention every other status here follows (INVALID_ARGUMENT / NOT_FOUND /
+    // PERMISSION_DENIED / RESOURCE_EXHAUSTED). §9 caught the 401 wrongly reusing the 400's code.
+    return { status: 401, body: errBody('The request does not have valid authentication credentials for the operation', message) };
+}
+function blockedError(message) {
+    return { status: 403, body: errBody('The caller does not have permission', message) };
+}
+// ── modeled authentication (401/403) ────────────────────────────────────────────────────
+// Real xAI requires a bearer credential on every request: missing/invalid → 401, a blocked
+// key → 403. The twin can't validate against real keys, so it models the CHECKABLE failures:
+// a missing credential, the reserved sentinel 'xai-invalid' (invalid-key path), and the
+// reserved sentinel 'xai-blocked' (blocked-key path — still allowed to introspect itself via
+// GET /v1/api-key, which is exactly what that endpoint is for). Any other non-empty key is
+// accepted. Trusted in-process calls (verify/connector) carry NEITHER `headers` nor `apiKey`
+// and are NOT auth-gated; the real SDK always sends a key → passes.
+function presentedKey(req) {
+    const auth = req.headers?.['authorization'];
+    const bearer = typeof auth === 'string' && auth.toLowerCase().startsWith('bearer ') ? auth.slice(7).trim() : '';
+    return (req.apiKey ?? '').trim() || bearer;
+}
+function checkAuth(req, path) {
+    const key = presentedKey(req);
+    if (!key)
+        return authError('No API key provided. You can obtain an API key from https://console.x.ai.');
+    const tokenAuth = req.headers?.['x-xai-token-auth'];
+    const cliTransport = tokenAuth !== undefined || req.headers?.['x-grok-model-override'] !== undefined;
+    if (cliTransport && tokenAuth !== 'xai-grok-cli') {
+        return authError('The Grok CLI token-auth marker is invalid.');
+    }
+    if (cliTransport && req.requireTwinOauth && !isCurrentXaiTwinAccessToken(key, req.root, req.occurredAt)) {
+        return authError('The Grok CLI credential was not issued by this sealed xAI Twin world.');
+    }
+    if (key === 'xai-invalid')
+        return authError('Incorrect API key provided. You can obtain an API key from https://console.x.ai.');
+    if (key === 'xai-blocked' && path !== '/v1/api-key') {
+        return blockedError('Your API key is blocked. Consult your team administrator or the xAI console at https://console.x.ai.');
+    }
+    return null;
+}
+// ── modeled rate limiting (429) ─────────────────────────────────────────────────────────
+// Rate limits are non-deterministic in production, so the twin exposes a DETERMINISTIC opt-in
+// trigger: a request carrying `x-twin-force-rate-limit: 1` (or `true`) returns the faithful
+// 429 envelope + retry-after. (No real timing/quotas — this is the checkable plumbing.)
+function rateLimitError() {
+    return {
+        status: 429,
+        body: errBody('Resource has been exhausted', 'You have exceeded your team\'s rate limit for this model. Slow down your request rate or retry after the indicated delay.'),
+        headers: { 'retry-after': '1' },
+    };
+}
+function rateLimitTriggered(req) {
+    const v = req.headers?.['x-twin-force-rate-limit'];
+    return v === '1' || v === 'true';
+}
+function nowEpoch(occurredAt) {
+    return Math.floor((occurredAt ? Date.parse(occurredAt) : 0) / 1000);
+}
+function nowIso(occurredAt) {
+    return occurredAt ? new Date(Date.parse(occurredAt)).toISOString() : '1970-01-01T00:00:00.000Z';
+}
+// ── kernel helpers ──────────────────────────────────────────────────────────────────────
+function rows(type, root) {
+    return projectResources(SERVICE, root).filter((r) => r.type === type);
+}
+function getRow(type, id, root) {
+    return rows(type, root).find((r) => r.id === id);
+}
+// ── request parsing ─────────────────────────────────────────────────────────────────────
+function parseJson(body) {
+    if (!body || !body.trim())
+        return {};
+    try {
+        const v = JSON.parse(body);
+        return v && typeof v === 'object' ? v : {};
+    }
+    catch {
+        return {};
+    }
+}
+function parseForm(body) {
+    return new URLSearchParams(body ?? '');
+}
+const SYSTEM_FINGERPRINT = 'fp_twin_stub';
+// ── Live Search parameters (xAI delta) ──────────────────────────────────────────────────
+const SEARCH_MODES = new Set(['auto', 'on', 'off']);
+const SEARCH_SOURCE_TYPES = new Set(['web', 'x', 'news', 'rss']);
+function validateSearchParameters(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { error: invalidArgument('search_parameters must be an object') };
+    }
+    const sp = raw;
+    let mode = 'auto';
+    if (sp.mode !== undefined) {
+        if (typeof sp.mode !== 'string' || !SEARCH_MODES.has(sp.mode)) {
+            return { error: invalidArgument(`search_parameters.mode must be one of "auto", "on", "off"`) };
+        }
+        mode = sp.mode;
+    }
+    const sourceTypes = [];
+    if (sp.sources !== undefined) {
+        if (!Array.isArray(sp.sources))
+            return { error: invalidArgument('search_parameters.sources must be an array') };
+        for (const s of sp.sources) {
+            const t = s?.type;
+            if (typeof t !== 'string' || !SEARCH_SOURCE_TYPES.has(t)) {
+                return { error: invalidArgument(`search_parameters.sources[].type must be one of "web", "x", "news", "rss"`) };
+            }
+            sourceTypes.push(t);
+        }
+    }
+    const returnCitations = sp.return_citations !== false; // vendor default: true
+    return { search: { mode, sourceTypes, returnCitations } };
+}
+function validateChat(params) {
+    if (params.model === undefined || params.model === '')
+        return { error: invalidArgument('the model field is required') };
+    if (typeof params.model !== 'string')
+        return { error: invalidArgument('the model field must be a string') };
+    const behavior = modelBehavior(params.model);
+    if (!behavior) {
+        // an image-generation model cannot chat; anything else is an unknown entity (vendor 404).
+        if (findImageGenerationModel(params.model))
+            return { error: invalidArgument(`The model ${params.model} is an image generation model and does not support chat`) };
+        return { error: modelNotFound(params.model) };
+    }
+    const model = canonicalModelId(params.model);
+    if (!Array.isArray(params.messages))
+        return { error: invalidArgument('the messages field is required') };
+    if (params.messages.length === 0)
+        return { error: invalidArgument('the messages field must not be empty') };
+    const messages = params.messages;
+    for (const m of messages) {
+        if (!m || typeof m !== 'object' || typeof m.role !== 'string') {
+            return { error: invalidArgument('each message must have a valid role') };
+        }
+    }
+    let n = 1;
+    if (params.n !== undefined) {
+        n = Number(params.n);
+        if (!Number.isInteger(n) || n < 1)
+            return { error: invalidArgument('n must be an integer >= 1') };
+    }
+    // max_completion_tokens is the current name; max_tokens is the compatible alias.
+    const maxRaw = params.max_completion_tokens ?? params.max_tokens;
+    let maxTokens;
+    if (maxRaw !== undefined) {
+        maxTokens = Number(maxRaw);
+        if (!Number.isInteger(maxTokens) || maxTokens < 1)
+            return { error: invalidArgument('max_tokens must be an integer >= 1') };
+    }
+    const stopRaw = params.stop;
+    let stop;
+    if (stopRaw !== undefined) {
+        if (typeof stopRaw === 'string')
+            stop = [stopRaw];
+        else if (Array.isArray(stopRaw))
+            stop = stopRaw;
+        else
+            return { error: invalidArgument('stop must be a string or array of strings') };
+    }
+    // tool_choice: 'auto' | 'none' | 'required' | { type:'function', function:{ name } }.
+    let toolChoice;
+    const tcRaw = params.tool_choice;
+    if (tcRaw !== undefined) {
+        if (tcRaw === 'auto' || tcRaw === 'none' || tcRaw === 'required')
+            toolChoice = tcRaw;
+        else if (tcRaw && typeof tcRaw === 'object') {
+            const fn = tcRaw.function;
+            if (typeof fn?.name === 'string')
+                toolChoice = { name: fn.name };
+            else
+                return { error: invalidArgument('invalid tool_choice — a named choice requires function.name') };
+        }
+        else
+            return { error: invalidArgument('tool_choice must be "auto", "none", "required" or a named function') };
+    }
+    // response_format: { type:'text' | 'json_object' | 'json_schema', json_schema? } (structured outputs).
+    let responseFormat = { kind: 'text' };
+    const rf = params.response_format;
+    if (rf !== undefined) {
+        if (!rf || typeof rf !== 'object')
+            return { error: invalidArgument('response_format must be an object') };
+        const t = rf.type;
+        if (t === 'json_object')
+            responseFormat = { kind: 'json_object' };
+        else if (t === 'json_schema')
+            responseFormat = { kind: 'json_schema', schema: rf.json_schema };
+        else if (t === 'text' || t === undefined)
+            responseFormat = { kind: 'text' };
+        else
+            return { error: invalidArgument('response_format.type must be "text", "json_object", or "json_schema"') };
+    }
+    // stream_options.include_usage → emit a final usage-only chunk in the stream.
+    const so = params.stream_options;
+    const includeUsage = !!(so && typeof so === 'object' && so.include_usage === true);
+    // seed → reproducible sampling (the twin is already deterministic; the seed varies the id the
+    // way a real seed-distinct request does).
+    let seed;
+    if (params.seed !== undefined) {
+        seed = Number(params.seed);
+        if (!Number.isInteger(seed))
+            return { error: invalidArgument('seed must be an integer') };
+    }
+    // reasoning_effort — the xAI rule: ONLY grok-3-mini accepts it; grok-4-family models reason
+    // internally but REJECT the parameter (a real vendor 400), as do the non-reasoning models.
+    let reasoningEffort;
+    if (params.reasoning_effort !== undefined) {
+        if (params.reasoning_effort !== 'low' && params.reasoning_effort !== 'high') {
+            return { error: invalidArgument('reasoning_effort must be "low" or "high"') };
+        }
+        if (!behavior.supportsReasoningEffort) {
+            return { error: invalidArgument(`Argument not supported: reasoning_effort is not supported by model ${model}`) };
+        }
+        reasoningEffort = params.reasoning_effort;
+    }
+    // Live Search (xAI delta).
+    let search;
+    if (params.search_parameters !== undefined) {
+        const v = validateSearchParameters(params.search_parameters);
+        if ('error' in v)
+            return v;
+        search = v.search;
+    }
+    return {
+        args: {
+            model,
+            requestedModel: params.model,
+            messages,
+            tools: params.tools,
+            n,
+            ...(maxTokens !== undefined ? { maxTokens } : {}),
+            ...(stop !== undefined ? { stop } : {}),
+            stream: params.stream === true,
+            ...(toolChoice !== undefined ? { toolChoice } : {}),
+            parallelToolCalls: params.parallel_tool_calls !== false,
+            responseFormat,
+            includeUsage,
+            ...(seed !== undefined ? { seed } : {}),
+            ...(reasoningEffort !== undefined ? { reasoningEffort } : {}),
+            ...(search !== undefined ? { search } : {}),
+            deferred: params.deferred === true,
+        },
+    };
+}
+// A deterministic id seed from the request (so ids are stable + assertable). Hash of the
+// prompt + model + seed (a distinct sampling seed changes the id like a real distinct request).
+function stableSeed(args) {
+    return `chat|${args.model}|${JSON.stringify(args.messages)}${args.seed !== undefined ? `|seed=${args.seed}` : ''}`;
+}
+// Deterministic reasoning-token budgets: grok-3-mini spends per requested effort; the
+// grok-4-family reasoning models spend a fixed internal budget (content never exposed).
+const REASONING_BUDGET = { low: 16, high: 64 };
+const INTERNAL_REASONING_TOKENS = 32;
+function emptyUsageDetails() {
+    return {
+        prompt_tokens: 0,
+        completion_tokens: 0,
+        total_tokens: 0,
+        prompt_tokens_details: { text_tokens: 0, audio_tokens: 0, image_tokens: 0, cached_tokens: 0 },
+        completion_tokens_details: { reasoning_tokens: 0, audio_tokens: 0, accepted_prediction_tokens: 0, rejected_prediction_tokens: 0 },
+        num_sources_used: 0,
+    };
+}
+// Build ONE deterministic stub choice (index `idx`). Honors tools (tool_calls +
+// finish_reason:'tool_calls'), tool_choice (none/required/named), parallel_tool_calls,
+// response_format (structured outputs), max_tokens, stop sequences, and reasoning_content
+// (grok-3-mini). A scripted scenario result (chat call only) overrides the generic stub.
+function buildChoice(args, idx, scripted) {
+    const behavior = modelBehavior(args.model);
+    const reasoningTokens = behavior.supportsReasoningEffort
+        ? (REASONING_BUDGET[args.reasoningEffort ?? 'low'] ?? 16)
+        : behavior.isReasoningModel ? INTERNAL_REASONING_TOKENS : 0;
+    // grok-3-mini exposes its (stubbed) reasoning trace; grok-4-family never does.
+    const reasoningContent = behavior.supportsReasoningEffort
+        ? stubReasoningText(args.messages, args.model, args.reasoningEffort ?? 'low')
+        : undefined;
+    if (scripted) {
+        if (scripted.toolCalls.length) {
+            return {
+                choice: {
+                    index: idx,
+                    message: { role: 'assistant', content: scripted.text, ...(reasoningContent !== undefined ? { reasoning_content: reasoningContent } : {}), tool_calls: scripted.toolCalls, refusal: null },
+                    logprobs: null,
+                    finish_reason: scripted.finishReason,
+                },
+                completionTokens: estimateTokens(JSON.stringify(scripted.toolCalls) + (scripted.text ?? '')),
+                reasoningTokens,
+            };
+        }
+        const text = scripted.text ?? '';
+        return {
+            choice: { index: idx, message: { role: 'assistant', content: text, ...(reasoningContent !== undefined ? { reasoning_content: reasoningContent } : {}), refusal: null }, logprobs: null, finish_reason: scripted.finishReason },
+            completionTokens: estimateTokens(text),
+            reasoningTokens,
+        };
+    }
+    const toolsSource = args.tools;
+    const hasTools = Array.isArray(toolsSource) && toolsSource.length > 0;
+    // tool_choice gates whether the stub calls a tool: 'none' forbids it; a named/required choice
+    // forces it; 'auto'/default calls when tools exist.
+    const forbidTools = args.toolChoice === 'none';
+    const forcedName = typeof args.toolChoice === 'object' ? args.toolChoice.name : undefined;
+    if (hasTools && !forbidTools) {
+        const list = toolsSource;
+        const calls = [];
+        if (forcedName || args.parallelToolCalls === false) {
+            const tc = stubToolCall(toolsSource, idx + 1, forcedName);
+            if (tc)
+                calls.push(tc);
+        }
+        else {
+            for (let t = 0; t < list.length; t++) {
+                const tc = stubToolCall([list[t]], idx * 100 + t + 1);
+                if (tc)
+                    calls.push(tc);
+            }
+        }
+        if (calls.length) {
+            return {
+                choice: {
+                    index: idx,
+                    message: { role: 'assistant', content: null, ...(reasoningContent !== undefined ? { reasoning_content: reasoningContent } : {}), tool_calls: calls, refusal: null },
+                    logprobs: null,
+                    finish_reason: 'tool_calls',
+                },
+                completionTokens: estimateTokens(JSON.stringify(calls)),
+                reasoningTokens,
+            };
+        }
+    }
+    // structured outputs: when response_format requests json_object/json_schema, the content is
+    // valid JSON (json_schema fills every declared property).
+    let text = args.responseFormat.kind === 'json_object'
+        ? stubJsonObject(args.messages, args.model)
+        : args.responseFormat.kind === 'json_schema'
+            ? stubJsonObject(args.messages, args.model, args.responseFormat.schema)
+            : stubAssistantText(args.messages, args.model);
+    let finish = 'stop';
+    // Truncate at the EARLIEST-occurring stop sequence across the whole `stop` list.
+    let stopAt = -1;
+    for (const s of args.stop ?? []) {
+        if (!s)
+            continue;
+        const i = text.indexOf(s);
+        if (i >= 0 && (stopAt < 0 || i < stopAt))
+            stopAt = i;
+    }
+    if (stopAt >= 0)
+        text = text.slice(0, stopAt);
+    if (args.maxTokens !== undefined && estimateTokens(text) > args.maxTokens) {
+        text = text.slice(0, args.maxTokens * 4);
+        finish = 'length';
+    }
+    return {
+        choice: { index: idx, message: { role: 'assistant', content: text, ...(reasoningContent !== undefined ? { reasoning_content: reasoningContent } : {}), refusal: null }, logprobs: null, finish_reason: finish },
+        completionTokens: estimateTokens(text),
+        reasoningTokens,
+    };
+}
+export function buildChatCompletion(args, occurredAt, scenarioEngine) {
+    // Scenario handlers: chat-completions calls only; a fired handler scripts the assistant
+    // turn (the envelope below stays vendor-faithful either way); a miss teaches in the stub.
+    let missTeach = '';
+    const scripted = scenarioEngine
+        ? (() => {
+            const decision = scenarioEngine.next({ model: args.requestedModel, messages: args.messages, tools: args.tools });
+            if (decision.kind === 'handler')
+                return realizeXaiRespond(decision.respond);
+            missTeach = `\n[twin-scenario miss — no handler matched. Author one in the world dir's handlers/xai.json (GET /twin explains; GET /twin/scenario lists handlers + misses). Features seen: ${JSON.stringify(decision.miss.features)}]`;
+            return null;
+        })()
+        : null;
+    const promptDetails = countPromptTokenDetails(args.messages);
+    const promptTokens = promptDetails.text + promptDetails.image;
+    const choices = [];
+    let completionTokens = 0;
+    let reasoningTokens = 0;
+    for (let i = 0; i < args.n; i++) {
+        const { choice, completionTokens: ct, reasoningTokens: rt } = buildChoice(args, i, scripted);
+        choices.push(choice);
+        completionTokens += ct;
+        reasoningTokens += rt;
+    }
+    if (missTeach) {
+        const first = choices[0];
+        if (first?.message && typeof first.message.content === 'string')
+            first.message.content += missTeach;
+    }
+    // Live Search: mode 'off' disables; 'on'/'auto' consult the (stubbed, labeled) sources. The
+    // twin treats 'auto' as searching so the behavior is deterministic — documented in README.
+    const searching = args.search !== undefined && args.search.mode !== 'off';
+    const citations = searching ? stubCitations(lastUserText(args.messages), args.search.sourceTypes) : [];
+    const usage = {
+        prompt_tokens: promptTokens,
+        completion_tokens: completionTokens + reasoningTokens,
+        total_tokens: promptTokens + completionTokens + reasoningTokens,
+        prompt_tokens_details: { text_tokens: promptDetails.text, audio_tokens: 0, image_tokens: promptDetails.image, cached_tokens: 0 },
+        completion_tokens_details: { reasoning_tokens: reasoningTokens, audio_tokens: 0, accepted_prediction_tokens: 0, rejected_prediction_tokens: 0 },
+        num_sources_used: citations.length,
+    };
+    return {
+        id: uuidFromSeed(stableSeed(args)),
+        object: 'chat.completion',
+        created: nowEpoch(occurredAt),
+        model: args.model,
+        choices,
+        usage,
+        system_fingerprint: SYSTEM_FINGERPRINT,
+        ...(searching && args.search.returnCitations ? { citations } : {}),
+    };
+}
+// Split text into deterministic streaming chunks (≤ ~20 chars each), preserving order.
+function chunkText(text) {
+    if (!text)
+        return [];
+    const out = [];
+    for (let i = 0; i < text.length; i += 20)
+        out.push(text.slice(i, i + 20));
+    return out;
+}
+/**
+ * Emit the vendor-faithful chat streaming sequence into the injected sink (NO sockets, NO
+ * setTimeout). Real order: a first chunk with `delta:{role:'assistant'}`, then
+ * `delta:{content}` chunks (or tool_calls deltas), then a final chunk with `finish_reason`,
+ * then a usage-only chunk when stream_options.include_usage, then `[DONE]`. Deterministic +
+ * synchronous so a collector can assert the full sequence.
+ */
+export function streamChat(args, sink, occurredAt, scenarioEngine) {
+    const full = buildChatCompletion(args, occurredAt, scenarioEngine);
+    const base = { id: full.id, object: 'chat.completion.chunk', created: full.created, model: full.model, system_fingerprint: SYSTEM_FINGERPRINT };
+    for (const choice of full.choices) {
+        const idx = choice.index;
+        sink({ data: { ...base, choices: [{ index: idx, delta: { role: 'assistant', content: '' }, logprobs: null, finish_reason: null }] } });
+        if (choice.message.tool_calls && choice.message.tool_calls.length) {
+            // xAI DELTA vs OpenAI: each streamed tool call arrives as ONE COMPLETE delta (id, type,
+            // function.name AND the full arguments in a single chunk) — xAI does not split a call's
+            // arguments across deltas. The real @ai-sdk/xai chunk schema REQUIRES every tool_calls
+            // delta to carry all of these fields, so an OpenAI-style split-delta stream fails its
+            // validation (observed against @ai-sdk/xai 2.0.x).
+            choice.message.tool_calls.forEach((tc, tIdx) => {
+                sink({ data: { ...base, choices: [{ index: idx, delta: { tool_calls: [{ index: tIdx, id: tc.id, type: 'function', function: { name: tc.function.name, arguments: tc.function.arguments } }] }, logprobs: null, finish_reason: null }] } });
+            });
+        }
+        else {
+            for (const piece of chunkText(choice.message.content ?? '')) {
+                sink({ data: { ...base, choices: [{ index: idx, delta: { content: piece }, logprobs: null, finish_reason: null }] } });
+            }
+        }
+        sink({ data: { ...base, choices: [{ index: idx, delta: {}, logprobs: null, finish_reason: choice.finish_reason }], ...(full.citations ? { citations: full.citations } : {}) } });
+    }
+    if (args.includeUsage) {
+        sink({ data: { ...base, choices: [], usage: full.usage } });
+    }
+    sink({ done: true });
+    return full;
+}
+// ── deferred completions (xAI delta: deferred:true → request_id → poll → result, once) ────
+// The vendor runs the inference asynchronously: POST returns { request_id }, and
+// GET /v1/chat/deferred-completion/{request_id} returns 202 while pending and 200 with the
+// chat completion when done — and the result can be RETRIEVED ONLY ONCE. The twin has nothing
+// to run in the background, so it persists the request (kernel action log) and models the
+// lifecycle deterministically: the FIRST poll is the pending 202, the SECOND poll serves the
+// completed result and consumes it, and any later poll (or an unknown id) is the vendor 404.
+async function createDeferredCompletion(args, req) {
+    const seq = rows('deferred_completion', req.root).length + 1;
+    const requestId = uuidFromSeed(`deferred|${seq}|${stableSeed(args)}`);
+    await applyTwinWrite(SERVICE, {
+        operation: 'deferred_completion.create',
+        subjectType: 'deferred_completion',
+        subjectId: requestId,
+        fields: { object: 'deferred_completion', status: 'pending', polls: 0, consumed: false, created_at: nowEpoch(req.occurredAt), _args: JSON.stringify(args) },
+        ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}),
+        actor: { kind: 'agent' },
+    }, req.root);
+    return { status: 200, body: { request_id: requestId } };
+}
+async function retrieveDeferredCompletion(requestId, req) {
+    const row = getRow('deferred_completion', requestId, req.root);
+    if (!row || row.consumed === true) {
+        return notFoundEntity(`The deferred completion ${requestId} does not exist, has expired, or has already been retrieved.`);
+    }
+    if (Number(row.polls ?? 0) === 0) {
+        // first poll → still pending (202, empty body), like the vendor mid-inference.
+        if (!req.readOnly) {
+            await applyTwinWrite(SERVICE, {
+                operation: 'deferred_completion.poll',
+                subjectType: 'deferred_completion',
+                subjectId: requestId,
+                fields: { polls: 1 },
+                ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}),
+                actor: { kind: 'agent' },
+            }, req.root);
+        }
+        return { status: 202, body: {} };
+    }
+    const args = JSON.parse(String(row._args ?? '{}'));
+    const completion = buildChatCompletion(args, req.occurredAt);
+    // A READ-ONLY twin must never mutate the kernel log — serving the result is a read; the
+    // consume is a WRITE, so it is skipped (the lifecycle simply cannot advance in a read-only
+    // mirror, and repeated read-only polls keep serving the still-unconsumed result). §9 found
+    // this consume unguarded — a read-only GET was consuming the row.
+    if (!req.readOnly) {
+        await applyTwinWrite(SERVICE, {
+            operation: 'deferred_completion.consume',
+            subjectType: 'deferred_completion',
+            subjectId: requestId,
+            fields: { status: 'done', consumed: true },
+            ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}),
+            actor: { kind: 'agent' },
+        }, req.root);
+    }
+    return { status: 200, body: completion };
+}
+// ── legacy completions (POST /v1/completions) ───────────────────────────────────────────
+function handleLegacyCompletions(params, occurredAt) {
+    if (params.model === undefined || params.model === '')
+        return invalidArgument('the model field is required');
+    if (typeof params.model !== 'string')
+        return invalidArgument('the model field must be a string');
+    if (!modelBehavior(params.model))
+        return modelNotFound(params.model);
+    const model = canonicalModelId(params.model);
+    if (params.prompt === undefined)
+        return invalidArgument('the prompt field is required');
+    const prompt = typeof params.prompt === 'string'
+        ? params.prompt
+        : Array.isArray(params.prompt) ? params.prompt.map(String).join('\n') : '';
+    const messages = [{ role: 'user', content: prompt }];
+    let text = stubAssistantText(messages, model);
+    let finish = 'stop';
+    const maxRaw = params.max_tokens;
+    if (maxRaw !== undefined) {
+        const maxTokens = Number(maxRaw);
+        if (!Number.isInteger(maxTokens) || maxTokens < 1)
+            return invalidArgument('max_tokens must be an integer >= 1');
+        if (estimateTokens(text) > maxTokens) {
+            text = text.slice(0, maxTokens * 4);
+            finish = 'length';
+        }
+    }
+    const promptTokens = estimateTokens(prompt);
+    const completionTokens = estimateTokens(text);
+    const usage = emptyUsageDetails();
+    usage.prompt_tokens = promptTokens;
+    usage.prompt_tokens_details.text_tokens = promptTokens;
+    usage.completion_tokens = completionTokens;
+    usage.total_tokens = promptTokens + completionTokens;
+    const out = {
+        id: uuidFromSeed(`cmpl|${model}|${prompt}`),
+        object: 'text_completion',
+        created: nowEpoch(occurredAt),
+        model,
+        choices: [{ text, index: 0, logprobs: null, finish_reason: finish }],
+        usage,
+        system_fingerprint: SYSTEM_FINGERPRINT,
+    };
+    return { status: 200, body: out };
+}
+// ── Anthropic-compatible Messages (POST /v1/messages) ───────────────────────────────────
+// xAI serves an Anthropic-style Messages endpoint so Anthropic-shaped clients can drive Grok.
+// The twin models the request rules (model / messages / REQUIRED max_tokens) and the response
+// envelope (content blocks, stop_reason, usage) faithfully; the text is the labeled stub and
+// Anthropic-style tools yield a faithful tool_use block.
+function handleMessagesCompat(params, occurredAt) {
+    if (params.model === undefined || params.model === '')
+        return invalidArgument('the model field is required');
+    if (typeof params.model !== 'string')
+        return invalidArgument('the model field must be a string');
+    if (!modelBehavior(params.model))
+        return modelNotFound(params.model);
+    const model = canonicalModelId(params.model);
+    if (!Array.isArray(params.messages) || params.messages.length === 0)
+        return invalidArgument('the messages field is required and must not be empty');
+    const maxTokens = Number(params.max_tokens);
+    if (params.max_tokens === undefined || !Number.isInteger(maxTokens) || maxTokens < 1) {
+        return invalidArgument('the max_tokens field is required and must be a positive integer');
+    }
+    const messages = params.messages;
+    const system = typeof params.system === 'string' ? params.system : '';
+    const inputTokens = estimateTokens(system) + countPromptTokenDetails(messages).text + countPromptTokenDetails(messages).image;
+    const content = [];
+    let stopReason = 'end_turn';
+    const tools = Array.isArray(params.tools) ? params.tools : [];
+    if (tools.length > 0) {
+        const first = tools[0];
+        const name = typeof first.name === 'string' ? first.name : 'unknown_tool';
+        // Anthropic tools carry `input_schema` (not `function.parameters`); stubToolArguments
+        // understands both, so tool_use.input validates against the declared schema.
+        let input = {};
+        try {
+            input = JSON.parse(stubToolArguments(first));
+        }
+        catch {
+            input = {};
+        }
+        content.push({ type: 'tool_use', id: `toolu_twin_${fnv1a(name).toString(36)}`, name, input });
+        stopReason = 'tool_use';
+    }
+    else {
+        let text = stubAssistantText(messages, model);
+        if (estimateTokens(text) > maxTokens) {
+            text = text.slice(0, maxTokens * 4);
+            stopReason = 'max_tokens';
+        }
+        content.push({ type: 'text', text });
+    }
+    const outputTokens = estimateTokens(JSON.stringify(content));
+    const out = {
+        id: `msg_twin_${fnv1a(`${model}|${JSON.stringify(messages)}`).toString(36)}`,
+        type: 'message',
+        role: 'assistant',
+        model,
+        content,
+        stop_reason: stopReason,
+        stop_sequence: null,
+        usage: { input_tokens: inputTokens, output_tokens: outputTokens },
+    };
+    return { status: 200, body: out };
+}
+// ── image generations (POST /v1/images/generations) ─────────────────────────────────────
+// xAI's image endpoint is OpenAI-shaped but REJECTS OpenAI's size/quality/style parameters
+// (a real vendor 400 — a faithful compatibility delta). The response shape (data[].url |
+// b64_json + revised_prompt) is faithful with clearly-labeled stub values.
+function handleImageGenerations(params, occurredAt) {
+    for (const unsupported of ['size', 'quality', 'style']) {
+        if (params[unsupported] !== undefined)
+            return invalidArgument(`Argument not supported: ${unsupported}`);
+    }
+    if (params.prompt === undefined || params.prompt === '')
+        return invalidArgument('the prompt field is required');
+    const modelRaw = typeof params.model === 'string' && params.model ? params.model : 'grok-2-image-1212';
+    const imageModel = findImageGenerationModel(modelRaw);
+    if (!imageModel) {
+        if (modelBehavior(modelRaw))
+            return invalidArgument(`The model ${modelRaw} is not an image generation model`);
+        return modelNotFound(modelRaw);
+    }
+    let n = 1;
+    if (params.n !== undefined) {
+        n = Number(params.n);
+        if (!Number.isInteger(n) || n < 1 || n > 10)
+            return invalidArgument('n must be an integer between 1 and 10');
+    }
+    const format = params.response_format ?? 'url';
+    if (format !== 'url' && format !== 'b64_json')
+        return invalidArgument('response_format must be "url" or "b64_json"');
+    const prompt = String(params.prompt);
+    const data = Array.from({ length: n }, (_, i) => {
+        const seed = fnv1a(`${prompt}|${i}`).toString(36);
+        const revised = `[twin-stub:${imageModel.id}] ${prompt}`;
+        if (format === 'b64_json') {
+            const marker = `[twin-stub-image] no real pixels; prompt: ${prompt} (#${i})`;
+            return { b64_json: Buffer.from(marker, 'utf8').toString('base64'), revised_prompt: revised };
+        }
+        return { url: `https://twin.invalid/xai-image-stub/${seed}-${i}.png`, revised_prompt: revised };
+    });
+    return { status: 200, body: { created: nowEpoch(occurredAt), data } };
+}
+// ── api-key introspection (GET /v1/api-key) ─────────────────────────────────────────────
+// Returns metadata about the PRESENTED key (redacted value, acls, blocked/disabled flags).
+// Keys are SYNTHETIC twin values — never real xAI credentials. The reserved sentinel
+// 'xai-blocked' reports api_key_blocked:true (and every other route 403s for it).
+function handleApiKey(req) {
+    const key = presentedKey(req) || 'xai-twin-trusted';
+    const redacted = key.length > 8 ? `${key.slice(0, 4)}...${key.slice(-4)}` : `${key.slice(0, 2)}...`;
+    return {
+        status: 200,
+        body: {
+            redacted_api_key: redacted,
+            user_id: uuidFromSeed(`user|${key}`),
+            name: 'twin api key',
+            create_time: nowIso(req.occurredAt),
+            modify_time: nowIso(req.occurredAt),
+            modified_by: uuidFromSeed(`user|${key}`),
+            team_id: uuidFromSeed(`team|${key}`),
+            acls: ['api-key:model:*', 'api-key:endpoint:*'],
+            api_key_id: uuidFromSeed(`key|${key}`),
+            team_blocked: false,
+            api_key_blocked: key === 'xai-blocked',
+            api_key_disabled: false,
+        },
+    };
+}
+// ── tokenize-text (POST /v1/tokenize-text) ──────────────────────────────────────────────
+function handleTokenizeText(params) {
+    if (params.text === undefined || typeof params.text !== 'string' || params.text === '') {
+        return invalidArgument('the text field is required');
+    }
+    if (params.model === undefined || params.model === '')
+        return invalidArgument('the model field is required');
+    if (typeof params.model !== 'string' || !modelBehavior(params.model))
+        return modelNotFound(String(params.model));
+    return { status: 200, body: { token_ids: pseudoTokenize(params.text) } };
+}
+// ── models catalogs (static + connector-observed) ───────────────────────────────────────
+function observedModels(root) {
+    const catalogIds = new Set(XAI_MODELS.map((m) => m.id));
+    return rows('model', root)
+        .filter((r) => !catalogIds.has(String(r.id)))
+        .map((r) => ({ id: String(r.id), object: 'model', created: Number(r.created ?? 0), owned_by: String(r.owned_by ?? 'xai') }));
+}
+function observedLanguageModels(root) {
+    const catalogIds = new Set(XAI_LANGUAGE_MODELS.map((m) => m.id));
+    return rows('language_model', root)
+        .filter((r) => !catalogIds.has(String(r.id)))
+        .map((r) => {
+        const { type: _t, updatedAt: _u, ...rest } = r;
+        return rest;
+    });
+}
+// ── public entry: cross-cutting protocol (auth / rate-limit) then route ──────────────────
+export async function handleXaiTwinRequest(req) {
+    const method = req.method.toUpperCase();
+    const path = (req.path.split('?')[0] ?? '/').replace(/\/+$/, '') || '/';
+    // OAuth device authorization is a separate public protocol surface. Its token exchange is
+    // authenticated by one-use device/refresh credentials in the form body, not an API bearer.
+    // Keeping it in this handler means identity, refresh, CLI inference, and usage all project the
+    // same kernel state rather than behaving like disconnected fixtures.
+    if (path === '/oauth2/device/code' && method === 'POST') {
+        if (req.readOnly)
+            return { status: 405, body: { error: 'invalid_request', error_description: 'twin is read-only' } };
+        return startXaiTwinDeviceAuthorization({
+            body: parseForm(req.body),
+            occurredAt: req.occurredAt,
+            origin: req.origin ?? 'http://127.0.0.1',
+            root: req.root,
+        });
+    }
+    if (path === '/oauth2/token' && method === 'POST') {
+        if (req.readOnly)
+            return { status: 405, body: { error: 'invalid_request', error_description: 'twin is read-only' } };
+        return exchangeXaiTwinToken({ body: parseForm(req.body), occurredAt: req.occurredAt, root: req.root });
+    }
+    if (path === '/twin/oauth/authorizations' && method === 'POST') {
+        if (req.readOnly)
+            return { status: 405, body: { error: 'invalid_request', error_description: 'twin is read-only' } };
+        const control = parseJson(req.body);
+        if (typeof control.user_code !== 'string' || typeof control.approved !== 'boolean') {
+            return invalidArgument('user_code (string) and approved (boolean) are required');
+        }
+        return decideXaiTwinDeviceAuthorization({ approved: control.approved, occurredAt: req.occurredAt, root: req.root, userCode: control.user_code });
+    }
+    // Modeled authentication (401/403). Gated only when the request carries an auth surface.
+    if (req.headers !== undefined || req.apiKey !== undefined) {
+        const authErr = checkAuth(req, path);
+        if (authErr)
+            return authErr;
+    }
+    // Modeled rate limiting (429) — deterministic opt-in trigger header.
+    if (rateLimitTriggered(req))
+        return rateLimitError();
+    const seg = path.replace(/^\/+/, '').split('/'); // ["v1","chat","completions",...]
+    const params = parseJson(req.body);
+    // D3: a read-only twin rejects any mutation with a vendor-shaped error.
+    if (req.readOnly && method !== 'GET') {
+        return { status: 405, body: errBody('The operation is not allowed', 'twin is read-only; omit readOnly to accept writes') };
+    }
+    // ---- model catalogs ----
+    if (path === '/v1/models' && method === 'GET') {
+        return { status: 200, body: { object: 'list', data: [...XAI_MODELS, ...observedModels(req.root)] } };
+    }
+    if (seg[1] === 'models' && seg.length === 3 && method === 'GET') {
+        const mid = decodeURIComponent(seg[2]);
+        const m = findModel(mid) ?? observedModels(req.root).find((om) => om.id === mid);
+        return m ? { status: 200, body: m } : modelNotFound(mid);
+    }
+    if (path === '/v1/language-models' && method === 'GET') {
+        return { status: 200, body: { models: [...XAI_LANGUAGE_MODELS, ...observedLanguageModels(req.root)] } };
+    }
+    if (seg[1] === 'language-models' && seg.length === 3 && method === 'GET') {
+        const mid = decodeURIComponent(seg[2]);
+        const m = findLanguageModel(mid) ?? observedLanguageModels(req.root).find((om) => om.id === mid);
+        return m ? { status: 200, body: m } : modelNotFound(mid);
+    }
+    if (path === '/v1/image-generation-models' && method === 'GET') {
+        return { status: 200, body: { models: XAI_IMAGE_GENERATION_MODELS } };
+    }
+    if (seg[1] === 'image-generation-models' && seg.length === 3 && method === 'GET') {
+        const mid = decodeURIComponent(seg[2]);
+        const m = findImageGenerationModel(mid);
+        return m ? { status: 200, body: m } : modelNotFound(mid);
+    }
+    // ---- chat completions (the generative stub; envelope is faithful) ----
+    if (path === '/v1/chat/completions' && method === 'POST') {
+        // The official Grok CLI proxy routes by x-grok-model-override rather than
+        // trusting the JSON model field. API callers omit it and keep ordinary
+        // the ordinary inference API behavior; CLI callers get the exact deployment selection they
+        // requested, including the built-in grok-build alias.
+        const modelOverride = req.headers?.['x-grok-model-override'];
+        const chatParams = typeof modelOverride === 'string' && modelOverride.trim()
+            ? { ...params, model: modelOverride.trim() }
+            : params;
+        const validated = validateChat(chatParams);
+        if ('error' in validated)
+            return validated.error;
+        const args = validated.args;
+        // deferred:true → { request_id } now, the completion on poll (stateful kernel row).
+        if (args.deferred)
+            return createDeferredCompletion(args, req);
+        if (args.stream && req.sseSink) {
+            const completion = streamChat(args, req.sseSink, req.occurredAt, req.scenarioEngine);
+            if (isCurrentXaiTwinAccessToken(presentedKey(req), req.root, req.occurredAt)) {
+                await recordXaiTwinUsage({ completionTokens: completion.usage.completion_tokens, occurredAt: req.occurredAt, promptTokens: completion.usage.prompt_tokens, requestId: completion.id, root: req.root });
+            }
+            return { status: 200, body: completion };
+        }
+        const completion = buildChatCompletion(args, req.occurredAt, req.scenarioEngine);
+        if (isCurrentXaiTwinAccessToken(presentedKey(req), req.root, req.occurredAt)) {
+            await recordXaiTwinUsage({ completionTokens: completion.usage.completion_tokens, occurredAt: req.occurredAt, promptTokens: completion.usage.prompt_tokens, requestId: completion.id, root: req.root });
+        }
+        return { status: 200, body: completion };
+    }
+    // deferred completion retrieval (202 pending → 200 once → 404 after).
+    if (seg[1] === 'chat' && seg[2] === 'deferred-completion' && seg.length === 4 && method === 'GET') {
+        return retrieveDeferredCompletion(decodeURIComponent(seg[3]), req);
+    }
+    // ---- legacy completions ----
+    if (path === '/v1/completions' && method === 'POST') {
+        return handleLegacyCompletions(params, req.occurredAt);
+    }
+    // ---- Anthropic-compatible messages ----
+    if (path === '/v1/messages' && method === 'POST') {
+        return handleMessagesCompat(params, req.occurredAt);
+    }
+    // ---- image generations ----
+    if (path === '/v1/images/generations' && method === 'POST') {
+        return handleImageGenerations(params, req.occurredAt);
+    }
+    // ---- api-key introspection ----
+    if (path === '/v1/api-key' && method === 'GET') {
+        return handleApiKey(req);
+    }
+    // ---- tokenizer ----
+    if (path === '/v1/tokenize-text' && method === 'POST') {
+        return handleTokenizeText(params);
+    }
+    // Unknown route → vendor-faithful 404 (never a fabricated success — D2).
+    return notFoundEntity(`Unknown request URL: ${method} ${path}. Please check the URL against https://docs.x.ai.`);
+}