@volter/twin-openai 0.1.1 → 2.0.0

package/src/openai-server.ts

@@ -3,68 +3,35 @@
 // (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).
+// Streaming: a chat completion or response with `"stream": true` is answered by its semantics
+// handler as server-sent events in OpenAI's `data: <json>\n\n` framing, ending `data: [DONE]`
+// (the manifest's framing); a failure decided before the stream answers JSON with its status.
 //
 // 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 { bindSemantics, coreFor, createDerivedFetch, crossCutting, semanticsContext, serveHttp, vendorError } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from './manifest.ts';
+import { openaiSemantics } from './semantics/index.ts';
+import { answerVendorErrors, RefusedWriteError } from '@volter/world-core';
+import { twinManifest } from '@volter/world-core';
 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 '{}';
-  }
-}
+import { openaiApiKeysScreen, projectKeyUse } from './screens/api-keys.tsx';
+import { openaiSessionFlow } from './screens/session.tsx';
+import { expireFiles } from './semantics/files.ts';
+import { observeBatches } from './semantics/batches.ts';
+import { observeJobs } from './semantics/fine-tuning.ts';
 
 /** Options every OpenAI-twin HTTP surface needs, independent of who owns the socket. */
 export interface OpenAITwinFetchOptions {
   root?: string;
   readOnly?: boolean;
   scenarioPath?: string;
+  /** a scenario engine already built (an in-process caller's), in place of `scenarioPath` */
+  scenarioEngine?: OpenAIScenarioEngine;
+  /** the World instant, when a caller pins it */
+  clock?: () => string;
 }
 
 /**
@@ -89,11 +56,14 @@ export interface OpenAITwinFetchOptions {
 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 scenarioEngine: OpenAIScenarioEngine | undefined = options.scenarioEngine ?? (scenarioPath ? createOpenAIScenarioEngine(loadOpenAIScenarioDocument(scenarioPath)) : undefined);
+  const scope = { ...(options.root !== undefined ? { root: options.root } : {}), ...(options.clock ? { clock: options.clock } : {}) };
+  // THE READ DOORS (TWIN-PROGRAMMING-MODEL): discovery + inspection, read-only.
+  const door = (request: Request): Response | undefined => {
     const url = new URL(request.url);
-    // THE READ DOORS (TWIN-PROGRAMMING-MODEL): discovery + inspection, read-only.
-    if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
+    if (request.method !== 'GET') return undefined;
+    const path = url.pathname.replace(/\/+$/, '');
+    if (path === '/twin') {
       return Response.json(twinManifest({
         vendor: 'openai',
         twinOf: 'OpenAI API (chat completions)',
@@ -103,62 +73,49 @@ export function createOpenAITwinFetch(options: OpenAITwinFetchOptions): (request
         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 ?? {}) } });
+    if (path === '/twin/scenario') return Response.json(scenarioEngine ? scenarioEngine.status() : { vendor: 'openai', handlers: [], misses: 0, recentMisses: [] });
+    return undefined;
+  };
+  // a refused or failed write at the head (kernel head.ts) answers in the vendor's own error shape
+  // The derived dispatch owns the wire: semantics handlers, then the derived core for resources the
+  // manifest declares; an operation neither models answers OpenAI's unknown-URL 404.
+  const inner = createDerivedFetch({
+    surface,
+    handlers: bindSemantics(manifest, openaiSemantics({ ...(scenarioEngine ? { scenarioEngine } : {}), readOnly }), scope),
+    core: coreFor(manifest, scope),
+    around: crossCutting(manifest, { readOnly, ...scope }),
+    gap: (request) => vendorError(manifest, { status: 404, message: `Unknown request URL: ${request.method} ${new URL(request.url).pathname}. Please check the URL for typos.` }),
+  });
+  const handle = answerVendorErrors(inner, (error) => Response.json({ error: { message: error.message, type: error instanceof RefusedWriteError ? 'invalid_request_error' : 'server_error', param: null, code: error instanceof RefusedWriteError ? 'refused' : 'vendor_failed' } }, { status: error instanceof RefusedWriteError ? 400 : 502 }));
+  // OpenAI's own pages sit beside the API: the log-in (and the World's account door), and the dashboard's API keys page,
+  // where a project's keys are made
+  const screens = [openaiSessionFlow(scope), openaiApiKeysScreen(scope)];
+  // which part serves each spec operation (the derived dispatch's owners), for the pack's report
+  // (a scenario's authoring failure is answered where the scenario is served: openai-scenario.ts)
+  // time's moves OpenAI makes on its own (a file expiring: semantics/files.ts) are caught up to the World's clock
+  // before anything is answered, so every door reads the organization as it stands now
+  const filesClock = (surface.operations as Array<{ id: string; method: string; path: string; class: string }>).find((o) => o.id === 'listFiles')!;
+  // a project key presented to the API is used: its last use is recorded, and a revoked one refused (screens/api-keys.tsx)
+  const useKey = projectKeyUse(scope);
+  // and a read of the files observes the work whose outputs are files (a batch's output, a fine-tuning job's results)
+  // first, as a read of that batch or job does: the files a read lists never depend on which other read came before it
+  const catchUp = async (request: Request): Promise<void> => {
+    const ctx = await semanticsContext(manifest, new Request(request.url), filesClock, scope);
+    await expireFiles(ctx);
+    if (request.method === 'GET' && /^\/v1\/files(\/|$)/.test(new URL(request.url).pathname)) for (const observe of [observeBatches, observeJobs]) await observe(ctx);
   };
+  return Object.assign(async (request: Request): Promise<Response> => {
+    const opened = door(request);
+    if (opened) return opened;
+    if (!readOnly) await catchUp(request);
+    if (!readOnly) { const refused = await useKey(request); if (refused) return refused; }
+    if (!readOnly) for (const screen of screens) { const page = await screen(request); if (page) return page; }
+    return handle(request);
+  }, { owners: inner.owners });
 }
 
-export function createOpenAITwinServer(options: { root?: string; port?: number; readOnly?: boolean; scenarioPath?: string }): { port: number; stop: () => void } {
-  const server = Bun.serve({
+export async function createOpenAITwinServer(options: { root?: string; port?: number; readOnly?: boolean; scenarioPath?: string }): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
     port: options.port ?? 0,
     idleTimeout: 60,
     fetch: createOpenAITwinFetch(options),

package/src/openai-stub.ts

@@ -1,4 +1,4 @@
-// THE GENERATIVE-STUB CORE (the honest carve-outs).
+// THE GENERATIVE-STUB CORE (the twin's answer to generation).
 //
 // 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,
@@ -7,7 +7,7 @@
 // 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
+// Pinned by `openai.chat.stub_labeled` and `openai.embeddings.deterministic` in the manifest.
 // capability manifest and the README ## Coverage: the protocol is real; the generation is a stub.
 
 import type { ChatMessageParam, ChatToolCall } from './openai-types.ts';
@@ -50,11 +50,9 @@ export function countPromptTokens(messages: ChatMessageParam[]): number {
 
 /** 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) : '';
+  const turn = [...messages].reverse().find((m) => m.role === 'user') ?? messages.at(-1);
+  return turn ? contentToText(turn.content) : '';
 }
 
 /**
@@ -72,9 +70,7 @@ export function stubAssistantText(messages: ChatMessageParam[], model: string):
  *  (`{ 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';
+  return o?.function && typeof o.function.name === 'string' ? o.function.name : typeof o?.name === 'string' ? o.name : 'unknown_function';
 }
 
 function placeholderForSchema(def: unknown): unknown {
@@ -90,19 +86,40 @@ function placeholderForSchema(def: unknown): unknown {
   }
 }
 
+// Words that name nothing a tool could take as a value.
+const STOPWORDS = new Set(['a', 'an', 'the', 'do', 'does', 'you', 'your', 'have', 'has', 'is', 'are', 'for', 'me', 'my', 'please', 'this', 'that', 'one', 'like', 'with', 'what', 'which', 'how', 'can', 'could', 'would', 'and', 'or', 'of', 'to', 'in', 'on', 'it', 'its', 'small', 'large', 'big', 'some', 'any']);
+
+/** The value the user's message names for a string parameter: its longest content word (the thing asked about: "Do you
+ *  have a small monstera?" names `monstera`), or none. */
+function namedIn(userText: string): string | undefined {
+  // a link the message carries (an image's URL) is not what it asks about
+  const words = (userText.replace(/\S+:\/\/\S+/g, ' ').toLowerCase().match(/[a-z][a-z0-9-]*/g) ?? []).filter((w) => !STOPWORDS.has(w));
+  return words.reduce<string | undefined>((best, w) => (!best || w.length > best.length ? w : best), undefined);
+}
+
 /**
  * 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.
+ * property with a type-appropriate placeholder so `strict` callers parse it cleanly. A required
+ * string is never left empty: an empty value is schema-valid in type but names nothing, so an
+ * application's tool could not act on it and a story could not follow the call. It takes what the
+ * user's message names (`namedIn`), else a deterministic value of the parameter's own name; an enum
+ * takes the value the message names, else its first.
  */
