@volter/twin-openai 0.1.2 → 2.0.1

package/dist/src/openai-media.js

@@ -0,0 +1,257 @@
+// The media an image or audio endpoint takes and gives. OpenAI takes an uploaded image or audio file only in the
+// formats its reference names, told by the file's bytes, and a GPT image model answers the image itself as base64:
+//   • an image to edit is "a `png`, `webp`, or `jpg` file" for the GPT image models, and for `dall-e-2` "a square
+//     `png`" (developers.openai.com/api/reference/resources/images/methods/edit, `image`); a variation's is "a valid
+//     PNG file, less than 4MB, and square" (…/images/methods/create_variation, `image`);
+//   • a transcription or translation takes "the audio file object (not file name)" in "one of these formats: flac,
+//     mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm" (…/audio/subresources/transcriptions/methods/create, `file`);
+//   • the GPT image models "always return base64-encoded images" (…/images/methods/generate, `response_format`).
+// Where the documentation stops and the twin decides: a format is told by its signature bytes; the image the twin
+// answers is a real PNG of the requested size in one flat colour drawn from the prompt, labeled in its own text
+// chunk, since the twin renders no pixels.
+import { createHash } from 'node:crypto';
+import { deflateSync } from 'node:zlib';
+/** The raw bytes of an uploaded file part, as the request's multipart parse keeps them; undefined for a string. */
+export function partBytes(v) {
+    const b = v && typeof v === 'object' ? v.bytes : undefined;
+    return b instanceof Uint8Array ? b : undefined;
+}
+const has = (b, sig, at = 0) => (typeof sig === 'string' ? [...sig].map((c) => c.charCodeAt(0)) : sig).every((x, i) => b[at + i] === x);
+const PNG = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+/** Each image format a signature tells, checked in this order. */
+const IMAGE = [
+    ['jpg', (b) => has(b, [0xff, 0xd8, 0xff])],
+    ['webp', (b) => has(b, 'RIFF') && has(b, 'WEBP', 8)],
+    ['png', (b) => has(b, PNG) && has(b, 'IHDR', 12)],
+];
+/** An image's format by its signature: png, jpg or webp, else undefined. */
+export const imageFormat = (b) => IMAGE.find(([, is]) => is(b))?.[0];
+/** A PNG's width and height from its IHDR chunk. */
+export function pngSize(b) {
+    const v = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    return { width: v.getUint32(16), height: v.getUint32(20) };
+}
+/** Each audio format OpenAI transcribes that a signature tells, checked in this order. */
+const AUDIO = [
+    ['flac', (b) => has(b, 'fLaC')],
+    ['ogg', (b) => has(b, 'OggS')],
+    ['webm', (b) => has(b, [0x1a, 0x45, 0xdf, 0xa3])],
+    ['mp4', (b) => has(b, 'ftyp', 4)],
+    ['mp3', (b) => has(b, 'ID3') || (b[0] === 0xff && ((b[1] ?? 0) & 0xe0) === 0xe0)],
+    ['wav', (b) => has(b, 'RIFF') && has(b, 'WAVE', 8)],
+];
+/** An audio file's format by its signature, among those OpenAI transcribes, else undefined. */
+export const audioFormat = (b) => AUDIO.find(([, is]) => is(b))?.[0];
+/** A WAV file's length in seconds, from its `fmt ` byte rate and its `data` size (RIFF chunks in any order); undefined
+ *  for any other format, whose length the twin does not read. */
+export function wavSeconds(b) {
+    if (!has(b, 'RIFF') || !has(b, 'WAVE', 8))
+        return undefined;
+    const v = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    let rate = 0;
+    let data = 0;
+    for (let at = 12; at + 8 <= b.length; at += 8 + v.getUint32(at + 4, true) + (v.getUint32(at + 4, true) & 1)) {
+        if (has(b, 'fmt ', at))
+            rate = v.getUint32(at + 16, true);
+        if (has(b, 'data', at))
+            data = v.getUint32(at + 4, true);
+    }
+    return rate > 0 ? Math.round((data / rate) * 1000) / 1000 : undefined;
+}
+const CRC = Array.from({ length: 256 }, (_, n) => {
+    let c = n;
+    for (let k = 0; k < 8; k++)
+        c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    return c >>> 0;
+});
+function crc32(b) {
+    let c = 0xffffffff;
+    for (const x of b)
+        c = CRC[(c ^ x) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+function chunk(type, data) {
+    const out = new Uint8Array(12 + data.length);
+    const v = new DataView(out.buffer);
+    v.setUint32(0, data.length);
+    out.set([...type].map((c) => c.charCodeAt(0)), 4);
+    out.set(data, 8);
+    v.setUint32(8 + data.length, crc32(out.subarray(4, 8 + data.length)));
+    return out;
+}
+/** The size an image request asks for (`1536x1024`), or the fallback for `auto` or none. */
+export function requestedSize(size, fallback = { width: 1024, height: 1024 }) {
+    const m = typeof size === 'string' ? /^(\d+)x(\d+)$/.exec(size) : null;
+    return m ? { width: Number(m[1]), height: Number(m[2]) } : fallback;
+}
+/** A real PNG of the size asked, one flat colour drawn from `seed`, labeled as the twin's placeholder. */
+export function placeholderPng(size, seed) {
+    const [r, g, bl] = createHash('sha256').update(seed).digest();
+    const { width, height } = size;
+    const ihdr = new Uint8Array(13);
+    const v = new DataView(ihdr.buffer);
+    v.setUint32(0, width);
+    v.setUint32(4, height);
+    ihdr.set([8, 2, 0, 0, 0], 8); // 8-bit RGB, no interlace
+    const row = new Uint8Array(1 + width * 3);
+    for (let x = 0; x < width; x++)
+        row.set([r, g, bl], 1 + x * 3);
+    const raw = new Uint8Array(row.length * height);
+    for (let y = 0; y < height; y++)
+        raw.set(row, y * row.length);
+    const text = new TextEncoder().encode(`Comment\0[twin-stub] placeholder image, no model is run: ${seed}`);
+    const parts = [Uint8Array.from(PNG), chunk('IHDR', ihdr), chunk('tEXt', text), chunk('IDAT', new Uint8Array(deflateSync(raw))), chunk('IEND', new Uint8Array(0))];
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let at = 0;
+    for (const p of parts) {
+        out.set(p, at);
+        at += p.length;
+    }
+    return out;
+}
+/** Bytes as base64. */
+export function base64(b) {
+    let bin = '';
+    for (let i = 0; i < b.length; i += 0x8000)
+        bin += String.fromCharCode(...b.subarray(i, i + 0x8000));
+    return btoa(bin);
+}
+// ── Speech: the audio file itself ────────────────────────────────────────────────────────────────────────────────
+// Text to speech answers "the audio file content" in the requested `response_format`, `mp3` by default, of mp3, opus,
+// aac, flac, wav and pcm (developers.openai.com/api/reference/resources/audio/subresources/speech/methods/create); its
+// audio is 24 kHz mono. The twin speaks nothing: each is a real file of that format, a second of silence.
+const RATE = 24000;
+/** A second of 24 kHz 16-bit mono silence as samples' bytes: `pcm`, raw little-endian with no header. */
+export const silentPcm = () => new Uint8Array(RATE * 2);
+/** The same second as a WAV file. */
+export function silentWav() {
+    const data = RATE * 2;
+    const b = new Uint8Array(44 + data);
+    const v = new DataView(b.buffer);
+    b.set(ascii('RIFF'), 0);
+    v.setUint32(4, 36 + data, true);
+    b.set(ascii('WAVEfmt '), 8);
+    v.setUint32(16, 16, true);
+    v.setUint16(20, 1, true);
+    v.setUint16(22, 1, true);
+    v.setUint32(24, RATE, true);
+    v.setUint32(28, RATE * 2, true);
+    v.setUint16(32, 2, true);
+    v.setUint16(34, 16, true);
+    b.set(ascii('data'), 36);
+    v.setUint32(40, data, true);
+    return b;
+}
+/** The same second as MP3: MPEG-2 Layer III frames at 24 kHz, 32 kbit/s, mono, each 576 samples in 96 bytes whose
+ *  side information codes no spectral data, which a decoder plays as silence. */
+export function silentMp3() {
+    const frames = Math.ceil(RATE / 576);
+    const b = new Uint8Array(frames * 96);
+    for (let i = 0; i < frames; i++)
+        b.set([0xff, 0xf3, 0x44, 0xc4], i * 96);
+    return b;
+}
+/** The same second as FLAC: a STREAMINFO block and frames of 4096 samples, each one CONSTANT subframe of zero. */
+export function silentFlac() {
+    const block = 4096;
+    const info = new Bits();
+    info.put(block, 16);
+    info.put(block, 16);
+    info.put(0, 24);
+    info.put(0, 24);
+    info.put(RATE, 20);
+    info.put(0, 3);
+    info.put(15, 5);
+    info.put(0, 4);
+    info.put(RATE, 32);
+    for (let i = 0; i < 16; i++)
+        info.put(0, 8); // MD5 unknown
+    const out = [...ascii('fLaC'), 0x80, 0, 0, 34, ...info.bytes()];
+    for (let n = 0, left = RATE; left > 0; n++, left -= block) {
+        const size = Math.min(block, left);
+        // blocksize 4096 (code 12) or, for the last, 16 bits of size-1 at the header's end (code 7); 24 kHz is code 7
+        const head = [0xff, 0xf8, ((size === block ? 12 : 7) << 4) | 7, 0x08, n, ...(size === block ? [] : [(size - 1) >> 8, (size - 1) & 0xff])];
+        const frame = [...head, crc8(head), 0x00, 0x00, 0x00];
+        const c = crc16(frame);
+        out.push(...frame, c >> 8, c & 0xff);
+    }
+    return Uint8Array.from(out);
+}
+/** The same second as AAC in ADTS: AAC-LC frames of 1024 samples at 24 kHz, mono, each one channel element with
+ *  no scale-factor bands, which a decoder plays as silence. */
+export function silentAac() {
+    const payload = [0x00, 0x00, 0x00, 0x07]; // SCE, global gain 0, max_sfb 0, no tools; END
+    const length = 7 + payload.length;
+    const frame = new Bits();
+    frame.put(0xfff, 12);
+    frame.put(0, 1);
+    frame.put(0, 2);
+    frame.put(1, 1); // MPEG-4, no CRC
+    frame.put(1, 2);
+    frame.put(6, 4);
+    frame.put(0, 1);
+    frame.put(1, 3); // AAC-LC, 24 kHz, mono
+    frame.put(0, 4);
+    frame.put(length, 13);
+    frame.put(0x7ff, 11);
+    frame.put(0, 2);
+    const one = [...frame.bytes(), ...payload];
+    return Uint8Array.from(Array.from({ length: Math.ceil(RATE / 1024) }, () => one).flat());
+}
+/** The same second as Opus in Ogg: its identification and comment headers, then 20 ms packets of silence. */
+export function silentOpus() {
+    const head = [...ascii('OpusHead'), 1, 1, 0x38, 0x01, ...le32(RATE), 0, 0, 0];
+    const tags = [...ascii('OpusTags'), ...le32(4), ...ascii('twin'), ...le32(0)];
+    const packets = Array.from({ length: 50 }, () => [0xf8, 0xff, 0xfe]);
+    return Uint8Array.from([...oggPage(0x02, 0, 0, [head]), ...oggPage(0, 0, 1, [tags]), ...oggPage(0x04, 312 + 48000, 2, packets)]);
+}
+const ascii = (s) => [...s].map((c) => c.charCodeAt(0));
+const le32 = (n) => [n & 0xff, (n >> 8) & 0xff, (n >> 16) & 0xff, (n >>> 24) & 0xff];
+/** A big-endian bit writer. */
+class Bits {
+    out = [];
+    acc = 0;
+    n = 0;
+    put(value, bits) {
+        for (let i = bits - 1; i >= 0; i--) {
+            this.acc = (this.acc << 1) | (Math.floor(value / 2 ** i) & 1);
+            if (++this.n === 8) {
+                this.out.push(this.acc);
+                this.acc = 0;
+                this.n = 0;
+            }
+        }
+    }
+    bytes() { return this.out; }
+}
+function crc8(b) {
+    let c = 0;
+    for (const x of b) {
+        c ^= x;
+        for (let k = 0; k < 8; k++)
+            c = c & 0x80 ? ((c << 1) ^ 0x07) & 0xff : (c << 1) & 0xff;
+    }
+    return c;
+}
+function crc16(b) {
+    let c = 0;
+    for (const x of b) {
+        c ^= x << 8;
+        for (let k = 0; k < 8; k++)
+            c = c & 0x8000 ? ((c << 1) ^ 0x8005) & 0xffff : (c << 1) & 0xffff;
+    }
+    return c;
+}
+/** One Ogg page of stream 1 holding whole packets, its CRC over the page with the field zeroed. */
+function oggPage(flags, granule, seq, packets) {
+    const lacing = packets.flatMap((p) => [...Array(Math.floor(p.length / 255)).fill(255), p.length % 255]);
+    const page = [...ascii('OggS'), 0, flags, ...le32(granule), 0, 0, 0, 0, ...le32(1), ...le32(seq), 0, 0, 0, 0, lacing.length, ...lacing, ...packets.flat()];
+    let c = 0;
+    for (const x of page) {
+        c ^= x << 24;
+        for (let k = 0; k < 8; k++)
+            c = c & 0x80000000 ? ((c << 1) ^ 0x04c11db7) >>> 0 : (c << 1) >>> 0;
+    }
+    page.splice(22, 4, ...le32(c));
+    return page;
+}

package/dist/src/openai-models.d.ts

@@ -0,0 +1,74 @@
+export type OpenAIModel = {
+    id: string;
+    object: 'model';
+    created: number;
+    owned_by: string;
+    /** When the model shuts down, or null when no date is announced (https://platform.openai.com/docs/api-reference/models/object) */
+    shutdown_date: string | null;
+};
+export declare const OPENAI_MODELS: OpenAIModel[];
+/** The instant a shutdown date takes effect: "At the time of the shut down, the model or endpoint will no longer be
+ *  accessible" (the deprecations page); the twin takes the date's first instant, UTC. */
+export declare const shutdownAt: (date: string) => number;
+/** Whether a catalogued model is live at the World instant `now` (unix seconds): released, and not yet shut down. A model
+ *  the catalog does not hold is not live: it does not exist. */
+export declare function live(id: string, now: number): boolean;
+/** The API families OpenAI removed, by the operations they serve, and the instant each is gone: the Assistants API on
+ *  2026-08-26 ("removal from the API one year later, on August 26, 2026"), the Evals API on 2026-11-30 ("The Evals
+ *  dashboard and API are scheduled to shut down"), its evals read-only from 2026-10-31 ("Existing evals become
+ *  read-only") (https://developers.openai.com/api/docs/deprecations). */
+export declare const REMOVED_FAMILIES: Array<{
+    family: string;
+    removed: string;
+    operations: RegExp;
+    readOnlyFrom?: string;
+    writes?: RegExp;
+}>;
+/** A removed family's answer to an operation at `now`, or none while it is served. The deprecations page says only that
+ *  a removed endpoint "will no longer be accessible": the status and wording of the answer are the twin's own. */
+export declare function removedAt(operation: string, now: number): {
+    status: number;
+    message: string;
+} | undefined;
+/** Fine-tuning's dated availability (the deprecations page, "Self-serve fine-tuning availability"): from 2026-05-07
+ *  "Creating fine-tuning jobs or training is not available to organizations that have not previously run fine-tuning";
+ *  from 2026-07-02 "Creating fine-tuning jobs is no longer available to organizations that have not run inference on a
+ *  fine-tuned model in the past 60 days"; from 2027-01-06 "Active existing customers will no longer be able to create
+ *  new fine-tuning jobs". The page documents no error: the refusal (403, its wording) is the twin's own. */
+export declare function fineTuningClosed(now: number, org: {
+    everFineTuned: boolean;
+    lastFineTunedInference?: number;
+}): string | undefined;
+/** Resolve a model object by id, or undefined if the twin doesn't model it. */
+export declare function findModel(id: string): OpenAIModel | undefined;
+/** Whether a model reasons, so that its responses list the reasoning item that describes its chain of thought and count
+ *  its reasoning tokens (the spec's ReasoningItem: "A description of the chain of thought used by a reasoning model while
+ *  generating a response"). The o-series and the GPT models from GPT-5 on reason: the spec speaks of "all reasoning models
+ *  after `gpt-5`", and the reasoning guide (https://developers.openai.com/api/docs/guides/reasoning) lists gpt-6-astra,
+ *  gpt-5.6, gpt-5.5 and gpt-5.4 among them; gpt-6-astra's page names "Reasoning token support"
+ *  (https://developers.openai.com/api/docs/models/gpt-6-astra). A fine-tuned model reasons as its base does. */
+export declare function reasons(model: string): boolean;
+/** The reasoning efforts the spec's ReasoningEffort names; a model may document fewer. */
+export declare const REASONING_EFFORTS: string[];
+/** The effort a reasoning model spends when the request names none: the spec's ReasoningEffort `default: medium`. */
+export declare const DEFAULT_EFFORT = "medium";
+/** OpenAI's refusal of a request a model does not take (an effort, custom sampling, log probabilities), or none. */
+export declare function unsupported(model: string, req: {
+    effort?: unknown;
+    effortParam: string;
+    temperature?: unknown;
+    top_p?: unknown;
+    logprobs?: unknown;
+    chatTools?: unknown;
+}): {
+    message: string;
+    param: string;
+} | undefined;
+/** The model an operation runs on when the request names none, from the spec's request schemas: a generation's
+ *  `dall-e-2` (CreateImageRequest `model` default), an edit's `gpt-image-1.5` (CreateImageEditRequest), a variation's
+ *  `dall-e-2` (it takes no other), a moderation's `omni-moderation-latest` (CreateModerationRequest). */
+export declare const DEFAULT_MODEL: Record<string, string>;
+/** The model a request runs on: the one it names, else its operation's default (a variation runs on dall-e-2 whatever it names). */
+export declare function modelOf(operation: string, params: {
+    model?: unknown;
+}): string | undefined;

package/dist/src/openai-models.js

@@ -0,0 +1,148 @@
+// OpenAI's timeline, as data (the catalog, each API family's removal, and the dated policy changes).
+//
+// Every model the pack's walks name, with its release (`created`) and its shutdown. Sources: the changelog
+// (https://developers.openai.com/api/docs/changelog) dates a release: "Released GPT-6 Astra" 2026-09-03, "Released GPT
+// Image 2.5 Sunburst and GPT Image 2.5 Flare" 2026-09-08, "Released GPT-5.2" 2025-12-11, "Released gpt-image-1.5"
+// 2025-12-16, "Added a new image generation model, `gpt-image-1`" 2025-04-23, "Released GPT-5 family of models"
+// 2025-08-07, "Added two new o-series reasoning models, `o3` and `o4-mini`" 2025-04-16, "Launched o3-mini" 2025-01-31,
+// "Added `gpt-4o-mini-tts`, `gpt-4o-transcribe`..." 2025-03-20, "Released GPT-4o mini" 2024-07-18, "Released new
+// `omni-moderation-latest`" 2024-09-26. The deprecations page (https://developers.openai.com/api/docs/deprecations) dates
+// a shutdown: gpt-3.5-turbo, gpt-4-turbo, o4-mini, o3-mini and gpt-image-1 on 2026-10-23; dall-e-2 and dall-e-3 on
+// 2026-05-12; gpt-image-1.5 on 2026-12-01; whisper-1 and the gpt-4o transcribe models on 2027-02-26.
+// Where neither page dates a release, `created` is the value OpenAI's own model object answers (the earlier catalog's
+// entries, and dall-e-2's and tts-1's). Extrapolation: gpt-4o-transcribe-diarize's release is documented nowhere the twin could
+// read; it is dated with the transcribe family it belongs to (2025-03-20).
+const model = (id, created, shutdown_date = null, owned_by = 'system') => ({ id, object: 'model', created, owned_by, shutdown_date });
+export const OPENAI_MODELS = [
+    model('gpt-6-astra', 1788393600, null, 'openai'),
+    model('gpt-5.2', 1765411200),
+    model('gpt-5', 1754524800),
+    model('gpt-4o', 1715367049),
+    model('gpt-4o-mini', 1721172741),
+    model('gpt-4o-mini-2024-07-18', 1721260800),
+    model('gpt-4.1', 1744316542),
+    model('gpt-4.1-mini', 1744317547),
+    model('gpt-4-turbo', 1712361441, '2026-10-23'),
+    model('o3', 1744761600),
+    model('o4-mini', 1744761600, '2026-10-23'),
+    model('o3-mini', 1738281600, '2026-10-23'),
+    model('gpt-3.5-turbo', 1677610602, '2026-10-23', 'openai'),
+    model('text-embedding-3-small', 1705948997),
+    model('text-embedding-3-large', 1705953180),
+    model('text-embedding-ada-002', 1671217299, null, 'openai-internal'),
+    model('dall-e-2', 1698798177, '2026-05-12'),
+    model('dall-e-3', 1698785189, '2026-05-12'),
+    model('gpt-image-1', 1745366400, '2026-10-23'),
+    model('gpt-image-1.5', 1765843200, '2026-12-01'),
+    model('gpt-image-2.5-flare', 1788825600),
+    model('whisper-1', 1677532384, '2027-02-26', 'openai-internal'),
+    model('gpt-4o-transcribe', 1742428800, '2027-02-26'),
+    model('gpt-4o-mini-transcribe', 1742428800, '2027-02-26'),
+    model('gpt-4o-transcribe-diarize', 1742428800, '2027-02-26'),
+    model('tts-1', 1681940951, null, 'openai-internal'),
+    model('gpt-4o-mini-tts', 1742428800),
+    model('omni-moderation-latest', 1727308800),
+];
+/** The instant a shutdown date takes effect: "At the time of the shut down, the model or endpoint will no longer be
+ *  accessible" (the deprecations page); the twin takes the date's first instant, UTC. */
+export const shutdownAt = (date) => Date.parse(`${date}T00:00:00Z`) / 1000;
+/** Whether a catalogued model is live at the World instant `now` (unix seconds): released, and not yet shut down. A model
+ *  the catalog does not hold is not live: it does not exist. */
+export function live(id, now) {
+    const m = OPENAI_MODELS.find((x) => x.id === id);
+    return !!m && m.created <= now && (m.shutdown_date === null || now < shutdownAt(m.shutdown_date));
+}
+/** The API families OpenAI removed, by the operations they serve, and the instant each is gone: the Assistants API on
+ *  2026-08-26 ("removal from the API one year later, on August 26, 2026"), the Evals API on 2026-11-30 ("The Evals
+ *  dashboard and API are scheduled to shut down"), its evals read-only from 2026-10-31 ("Existing evals become
+ *  read-only") (https://developers.openai.com/api/docs/deprecations). */
+export const REMOVED_FAMILIES = [
+    { family: 'Assistants API', removed: '2026-08-26', operations: /^(createAssistant|listAssistants|getAssistant|modifyAssistant|deleteAssistant|createThread|createThreadAndRun|getThread|modifyThread|deleteThread|createMessage|listMessages|getMessage|modifyMessage|deleteMessage|createRun|listRuns|getRun|modifyRun|cancelRun|submitToolOuputsToRun|listRunSteps|getRunStep)$/ },
+    { family: 'Evals API', removed: '2026-11-30', operations: /^(createEval|listEvals|getEval|updateEval|deleteEval|createEvalRun|getEvalRuns|getEvalRun|cancelEvalRun|deleteEvalRun|getEvalRunOutputItems|getEvalRunOutputItem)$/, readOnlyFrom: '2026-10-31', writes: /^(createEval|updateEval|deleteEval|createEvalRun|cancelEvalRun|deleteEvalRun)$/ },
+];
+/** A removed family's answer to an operation at `now`, or none while it is served. The deprecations page says only that
+ *  a removed endpoint "will no longer be accessible": the status and wording of the answer are the twin's own. */
+export function removedAt(operation, now) {
+    for (const f of REMOVED_FAMILIES) {
+        if (!f.operations.test(operation))
+            continue;
+        if (now >= shutdownAt(f.removed))
+            return { status: 404, message: `The ${f.family} was removed on ${f.removed}.` };
+        if (f.readOnlyFrom && f.writes?.test(operation) && now >= shutdownAt(f.readOnlyFrom))
+            return { status: 400, message: `Evals are read-only since ${f.readOnlyFrom}.` };
+    }
+    return undefined;
+}
+/** Fine-tuning's dated availability (the deprecations page, "Self-serve fine-tuning availability"): from 2026-05-07
+ *  "Creating fine-tuning jobs or training is not available to organizations that have not previously run fine-tuning";
+ *  from 2026-07-02 "Creating fine-tuning jobs is no longer available to organizations that have not run inference on a
+ *  fine-tuned model in the past 60 days"; from 2027-01-06 "Active existing customers will no longer be able to create
+ *  new fine-tuning jobs". The page documents no error: the refusal (403, its wording) is the twin's own. */
+export function fineTuningClosed(now, org) {
+    if (now >= shutdownAt('2027-01-06'))
+        return 'Creating fine-tuning jobs is no longer available (since 2027-01-06).';
+    if (now >= shutdownAt('2026-07-02') && (org.lastFineTunedInference === undefined || now - org.lastFineTunedInference > 60 * 86400))
+        return 'Creating fine-tuning jobs is not available to organizations that have not run inference on a fine-tuned model in the past 60 days (since 2026-07-02).';
+    if (now >= shutdownAt('2026-05-07') && !org.everFineTuned)
+        return 'Creating fine-tuning jobs is not available to organizations that have not previously run fine-tuning (since 2026-05-07).';
+    return undefined;
+}
+/** Resolve a model object by id, or undefined if the twin doesn't model it. */
+export function findModel(id) {
+    return OPENAI_MODELS.find((m) => m.id === id);
+}
+/** Whether a model reasons, so that its responses list the reasoning item that describes its chain of thought and count
+ *  its reasoning tokens (the spec's ReasoningItem: "A description of the chain of thought used by a reasoning model while
+ *  generating a response"). The o-series and the GPT models from GPT-5 on reason: the spec speaks of "all reasoning models
+ *  after `gpt-5`", and the reasoning guide (https://developers.openai.com/api/docs/guides/reasoning) lists gpt-6-astra,
+ *  gpt-5.6, gpt-5.5 and gpt-5.4 among them; gpt-6-astra's page names "Reasoning token support"
+ *  (https://developers.openai.com/api/docs/models/gpt-6-astra). A fine-tuned model reasons as its base does. */
+export function reasons(model) {
+    const base = model.startsWith('ft:') ? model.split(':')[1] ?? '' : model;
+    return /^o\d/.test(base) || /^gpt-([5-9]|\d{2,})(\b|[.-])/.test(base);
+}
+/** The reasoning efforts the spec's ReasoningEffort names; a model may document fewer. */
+export const REASONING_EFFORTS = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+/** The effort a reasoning model spends when the request names none: the spec's ReasoningEffort `default: medium`. */
+export const DEFAULT_EFFORT = 'medium';
+/** What a model's page says it takes and refuses. gpt-6-astra: "`reasoning.effort` supports `low`, `medium`, `high`,
+ *  `xhigh`, and `max`" (its model page); "GPT-6 Astra does not support `none` reasoning effort. Setting
+ *  `reasoning.effort` (Responses) or `reasoning_effort` (Chat Completions) to `none` returns HTTP 400" (the reasoning
+ *  guide); "does not support custom `temperature` or `top_p` values or log probabilities (`logprobs`)" (the changelog,
+ *  2026-09-03). */
+const LIMITS = {
+    'gpt-6-astra': { efforts: ['low', 'medium', 'high', 'xhigh', 'max'], sampling: false, logprobs: false, chatTools: false },
+};
+/** OpenAI's refusal of a request a model does not take (an effort, custom sampling, log probabilities), or none. */
+export function unsupported(model, req) {
+    const base = model.startsWith('ft:') ? model.split(':')[1] ?? '' : model;
+    const limits = LIMITS[base];
+    const efforts = limits?.efforts ?? REASONING_EFFORTS;
+    if (req.effort !== undefined && (typeof req.effort !== 'string' || !efforts.includes(req.effort))) {
+        return { message: `Unsupported value: '${req.effortParam}' does not support ${JSON.stringify(req.effort)} with this model. Supported values are: ${efforts.map((e) => `'${e}'`).join(', ')}.`, param: req.effortParam };
+    }
+    if (!limits)
+        return undefined;
+    for (const k of ['temperature', 'top_p']) {
+        if (req[k] !== undefined && req[k] !== 1)
+            return { message: `Unsupported value: '${k}' does not support ${JSON.stringify(req[k])} with this model. Only the default (1) value is supported.`, param: k };
+    }
+    if (req.logprobs === true)
+        return { message: "Unsupported parameter: 'logprobs' is not supported with this model.", param: 'logprobs' };
+    // "Tool calling requires the Responses API. If you use tools with Chat Completions, follow the Responses migration
+    // guide" (https://developers.openai.com/api/docs/changelog, 2026-09-03). The changelog gives no wording for the
+    // refusal: this message is the twin's own.
+    if (Array.isArray(req.chatTools) && req.chatTools.length)
+        return { message: 'Tool calling with this model requires the Responses API: send the request to /v1/responses.', param: 'tools' };
+    return undefined;
+}
+/** The model an operation runs on when the request names none, from the spec's request schemas: a generation's
+ *  `dall-e-2` (CreateImageRequest `model` default), an edit's `gpt-image-1.5` (CreateImageEditRequest), a variation's
+ *  `dall-e-2` (it takes no other), a moderation's `omni-moderation-latest` (CreateModerationRequest). */
+export const DEFAULT_MODEL = { createImage: 'dall-e-2', createImageEdit: 'gpt-image-1.5', createImageVariation: 'dall-e-2', createModeration: 'omni-moderation-latest' };
+/** The model a request runs on: the one it names, else its operation's default (a variation runs on dall-e-2 whatever it names). */
+export function modelOf(operation, params) {
+    if (operation === 'createImageVariation')
+        return DEFAULT_MODEL.createImageVariation;
+    return typeof params.model === 'string' && params.model ? params.model : DEFAULT_MODEL[operation];
+}

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

@@ -0,0 +1,51 @@
+import { type PackScenarioAdapter, type ScenarioDecision, type ScenarioDocument, ScenarioEngine } from '@volter/world-core';
+import type { ChatChoice, ChatMessageParam, ChatToolCall } from './openai-types.js';
+export type OpenAIScenarioRequest = {
+    model: string;
+    messages: ChatMessageParam[];
+    tools?: unknown;
+    maxTokens?: number;
+};
+export type OpenAIScenarioEngine = ScenarioEngine<OpenAIScenarioRequest>;
+export type ScenarioToolCall = {
+    name: string;
+    arguments: Record<string, unknown>;
+    id?: string;
+};
+export type OpenAIScenarioRespond = {
+    text?: string;
+    toolCalls?: ScenarioToolCall | ScenarioToolCall[];
+    finishReason?: 'stop' | 'length' | 'tool_calls' | 'content_filter';
+};
+export type ScriptedResult = {
+    text: string | null;
+    toolCalls: ChatToolCall[];
+    finishReason: 'stop' | 'length' | 'tool_calls' | 'content_filter';
+};
+export declare const openaiScenarioAdapter: PackScenarioAdapter<OpenAIScenarioRequest>;
+export declare function loadOpenAIScenarioDocument(path: string): ScenarioDocument;
+/** What the scenario makes of one request: the decision a builder realizes, or a fault answered at once
+ *  (a status the script names; the script's own authoring failure is a 500 before any stream starts). */
+export declare function serveScenario(engine: OpenAIScenarioEngine, req: OpenAIScenarioRequest, path: string): Promise<ScenarioDecision | {
+    kind: 'fault';
+    result: {
+        status: number;
+        body: unknown;
+        headers?: Record<string, string>;
+    };
+}>;
+/** A decision as a turn: the scripted result, or, on a miss, the note that teaches where to script it. */
+export declare function scenarioTurn(decision: ScenarioDecision, callIdPrefix?: string): {
+    scripted: ScriptedResult;
+    missTeach?: undefined;
+} | {
+    scripted?: undefined;
+    missTeach: string;
+};
+/** A scripted turn as a chat completion's choice. */
+export declare function scriptedChoice(scripted: ScriptedResult, index: number): {
+    choice: ChatChoice;
+    completionTokens: number;
+};
+export declare function createOpenAIScenarioEngine(document?: ScenarioDocument): OpenAIScenarioEngine;
+export declare function realizeOpenAIRespond(respond: OpenAIScenarioRespond, callIdPrefix?: string): ScriptedResult;