@volter/world-core 2.0.37 → 3.0.1

package/dist/src/openai-wire.js

@@ -0,0 +1,337 @@
+import { sampleFromSchema } from "./schema-sample.js";
+const obj = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : {});
+const arr = (v) => (Array.isArray(v) ? v : []);
+/** Tokens, estimated at about four characters a token: a twin's count, not a tokenizer's. */
+export const estimateTokens = (text) => Math.max(1, Math.ceil(text.length / 4));
+// ── chat completions: requests ─────────────────────────────────────────────────────────────────
+/** A message's content as text: a string, or its text parts joined. */
+export const chatText = (content) => (typeof content === 'string' ? content : arr(content).map((p) => (typeof p.text === 'string' ? p.text : '')).join(''));
+/** The last user message's text. */
+export function chatLastUserText(messages) {
+    for (let i = messages.length - 1; i >= 0; i--)
+        if (messages[i].role === 'user')
+            return chatText(messages[i].content);
+    return '';
+}
+/** The tool results the last message carries (a `tool` message), by its name or call id. */
+export const chatToolResults = (messages) => (messages.at(-1)?.role === 'tool' ? [String(messages.at(-1).name ?? messages.at(-1).tool_call_id ?? '')] : []);
+/** The labeled stub for a chat request: with tools offered (`tool_choice` not `none`) and the last message not a tool's
+ *  result, it calls the tool the choice names, else the first, with arguments its schema admits; with a JSON response
+ *  format, it answers a value the schema admits; otherwise it echoes the last user message. `label` names the twin. */
+export function chatStubTurn(body, label) {
+    const model = String(body.model);
+    const messages = arr(body.messages);
+    const tools = arr(body.tools).filter((t) => obj(t.function).name !== undefined);
+    const choice = body.tool_choice ?? 'auto';
+    const named = typeof choice === 'object' ? String(obj(obj(choice).function).name ?? '') : '';
+    if (tools.length && choice !== 'none' && (chatToolResults(messages).length === 0 || choice === 'required' || named)) {
+        const f = obj(((named ? tools.find((t) => obj(t.function).name === named) : undefined) ?? tools[0]).function);
+        return { toolCalls: [{ name: String(f.name), arguments: sampleFromSchema(f.parameters, String(f.name)) }] };
+    }
+    const format = obj(body.response_format);
+    if (format.type === 'json_schema')
+        return { text: JSON.stringify(sampleFromSchema(obj(format.json_schema).schema)) };
+    if (format.type === 'json_object')
+        return { text: JSON.stringify({ twin_stub: `deterministic stub from the ${label} (${model}): no model runs` }) };
+    const said = chatLastUserText(messages).trim();
+    return { text: `[twin-stub:${model}] This is a deterministic stub from the ${label} (no model runs). Your last message: ${said.length > 200 ? `${said.slice(0, 200)}…` : said || '(empty)'}` };
+}
+function chatParts(s) {
+    let text = s.turn.text ?? null;
+    let finish = s.turn.finishReason ?? (s.turn.toolCalls?.length ? 'tool_calls' : 'stop');
+    if (text !== null && s.maxTokens !== undefined && estimateTokens(text) > s.maxTokens) {
+        text = text.slice(0, s.maxTokens * 4);
+        finish = 'length';
+    }
+    const calls = (s.turn.toolCalls ?? []).map((c, i) => ({ id: s.callId(i), type: 'function', function: { name: c.name, arguments: JSON.stringify(c.arguments ?? {}) } }));
+    const reasoning = s.turn.reasoning ?? null;
+    const prompt = estimateTokens(s.messages.map((m) => chatText(m.content)).join('\n'));
+    const completion = estimateTokens([text ?? '', ...calls.map((c) => c.function.arguments)].join(''));
+    const reasoningTokens = reasoning ? estimateTokens(reasoning) : 0;
+    const usage = {
+        prompt_tokens: prompt, completion_tokens: completion + reasoningTokens, total_tokens: prompt + completion + reasoningTokens,
+        prompt_tokens_details: { cached_tokens: 0 }, completion_tokens_details: { reasoning_tokens: reasoningTokens }, ...(s.usageExtra ?? {}),
+    };
+    return { text, finish, calls, usage, reasoning };
+}
+/** A chat completion's body (`object: chat.completion`), one choice. */
+export function chatCompletion(s) {
+    const p = chatParts(s);
+    const field = s.reasoningField ?? 'reasoning';
+    const message = { role: 'assistant', content: p.text, refusal: null, ...(p.reasoning ? { [field]: p.reasoning } : {}), ...(p.calls.length ? { tool_calls: p.calls } : {}) };
+    return {
+        id: s.id, ...(s.extra ?? {}), model: s.model, object: 'chat.completion', created: s.created,
+        choices: [{ index: 0, message, logprobs: null, finish_reason: p.finish, ...(s.nativeFinish ? { native_finish_reason: p.finish } : {}) }], usage: p.usage,
+    };
+}
+/** A chat completion streamed: its chunks (`object: chat.completion.chunk`) as Server-Sent Events, the text in two
+ *  deltas, the last chunk carrying the finish reason and the usage, then `data: [DONE]`. `comment` is a keep-alive a
+ *  vendor sends first (OpenRouter's `: OPENROUTER PROCESSING`). */
+export function chatCompletionSSE(s) {
+    const p = chatParts(s);
+    const field = s.reasoningField ?? 'reasoning';
+    const chunk = (delta, last) => `data: ${JSON.stringify({
+        id: s.id, ...((last ? s.extra : s.interimExtra ?? s.extra) ?? {}), model: s.model, object: 'chat.completion.chunk', created: s.created,
+        choices: [{ index: 0, delta, logprobs: null, finish_reason: last ? p.finish : null, ...(s.nativeFinish ? { native_finish_reason: last ? p.finish : null } : {}) }],
+        ...(last ? { usage: p.usage } : {}),
+    })}\n\n`;
+    const half = p.text ? Math.ceil(p.text.length / 2) : 0;
+    return [
+        ...(s.comment ? [`: ${s.comment}\n\n`] : []),
+        ...(p.reasoning ? [chunk({ role: 'assistant', content: '', [field]: p.reasoning }, false)] : []),
+        ...(p.text ? [chunk({ role: 'assistant', content: p.text.slice(0, half) }, false), ...(p.text.length > half ? [chunk({ content: p.text.slice(half) }, false)] : [])] : []),
+        ...(p.calls.length ? [chunk({ role: 'assistant', content: null, tool_calls: p.calls.map((c, i) => ({ index: i, ...c })) }, false)] : []),
+        chunk({}, true),
+        'data: [DONE]\n\n',
+    ].join('');
+}
+// ── the AI SDK's language-model protocol (Vercel's AI Gateway) ─────────────────────────────────────
+// `@ai-sdk/gateway` posts a model call's options as `@ai-sdk/provider`'s LanguageModelV4 defines them (the model in the
+// `ai-language-model-id` header) and reads back its generate result, or its stream parts as Server-Sent Events
+// (https://unpkg.com/@ai-sdk/provider@4.0.14/dist/index.d.ts, `LanguageModelV4GenerateResult`, `LanguageModelV4StreamPart`).
+/** A V4 call's options as the chat completions request they mean: its prompt as messages, its tools, tool choice,
+ *  response format and output limit; so the chat stub and the wire's scenario read it. */
+export function aiSdkChatBody(call, model) {
+    const text = (content) => (typeof content === 'string' ? content : arr(content).filter((p) => p.type === 'text' || p.type === 'reasoning').map((p) => String(p.text ?? '')).join(''));
+    const messages = [];
+    for (const m of arr(call.prompt)) {
+        if (m.role === 'tool')
+            for (const r of arr(m.content).filter((p) => p.type === 'tool-result'))
+                messages.push({ role: 'tool', tool_call_id: r.toolCallId, name: r.toolName, content: JSON.stringify(r.output ?? null) });
+        else if (m.role === 'assistant') {
+            const calls = arr(m.content).filter((p) => p.type === 'tool-call').map((c) => ({ id: c.toolCallId, type: 'function', function: { name: c.toolName, arguments: typeof c.input === 'string' ? c.input : JSON.stringify(c.input ?? {}) } }));
+            messages.push({ role: 'assistant', content: text(m.content), ...(calls.length ? { tool_calls: calls } : {}) });
+        }
+        else
+            messages.push({ role: String(m.role ?? 'user'), content: text(m.content) });
+    }
+    const tools = arr(call.tools).filter((x) => x.type === 'function').map((x) => ({ type: 'function', function: { name: x.name, description: x.description, parameters: x.inputSchema } }));
+    const choice = obj(call.toolChoice);
+    const format = obj(call.responseFormat);
+    return {
+        model, messages,
+        ...(tools.length ? { tools } : {}),
+        ...(choice.type === 'tool' ? { tool_choice: { type: 'function', function: { name: choice.toolName } } } : typeof choice.type === 'string' ? { tool_choice: choice.type } : {}),
+        ...(format.type === 'json' ? { response_format: format.schema ? { type: 'json_schema', json_schema: { name: format.name ?? 'response', schema: format.schema } } : { type: 'json_object' } } : {}),
+        ...(typeof call.maxOutputTokens === 'number' ? { max_tokens: call.maxOutputTokens } : {}),
+    };
+}
+const UNIFIED = { stop: 'stop', length: 'length', tool_calls: 'tool-calls', content_filter: 'content-filter' };
+function lmParts(s) {
+    const p = chatParts(s);
+    const u = p.usage;
+    return {
+        content: [
+            ...(p.reasoning ? [{ type: 'reasoning', text: p.reasoning }] : []),
+            ...(p.text !== null ? [{ type: 'text', text: p.text }] : []),
+            ...p.calls.map((c) => ({ type: 'tool-call', toolCallId: c.id, toolName: c.function.name, input: c.function.arguments })),
+        ],
+        finishReason: { unified: UNIFIED[p.finish] ?? 'other', raw: p.finish },
+        usage: {
+            inputTokens: { total: u.prompt_tokens, noCache: u.prompt_tokens, cacheRead: 0, cacheWrite: 0 },
+            outputTokens: { total: u.completion_tokens, text: u.completion_tokens - u.completion_tokens_details.reasoning_tokens, reasoning: u.completion_tokens_details.reasoning_tokens },
+        },
+    };
+}
+/** A V4 generate result: the turn's content (reasoning, text, tool calls with their input as JSON text), its finish
+ *  reason (unified, and the raw one) and its usage; `extra` is what the server adds (the gateway's provider metadata). */
+export function languageModelResult(s) {
+    const r = lmParts(s);
+    return { ...r, response: { id: s.id, modelId: s.model, timestamp: new Date(s.created * 1000).toISOString() }, warnings: [], ...(s.extra ?? {}) };
+}
+/** A V4 stream: its parts as Server-Sent Events (stream-start, response-metadata, the reasoning, the text in two deltas,
+ *  each tool call's input then the call, and the finish), with no `[DONE]`: the SDK reads every event as a part. */
+export function languageModelSSE(s) {
+    const r = lmParts(s);
+    const out = [{ type: 'stream-start', warnings: [] }, { type: 'response-metadata', id: s.id, modelId: s.model, timestamp: new Date(s.created * 1000).toISOString() }];
+    for (const [i, c] of r.content.entries()) {
+        if (c.type === 'reasoning')
+            out.push({ type: 'reasoning-start', id: `reasoning-${i}` }, { type: 'reasoning-delta', id: `reasoning-${i}`, delta: c.text }, { type: 'reasoning-end', id: `reasoning-${i}` });
+        else if (c.type === 'text') {
+            const text = String(c.text);
+            const half = Math.ceil(text.length / 2);
+            out.push({ type: 'text-start', id: `text-${i}` }, { type: 'text-delta', id: `text-${i}`, delta: text.slice(0, half) }, ...(text.length > half ? [{ type: 'text-delta', id: `text-${i}`, delta: text.slice(half) }] : []), { type: 'text-end', id: `text-${i}` });
+        }
+        else
+            out.push({ type: 'tool-input-start', id: c.toolCallId, toolName: c.toolName }, { type: 'tool-input-delta', id: c.toolCallId, delta: c.input }, { type: 'tool-input-end', id: c.toolCallId }, c);
+    }
+    out.push({ type: 'finish', finishReason: r.finishReason, usage: r.usage, ...(s.extra ?? {}) });
+    return out.map((part) => `data: ${JSON.stringify(part)}\n\n`).join('');
+}
+// ── Responses: requests ────────────────────────────────────────────────────────────────────────
+/** A Responses request's input as items: a string is one user message. */
+export const responsesItems = (input) => (typeof input === 'string' ? [{ type: 'message', role: 'user', content: input }] : arr(input));
+const itemText = (content) => (typeof content === 'string' ? content : arr(content).map((p) => (typeof p.text === 'string' ? p.text : '')).join(''));
+/** The last user message's text in a Responses input. */
+export function responsesLastUserText(input) {
+    const items = responsesItems(input);
+    for (let i = items.length - 1; i >= 0; i--)
+        if ((items[i].role ?? (items[i].type === 'message' ? 'user' : '')) === 'user')
+            return itemText(items[i].content);
+    return '';
+}
+/** The function-call outputs the input ends with. */
+export const responsesToolResults = (input) => responsesItems(input).filter((i) => i.type === 'function_call_output').map((i) => String(i.call_id ?? ''));
+/** The labeled stub for a Responses request: a function tool is called (unless the input already carries its output or
+ *  `tool_choice` is `none`), a JSON schema format answers a value it admits, otherwise the last user text is echoed. */
+export function responsesStubTurn(body, label) {
+    const model = String(body.model);
+    const tools = arr(body.tools).filter((t) => t.type === 'function' && typeof t.name === 'string');
+    const choice = body.tool_choice ?? 'auto';
+    const named = typeof choice === 'object' ? String(obj(choice).name ?? '') : '';
+    if (tools.length && choice !== 'none' && (responsesToolResults(body.input).length === 0 || choice === 'required' || named)) {
+        const t = (named ? tools.find((x) => x.name === named) : undefined) ?? tools[0];
+        return { toolCalls: [{ name: String(t.name), arguments: sampleFromSchema(t.parameters, String(t.name)) }] };
+    }
+    const format = obj(obj(body.text).format);
+    if (format.type === 'json_schema')
+        return { text: JSON.stringify(sampleFromSchema(format.schema)) };
+    if (format.type === 'json_object')
+        return { text: JSON.stringify({ twin_stub: `deterministic stub from the ${label} (${model}): no model runs` }) };
+    const said = responsesLastUserText(body.input).trim();
+    return { text: `[twin-stub:${model}] This is a deterministic stub from the ${label} (no model runs). Your last message: ${said.length > 200 ? `${said.slice(0, 200)}…` : said || '(empty)'}` };
+}
+/** A Responses object (`object: response`, `status: completed`): its output items (the reasoning when there is some,
+ *  the message with its output text, or function calls) and its usage. */
+export function responsesAnswer(s) {
+    const b = s.body;
+    let text = s.turn.text ?? null;
+    const max = typeof b.max_output_tokens === 'number' ? b.max_output_tokens : undefined;
+    let incomplete = null;
+    if (text !== null && max !== undefined && estimateTokens(text) > max) {
+        text = text.slice(0, max * 4);
+        incomplete = { reason: 'max_output_tokens' };
+    }
+    const output = [
+        ...(s.turn.reasoning ? [{ type: 'reasoning', id: s.itemId('rs', 0), summary: [{ type: 'summary_text', text: s.turn.reasoning }], status: 'completed' }] : []),
+        ...(text !== null ? [{ type: 'message', id: s.itemId('msg', 0), status: incomplete ? 'incomplete' : 'completed', role: 'assistant', content: [{ type: 'output_text', text, annotations: [], logprobs: [] }] }] : []),
+        ...(s.turn.toolCalls ?? []).map((c, i) => ({ type: 'function_call', id: s.itemId('fc', i), call_id: s.itemId('call', i), name: c.name, arguments: JSON.stringify(c.arguments ?? {}), status: 'completed' })),
+    ];
+    const input = estimateTokens([String(b.instructions ?? ''), ...responsesItems(b.input).map((i) => itemText(i.content ?? i.output))].join('\n'));
+    const out = estimateTokens([text ?? '', ...(s.turn.toolCalls ?? []).map((c) => JSON.stringify(c.arguments ?? {}))].join(''));
+    const reasoningTokens = s.turn.reasoning ? estimateTokens(s.turn.reasoning) : 0;
+    return {
+        id: s.id, object: 'response', created_at: s.createdAt, status: incomplete ? 'incomplete' : 'completed', ...(s.extra ?? {}),
+        error: null, incomplete_details: incomplete, instructions: b.instructions ?? null, max_output_tokens: max ?? null, model: s.model, output,
+        parallel_tool_calls: b.parallel_tool_calls ?? true, previous_response_id: b.previous_response_id ?? null,
+        reasoning: { effort: obj(b.reasoning).effort ?? null, summary: obj(b.reasoning).summary ?? null }, store: b.store ?? true,
+        temperature: b.temperature ?? 1, text: b.text ?? { format: { type: 'text' } }, tool_choice: b.tool_choice ?? 'auto', tools: b.tools ?? [], top_p: b.top_p ?? 1,
+        usage: { input_tokens: input, input_tokens_details: { cached_tokens: 0 }, output_tokens: out + reasoningTokens, output_tokens_details: { reasoning_tokens: reasoningTokens }, total_tokens: input + out + reasoningTokens },
+        metadata: b.metadata ?? {},
+    };
+}
+/** A Responses object streamed: the events the wire sends (`response.created`, `response.in_progress`, each output
+ *  item's added, its text deltas and done, `response.completed`), each `event:` and `data:` with its sequence number. */
+export function responsesSSE(s) {
+    const done = responsesAnswer(s);
+    const pending = { ...done, status: 'in_progress', output: [], usage: null };
+    const events = [{ type: 'response.created', response: pending }, { type: 'response.in_progress', response: pending }];
+    for (const [i, item] of done.output.entries()) {
+        if (item.type === 'message') {
+            const text = String((item.content[0] ?? {}).text ?? '');
+            events.push({ type: 'response.output_item.added', output_index: i, item: { ...item, status: 'in_progress', content: [] } });
+            events.push({ type: 'response.content_part.added', item_id: item.id, output_index: i, content_index: 0, part: { type: 'output_text', text: '', annotations: [] } });
+            const half = Math.ceil(text.length / 2);
+            for (const delta of [text.slice(0, half), text.slice(half)].filter(Boolean))
+                events.push({ type: 'response.output_text.delta', item_id: item.id, output_index: i, content_index: 0, delta, logprobs: [] });
+            events.push({ type: 'response.output_text.done', item_id: item.id, output_index: i, content_index: 0, text, logprobs: [] });
+            events.push({ type: 'response.content_part.done', item_id: item.id, output_index: i, content_index: 0, part: item.content[0] });
+        }
+        else if (item.type === 'function_call') {
+            events.push({ type: 'response.output_item.added', output_index: i, item: { ...item, arguments: '', status: 'in_progress' } });
+            events.push({ type: 'response.function_call_arguments.delta', item_id: item.id, output_index: i, delta: item.arguments });
+            events.push({ type: 'response.function_call_arguments.done', item_id: item.id, output_index: i, arguments: item.arguments });
+        }
+        else {
+            events.push({ type: 'response.output_item.added', output_index: i, item });
+        }
+        events.push({ type: 'response.output_item.done', output_index: i, item });
+    }
+    events.push({ type: done.status === 'incomplete' ? 'response.incomplete' : 'response.completed', response: done });
+    return events.map((e, n) => `event: ${String(e.type)}\ndata: ${JSON.stringify({ ...e, sequence_number: n })}\n\n`).join('');
+}
+/** Whether a request forbids every tool call: OpenAI's `tool_choice: 'none'`, Anthropic's `{ type: 'none' }`. */
+export const forbidsTools = (choice) => choice === 'none' || obj(choice).type === 'none';
+/** The turn a scenario's decision scripts (`respond`: text, toolCalls, reasoning, finishReason), or undefined. */
+export function scenarioTurn(decision) {
+    if (!decision || decision.kind !== 'handler')
+        return undefined;
+    const r = obj(decision.respond);
+    return {
+        ...(typeof r.text === 'string' ? { text: r.text } : {}),
+        ...(r.toolCalls !== undefined ? { toolCalls: (Array.isArray(r.toolCalls) ? r.toolCalls : [r.toolCalls]) } : {}),
+        ...(typeof r.reasoning === 'string' ? { reasoning: r.reasoning } : {}),
+        ...(typeof r.finishReason === 'string' ? { finishReason: r.finishReason } : {}),
+    };
+}
+const nonEmpty = (v) => typeof v === 'string' && v.length > 0;
+const RESPOND_KEYS = new Set(['text', 'toolCalls', 'reasoning', 'finishReason']);
+/** A request as the scenario reads it: its model, its text, its last user text, the tools it offers and the tool
+ *  results it ends with, from a chat completion's messages or a Responses input. */
+export function wireRequest(body) {
+    const messages = arr(body.messages);
+    const tools = arr(body.tools).map((t) => String(obj(t.function).name ?? t.name ?? '')).filter(Boolean);
+    const forbidden = forbidsTools(body.tool_choice) ? { toolsForbidden: true } : {};
+    if (messages.length)
+        return { model: String(body.model ?? ''), text: messages.map((m) => chatText(m.content)).join('\n'), lastUser: chatLastUserText(messages), tools, results: chatToolResults(messages), ...forbidden };
+    const items = responsesItems(body.input);
+    return { model: String(body.model ?? ''), text: [String(body.instructions ?? ''), ...items.map((i) => itemText(i.content))].join('\n'), lastUser: responsesLastUserText(body.input), tools, results: responsesToolResults(body.input), ...forbidden };
+}
+/** The scenario of a vendor on this wire: its operations, and its error body for a scripted fault. `readers` reads an
+ *  operation whose request is another wire's (a gateway's Anthropic Messages surface: anthropicWire's
+ *  `messagesWireRequest`), so one scenario scripts every surface's turns alike. */
+export function scenario(vendor, operations, faultBody, readers = {}) {
+    const adapter = {
+        vendor,
+        renderFault: (f) => ({ body: faultBody(f.status, f.message) }),
+        features: (r) => ({ model: r.model, lastUserText: r.lastUser.slice(0, 300), tools: r.tools, lastMessageIsToolResult: r.results.length > 0, toolResultFor: r.results }),
+        matchers: {
+            modelEquals: (r, c) => nonEmpty(c) && r.model === c,
+            userTextIncludes: (r, c) => nonEmpty(c) && r.lastUser.toLowerCase().includes(c.toLowerCase()),
+            anyTextIncludes: (r, c) => nonEmpty(c) && r.text.toLowerCase().includes(c.toLowerCase()),
+            lastMessageIsToolResult: (r, c) => typeof c === 'boolean' && (r.results.length > 0) === c,
+            toolResultFor: (r, c) => nonEmpty(c) && r.results.includes(c),
+            hasTool: (r, c) => nonEmpty(c) && r.tools.includes(c),
+        },
+        text: (r) => r.text,
+        // source: https://platform.openai.com/docs/api-reference/chat/create "none means the model will not call any tool and instead generates a message"
+        admits: (r, respond) => !(r.toolsForbidden && obj(respond).toolCalls !== undefined),
+        validateOn: (on) => {
+            for (const k of ['modelEquals', 'userTextIncludes', 'anyTextIncludes', 'toolResultFor', 'hasTool'])
+                if (on[k] !== undefined && !nonEmpty(on[k]))
+                    return `on.${k} is a non-empty string`;
+            if (on.lastMessageIsToolResult !== undefined && typeof on.lastMessageIsToolResult !== 'boolean')
+                return 'on.lastMessageIsToolResult is a boolean';
+            return null;
+        },
+        validateRespond: (respond) => {
+            if (typeof respond !== 'object' || respond === null || Array.isArray(respond))
+                return 'respond is an object { text?, toolCalls?, reasoning?, finishReason? }';
+            const r = respond;
+            for (const k of Object.keys(r))
+                if (!RESPOND_KEYS.has(k))
+                    return `respond: unknown key "${k}" (valid: ${[...RESPOND_KEYS].join(', ')})`;
+            if (r.text !== undefined && typeof r.text !== 'string')
+                return 'respond.text is a string';
+            if (r.reasoning !== undefined && typeof r.reasoning !== 'string')
+                return 'respond.reasoning is a string';
+            for (const c of r.toolCalls === undefined ? [] : Array.isArray(r.toolCalls) ? r.toolCalls : [r.toolCalls]) {
+                const u = c;
+                if (!u || typeof u !== 'object' || Array.isArray(u) || !nonEmpty(u.name))
+                    return 'respond.toolCalls[].name is a non-empty string';
+            }
+            if (r.text === undefined && r.toolCalls === undefined)
+                return 'respond needs text or toolCalls';
+            return null;
+        },
+    };
+    // a V4 call (the AI SDK's protocol) is read as the chat request it means, its model in its header
+    const request = (ctx) => {
+        const body = (ctx.body ?? {});
+        const read = Object.hasOwn(readers, ctx.call.operation.id) ? readers[ctx.call.operation.id] : undefined;
+        if (read)
+            return read(body);
+        return wireRequest(Array.isArray(body.prompt) ? aiSdkChatBody(body, ctx.call.request.headers.get('ai-language-model-id') ?? '') : body);
+    };
+    return { adapter, operations, request };
+}