-export function stubToolArguments(tool: unknown): string {
+export function stubToolArguments(tool: unknown, userText = ''): 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 schema = (o?.function?.parameters ?? o?.parameters) as { properties?: Record<string, unknown>; required?: unknown } | undefined;
   const props = schema && typeof schema === 'object' ? schema.properties : undefined;
   if (!props || typeof props !== 'object') return '{}';
+  const required = new Set(Array.isArray(schema!.required) ? schema!.required.map(String) : []);
+  const words = new Set(userText.toLowerCase().match(/[a-z0-9-]+/g) ?? []);
   const out: Record<string, unknown> = {};
-  for (const [key, def] of Object.entries(props)) out[key] = placeholderForSchema(def);
+  for (const [key, def] of Object.entries(props)) {
+    const d = def as { type?: unknown; enum?: unknown[] } | undefined;
+    const named = Array.isArray(d?.enum) ? d!.enum!.find((e) => typeof e === 'string' && words.has(e.toLowerCase())) : undefined;
+    out[key] = named ?? (required.has(key) && d?.type === 'string' && !Array.isArray(d?.enum) ? namedIn(userText) ?? `twin-${key}` : placeholderForSchema(def));
+  }
   return JSON.stringify(out);
 }
 
@@ -113,10 +130,10 @@ export function stubToolArguments(tool: unknown): string {
  * 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 {
+export function stubToolCall(tools: unknown, seq: number, forcedName?: string, userText = ''): 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) } };
+  return { id: `call_twin_${seq}`, type: 'function', function: { name: toolName(chosen), arguments: stubToolArguments(chosen, userText) } };
 }
 
 /**
@@ -128,11 +145,14 @@ export function stubToolCall(tools: unknown, seq: number, forcedName?: string):
 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);
-  }
+  if (!props || typeof props !== 'object') return freeformJson(messages, model);
+  const out: Record<string, unknown> = {};
+  for (const [key, def] of Object.entries(props)) out[key] = placeholderForSchema(def);
+  return JSON.stringify(out);
+}
+
+/** JSON mode with no schema (`json_object`): a labeled object echoing the request. */
+function freeformJson(messages: ChatMessageParam[], model: string): string {
   return JSON.stringify({ _twin_stub: true, model, echo: lastUserText(messages).slice(0, 200) });
 }
 
