@volter/twin-openai 0.1.1 → 2.0.0

package/dist/src/openai-twin.js

@@ -0,0 +1,1117 @@
+// OpenAI twin: the pack's behaviour and its in-process door. `handleOpenAITwinRequest` answers one
+// request through the pack's fetch (openai-server.ts), which the derived dispatch owns: an operation
+// OpenAI's spec publishes is a semantics handler (semantics/), the derived core (manifest.ts), or
+// OpenAI's unknown-URL 404. What lives here is what those share:
+//   • the generative stubs: chat completions and responses (validation, the deterministic stub or a
+//     scripted scenario's turn, the streaming event sequences), embeddings (pseudo-vectors),
+//     moderations, images and audio (labeled placeholders); never a model's output;
+//   • the Responses API's atomic id allocation and background-poll completion;
+//   • the usage and costs reports over the recorded usage.
+// No real OpenAI is called from this path.
+import { applyTwinWriteAtomic } from '@volter/world-core';
+import { buildLogprobs, countPromptTokens, estimateTokens, lastUserText, moderateText, pseudoEmbedding, stubAssistantText, stubJsonObject, stubToolCall, } from "./openai-stub.js";
+import { DEFAULT_EFFORT, modelOf, reasons, unsupported } from "./openai-models.js";
+import { scenarioTurn, scriptedChoice } from "./openai-scenario.js";
+import { audioFormat, base64, imageFormat, partBytes, placeholderPng, pngSize, requestedSize, silentAac, silentFlac, silentMp3, silentOpus, silentPcm, silentWav, wavSeconds } from "./openai-media.js";
+import { createOpenAITwinFetch } from "./openai-server.js";
+const SERVICE = 'openai';
+// ── vendor-shaped errors ──────────────────────────────────────────────────────────────
+function errBody(type, message, code = null, param = null) {
+    return { error: { message, type, param, code } };
+}
+function invalidRequest(message, param = null, code = null) {
+    return { status: 400, body: errBody('invalid_request_error', message, code, param) };
+}
+function nowEpoch(occurredAt) {
+    return Math.floor((occurredAt ? Date.parse(occurredAt) : 0) / 1000);
+}
+// ── usage ledger (real recorded usage → the usage/costs reporting endpoints) ──────────────
+// Every billable inference call appends a usage record (model + token counts + a synthetic cost
+// computed from a per-model price table). The /v1/organization/usage|costs endpoints aggregate
+// these REAL recorded rows — nothing is hardcoded; with no traffic the report is genuinely empty.
+// Per-model USD price per 1M tokens (a faithful slice of the published price sheet; deterministic).
+const MODEL_PRICES = {
+    'gpt-4o': { input: 2.5, output: 10 },
+    'gpt-4o-mini': { input: 0.15, output: 0.6 },
+    'gpt-4.1': { input: 2, output: 8 },
+    'gpt-4.1-mini': { input: 0.4, output: 1.6 },
+    'gpt-4-turbo': { input: 10, output: 30 },
+    'o3': { input: 2, output: 8 },
+    'o4-mini': { input: 1.1, output: 4.4 },
+    'gpt-3.5-turbo': { input: 0.5, output: 1.5 },
+    'text-embedding-3-small': { input: 0.02, output: 0 },
+    'text-embedding-3-large': { input: 0.13, output: 0 },
+    'text-embedding-ada-002': { input: 0.1, output: 0 },
+};
+function modelPrice(model) {
+    return MODEL_PRICES[model] ?? { input: 0, output: 0 };
+}
+export function usageCost(model, inputTokens, outputTokens) {
+    const p = modelPrice(model);
+    return (inputTokens / 1e6) * p.input + (outputTokens / 1e6) * p.output;
+}
+const WIDTHS = {
+    '1m': { seconds: 60, limit: 60, max: 1440 },
+    '1h': { seconds: 3600, limit: 24, max: 168 },
+    '1d': { seconds: 86400, limit: 7, max: 31 },
+};
+/** A report's query from its parameters; Costs buckets by day only and pages up to 180 of them. */
+export function reportQuery(params, now, costs) {
+    const width = WIDTHS[String(params.bucket_width ?? '1d')] ?? WIDTHS['1d'];
+    const max = costs ? 180 : width.max;
+    const asked = Number(params.limit);
+    const limit = Number.isInteger(asked) && asked >= 1 ? Math.min(asked, max) : width.limit;
+    const start = Number(params.start_time);
+    const end = params.end_time !== undefined ? Number(params.end_time) : now;
+    const page = /^page_(\d+)$/.exec(String(params.page ?? ''));
+    const groups = params.group_by;
+    return { start, end, width: width.seconds, limit, from: page ? Number(page[1]) : start, groupBy: (Array.isArray(groups) ? groups : groups === undefined ? [] : [groups]).map(String) };
+}
+/** Buckets of one page of the query, each holding `results(rows in its window)`. */
+export function bucketed(records, q, results) {
+    const data = [];
+    let at = q.from;
+    while (at < q.end && data.length < q.limit) {
+        const until = Math.min(at + q.width, q.end);
+        data.push({ object: 'bucket', start_time: at, end_time: until, results: results(records.filter((r) => Number(r.created_at) >= at && Number(r.created_at) < until), at, until) });
+        at = until;
+    }
+    return { object: 'page', data, has_more: at < q.end, next_page: at < q.end ? `page_${at}` : null };
+}
+/** Rows grouped by `key` when grouping by it, else all in one group keyed null; none when there are no rows. */
+function grouped(rows, by) {
+    const out = new Map();
+    for (const r of rows) {
+        const k = by === null ? null : String(r[by]);
+        out.set(k, [...(out.get(k) ?? []), r]);
+    }
+    return [...out.entries()].sort((a, b) => (String(a[0]) < String(b[0]) ? -1 : 1));
+}
+/** What each usage kind's result counts, and the object it answers as (the spec's Usage*Result schemas;
+ *  https://platform.openai.com/docs/api-reference/usage). A result names the grouping it answers (model, and for images
+ *  their size and source) and null for the groupings not asked for. */
+const USAGE_RESULTS = {
+    completions: {
+        object: 'organization.usage.completions.result',
+        // the twin caches nothing and hears, sees and speaks nothing: every token is uncached text
+        count: (rs) => {
+            const input = sum(rs, 'input_tokens');
+            const output = sum(rs, 'output_tokens');
+            return { input_tokens: input, input_cached_tokens: 0, input_cache_write_tokens: 0, input_uncached_tokens: input, output_tokens: output, input_text_tokens: input, output_text_tokens: output, input_cached_text_tokens: 0, input_audio_tokens: 0, input_cached_audio_tokens: 0, output_audio_tokens: 0, input_image_tokens: 0, input_cached_image_tokens: 0, output_image_tokens: 0, num_model_requests: sum(rs, 'num_model_requests'), user_id: null, api_key_id: null, batch: null, service_tier: null };
+        },
+    },
+    embeddings: { object: 'organization.usage.embeddings.result', count: (rs) => ({ input_tokens: sum(rs, 'input_tokens'), num_model_requests: sum(rs, 'num_model_requests'), user_id: null, api_key_id: null }) },
+    moderations: { object: 'organization.usage.moderations.result', count: (rs) => ({ input_tokens: sum(rs, 'input_tokens'), num_model_requests: sum(rs, 'num_model_requests'), user_id: null, api_key_id: null }) },
+    audio_speeches: { object: 'organization.usage.audio_speeches.result', count: (rs) => ({ characters: sum(rs, 'characters'), num_model_requests: sum(rs, 'num_model_requests'), user_id: null, api_key_id: null }) },
+    audio_transcriptions: { object: 'organization.usage.audio_transcriptions.result', count: (rs) => ({ seconds: sum(rs, 'seconds'), num_model_requests: sum(rs, 'num_model_requests'), user_id: null, api_key_id: null }) },
+    images: { object: 'organization.usage.images.result', by: ['size', 'source'], count: (rs) => ({ images: sum(rs, 'images'), num_model_requests: sum(rs, 'num_model_requests'), user_id: null, api_key_id: null }) },
+    code_interpreter_sessions: { object: 'organization.usage.code_interpreter_sessions.result', count: (rs) => ({ num_sessions: sum(rs, 'num_sessions') }) },
+    file_search_calls: { object: 'organization.usage.file_searches.result', count: (rs) => ({ num_requests: sum(rs, 'num_model_requests'), user_id: null, api_key_id: null, vector_store_id: null }) },
+    web_search_calls: { object: 'organization.usage.web_searches.result', count: (rs) => ({ num_model_requests: sum(rs, 'num_model_requests'), num_requests: sum(rs, 'num_model_requests'), user_id: null, api_key_id: null, context_level: null }) },
+};
+const sum = (rows, k) => rows.reduce((n, r) => n + Number(r[k] ?? 0), 0);
+/** The kinds whose results name a model. */
+const MODELLESS = new Set(['code_interpreter_sessions', 'file_search_calls']);
+/** The usage report over the recorded usage rows, for one kind ('completions', 'embeddings', …). */
+export function usageReport(records, kind, q) {
+    const spec = USAGE_RESULTS[kind ?? 'completions'] ?? USAGE_RESULTS.completions;
+    const byModel = q.groupBy.includes('model') && !MODELLESS.has(kind ?? '');
+    const extra = (spec.by ?? []).filter((k) => q.groupBy.includes(k));
+    return bucketed(records.filter((r) => kind === undefined || r.kind === kind), q, (rows) => groupedBy(rows, [...(byModel ? ['model'] : []), ...extra]).map(([key, rs]) => ({
+        object: spec.object,
+        ...spec.count(rs),
+        project_id: null,
+        ...(MODELLESS.has(kind ?? '') ? {} : { model: byModel ? key.model : null }),
+        ...(spec.by ? Object.fromEntries(spec.by.map((k) => [k, extra.includes(k) ? key[k] : null])) : {}),
+    })));
+}
+/** Rows grouped by the values of `keys`, in key order; one group of all rows when no key; none when there are no rows. */
+function groupedBy(rows, keys) {
+    const out = new Map();
+    for (const r of rows) {
+        const key = Object.fromEntries(keys.map((k) => [k, r[k] === undefined ? null : String(r[k])]));
+        const id = JSON.stringify(key);
+        out.set(id, [key, [...(out.get(id)?.[1] ?? []), r]]);
+    }
+    return [...out.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1)).map(([, v]) => v);
+}
+/** The costs report: the recorded usage priced per model, per bucket, by line item (usage kind) when grouped so. */
+export function costsReport(records, q) {
+    const byLine = q.groupBy.includes('line_item');
+    return bucketed(records, q, (rows) => grouped(rows, byLine ? 'kind' : null).map(([line, rs]) => ({
+        object: 'organization.costs.result',
+        amount: { value: rs.reduce((n, r) => n + Number(r.cost_usd ?? 0), 0), currency: 'usd' },
+        line_item: line, project_id: null, api_key_id: null, quantity: null, quantity_unit: null,
+    })));
+}
+const SYSTEM_FINGERPRINT = 'fp_twin_stub';
+/** The roles a chat message may have (the spec's ChatCompletionRequestMessage variants). */
+const ROLES = new Set(['developer', 'system', 'user', 'assistant', 'tool', 'function']);
+/** OpenAI's refusal of a chat message whose role is not one of the request message types
+ *  (https://platform.openai.com/docs/api-reference/chat/create, `messages`). */
+function invalidRole() {
+    return { error: invalidRequest("each message must have a valid 'role'", 'messages') };
+}
+// The chat options below are OpenAI's (https://platform.openai.com/docs/api-reference/chat/create); each
+// parser answers the option's value or OpenAI's refusal of it.
+/** `n`: how many choices to generate, at least one. */
+function chatN(raw) {
+    const n = Number(raw);
+    return Number.isInteger(n) && n >= 1 ? n : { error: invalidRequest("'n' must be an integer >= 1", 'n') };
+}
+/** `max_completion_tokens` (or the legacy `max_tokens`): a cap of at least one token. */
+function chatMaxTokens(raw) {
+    const max = Number(raw);
+    return Number.isInteger(max) && max >= 1 ? max : { error: invalidRequest("'max_tokens' must be an integer >= 1", 'max_tokens') };
+}
+/** `stop`: one sequence or a list of them. */
+function chatStop(raw) {
+    if (typeof raw === 'string')
+        return [raw];
+    return Array.isArray(raw) ? raw : { error: invalidRequest("'stop' must be a string or array of strings", 'stop') };
+}
+/** `tool_choice`: 'auto' | 'none' | 'required' | { type:'function', function:{ name } }. */
+function chatToolChoice(raw) {
+    if (raw === 'auto' || raw === 'none' || raw === 'required')
+        return raw;
+    if (!raw || typeof raw !== 'object')
+        return { error: invalidRequest("'tool_choice' must be 'auto'/'none'/'required' or a named function", 'tool_choice') };
+    const fn = raw.function;
+    return typeof fn?.name === 'string' ? { name: fn.name } : { error: invalidRequest("invalid 'tool_choice' — named choice requires function.name", 'tool_choice') };
+}
+/** OpenAI's refusal of a `response_format` whose type is none of text, json_object and json_schema. */
+function badResponseFormat() {
+    return { error: invalidRequest("'response_format.type' must be 'text', 'json_object', or 'json_schema'", 'response_format') };
+}
+/** `top_logprobs`: 0 to 20 alternatives per token, only with `logprobs: true`. */
+function chatTopLogprobs(raw, logprobs) {
+    const top = Number(raw);
+    if (!Number.isInteger(top) || top < 0 || top > 20)
+        return { error: invalidRequest("'top_logprobs' must be an integer between 0 and 20", 'top_logprobs') };
+    return logprobs ? top : { error: invalidRequest("'top_logprobs' requires 'logprobs' to be true", 'top_logprobs') };
+}
+/** `seed`: an integer for best-effort reproducible sampling. */
+function chatSeed(raw) {
+    const seed = Number(raw);
+    return Number.isInteger(seed) ? seed : { error: invalidRequest("'seed' must be an integer", 'seed') };
+}
+/** `logit_bias`: token ids mapped to a bias from -100 to 100. */
+function chatLogitBias(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return { error: invalidRequest("'logit_bias' must be an object mapping token ids to bias values", 'logit_bias') };
+    const bias = {};
+    for (const [k, v] of Object.entries(raw)) {
+        const num = Number(v);
+        if (!Number.isFinite(num) || num < -100 || num > 100)
+            return { error: invalidRequest("each 'logit_bias' value must be a number between -100 and 100", 'logit_bias') };
+        bias[k] = num;
+    }
+    return bias;
+}
+/** `prediction`: predicted output, `{ type: 'content', content }`, its content a string or text parts. */
+function chatPrediction(raw) {
+    const p = raw;
+    if (!p || typeof p !== 'object' || p.type !== 'content' || p.content === undefined)
+        return { error: invalidRequest("'prediction' must be an object with type 'content' and a content field", 'prediction') };
+    if (typeof p.content === 'string')
+        return p.content;
+    return Array.isArray(p.content) ? p.content.map((c) => (c && typeof c === 'object' ? String(c.text ?? '') : String(c))).join('') : '';
+}
+/** `modalities` with `audio`: a spoken answer needs `audio: { voice, format }` (the vendor's rule). The twin
+ *  can't synthesize speech, so the returned bytes are a labeled stub; the envelope is faithful. */
+function chatAudio(modalities, audio) {
+    if (!Array.isArray(modalities))
+        return { error: invalidRequest("'modalities' must be an array", 'modalities') };
+    if (!modalities.includes('audio'))
+        return undefined;
+    const a = audio;
+    if (!a || typeof a !== 'object' || typeof a.voice !== 'string' || typeof a.format !== 'string')
+        return { error: invalidRequest("'audio' with a 'voice' and 'format' is required when 'modalities' includes 'audio'", 'audio') };
+    return { voice: a.voice, format: a.format };
+}
+export function validateChat(params) {
+    if (params.model === undefined || params.model === '')
+        return { error: invalidRequest("you must provide a model parameter", 'model') };
+    if (typeof params.model !== 'string')
+        return { error: invalidRequest("'model' must be a string", 'model') };
+    if (!Array.isArray(params.messages))
+        return { error: invalidRequest("you must provide a messages parameter", 'messages') };
+    if (params.messages.length === 0)
+        return { error: invalidRequest("[] is too short - 'messages'", 'messages') };
+    const messages = params.messages;
+    if (messages.some((m) => !m || typeof m !== 'object' || !ROLES.has(String(m.role))))
+        return invalidRole();
+    // Each option the request may carry is parsed by its own function (below): a function returns the
+    // option's value, or OpenAI's refusal of it as `{ error }`.
+    const n = params.n === undefined ? 1 : chatN(params.n);
+    if (typeof n !== 'number')
+        return n;
+    // max_completion_tokens is the current name; max_tokens is the legacy alias.
+    const maxRaw = params.max_completion_tokens ?? params.max_tokens;
+    const maxTokens = maxRaw === undefined ? undefined : chatMaxTokens(maxRaw);
+    if (typeof maxTokens === 'object')
+        return maxTokens;
+    const stop = params.stop === undefined ? undefined : chatStop(params.stop);
+    if (stop && !Array.isArray(stop))
+        return stop;
+    const toolChoice = params.tool_choice === undefined ? undefined : chatToolChoice(params.tool_choice);
+    if (toolChoice && typeof toolChoice === 'object' && 'error' in toolChoice)
+        return toolChoice;
+    // response_format: { type:'text' | 'json_object' | 'json_schema', json_schema? }.
+    let responseFormat = { kind: 'text' };
+    const rf = params.response_format;
+    if (rf !== undefined) {
+        if (!rf || typeof rf !== 'object')
+            return { error: invalidRequest("'response_format' must be an object", 'response_format') };
+        const t = rf.type ?? 'text';
+        const format = t === 'json_schema' ? { kind: 'json_schema', schema: rf.json_schema } : t === 'json_object' || t === 'text' ? { kind: t } : undefined;
+        if (!format)
+            return badResponseFormat();
+        responseFormat = format;
+    }
+    // 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);
+    // logprobs (boolean) + top_logprobs (0..20, requires logprobs:true) → per-token logprob detail.
+    const logprobs = params.logprobs === true;
+    const topLogprobs = params.top_logprobs === undefined ? undefined : chatTopLogprobs(params.top_logprobs, logprobs);
+    if (typeof topLogprobs === 'object')
+        return topLogprobs;
+    // seed → reproducible sampling (the twin is already deterministic; we echo it via fingerprint).
+    const seed = params.seed === undefined ? undefined : chatSeed(params.seed);
+    if (typeof seed === 'object')
+        return seed;
+    // logit_bias → a map of token-id → bias in [-100, 100].
+    const logitBias = params.logit_bias === undefined ? undefined : chatLogitBias(params.logit_bias);
+    if (logitBias && 'error' in logitBias)
+        return logitBias;
+    // prediction → predicted outputs ({ type:'content', content }); content may be a string or parts.
+    const prediction = params.prediction === undefined ? undefined : chatPrediction(params.prediction);
+    if (typeof prediction === 'object')
+        return prediction;
+    // modalities + audio → audio output.
+    const audioOutput = params.modalities === undefined ? undefined : chatAudio(params.modalities, params.audio);
+    if (audioOutput && 'error' in audioOutput)
+        return audioOutput;
+    // store + metadata → stored completions (retrievable later); metadata must be a flat object.
+    // a model refuses what its page says it does not take (openai-models.ts); a reasoning model reasons with the effort
+    // asked for, else the spec's default
+    const refused = unsupported(params.model, { effort: params.reasoning_effort, effortParam: 'reasoning_effort', temperature: params.temperature, top_p: params.top_p, logprobs: params.logprobs, chatTools: params.tools ?? params.functions });
+    if (refused)
+        return { error: invalidRequest(refused.message, refused.param, 'unsupported_value') };
+    const reasoningEffort = typeof params.reasoning_effort === 'string' ? params.reasoning_effort : reasons(params.model) ? DEFAULT_EFFORT : undefined;
+    const store = params.store === true;
+    let metadata;
+    if (params.metadata !== undefined) {
+        if (!params.metadata || typeof params.metadata !== 'object' || Array.isArray(params.metadata))
+            return { error: invalidRequest("'metadata' must be an object", 'metadata') };
+        metadata = params.metadata;
+    }
+    return {
+        args: {
+            model: params.model,
+            messages,
+            tools: params.tools,
+            functions: params.functions,
+            n,
+            ...(maxTokens !== undefined ? { maxTokens } : {}),
+            ...(stop !== undefined ? { stop } : {}),
+            stream: params.stream === true,
+            ...(toolChoice !== undefined ? { toolChoice } : {}),
+            parallelToolCalls: params.parallel_tool_calls !== false,
+            responseFormat,
+            includeUsage,
+            logprobs,
+            ...(topLogprobs !== undefined ? { topLogprobs } : {}),
+            ...(seed !== undefined ? { seed } : {}),
+            ...(logitBias !== undefined ? { logitBias: logitBias } : {}),
+            ...(prediction !== undefined ? { prediction } : {}),
+            ...(reasoningEffort !== undefined ? { reasoningEffort } : {}),
+            store,
+            ...(metadata !== undefined ? { metadata } : {}),
+            ...(audioOutput !== undefined ? { audioOutput: audioOutput } : {}),
+        },
+    };
+}
+/** The text cut at the EARLIEST-occurring stop sequence across the whole `stop` list, not whichever is
+ *  listed first: the real vendor's "stop generation at the first hit", regardless of array order. */
+function stoppedAt(text, stops) {
+    let stopAt = -1;
+    for (const s of stops) {
+        if (!s)
+            continue;
+        const i = text.indexOf(s);
+        if (i >= 0 && (stopAt < 0 || i < stopAt))
+            stopAt = i;
+    }
+    return stopAt >= 0 ? text.slice(0, stopAt) : text;
+}
+/** The text cut to a `max_completion_tokens` cap (about four characters a token); the choice finishes `length`. */
+function cutAt(text, maxTokens) {
+    return text.slice(0, maxTokens * 4);
+}
+/** modalities:['audio'] → the assistant replies with an audio object (content is null, the text lives in
+ *  audio.transcript). The twin can't synthesize speech, so `data` is a labeled-stub base64 string; the shape
+ *  (id/data/transcript/expires_at) is vendor-faithful. */
+function audioChoice(args, idx, transcript, logprobs, finish) {
+    const voice = args.audioOutput;
+    const stubBytes = `[twin-stub:${args.model}] no real audio synthesis — voice=${voice.voice} format=${voice.format}; transcript: ${transcript}`;
+    const audio = {
+        id: `audio-twin-${stableSuffix(args)}-${idx}`,
+        data: Buffer.from(stubBytes, 'utf8').toString('base64'),
+        transcript,
+        expires_at: nowEpoch() + 3600,
+    };
+    return {
+        choice: { index: idx, message: { role: 'assistant', content: null, refusal: null, audio }, logprobs, finish_reason: finish },
+        completionTokens: estimateTokens(transcript),
+    };
+}
+// Build ONE deterministic stub choice (index `idx`). Honors tools/functions (tool_calls +
+// finish_reason tool_calls), tool_choice (none/required/named), parallel_tool_calls,
+// response_format (json_object/json_schema), max_tokens, and stop sequences.
+function buildChoice(args, idx) {
+    const toolsSource = args.tools ?? args.functions;
+    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 (even when the heuristic otherwise would not); 'auto'/default calls when tools exist.
+    const forbidTools = args.toolChoice === 'none';
+    const forcedName = typeof args.toolChoice === 'object' ? args.toolChoice.name : undefined;
+    // a model answers a tool's result in words unless the caller insists on another call; one that always
+    // called a tool would never let an app's tool loop end
+    const answeringTool = ['tool', 'function'].includes(String(args.messages.at(-1)?.role));
+    const wantTool = hasTools && !forbidTools && (!answeringTool || forcedName !== undefined || args.toolChoice === 'required');
+    if (wantTool) {
+        // parallel_tool_calls (default true) → the stub may emit one call per provided tool; a named
+        // choice or parallel:false collapses to a single call.
+        // (the tools are there, so each call is made)
+        const calls = forcedName || args.parallelToolCalls === false
+            ? [stubToolCall(toolsSource, idx + 1, forcedName, lastUserText(args.messages))]
+            : toolsSource.map((tool, t) => stubToolCall([tool], idx * 100 + t + 1, undefined, lastUserText(args.messages)));
+        return {
+            choice: { index: idx, message: { role: 'assistant', content: null, tool_calls: calls, refusal: null }, logprobs: null, finish_reason: 'tool_calls' },
+            completionTokens: estimateTokens(JSON.stringify(calls)),
+        };
+    }
+    // json_mode: when response_format requests json_object/json_schema, the content is valid JSON.
+    // prediction (predicted outputs): a real model uses the prediction to speed decoding but still
+    // returns its own generation — the twin echoes the predicted content (clearly still a stub) so
+    // the prediction round-trips, then reports accepted/rejected prediction tokens in usage.
+    let text = args.prediction !== undefined
+        ? `[twin-stub:${args.model}] predicted-output echo: ${args.prediction}`
+        : 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);
+    if (args.stop)
+        text = stoppedAt(text, args.stop);
+    const capped = args.maxTokens !== undefined && estimateTokens(text) > args.maxTokens;
+    if (capped)
+        text = cutAt(text, args.maxTokens);
+    const finish = capped ? 'length' : 'stop';
+    const logprobs = args.logprobs ? buildLogprobs(text, args.topLogprobs ?? 0) : null;
+    if (args.audioOutput)
+        return audioChoice(args, idx, text, logprobs, finish);
+    return {
+        // a text answer carries its annotations (none: the twin cites no web source), as OpenAI's does
+        // (https://platform.openai.com/docs/api-reference/chat/object, `choices[].message.annotations`)
+        choice: { index: idx, message: { role: 'assistant', content: text, refusal: null, annotations: [] }, logprobs, finish_reason: finish },
+        completionTokens: estimateTokens(text),
+    };
+}
+/** Predicted-output accounting: the twin echoes the prediction, so every predicted token is "accepted". */
+function predictionUsage(prediction) {
+    return { accepted_prediction_tokens: estimateTokens(prediction), rejected_prediction_tokens: 0 };
+}
+export function buildChatCompletion(args, occurredAt, decision) {
+    const promptTokens = countPromptTokens(args.messages);
+    // Scenario handlers: a fired handler scripts the assistant turn; a miss teaches in the stub. The
+    // decision was made (and any fault honored) by the request handler through the engine's serve(); this
+    // builder only realizes it — a status fault never reaches here.
+    const turn = decision && scenarioTurn(decision);
+    const choices = [];
+    let completionTokens = 0;
+    for (let i = 0; i < args.n; i++) {
+        const { choice, completionTokens: ct } = turn?.scripted ? scriptedChoice(turn.scripted, i) : buildChoice(args, i);
+        if (turn?.missTeach && typeof choice.message.content === 'string')
+            choice.message.content += turn.missTeach;
+        choices.push(choice);
+        completionTokens += ct;
+    }
+    // usage breaks its counts down as OpenAI's does (https://platform.openai.com/docs/api-reference/chat/object,
+    // `usage.prompt_tokens_details`, `usage.completion_tokens_details`): the twin caches nothing and reasons and
+    // speaks nothing, so those are zero
+    const usage = {
+        prompt_tokens: promptTokens, completion_tokens: completionTokens, total_tokens: promptTokens + completionTokens,
+        prompt_tokens_details: { cached_tokens: 0, audio_tokens: 0 },
+        completion_tokens_details: { reasoning_tokens: 0, audio_tokens: 0, accepted_prediction_tokens: 0, rejected_prediction_tokens: 0 },
+    };
+    // prediction (predicted outputs): real responses report how many predicted tokens were accepted
+    // vs rejected. The twin echoes the prediction, so all predicted tokens are "accepted".
+    if (args.prediction !== undefined)
+        usage.completion_tokens_details = { ...usage.completion_tokens_details, ...predictionUsage(args.prediction) };
+    // a reasoning model's reasoning tokens are billed as output tokens (https://developers.openai.com/api/docs/guides/reasoning:
+    // "they still occupy space in the model's context window and are billed as output tokens")
+    if (args.reasoningEffort !== undefined && reasons(args.model)) {
+        const spent = REASONING_BUDGET[args.reasoningEffort] ?? 0;
+        usage.completion_tokens += spent;
+        usage.total_tokens += spent;
+        usage.completion_tokens_details = { ...usage.completion_tokens_details, reasoning_tokens: spent };
+    }
+    return {
+        id: `chatcmpl-twin-${stableSuffix(args)}`,
+        object: 'chat.completion',
+        created: nowEpoch(occurredAt),
+        model: args.model,
+        choices,
+        usage,
+        system_fingerprint: SYSTEM_FINGERPRINT,
+        // the tier that served the request: the standard one, which is what `auto` and `default` pick for a project
+        // not on Scale Tier (https://platform.openai.com/docs/api-reference/chat/object, `service_tier`)
+        service_tier: 'default',
+        ...(args.metadata !== undefined ? { metadata: args.metadata } : {}),
+    };
+}
+// A deterministic id suffix from the request (so ids are stable + assertable, like the twin's
+// other deterministic outputs). Hash of the prompt text + model + seed (seed changes sampling,
+// so it changes the response id the way a real seed-distinct request does).
+function stableSuffix(args) {
+    let h = 0x811c9dc5;
+    const s = JSON.stringify(args.messages) + args.model + (args.seed !== undefined ? `|seed=${args.seed}` : '');
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(36);
+}
+// 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;
+}
+/** A streamed choice's tool calls: one tool_calls delta-pair per call, each carrying its own `index`
+ *  (parallel tool calls). */
+function streamToolCalls(calls, idx, base, sink) {
+    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: '' } }] }, logprobs: null, finish_reason: null }] } });
+        sink({ data: { ...base, choices: [{ index: idx, delta: { tool_calls: [{ index: tIdx, function: { arguments: tc.function.arguments } }] }, logprobs: null, finish_reason: null }] } });
+    });
+}
+/**
+ * Emit the vendor-faithful Chat Completions 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 `[DONE]`. Deterministic + synchronous so a collector can assert the full sequence.
+ */
+export function streamChat(args, sink, occurredAt, decision) {
+    const full = buildChatCompletion(args, occurredAt, decision);
+    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;
+        // role chunk
+        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)
+            streamToolCalls(choice.message.tool_calls, idx, base, sink);
+        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 }] } });
+    }
+    // stream_options.include_usage → a final chunk with an empty choices array carrying `usage`.
+    if (args.includeUsage) {
+        sink({ data: { ...base, choices: [], usage: full.usage } });
+    }
+    sink({ done: true });
+    return full;
+}
+export function responseMessages(items, instructions) {
+    const messages = instructions ? [{ role: 'system', content: instructions }] : [];
+    const partsText = (content) => typeof content === 'string' ? content : Array.isArray(content) ? content.map((c) => c && typeof c === 'object' ? String(c.text ?? JSON.stringify(c)) : String(c)).join('\n') : '';
+    for (const item of items) {
+        if (item.type === 'function_call') {
+            messages.push({ role: 'assistant', content: '', tool_calls: [{ id: String(item.call_id ?? item.id ?? ''), type: 'function', function: { name: String(item.name ?? ''), arguments: typeof item.arguments === 'string' ? item.arguments : JSON.stringify(item.arguments ?? {}) } }] });
+        }
+        else if (item.type === 'function_call_output') {
+            messages.push({ role: 'tool', content: partsText(item.output), tool_call_id: String(item.call_id ?? '') });
+        }
+        else if (item.type === 'message' || item.type === undefined) {
+            messages.push({ role: (item.role ?? 'user'), content: partsText(item.content) });
+        }
+        // Reasoning and other typed items remain in state, without inventing user turns.
+    }
+    return messages;
+}
+/** OpenAI's refusal of an `input` list holding something other than input items (objects)
+ *  (https://platform.openai.com/docs/api-reference/responses/create, `input`). */
+function itemsNotObjects() {
+    return { error: invalidRequest("'input' items must be objects", 'input') };
+}
+export function validateResponses(params) {
+    if (params.model === undefined || params.model === '')
+        return { error: invalidRequest("you must provide a model parameter", 'model') };
+    if (typeof params.model !== 'string')
+        return { error: invalidRequest("'model' must be a string", 'model') };
+    if (params.input === undefined)
+        return { error: invalidRequest("you must provide an input parameter", 'input') };
+    // Keep vendor items as state; the messages view is only a projection for the scenario.
+    let inputItems;
+    if (typeof params.input === 'string') {
+        inputItems = [{ type: 'message', role: 'user', content: [{ type: 'input_text', text: params.input }] }];
+    }
+    else if (Array.isArray(params.input)) {
+        if (params.input.some((item) => !item || typeof item !== 'object' || Array.isArray(item)))
+            return itemsNotObjects();
+        inputItems = params.input.map((item) => {
+            if (item.type !== undefined && item.type !== 'message')
+                return { ...item };
+            return { ...item, type: 'message', role: item.role ?? 'user', content: typeof item.content === 'string' ? [{ type: item.role === 'assistant' ? 'output_text' : 'input_text', text: item.content }] : item.content };
+        });
+    }
+    else {
+        return { error: invalidRequest("'input' must be a string or an array of input items", 'input') };
+    }
+    const instructions = typeof params.instructions === 'string' ? params.instructions : undefined;
+    const messages = responseMessages(inputItems, instructions);
+    const inputText = responseMessages(inputItems).map((m) => m.content).filter(Boolean).join('\n');
+    if (params.tools !== undefined && !Array.isArray(params.tools))
+        return { error: invalidRequest("'tools' must be an array", 'tools') };
+    const maxOut = params.max_output_tokens;
+    if (maxOut !== undefined && (typeof maxOut !== 'number' || !Number.isInteger(maxOut) || maxOut < 1))
+        return { error: invalidRequest("'max_output_tokens' must be a positive integer", 'max_output_tokens') };
+    const prev = params.previous_response_id;
+    if (prev !== undefined && (typeof prev !== 'string' || !prev))
+        return { error: invalidRequest("'previous_response_id' must be a string", 'previous_response_id') };
+    // reasoning.effort → the model spends a (stubbed) reasoning budget; the item shape is faithful.
+    let reasoningEffort;
+    if (params.reasoning !== undefined) {
+        const r = params.reasoning;
+        if (!r || typeof r !== 'object' || Array.isArray(r))
+            return { error: invalidRequest("'reasoning' must be an object", 'reasoning') };
+        const effort = r.effort;
+        if (effort !== undefined && effort !== null)
+            reasoningEffort = effort;
+    }
+    // a model refuses what its page says it does not take (openai-models.ts); a reasoning model reasons with the effort
+    // asked for, else the spec's default
+    const refused = unsupported(params.model, { effort: reasoningEffort, effortParam: 'reasoning.effort', temperature: params.temperature, top_p: params.top_p });
+    if (refused)
+        return { error: invalidRequest(refused.message, refused.param, 'unsupported_value') };
+    if (reasoningEffort === undefined && reasons(params.model))
+        reasoningEffort = DEFAULT_EFFORT;
+    const reasoningSummary = params.reasoning && typeof params.reasoning.summary === 'string' ? String(params.reasoning.summary) : undefined;
+    return {
+        args: {
+            model: params.model,
+            inputItems,
+            instructions,
+            inputText,
+            messages,
+            stream: params.stream === true,
+            store: params.store !== false, // OpenAI defaults store=true (stored & retrievable)
+            background: params.background === true,
+            ...(typeof prev === 'string' ? { previousResponseId: prev } : {}),
+            ...(reasoningEffort !== undefined ? { reasoningEffort } : {}),
+            ...(Array.isArray(params.tools) ? { tools: params.tools } : {}),
+            ...(typeof maxOut === 'number' ? { maxTokens: maxOut } : {}),
+            ...(reasoningSummary !== undefined ? { reasoningSummary } : {}),
+            // OpenAI's defaults for what was not sent (the Response schema's): temperature and top_p 1, tools in parallel, auto;
+            // plain text out, no truncation, no end user, no tool-call cap, no alternative tokens, the default tier
+            // (https://platform.openai.com/docs/api-reference/responses/object)
+            echo: {
+                metadata: params.metadata ?? {}, temperature: params.temperature ?? 1, top_p: params.top_p ?? 1, parallel_tool_calls: params.parallel_tool_calls ?? true, tool_choice: params.tool_choice ?? 'auto',
+                text: params.text ?? { format: { type: 'text' } }, truncation: params.truncation ?? 'disabled', user: params.user ?? null, max_tool_calls: params.max_tool_calls ?? null,
+                top_logprobs: params.top_logprobs ?? 0, service_tier: ['flex', 'priority', 'scale'].includes(String(params.service_tier)) ? params.service_tier : 'default',
+            },
+        },
+    };
+}
+/** A tool as a response answers it: as sent, with what OpenAI fills in for what was not. A web search preview searches
+ *  with `medium` context from the United States unless told otherwise (the spec's WebSearchPreviewTool: "`medium` is
+ *  the default"; `user_location` "If omitted or null, defaults to the United States"); a function tool sent without
+ *  `strict` answers strict, as the reference's Functions example answers the tool it sends; a file search tool, its
+ *  default filter and ranking
+ *  (https://platform.openai.com/docs/api-reference/responses/create). */
+const TOOL_DEFAULTS = {
+    function: (t) => ({ ...t, strict: t.strict ?? true }),
+    // a file search sent without filters or ranking answers no filter and the automatic ranker with no threshold, as the
+    // reference's File search example answers the tool it sends
+    file_search: (t) => ({ ...t, filters: t.filters ?? null, ranking_options: t.ranking_options ?? { ranker: 'auto', score_threshold: 0 } }),
+    // and the domains it is limited to, none unless sent, as the reference's Web search example answers `"domains": []`
+    web_search_preview: (t) => ({ ...t, domains: t.domains ?? [], search_context_size: t.search_context_size ?? 'medium', user_location: t.user_location ?? { type: 'approximate', city: null, country: 'US', region: null, timezone: null } }),
+};
+TOOL_DEFAULTS.web_search_preview_2025_03_11 = TOOL_DEFAULTS.web_search_preview;
+function answeredTool(tool) {
+    const t = (tool && typeof tool === 'object' ? tool : {});
+    return TOOL_DEFAULTS[String(t.type)]?.(t) ?? tool;
+}
+/** The built-in tool calls a response makes: a web search for a web search tool, a file search over the named stores for a
+ *  file search tool, each querying the input's text (its results are not included unless asked for: `results` null). */
+function builtInCalls(args, suffix) {
+    const query = args.inputText.slice(0, 200);
+    const out = [];
+    for (const [i, tool] of (Array.isArray(args.tools) ? args.tools : []).entries()) {
+        const type = String(tool?.type ?? '');
+        if (/^web_search/.test(type))
+            out.push({ type: 'web_search_call', id: `ws-twin-${suffix}-${i}`, status: 'completed', action: { type: 'search', query } });
+        if (type === 'file_search')
+            out.push({ type: 'file_search_call', id: `fs-twin-${suffix}-${i}`, status: 'completed', queries: [query], results: null });
+    }
+    return out;
+}
+/** What every response answers besides its output: the request's settings as sent (or OpenAI's defaults), no error,
+ *  no program access (https://platform.openai.com/docs/api-reference/responses/object). */
+const responseSettings = (args) => ({
+    instructions: args.instructions ?? null, tools: Array.isArray(args.tools) ? args.tools.map(answeredTool) : [], ...args.echo,
+    access_programs: null, error: null, incomplete_details: null,
+    // whether it is kept: the spec's own Response example answers `"store": true` (spec/patches.json)
+    background: args.background, store: args.store, max_output_tokens: args.maxTokens ?? null,
+    previous_response_id: args.previousResponseId ?? null,
+    reasoning: { effort: args.reasoningEffort ?? null, summary: args.reasoningSummary ?? null },
+});
+// A deterministic reasoning-token budget per effort level (more effort → more reasoning tokens).
+const REASONING_BUDGET = { none: 0, minimal: 8, low: 16, medium: 48, high: 128, xhigh: 256, max: 512 };
+/** The function call an unscripted response makes: when the caller requires one or names one, or on
+ *  `auto` unless the input ends with a tool's result, which a model answers in words. */
+function responseToolCall(args) {
+    const choice = args.echo.tool_choice;
+    const named = choice && typeof choice === 'object' ? String(choice.name ?? '') : undefined;
+    const answering = args.inputItems.at(-1)?.type === 'function_call_output';
+    const functions = (Array.isArray(args.tools) ? args.tools : []).filter((t) => t.type === 'function');
+    if (!functions.length || choice === 'none' || (answering && !named && choice !== 'required'))
+        return null;
+    return stubToolCall(functions, 1, named, lastUserText(args.messages));
+}
+export function buildResponse(args, occurredAt, idSuffix, decision) {
+    // The scenario decides the turn exactly as it does for chat completions: a fired handler scripts the
+    // text and the tool calls; a miss answers the labeled stub and teaches. The request handler has
+    // already honored a fault; only a content decision reaches here.
+    const suffix = idSuffix ?? String(nowEpoch(occurredAt));
+    const turn = decision && scenarioTurn(decision, `call-twin-${suffix}`);
+    const scripted = turn?.scripted;
+    let text = scripted ? (scripted.text ?? '') : stubAssistantText(args.messages, args.model) + (turn?.missTeach ?? '');
+    const inputTokens = countPromptTokens(args.messages);
+    const messageItem = {
+        type: 'message',
+        id: `msg-twin-${suffix}`,
+        status: 'completed',
+        role: 'assistant',
+        // no log probabilities unless asked for (`include: ["message.output_text.logprobs"]`): an empty list
+        content: [{ type: 'output_text', text, annotations: [], logprobs: [] }],
+    };
+    // unscripted, the stub calls a function tool as the chat stub does (buildChoice)
+    const stubbed = scripted ? null : responseToolCall(args);
+    if (stubbed)
+        text = '';
+    const calls = (scripted?.toolCalls ?? (stubbed ? [stubbed] : [])).map((tc, i) => ({ type: 'function_call', id: `fc-twin-${suffix}-${i}`, status: 'completed', call_id: tc.id, name: tc.function.name, arguments: tc.function.arguments }));
+    const messageTokens = estimateTokens(text) + estimateTokens(calls.map((c) => c.arguments).join(''));
+    const output = [];
+    // usage breaks its counts down as OpenAI's does (https://platform.openai.com/docs/api-reference/responses/object, `usage`):
+    // the twin caches nothing, so no input token was read from or written to a cache
+    const usage = { input_tokens: inputTokens, input_tokens_details: { cached_tokens: 0, cache_write_tokens: 0 }, output_tokens: messageTokens, output_tokens_details: { reasoning_tokens: 0 }, total_tokens: inputTokens + messageTokens };
+    // reasoning.effort → a faithful reasoning item (labeled-stub summary) BEFORE the message item,
+    // plus output_tokens_details.reasoning_tokens in usage (counted into output_tokens, like the vendor).
+    if (args.reasoningEffort) {
+        const reasoningTokens = REASONING_BUDGET[args.reasoningEffort] ?? 16;
+        // a summary only when one was asked for (`reasoning.summary`); without, OpenAI answers the item's summary empty
+        // (https://platform.openai.com/docs/guides/reasoning#reasoning-summaries)
+        const reasoningItem = {
+            type: 'reasoning',
+            id: `rs-twin-${suffix}`,
+            summary: args.reasoningSummary ? [{ type: 'summary_text', text: `[twin-stub] reasoning summary (effort=${args.reasoningEffort}); the twin cannot run the model, so the chain-of-thought is not real.` }] : [],
+        };
+        // only a model that reasons lists its reasoning item (openai-models.ts)
+        if (reasons(args.model))
+            output.push(reasoningItem);
+        usage.output_tokens += reasoningTokens;
+        usage.total_tokens += reasoningTokens;
+        usage.output_tokens_details = { reasoning_tokens: reasoningTokens };
+    }
+    // the built-in tools the request offers, which OpenAI runs itself before answering: the placeholder model searches
+    // with each one offered, on the input's text, unless `tool_choice` is `none` (the reference's Web search and File search
+    // examples answer a `web_search_call` / `file_search_call` item before the message:
+    // https://platform.openai.com/docs/guides/tools-web-search, https://platform.openai.com/docs/guides/tools-file-search)
+    if (!scripted && args.echo.tool_choice !== 'none')
+        output.push(...builtInCalls(args, suffix));
+    // A scripted turn with tool calls and no words carries the calls alone, as the vendor does.
+    if (text || !calls.length)
+        output.push(messageItem);
+    output.push(...calls);
+    return {
+        id: `resp-twin-${suffix}`,
+        object: 'response',
+        created_at: nowEpoch(occurredAt),
+        status: 'completed',
+        // answered whole at once: completed the instant it was created
+        completed_at: nowEpoch(occurredAt),
+        model: args.model,
+        // no `output_text`: the spec's is an "SDK-only convenience property" the SDKs compute from `output`
+        output,
+        usage,
+        ...responseSettings(args),
+    };
+}
+// Unstored responses have no state to overwrite. Stored identities are allocated atomically below.
+export function responseSuffix(args) {
+    let h = 0x811c9dc5;
+    const s = JSON.stringify([args.model, args.inputItems ?? args.messages, args.previousResponseId, args.instructions]);
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(36);
+}
+// Allocate and create under the kernel's cross-process lock. Repeated requests are occurrences;
+// a content hash alone would overwrite an earlier response (and its queued scenario decision).
+export async function createStoredResponse(args, req, decision) {
+    const { value } = await applyTwinWriteAtomic(SERVICE, (resources) => {
+        let ordinal = 0;
+        for (const row of resources) {
+            if (row.type !== 'response')
+                continue;
+            const match = /^resp-twin-(\d+)$/.exec(String(row.id));
+            if (match)
+                ordinal = Math.max(ordinal, Number(match[1]));
+        }
+        const suffix = String(ordinal + 1);
+        const inputItems = args.inputItems.map((item, i) => ({ ...item, id: item.id ?? `item-in-${suffix}-${i}` }));
+        const resp = args.background ? {
+            id: `resp-twin-${suffix}`, object: 'response', created_at: nowEpoch(req.occurredAt),
+            status: 'queued', completed_at: null, model: args.model, output: [],
+            usage: null, ...responseSettings(args),
+        } : buildResponse(args, req.occurredAt, suffix, decision);
+        return { kind: 'write', value: resp, write: {
+                operation: 'response.create', subjectType: 'response', subjectId: resp.id,
+                fields: { ...resp, _stored: true, _input_items: inputItems,
+                    ...(args.background ? { _bg_args: JSON.stringify(args), _bg_suffix: suffix, _bg_decision: decision ? JSON.stringify(decision) : null } : {}),
+                },
+                ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' },
+            } };
+    }, req.root);
+    return value;
+}
+export function emitResponse(resp, sink) {
+    sink({ data: { type: 'response.created', response: { ...resp, output: [] } } });
+    // Emit each output item in order, as the vendor streams them: a reasoning item whole, the message
+    // item's text as deltas at its own index, a function call's arguments as one delta then done.
+    resp.output.forEach((item, i) => {
+        sink({ data: { type: 'response.output_item.added', output_index: i, item: item.type === 'function_call' ? { ...item, arguments: '' } : item } });
+        if (item.type === 'message') {
+            const text = item.content[0]?.text ?? '';
+            for (const piece of chunkText(text))
+                sink({ data: { type: 'response.output_text.delta', output_index: i, content_index: 0, delta: piece } });
+            sink({ data: { type: 'response.output_text.done', output_index: i, content_index: 0, text } });
+        }
+        if (item.type === 'function_call') {
+            sink({ data: { type: 'response.function_call_arguments.delta', output_index: i, item_id: item.id, delta: item.arguments } });
+            sink({ data: { type: 'response.function_call_arguments.done', output_index: i, item_id: item.id, arguments: item.arguments } });
+        }
+        sink({ data: { type: 'response.output_item.done', output_index: i, item } });
+    });
+    sink({ data: { type: 'response.completed', response: resp } });
+    sink({ done: true });
+    return resp;
+}
+// ── Embeddings (deterministic pseudo-vectors) ───────────────────────────────────────────
+export function handleEmbeddings(params) {
+    if (params.model === undefined || params.model === '')
+        return invalidRequest("you must provide a model parameter", 'model');
+    if (params.input === undefined)
+        return invalidRequest("you must provide an input parameter", 'input');
+    const model = String(params.model);
+    const inputs = typeof params.input === 'string'
+        ? [params.input]
+        : Array.isArray(params.input)
+            ? params.input.map((x) => (typeof x === 'string' ? x : JSON.stringify(x)))
+            : [];
+    if (inputs.length === 0)
+        return invalidRequest("'input' must be a non-empty string or array", 'input');
+    const dimensions = params.dimensions !== undefined ? Number(params.dimensions) : defaultDims(model);
+    if (!Number.isInteger(dimensions) || dimensions < 1)
+        return invalidRequest("'dimensions' must be a positive integer", 'dimensions');
+    // The `openai` SDK defaults to encoding_format:'base64' and decodes a base64 Float32 buffer
+    // back into numbers client-side. Honor both formats faithfully.
+    const asBase64 = params.encoding_format === 'base64';
+    let promptTokens = 0;
+    const data = inputs.map((text, index) => {
+        promptTokens += estimateTokens(text);
+        const vec = pseudoEmbedding(text, dimensions);
+        return { object: 'embedding', index, embedding: (asBase64 ? floatsToBase64(vec) : vec) };
+    });
+    const out = { object: 'list', data, model, usage: { prompt_tokens: promptTokens, total_tokens: promptTokens } };
+    return { status: 200, body: out };
+}
+function defaultDims(model) {
+    if (model.includes('large'))
+        return 3072;
+    return 1536; // small + ada-002
+}
+/** Encode a float vector as a base64 little-endian Float32 buffer (the SDK's base64 format). */
+function floatsToBase64(vec) {
+    const buf = new ArrayBuffer(vec.length * 4);
+    const view = new DataView(buf);
+    for (let i = 0; i < vec.length; i++)
+        view.setFloat32(i * 4, vec[i], true);
+    // btoa over the raw bytes (available in Bun/browser).
+    let bin = '';
+    const bytes = new Uint8Array(buf);
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin);
+}
+// ── Moderations (deterministic) ─────────────────────────────────────────────────────────
+export function handleModerations(params, occurredAt) {
+    if (params.input === undefined)
+        return invalidRequest("you must provide an input parameter", 'input');
+    // an array of strings is several inputs, one result each; an array of text and image parts is ONE multimodal input,
+    // one result (https://platform.openai.com/docs/api-reference/moderations/create, `input`)
+    const list = Array.isArray(params.input) ? params.input : [];
+    const parts = list.length > 0 && list.every((x) => x && typeof x === 'object' && !Array.isArray(x));
+    const inputs = typeof params.input === 'string'
+        ? [{ text: params.input, image: false }]
+        : parts
+            ? [{ text: list.filter((x) => x.type === 'text').map((x) => String(x.text ?? '')).join('\n'), image: list.some((x) => x.type === 'image_url') }]
+            : list.map((x) => ({ text: typeof x === 'string' ? x : JSON.stringify(x), image: false }));
+    if (inputs.length === 0)
+        return invalidRequest("'input' must be a non-empty string or array", 'input');
+    const model = modelOf('createModeration', params);
+    const results = inputs.map((t) => moderateText(t.text, t.image));
+    return { status: 200, body: { id: `modr-twin-${nowEpoch(occurredAt)}`, model, results } };
+}
+// ── Images (a real placeholder image, no model: ./openai-media.ts) ─────────────────────────────────
+const gptImage = (model) => /^(gpt-image|chatgpt-image)/.test(model);
+/** One answered image: the GPT image models give the image itself as base64, always; `dall-e-2` and `dall-e-3` a URL
+ *  unless `response_format` is `b64_json`, and `dall-e-3` its revised prompt (developers.openai.com/api/reference/
+ *  resources/images/methods/generate, `response_format`; the Image object's `b64_json`, `url`, `revised_prompt`). */
+function imageData(params, model, size, seed, kind, i, occurredAt) {
+    return gptImage(model) || params.response_format === 'b64_json' ? { b64_json: base64(placeholderPng(size, `${seed} #${i + 1}`)) } : dalleUrl(model, seed, kind, i, occurredAt);
+}
+/** A DALL·E image as its URL, the default for `dall-e-2` and `dall-e-3`. */
+function dalleUrl(model, seed, kind, i, occurredAt) {
+    return { url: `https://twin.invalid/openai-${kind}-stub/${nowEpoch(occurredAt)}-${i}.png`, ...(model === 'dall-e-3' ? { revised_prompt: `[twin-stub] ${seed}` } : {}) };
+}
+function imageCount(params) {
+    const n = Number(params.n ?? 1);
+    return Number.isInteger(n) && n > 0 ? n : 1;
+}
+/** A GPT image model's answer: the images with the tokens they cost (the image generation guide's 1024x1024
+ *  medium-quality image is 1056 output tokens, scaled here by area; the twin reads no pixels, so it counts no input image
+ *  tokens: https://platform.openai.com/docs/guides/image-generation#cost-and-latency), or, with `stream`, the
+ *  `partial_images` asked (none by default: "When set to 0, the response will be a single image sent in one streaming
+ *  event") then the completed image (https://platform.openai.com/docs/api-reference/images-streaming). */
+function gptImageAnswer(params, size, data, kind, occurredAt) {
+    const text = estimateTokens(String(params.prompt ?? ''));
+    const output = Math.ceil((1056 * size.width * size.height) / (1024 * 1024)) * data.length;
+    const usage = { total_tokens: text + output, input_tokens: text, output_tokens: output, input_tokens_details: { text_tokens: text, image_tokens: 0 } };
+    const created = nowEpoch(occurredAt);
+    if (params.stream !== true && params.stream !== 'true')
+        return { status: 200, body: { created, data, usage } };
+    const settings = {
+        created_at: created, size: `${size.width}x${size.height}`,
+        // what `auto` settles on for a placeholder: an opaque PNG of medium quality
+        quality: params.quality && params.quality !== 'auto' ? params.quality : 'medium',
+        background: params.background && params.background !== 'auto' ? params.background : 'opaque',
+        output_format: params.output_format ?? 'png',
+    };
+    const partials = Math.min(3, Math.max(0, Number(params.partial_images ?? 0) || 0));
+    const b64 = String(data[0]?.b64_json ?? '');
+    const events = [
+        ...Array.from({ length: partials }, (_, i) => ({ event: `${kind}.partial_image`, data: { type: `${kind}.partial_image`, b64_json: b64, ...settings, partial_image_index: i } })),
+        { event: `${kind}.completed`, data: { type: `${kind}.completed`, b64_json: b64, ...settings, usage } },
+    ];
+    return { status: 200, body: { created, data, usage }, events };
+}
+export function handleImages(params, occurredAt) {
+    if (params.prompt === undefined || params.prompt === '')
+        return invalidRequest("you must provide a prompt parameter", 'prompt');
+    const model = modelOf('createImage', params);
+    const size = requestedSize(params.size);
+    const data = Array.from({ length: imageCount(params) }, (_, i) => imageData(params, model, size, String(params.prompt), 'image', i, occurredAt));
+    if (gptImage(model))
+        return gptImageAnswer(params, size, data, 'image_generation', occurredAt);
+    return { status: 200, body: { created: nowEpoch(occurredAt), data } };
+}
+/** OpenAI's refusal of an upload that is not an image the model takes. */
+const badImage = (formats) => invalidRequest(`Invalid image file: 'image' must be ${formats}.`, 'image', 'invalid_image_format');
+// An EDIT takes an image file and a prompt; a VARIATION (dall-e-2 only) a square PNG. Each is told by its bytes.
+export function handleImageEdit(params, occurredAt) {
+    // a GPT image model edits several images sent as `image[]` (the form keeps the last one named so)
+    const image = params.image ?? params['image[]'];
+    if (image === undefined || image === '')
+        return invalidRequest("you must provide an image to edit", 'image');
+    if (params.prompt === undefined || params.prompt === '')
+        return invalidRequest("you must provide a prompt parameter", 'prompt');
+    const model = modelOf('createImageEdit', params);
+    const bytes = partBytes(image);
+    const format = bytes && imageFormat(bytes);
+    if (gptImage(model) ? !format : format !== 'png' || !square(bytes))
+        return badImage(gptImage(model) ? 'a png, webp, or jpg file' : 'a square png file');
+    const size = requestedSize(params.size, format === 'png' ? pngSize(bytes) : undefined);
+    const data = Array.from({ length: imageCount(params) }, (_, i) => imageData(params, model, size, String(params.prompt), 'image-edit', i, occurredAt));
+    if (gptImage(model))
+        return gptImageAnswer(params, size, data, 'image_edit', occurredAt);
+    return { status: 200, body: { created: nowEpoch(occurredAt), data } };
+}
+const square = (png) => { const s = pngSize(png); return s.width === s.height; };
+export function handleImageVariation(params, occurredAt) {
+    if (params.image === undefined || params.image === '')
+        return invalidRequest("you must provide an image", 'image');
+    const bytes = partBytes(params.image);
+    if (!bytes || imageFormat(bytes) !== 'png' || !square(bytes))
+        return badImage('a valid square png file');
+    const size = requestedSize(params.size);
+    const data = Array.from({ length: imageCount(params) }, (_, i) => imageData(params, modelOf('createImageVariation', params), size, 'variation', 'image-variation', i, occurredAt));
+    return { status: 200, body: { created: nowEpoch(occurredAt), data } };
+}
+// ── Audio (deterministic stubs; the twin runs no model) ──────────────────────
+// Transcription/translation cannot run a real speech model, so the twin returns a clearly
+// labeled deterministic transcript naming the uploaded file. It takes the audio file itself, in a
+// format OpenAI transcribes (./openai-media.ts), never a file's name. The response SHAPE
+// (json / verbose_json / text) is vendor-faithful.
+/** A multipart list field (`include[]`, `timestamp_granularities[]`), however the form named it. */
+function formList(params, name) {
+    const v = params[name] ?? params[`${name}[]`];
+    return (Array.isArray(v) ? v : v === undefined ? [] : [v]).map(String);
+}
+/** What a transcription is billed on: the GPT-4o transcribe models by tokens, whisper-1 and the diarizing model by the
+ *  audio's seconds (https://platform.openai.com/docs/api-reference/audio/json-object, `usage`). The twin counts ten
+ *  audio tokens a second and its transcript's text tokens; neither is a model's count. */
+function transcriptionUsage(model, seconds, text) {
+    if (model.startsWith('whisper') || model.includes('diarize'))
+        return { type: 'duration', seconds: Math.ceil(seconds) };
+    const audio = Math.ceil(seconds * 10);
+    const out = estimateTokens(text);
+    return { type: 'tokens', input_tokens: audio, input_token_details: { text_tokens: 0, audio_tokens: audio }, output_tokens: out, total_tokens: audio + out };
+}
+/** The transcript's words spread evenly over the audio: the twin hears nothing, so its timings are the file's length
+ *  shared out, not a model's alignment. */
+function words(text, seconds) {
+    const all = text.split(/\s+/).filter(Boolean);
+    const each = seconds / Math.max(1, all.length);
+    return all.map((word, i) => ({ word, start: i * each, end: (i + 1) * each }));
+}
+/** A transcription (or translation) of the uploaded audio: a labeled transcript naming the file, in the response
+ *  format asked (json, text, verbose_json with the word or segment timestamps asked, or diarized_json), with the
+ *  token log probabilities when `include[]=logprobs`, and as `transcript.text.delta` events then
+ *  `transcript.text.done` when `stream=true` on a model that streams (https://platform.openai.com/docs/api-reference/audio/createTranscription). */
+export function handleTranscription(params, translate) {
+    if (params.file === undefined || params.file === '')
+        return invalidRequest("you must provide a file parameter", 'file');
+    if (params.model === undefined || params.model === '')
+        return invalidRequest("you must provide a model parameter", 'model');
+    const bytes = partBytes(params.file);
+    if (!bytes || !audioFormat(bytes))
+        return invalidRequest("Invalid file format. Supported formats: ['flac', 'm4a', 'mp3', 'mp4', 'mpeg', 'mpga', 'oga', 'ogg', 'wav', 'webm']", 'file', 'invalid_value');
+    const filename = String(params.file.name || 'upload');
+    const model = String(params.model);
+    const verb = translate ? 'translation' : 'transcription';
+    const text = `[twin-stub] deterministic ${verb} of ${filename} (no speech model is run)`;
+    const format = typeof params.response_format === 'string' ? params.response_format : 'json';
+    // the file's own length where the twin can read it (a WAV's header), else a labeled second
+    const duration = wavSeconds(bytes) ?? 1.0;
+    if (format === 'text')
+        return { status: 200, body: text, seconds: duration };
+    if (translate)
+        return { status: 200, seconds: duration, body: format === 'verbose_json' ? { task: 'translation', language: 'english', duration, text, segments: [{ id: 0, start: 0, end: duration, text }] } : { text } };
+    const usage = transcriptionUsage(model, duration, text);
+    if (format === 'diarized_json') {
+        // one speaker the twin cannot tell apart: the first name the caller knows, else OpenAI's first label
+        const speaker = formList(params, 'known_speaker_names')[0] ?? 'A';
+        return { status: 200, seconds: duration, body: { task: 'transcribe', duration, text, segments: [{ type: 'transcript.text.segment', id: 'seg_001', start: 0, end: duration, text, speaker }], usage } };
+    }
+    if (format === 'verbose_json') {
+        const granularities = formList(params, 'timestamp_granularities');
+        const segment = { id: 0, seek: 0, start: 0, end: duration, text, tokens: [], temperature: 0, avg_logprob: 0, compression_ratio: 1, no_speech_prob: 0 };
+        return {
+            status: 200,
+            seconds: duration,
+            body: {
+                task: 'transcribe', language: typeof params.language === 'string' ? params.language : 'english', duration, text,
+                ...(granularities.includes('word') ? { words: words(text, duration) } : {}),
+                ...(!granularities.length || granularities.includes('segment') ? { segments: [segment] } : {}),
+                usage,
+            },
+        };
+    }
+    const logprobs = formList(params, 'include').includes('logprobs') ? buildLogprobs(text, 0).content.map(({ token, logprob, bytes: b }) => ({ token, logprob, bytes: b })) : undefined;
+    const body = { text, ...(logprobs ? { logprobs } : {}), usage };
+    // whisper-1 does not stream ("Streaming is not supported for the whisper-1 model and will be ignored")
+    if (String(params.stream) === 'true' && !model.startsWith('whisper')) {
+        const pieces = text.match(/\s*\S+/g) ?? [];
+        const events = pieces.map((delta) => ({ data: { type: 'transcript.text.delta', delta, ...(logprobs ? { logprobs: buildLogprobs(delta, 0).content.map(({ token, logprob, bytes: b }) => ({ token, logprob, bytes: b })) } : {}) } }));
+        events.push({ data: { type: 'transcript.text.done', text, ...(logprobs ? { logprobs } : {}), usage } });
+        return { status: 200, body, seconds: duration, events };
+    }
+    return { status: 200, body, seconds: duration };
+}
+// Text-to-speech: runs no speech model, but answers the audio file itself in the requested format, as OpenAI does
+// (a second of silence: ./openai-media.ts), with that format's Content-Type.
+const SPEECH = {
+    mp3: { type: 'audio/mpeg', file: silentMp3 },
+    opus: { type: 'audio/opus', file: silentOpus },
+    aac: { type: 'audio/aac', file: silentAac },
+    flac: { type: 'audio/flac', file: silentFlac },
+    wav: { type: 'audio/wav', file: silentWav },
+    pcm: { type: 'audio/pcm', file: silentPcm },
+};
+export function handleSpeech(params) {
+    if (params.model === undefined || params.model === '')
+        return invalidRequest("you must provide a model parameter", 'model');
+    if (params.input === undefined || params.input === '')
+        return invalidRequest("you must provide an input parameter", 'input');
+    if (params.voice === undefined || params.voice === '')
+        return invalidRequest("you must provide a voice parameter", 'voice');
+    const format = SPEECH[String(params.response_format ?? 'mp3')];
+    if (!format)
+        return invalidRequest("'response_format' must be one of 'mp3', 'opus', 'aac', 'flac', 'wav', 'pcm'", 'response_format');
+    return { status: 200, audio: format.file(), type: format.type };
+}
+// ── public entry: cross-cutting protocol (auth / rate-limit) then route ─────────────────────
+// The HTTP server passes request headers, so on the live wire every call is auth/rate-limit-
+// checked; in-process trusted calls (capability verify, connector) omit `headers`/`apiKey` and are
+// NOT gated.
+/** OpenAI's API as one call: the request goes through the pack's own dispatch (the derived dispatch over its
+ *  semantics, its derived core and the hand-written routes below), so a caller that holds no HTTP
+ *  server reaches exactly what an SDK does. A caller that presents no credential is a trusted
+ *  in-process caller and is not held to the auth rule; `sseSink` receives a stream's events. */
+export async function handleOpenAITwinRequest(req) {
+    const twin = createOpenAITwinFetch({
+        ...(req.root !== undefined ? { root: req.root } : {}),
+        readOnly: req.readOnly ?? false,
+        ...(req.scenarioEngine ? { scenarioEngine: req.scenarioEngine } : {}),
+        ...(req.occurredAt ? { clock: () => req.occurredAt } : {}),
+    });
+    const headers = { ...(req.headers ?? {}) };
+    if (req.apiKey !== undefined)
+        headers.authorization = `Bearer ${req.apiKey}`;
+    else if (req.headers === undefined)
+        headers.authorization = 'Bearer sk-twin-in-process';
+    const method = req.method.toUpperCase();
+    if (typeof req.body === 'string' && method !== 'GET' && method !== 'HEAD' && !headers['content-type'])
+        headers['content-type'] = 'application/json';
+    const path = req.path.startsWith('/') ? req.path : `/${req.path}`;
+    const response = await twin(new Request(`https://api.openai.com${path}`, { method, headers, ...(req.body !== undefined && method !== 'GET' && method !== 'HEAD' ? { body: req.body } : {}) }));
+    const answerHeaders = {};
+    response.headers.forEach((v, k) => { if (k !== 'content-type')
+        answerHeaders[k] = v; });
+    const type = response.headers.get('content-type') ?? '';
+    const text = await response.text();
+    if (type.includes('text/event-stream')) {
+        // the frames back into events, for a caller that collects them
+        for (const frame of text.split('\n\n')) {
+            const data = frame.split('\n').filter((l) => l.startsWith('data: ')).map((l) => l.slice(6)).join('\n');
+            if (!data)
+                continue;
+            req.sseSink?.(data === '[DONE]' ? { done: true } : { data: JSON.parse(data) });
+        }
+        return { status: response.status, body: null, headers: answerHeaders };
+    }
+    const body = type.includes('json') ? (text ? JSON.parse(text) : null) : text;
+    return { status: response.status, body, headers: answerHeaders };
+}