package/dist/src/pack-assets.d.ts

@@ -7,15 +7,14 @@ export interface PackAssetStore {
 export declare function assetContentType(relPath: string): string;
 /** A relative path confined to a pack's tree: no absolute, no `..`, no empty segment. */
 export declare function confinedAssetPath(relPath: string): string | null;
-/** The Bun shell's store: the pack's own directory under the catalog (`packages/twin/<vendor>`).
- *  `twinDir` ends with a slash. */
+/** The host's store: a pack-directory resolver, or a catalog root ending in a slash. */
 export declare class LocalPackAssets implements PackAssetStore {
     private readonly twinDir;
-    constructor(twinDir: string);
+    constructor(twinDir: string | ((vendor: string) => string | undefined | Promise<string | undefined>));
     fetch(vendor: string, relPath: string): Promise<Response | null>;
 }
 /** The workerd shell's store: the static-assets binding, where the deploy step places each
- *  pack's declared assets under `/{vendor}/pack/<relPath>` beside the mirror shells. */
+ *  pack's declared assets under `/{vendor}/pack/<relPath>`. */
 export declare class BindingPackAssets implements PackAssetStore {
     private readonly assets;
     constructor(assets: {

package/dist/src/pack-assets.js

@@ -1,15 +1,14 @@
 // THE PACK-ASSET SEAM (runtime contract R20). A pack may ship bytes it serves byte-for-byte —
-// clerk's vendored clerk-js dist (136 files, 14.5 MB), a mirror shell — that are neither
+// clerk's vendored clerk-js dist (136 files, 14.5 MB) — that are neither
 // committed text (size) nor world-state blobs (R11's seam is keyed under a world's state root
 // and filled by requests). They are PACK assets: read-only, versioned with the package, the
 // same on every world. This seam is how a pack reaches them without touching a host: the
 // pack declares them on its descriptor (`assets`), reads them through `getActivePackAssets()`,
 // and the SHELL binds the store — the Bun shell reads the pack's own tree, workerd the
-// static-assets binding the mirror shells already deploy through. A pack that reads its tree
+// static-assets binding. A pack that reads its tree
 // with Bun.file or import.meta is host-bound (R12b); one that reads through here is not.
-// No node builtins at module scope: `@volter/world-core`'s index re-exports this module and every mirror
-// client bundle (browser target) pulls the index in — a static `node:fs`/`node:url` import here
-// broke every mirror bundle the day the seam landed. The local store reads through Bun's file
+// No node builtins at module scope: `@volter/world-core`'s index re-exports this module and a browser
+// bundle pulls the index in, so a static `node:fs`/`node:url` import here would break it. The local store reads through Bun's file
 // API at call time; the worker store never touches a filesystem.
 import { existsSync, readFileSync, statSync } from 'node:fs';
 const CONTENT_TYPES = {
@@ -30,8 +29,7 @@ export function confinedAssetPath(relPath) {
         return null;
     return segs.join('/');
 }
-/** The Bun shell's store: the pack's own directory under the catalog (`packages/twin/<vendor>`).
- *  `twinDir` ends with a slash. */
+/** The host's store: a pack-directory resolver, or a catalog root ending in a slash. */
 export class LocalPackAssets {
     twinDir;
     constructor(twinDir) {
@@ -41,14 +39,17 @@ export class LocalPackAssets {
         const safe = confinedAssetPath(relPath);
         if (safe === null || !/^[a-z][a-z0-9-]*$/.test(vendor))
             return null;
-        const file = `${this.twinDir}${vendor}/${safe}`; // confined: no `..`, no absolute, no empty segment (above)
+        const dir = typeof this.twinDir === 'string' ? `${this.twinDir}${vendor}` : await this.twinDir(vendor);
+        if (dir === undefined)
+            return null;
+        const file = `${dir}/${safe}`; // confined: no `..`, no absolute, no empty segment (above)
         if (!existsSync(file) || !statSync(file).isFile())
             return null;
         return new Response(readFileSync(file), { status: 200, headers: { 'content-type': assetContentType(safe) } });
     }
 }
 /** The workerd shell's store: the static-assets binding, where the deploy step places each
- *  pack's declared assets under `/{vendor}/pack/<relPath>` beside the mirror shells. */
+ *  pack's declared assets under `/{vendor}/pack/<relPath>`. */
 export class BindingPackAssets {
     assets;
     constructor(assets) {
@@ -68,7 +69,11 @@ let active;
 /** The bound store — the Bun shell's local tree unless a shell bound another. */
 export function getActivePackAssets() {
     if (active === undefined)
-        active = new LocalPackAssets(new URL('../../twin/', import.meta.url).pathname);
+        active = new LocalPackAssets(async (vendor) => {
+            const { vendorPackageDir } = await import("./pack-paths.js");
+            const { fileURLToPath } = await import('node:url');
+            return vendorPackageDir(process.cwd(), vendor) ?? vendorPackageDir(fileURLToPath(new URL('.', import.meta.url)), vendor);
+        });
     return active;
 }
 export function setActivePackAssets(store) {

package/dist/src/pack-fetch.d.ts

@@ -0,0 +1,77 @@
+import { type DerivedManifest, type Handler, type HandlerContext, type VendorManifest } from './derived-core.js';
+import { type DerivedFetch, type DerivedOwner, type DerivedSurface } from './derived.js';
+import { type PackScenarioAdapter } from './scenario.js';
+import { type SocketEngine } from './sockets.js';
+import { type GraphqlPart } from './graphql-wire.js';
+/** What a pack declares and writes, and nothing it assembles itself. */
+export type PackParts = {
+    manifest: DerivedManifest;
+    surface: DerivedSurface;
+    /** `semantics/index.ts`: the handlers, by operationId. */
+    handlers?: Record<string, Handler>;
+    /** `semantics/doors.ts`: a door's answer, by the id the manifest's `doors` gives it. */
+    doors?: Record<string, Handler>;
+    /** Each `screens/<id>.tsx`'s answer, by the id the manifest's `screens` gives it. */
+    screens?: Record<string, Handler>;
+    /** `semantics/around.ts`: what the vendor does around every request to its API, one the surface names or not (a key
+     *  checked, a plan's limits, a quota counted after a success), over a context whose operation is the request's (or
+     *  `unmatched`); `next` answers the request itself, or the one it is given (the vendor's own rewrite of it: a query
+     *  token moved to its header, a caller resolved into a header only the vendor's own front sets). */
+    around?: (ctx: HandlerContext, next: (request?: Request) => Promise<Response>) => Promise<Response>;
+    /** `semantics/clock.ts`: the vendor's own moves the World clock has made due, caught up before anything is answered.
+     *  They are the vendor's, not the caller's: they land under a read-only request too. */
+    clock?: (ctx: HandlerContext) => Promise<void>;
+    /** `semantics/scenario.ts`: how the World's scenario decides a model vendor's turn — the operations it decides, the
+     *  request each is as the scenario reads it, and the vendor's own matchers and fault body (the adapter). */
+    scenario?: PackScenario;
+    /** `semantics/gap.ts`: the vendor's answer for what it does not serve, where its manifest's `gap` cannot say it (Clerk's
+     *  Frontend API: Go's plain-text 404 for a path it does not have, `signed_out` for an operation asked without a
+     *  client), over a context whose operation is the one matched, or `unmatched`. */
+    gap?: (ctx: HandlerContext) => Response | Promise<Response>;
+    /** `semantics/tenant.ts`: the tenant the caller acts in, which the core scopes the manifest's `tenant` by. */
+    tenant?: (ctx: HandlerContext) => string | undefined | Promise<string | undefined>;
+    /** The vendor's lanes, by the name the manifest's `lanes` routes give them: each its own pack fetch and manifest. */
+    lanes?: Record<string, LanePart>;
+    /** `semantics/graphql.ts` with the vendor's schema (`generated/graphql-sdl.gen.json`): the GraphQL wire over the same
+     *  state, served at the manifest's `graphql.paths` (graphql-wire.ts). */
+    graphql?: GraphqlPart<HandlerContext> & {
+        sdl: string;
+    };
+    /** `semantics/sockets.ts`: each socket's engine, by the id the manifest's `sockets` gives it (sockets.ts). */
+    sockets?: Record<string, SocketEngine<HandlerContext>>;
+};
+/** A pack's scenario (`semantics/scenario.ts` exports `scenario`): the adapter the kernel's engine reads the World's
+ *  scenario document with, the operations it decides a turn of, and the request an operation is to it (undefined when
+ *  the request is not one it decides: the handler answers the vendor's refusal). */
+export type PackScenario<Req = any> = {
+    adapter: PackScenarioAdapter<Req>;
+    operations: ReadonlyArray<string>;
+    request: (ctx: HandlerContext) => Req | undefined;
+};
+/** A lane as its vendor's fetch is given it: its own pack fetch, and its manifest (the doors it declares). */
+export type LanePart = {
+    fetch: ((request: Request) => Promise<Response>) & {
+        serves?: (method: string, path: string) => boolean;
+    };
+    manifest: {
+        doors?: ReadonlyArray<{
+            method: string;
+            path: string;
+        }>;
+    };
+};
+/** Where a pack serves: its World's root, whether it was started read-only, the World instant when a caller pins it, the
+ *  World's managed Postgres the runtime binds a pack declaring `managedDatabase` to (a handler's `ctx.engine`), and the
+ *  World's scenario file for a model vendor's turns (`scenarioPath`, the runtime's `--scenario`). */
+export type PackFetchOptions = {
+    root?: string;
+    readOnly?: boolean;
+    clock?: () => string;
+    database?: string;
+    scenarioPath?: string;
+};
+/** A pack's HTTP surface, as the kernel serves it from the pack's parts. */
+export declare function createPackFetch(parts: PackParts, options?: PackFetchOptions): DerivedFetch;
+export declare function createVendorFetch(manifest: VendorManifest, lanes: Record<string, LanePart>): ((request: Request) => Promise<Response>) & {
+    owners: () => Record<string, DerivedOwner>;
+};