@volter/twin-openai 0.1.0

package/src/openai-server.ts

@@ -0,0 +1,167 @@
+// OpenAI twin HTTP server — serve the full OpenAI twin handler over HTTP so the real `openai`
+// SDK (constructed with `baseURL: http://127.0.0.1:<port>/v1`) works unmodified. JSON bodies
+// (what the SDK sends for most calls) pass straight through. Writable by default; pass readOnly
+// to reject mutations (D3).
+//
+// Streaming: when the request body has `"stream": true`, the server constructs a REAL SSE
+// response by feeding the handler an sseSink that writes each chunk onto the HTTP stream in
+// OpenAI's `data: <json>\n\n` wire format, ending with `data: [DONE]\n\n`. (The handler itself
+// stays socket-free — the sink is the only place a socket is touched, on the live HTTP path.)
+//
+// File uploads: the SDK sends `multipart/form-data` to POST /v1/files. The server parses the
+// multipart form into the handler's JSON contract ({ purpose, filename, content, bytes }) so
+// the handler stays a pure JSON function (offline-testable).
+//
+// The surface is a plain `fetch` (`createOpenAITwinFetch`) and the SERVER is one line of
+// `Bun.serve` around it — see that factory's docstring for why (a serverless entry has no
+// port to bind, so it mounts the fetch in-process).
+import { handleOpenAITwinRequest } from './openai-twin.ts';
+import { twinManifest, worldNow } from '@volter/twin';
+import { createOpenAIScenarioEngine, loadOpenAIScenarioDocument, type OpenAIScenarioEngine } from './openai-scenario.ts';
+import type { SseEvent } from './openai-types.ts';
+
+function wantsStream(body: string): boolean {
+  if (!body) return false;
+  try {
+    return (JSON.parse(body) as { stream?: unknown })?.stream === true;
+  } catch {
+    return false;
+  }
+}
+
+function encodeSse(event: SseEvent): string {
+  if (event.done) return 'data: [DONE]\n\n';
+  return `data: ${JSON.stringify(event.data)}\n\n`;
+}
+
+const STREAMABLE = new Set(['/v1/chat/completions', '/v1/responses']);
+
+async function multipartToJson(request: Request): Promise<string> {
+  try {
+    const form = await request.formData();
+    const out: Record<string, unknown> = {};
+    // Forward every scalar field generically (model, purpose, response_format, language, …).
+    for (const [key, value] of form.entries()) {
+      if (typeof value === 'string') out[key] = value;
+    }
+    const file = form.get('file');
+    if (file instanceof File) {
+      // The handler's contract uses `file` as the filename and `content`/`bytes` for the body.
+      const content = await file.text();
+      out.file = file.name || 'upload';
+      out.filename = file.name || 'upload';
+      out.content = content;
+      out.bytes = file.size || content.length;
+    }
+    if (out.purpose === undefined) out.purpose = '';
+    return JSON.stringify(out);
+  } catch {
+    return '{}';
+  }
+}
+
+/** Options every OpenAI-twin HTTP surface needs, independent of who owns the socket. */
+export interface OpenAITwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+  scenarioPath?: string;
+}
+
+/**
+ * The pack's whole HTTP surface as a plain `fetch` — Request in, Response out, no listener.
+ *
+ * This is the composable form (runtime contract R12's Cloudflare consequence): a Worker /
+ * Durable Object entry has NO loopback ports, so it must mount a pack's handler IN-PROCESS.
+ * `createOpenAITwinServer` is nothing but `Bun.serve` wrapped around this closure, so the
+ * standalone (R1) and hosted surfaces are the SAME code — there is no second HTTP adaptation
+ * to drift.
+ *
+ * WHAT IT SERVES IS UNCHANGED (R9): openai is a GENERATIVE pack, so chat/responses/embeddings
+ * answer a labeled deterministic stub or a scripted scenario — never a model, here or anywhere.
+ * The only wall-clock-shaped call on this path is `worldNow()`, the world's frozen instant.
+ *
+ * The scenario document is read ONCE, when the factory is called — the per-request path never
+ * touches storage at all. That one read goes through the ACTIVE WorldStore (runtime contract
+ * R12b), so a serverless entry MAY pass a `scenarioPath`: the handlers document is hydrated
+ * world state like any other, and a memory-backed namespace serves its own scripted answers
+ * with no filesystem in the picture (openai-serverless.test.ts pins exactly that).
+ */
+export function createOpenAITwinFetch(options: OpenAITwinFetchOptions): (request: Request) => Promise<Response> {
+  const readOnly = options.readOnly ?? false;
+  const scenarioPath = options.scenarioPath ?? process.env.TWIN_OPENAI_SCENARIO;
+  const scenarioEngine: OpenAIScenarioEngine | undefined = scenarioPath ? createOpenAIScenarioEngine(loadOpenAIScenarioDocument(scenarioPath)) : undefined;
+  return async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    // THE READ DOORS (TWIN-PROGRAMMING-MODEL): discovery + inspection, read-only.
+    if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
+      return Response.json(twinManifest({
+        vendor: 'openai',
+        twinOf: 'OpenAI API (chat completions)',
+        stateSentence: 'Seed stored completions/files through the ordinary API with any key.',
+        behaviorSentence: 'Chat completions are scripted by MSW-shaped handlers in the world dir (handlers/openai.json): {on:{userTextIncludes|anyTextIncludes|modelEquals|hasTool|toolResultFor|lastMessageIsToolResult|nthCall}, respond:{text|toolCalls, finishReason?}, once?, phase?}. Unmatched requests answer a labeled stub naming this door.',
+        exampleHandler: { on: { userTextIncludes: 'summarize', hasTool: 'file_search' }, respond: { text: 'Scripted summary.' }, once: true },
+        engine: scenarioEngine as never,
+      }));
+    }
+    if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin/scenario') {
+      return Response.json(scenarioEngine ? scenarioEngine.status() : { vendor: 'openai', handlers: [], misses: 0, recentMisses: [] });
+    }
+    const path = url.pathname + (url.search || '');
+    const cleanPath = url.pathname.replace(/\/+$/, '');
+    const contentType = request.headers.get('content-type') ?? '';
+
+    // Pass through the headers the handler models (auth 401, idempotency dedup, rate-limit
+    // trigger), lower-cased. Their presence is what makes the live wire auth/idempotency/
+    // rate-limit-aware (in-process trusted calls omit them and are not gated).
+    const passHeaders: Record<string, string> = {};
+    for (const k of ['authorization', 'idempotency-key', 'x-twin-force-rate-limit']) {
+      const v = request.headers.get(k);
+      if (v !== null) passHeaders[k] = v;
+    }
+
+    let body = '';
+    if (request.method !== 'GET') {
+      body = contentType.includes('multipart/form-data') ? await multipartToJson(request) : await request.text();
+    }
+
+    // Streaming POST → a real text/event-stream response built from the sink.
+    if (!readOnly && request.method.toUpperCase() === 'POST' && STREAMABLE.has(cleanPath) && wantsStream(body)) {
+      const stream = new ReadableStream<Uint8Array>({
+        async start(controller) {
+          const enc = new TextEncoder();
+          const sink = (e: SseEvent) => controller.enqueue(enc.encode(encodeSse(e)));
+          const { status, body: out } = await handleOpenAITwinRequest({
+            ...(scenarioEngine ? { scenarioEngine } : {}),
+            method: request.method, path, body, readOnly, occurredAt: worldNow(), headers: passHeaders,
+            ...(options.root !== undefined ? { root: options.root } : {}), sseSink: sink,
+          });
+          // A validation error before streaming → emit a single SSE data event (vendor shape).
+          if (status >= 400) controller.enqueue(enc.encode(`data: ${JSON.stringify(out)}\n\n`));
+          controller.close();
+        },
+      });
+      return new Response(stream, { headers: { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-cache', 'x-request-id': 'req_twin' } });
+    }
+
+    const { status, body: out, headers: outHeaders } = await handleOpenAITwinRequest({
+      ...(scenarioEngine ? { scenarioEngine } : {}),
+      method: request.method, path, body, readOnly,
+      occurredAt: worldNow(), headers: passHeaders,
+      ...(options.root !== undefined ? { root: options.root } : {}),
+    });
+    // File content downloads return raw text, not JSON.
+    if (request.method === 'GET' && /\/v1\/files\/[^/]+\/content$/.test(cleanPath) && typeof out === 'string') {
+      return new Response(out, { status, headers: { 'content-type': 'application/octet-stream', 'x-request-id': 'req_twin' } });
+    }
+    return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json', 'x-request-id': 'req_twin', ...(outHeaders ?? {}) } });
+  };
+}
+
+export function createOpenAITwinServer(options: { root?: string; port?: number; readOnly?: boolean; scenarioPath?: string }): { port: number; stop: () => void } {
+  const server = Bun.serve({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createOpenAITwinFetch(options),
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

package/src/openai-stub.ts

@@ -0,0 +1,247 @@
+// THE GENERATIVE-STUB CORE (the honest carve-outs).
+//
+// The twin CANNOT run the model — there are no weights here. So `POST /v1/chat/completions`
+// and `POST /v1/responses` return a DETERMINISTIC STUB completion that is CLEARLY a twin stub,
+// NEVER pretending to be real model output. `POST /v1/embeddings` returns DETERMINISTIC
+// pseudo-vectors (seeded from the input hash) — never real embedding values. What IS faithful
+// is the ENTIRE PROTOCOL ENVELOPE: the response shape, streaming chunk sequence, tool_calls
+// shape, finish_reason, and deterministic token counts.
+//
+// Surfaced as `openai.chat.inference` + `openai.embeddings.real_vectors` (out of scope) in the
+// capability manifest and the README ## Coverage: the protocol is real; the generation is a stub.
+
+import type { ChatMessageParam, ChatToolCall } from './openai-types.ts';
+
+/** Deterministic token estimate for a string: ~1 token per 4 chars (faithful order of
+ *  magnitude; deterministic so usage counts are assertable, like the vendor's tokenizer on a
+ *  fixed input). Never zero for non-empty text. */
+export function estimateTokens(text: string): number {
+  if (!text) return 0;
+  return Math.max(1, Math.ceil(text.length / 4));
+}
+
+/** Flatten a chat message's content (string OR content-part array) to its text for token
+ *  counting / echo. Non-text parts contribute their JSON length so the count is deterministic
+ *  and reflects payload size. */
+export function contentToText(content: ChatMessageParam['content']): string {
+  if (typeof content === 'string') return content;
+  if (content === null || content === undefined) return '';
+  if (!Array.isArray(content)) return '';
+  return content
+    .map((part) => {
+      if (part && typeof part === 'object' && (part as { type?: string }).type === 'text') {
+        return String((part as { text?: unknown }).text ?? '');
+      }
+      return JSON.stringify(part);
+    })
+    .join('\n');
+}
+
+/** Deterministic prompt-token count for the full set of messages. */
+export function countPromptTokens(messages: ChatMessageParam[]): number {
+  let total = 0;
+  for (const m of messages) {
+    total += estimateTokens(contentToText(m.content));
+    if (m.name) total += estimateTokens(m.name);
+    for (const tc of m.tool_calls ?? []) total += estimateTokens(JSON.stringify(tc));
+  }
+  return total;
+}
+
+/** The last user turn's text — the thing the stub echoes (deterministic, clearly labeled). */
+export function lastUserText(messages: ChatMessageParam[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i]!.role === 'user') return contentToText(messages[i]!.content);
+  }
+  // No user turn (e.g. only system) → fall back to the last message's text.
+  return messages.length ? contentToText(messages[messages.length - 1]!.content) : '';
+}
+
+/**
+ * Build the deterministic stub ASSISTANT text. It is unmistakably a twin stub: it carries the
+ * `[twin-stub:<model>]` marker and echoes the prompt, so no caller can mistake it for real
+ * model output. Deterministic for a given prompt → assertable in tests.
+ */
+export function stubAssistantText(messages: ChatMessageParam[], model: string): string {
+  const prompt = lastUserText(messages).trim();
+  const echo = prompt.length > 200 ? `${prompt.slice(0, 200)}…` : prompt;
+  return `[twin-stub:${model}] This is a deterministic stub from the OpenAI twin (no model weights are run). Echoing your last message: ${echo || '(empty)'}`;
+}
+
+/** Extract a tool's function name from either a Chat Completions tool
+ *  (`{ type:'function', function:{ name } }`) or a legacy `functions` entry (`{ name }`). */
+function toolName(t: unknown): string {
+  const o = t as { function?: { name?: unknown }; name?: unknown } | undefined;
+  if (o?.function && typeof o.function.name === 'string') return o.function.name;
+  if (typeof o?.name === 'string') return o.name;
+  return 'unknown_function';
+}
+
+function placeholderForSchema(def: unknown): unknown {
+  const d = def as { type?: unknown; enum?: unknown[] } | undefined;
+  if (Array.isArray(d?.enum) && d!.enum!.length) return d!.enum![0];
+  switch (d?.type) {
+    case 'number':
+    case 'integer': return 0;
+    case 'boolean': return false;
+    case 'array': return [];
+    case 'object': return {};
+    default: return '';
+  }
+}
+
+/**
+ * Build a deterministic stub argument string for a tool. When the tool declares a JSON-schema
+ * `parameters` object (especially with `strict:true`), real models emit arguments that validate
+ * against the schema; the twin synthesizes a deterministic object containing every declared
+ * property with a type-appropriate placeholder so `strict` callers parse it cleanly.
+ */
+export function stubToolArguments(tool: unknown): string {
+  const o = tool as { function?: { parameters?: unknown }; parameters?: unknown } | undefined;
+  const schema = (o?.function?.parameters ?? o?.parameters) as { properties?: Record<string, unknown> } | undefined;
+  const props = schema && typeof schema === 'object' ? schema.properties : undefined;
+  if (!props || typeof props !== 'object') return '{}';
+  const out: Record<string, unknown> = {};
+  for (const [key, def] of Object.entries(props)) out[key] = placeholderForSchema(def);
+  return JSON.stringify(out);
+}
+
+/**
+ * When tools/functions are provided, real models may respond with `tool_calls` and
+ * `finish_reason:'tool_calls'`. The stub deterministically "calls" the tool selected by
+ * `forcedName` (a named tool_choice) or the FIRST provided tool. Arguments are synthesized
+ * from the tool's JSON schema so strict callers parse them — clearly a stub, but a
+ * vendor-faithful tool_calls envelope. Returns the tool_call, or null when no tools provided.
+ */
+export function stubToolCall(tools: unknown, seq: number, forcedName?: string): ChatToolCall | null {
+  if (!Array.isArray(tools) || tools.length === 0) return null;
+  const chosen = forcedName ? (tools.find((t) => toolName(t) === forcedName) ?? tools[0]) : tools[0];
+  return { id: `call_twin_${seq}`, type: 'function', function: { name: toolName(chosen), arguments: stubToolArguments(chosen) } };
+}
+
+/**
+ * Build a deterministic JSON-object stub for `response_format` json_object / json_schema. The
+ * model's job is to emit parseable JSON; the twin returns a clearly-labeled deterministic object
+ * (and, for json_schema, fills every declared property with a schema-typed placeholder so the
+ * caller's strict parse succeeds). Always valid JSON.
+ */
+export function stubJsonObject(messages: ChatMessageParam[], model: string, jsonSchema?: unknown): string {
+  const schema = jsonSchema as { schema?: { properties?: Record<string, unknown> }; properties?: Record<string, unknown> } | undefined;
+  const props = schema?.schema?.properties ?? schema?.properties;
+  if (props && typeof props === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [key, def] of Object.entries(props)) out[key] = placeholderForSchema(def);
+    return JSON.stringify(out);
+  }
+  return JSON.stringify({ _twin_stub: true, model, echo: lastUserText(messages).slice(0, 200) });
+}
+
+// ── Logprobs (deterministic pseudo-logprobs) ────────────────────────────────────────────
+/** The per-token logprob shape OpenAI returns in `choices[].logprobs.content[]`. */
+export type LogprobToken = {
+  token: string;
+  logprob: number;
+  bytes: number[];
+  top_logprobs: Array<{ token: string; logprob: number; bytes: number[] }>;
+};
+
+/** A whitespace-preserving token split: deterministic chunks of the stub text whose `token`
+ *  fields re-join into the exact text. NOT a real BPE tokenizer. */
+function splitForLogprobs(text: string): string[] {
+  if (!text) return [];
+  return text.match(/\s+|\S+/g) ?? [];
+}
+
+/**
+ * Build deterministic pseudo-logprobs for the stub completion text. Real models return a per-token
+ * logprob (a negative number) plus `top_logprobs` alternatives; the twin synthesizes a deterministic
+ * negative logprob per token (seeded from the token text) and `topN` alternatives. NOT real
+ * probabilities — the SHAPE and DETERMINISM are faithful, the values carry no model meaning.
+ * Re-joining `content[].token` reconstructs the full text exactly.
+ */
+export function buildLogprobs(text: string, topN: number): { content: LogprobToken[] } {
+  const tokens = splitForLogprobs(text);
+  const content: LogprobToken[] = tokens.map((tok) => {
+    const seed = fnv1a(tok);
+    const lp = -((seed % 5000) / 1000); // deterministic logprob in (-5, 0]
+    const bytes = Array.from(new TextEncoder().encode(tok));
+    const top: LogprobToken['top_logprobs'] = [{ token: tok, logprob: lp, bytes }];
+    for (let i = 0; i < topN; i++) {
+      const altSeed = fnv1a(`${tok}#${i}`);
+      top.push({ token: `«alt${i}»`, logprob: lp - 1 - (altSeed % 3000) / 1000, bytes: [] });
+    }
+    return { token: tok, logprob: lp, bytes, top_logprobs: top.slice(0, Math.max(1, topN)) };
+  });
+  return { content };
+}
+
+// ── Embeddings: deterministic pseudo-vectors ────────────────────────────────────────────
+/** A small deterministic 32-bit hash (FNV-1a) of a string — the seed for a pseudo-vector. */
+function fnv1a(text: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+/** A deterministic, reproducible L2-normalized pseudo-embedding vector for `text`. NOT a real
+ *  embedding — the values carry no semantic meaning; only the SHAPE and DETERMINISM are
+ *  faithful (the `openai.embeddings.real_vectors` carve-out). Same text → same vector. */
+export function pseudoEmbedding(text: string, dimensions: number): number[] {
+  const dim = Math.max(1, Math.floor(dimensions));
+  let state = fnv1a(text) || 1;
+  const raw = new Array<number>(dim);
+  let norm = 0;
+  for (let i = 0; i < dim; i++) {
+    // xorshift32 PRNG seeded from the text hash → deterministic per (text, index).
+    state ^= state << 13; state >>>= 0;
+    state ^= state >> 17;
+    state ^= state << 5; state >>>= 0;
+    // map to [-1, 1)
+    const v = (state / 0xffffffff) * 2 - 1;
+    raw[i] = v;
+    norm += v * v;
+  }
+  norm = Math.sqrt(norm) || 1;
+  for (let i = 0; i < dim; i++) raw[i] = raw[i]! / norm;
+  return raw;
+}
+
+// ── Moderations: deterministic classifier ───────────────────────────────────────────────
+/** The moderation categories the twin reports (faithful key set). */
+export const MODERATION_CATEGORIES = [
+  'hate', 'hate/threatening', 'harassment', 'harassment/threatening',
+  'self-harm', 'self-harm/intent', 'self-harm/instructions',
+  'sexual', 'sexual/minors', 'violence', 'violence/graphic',
+] as const;
+
+// Deterministic keyword → category map. The twin can't run the real classifier, so it flags
+// on a fixed keyword list (clearly a heuristic). Shape is faithful; the decision is a stub.
+const MODERATION_KEYWORDS: Record<string, string> = {
+  kill: 'violence', murder: 'violence', attack: 'violence',
+  hate: 'hate', hateful: 'hate',
+  harass: 'harassment',
+  suicide: 'self-harm', 'self-harm': 'self-harm',
+};
+
+export type ModerationResult = {
+  flagged: boolean;
+  categories: Record<string, boolean>;
+  category_scores: Record<string, number>;
+  category_applied_input_types?: Record<string, string[]>;
+};
+
+/** Deterministically moderate one input string into the faithful result shape. */
+export function moderateText(text: string): ModerationResult {
+  const lower = text.toLowerCase();
+  const categories: Record<string, boolean> = {};
+  const scores: Record<string, number> = {};
+  for (const c of MODERATION_CATEGORIES) { categories[c] = false; scores[c] = 0; }
+  let flagged = false;
+  for (const [kw, cat] of Object.entries(MODERATION_KEYWORDS)) {
+    if (lower.includes(kw)) { categories[cat] = true; scores[cat] = 0.99; flagged = true; }
+  }
+  return { flagged, categories, category_scores: scores };
+}