@@ -165,11 +185,8 @@ export function buildLogprobs(text: string, topN: number): { content: LogprobTok
     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: [] });
-    }
+    // the token itself, then `topN` labeled alternatives, each less likely
+    const top: LogprobToken['top_logprobs'] = [{ token: tok, logprob: lp, bytes }, ...Array.from({ length: topN }, (_, i) => ({ token: `«alt${i}»`, logprob: lp - 1 - (fnv1a(`${tok}#${i}`) % 3000) / 1000, bytes: [] as number[] }))];
     return { token: tok, logprob: lp, bytes, top_logprobs: top.slice(0, Math.max(1, topN)) };
   });
   return { content };
@@ -188,7 +205,7 @@ function fnv1a(text: string): number {
 
 /** 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. */
+ *  faithful (`openai.embeddings.deterministic`). 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;
@@ -212,10 +229,13 @@ export function pseudoEmbedding(text: string, dimensions: number): number[] {
 // ── Moderations: deterministic classifier ───────────────────────────────────────────────
 /** The moderation categories the twin reports (faithful key set). */
 export const MODERATION_CATEGORIES = [
-  'hate', 'hate/threatening', 'harassment', 'harassment/threatening',
+  'hate', 'hate/threatening', 'harassment', 'harassment/threatening', 'illicit', 'illicit/violent',
   'self-harm', 'self-harm/intent', 'self-harm/instructions',
   'sexual', 'sexual/minors', 'violence', 'violence/graphic',
 ] as const;
+/** The categories an image is classified in besides text (the spec's `category_applied_input_types`; the moderation
+ *  guide, https://platform.openai.com/docs/guides/moderation). */
+const IMAGE_CATEGORIES = new Set(['self-harm', 'self-harm/intent', 'self-harm/instructions', 'sexual', 'violence', 'violence/graphic']);
 
 // 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.
@@ -233,8 +253,10 @@ export type ModerationResult = {
   category_applied_input_types?: Record<string, string[]>;
 };
 
-/** Deterministically moderate one input string into the faithful result shape. */
-export function moderateText(text: string): ModerationResult {
+/** Deterministically moderate one input (its text, and whether it held an image) into the faithful result shape: each
+ *  category with the input types its score applies to, as every result carries them
+ *  (https://platform.openai.com/docs/api-reference/moderations/object). */
+export function moderateText(text: string, image = false): ModerationResult {
   const lower = text.toLowerCase();
   const categories: Record<string, boolean> = {};
   const scores: Record<string, number> = {};
@@ -243,5 +265,7 @@ export function moderateText(text: string): ModerationResult {
   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 };
+  const applied: Record<string, string[]> = {};
+  for (const c of MODERATION_CATEGORIES) applied[c] = image && IMAGE_CATEGORIES.has(c) ? ['text', 'image'] : ['text'];
+  return { flagged, categories, category_scores: scores, category_applied_input_types: applied };
 }