zengate 1.0.0

package/src/openai/generate.js

@@ -0,0 +1,143 @@
+import { createStopFilter } from './stop.js';
+import { createToolCallParser } from './tool-calls.js';
+
+const STOP_REACHED = Symbol('stop-sequence');
+const SEPARATOR = '\n\n';
+
+const FORCED_RETRY_NOTE = 'To call a function, write a <tool_call>{"name": ..., "arguments": {...}}</tool_call> block as plain text in your reply. Do not describe the call; write the block.';
+
+const addUsage = (a, b) => ({ input: a.input + b.input, output: a.output + b.output, reasoning: a.reasoning + b.reasoning, cacheRead: a.cacheRead + b.cacheRead });
+
+/**
+ * Run one completion through OpenCode and apply the OpenAI-side semantics:
+ * stop sequences, emulated function calls and structured output.
+ *
+ * @param {{ runner: object, prompt: object, request: object, signal: AbortSignal,
+ *           onText?: (text: string) => void, onReasoning?: (text: string) => void }} options
+ * @returns {Promise<{ content: string, reasoning: string, toolCalls: object[], finish: string, usage: object }>}
+ */
+async function attempt({ runner, prompt, request, signal, onText, onReasoning }) {
+    const controller = new AbortController();
+    const forward = () => controller.abort(signal.reason);
+    if (signal.aborted) forward();
+    else signal.addEventListener('abort', forward, { once: true });
+
+    const stopFilter = createStopFilter(request.stop);
+    const parser = request.tools.length && request.toolChoice !== 'none' ? createToolCallParser(request.tools) : null;
+    // With native structured output, OpenCode returns the JSON separately
+    // (info.structured) and any streamed text may be prose, so hold it back.
+    const nativeFormat = Boolean(prompt.format);
+    let held = '';
+    let content = '';
+    let reasoning = '';
+
+    const emitText = (text) => {
+        if (!text) return;
+        content += text;
+        onText(text);
+    };
+    const acceptText = (text) => {
+        const allowed = stopFilter.push(text);
+        emitText(parser ? parser.push(allowed) : allowed);
+        if (stopFilter.stopped && !controller.signal.aborted) controller.abort(STOP_REACHED);
+    };
+
+    let result = null;
+    try {
+        result = await runner.run(prompt, {
+            signal: controller.signal,
+            onDelta(kind, text) {
+                if (kind === 'reasoning') {
+                    reasoning += text;
+                    onReasoning(text);
+                } else if (nativeFormat) {
+                    held += text;
+                } else if (!stopFilter.stopped) {
+                    acceptText(text);
+                }
+            },
+        });
+    } catch (error) {
+        if (controller.signal.reason !== STOP_REACHED) throw error;
+    } finally {
+        signal.removeEventListener('abort', forward);
+    }
+
+    if (result?.structured !== undefined) {
+        acceptText(typeof result.structured === 'string' ? result.structured : JSON.stringify(result.structured));
+    } else if (held) {
+        acceptText(held);
+    }
+    const tail = stopFilter.flush();
+    emitText(parser ? parser.push(tail) : tail);
+    let toolCalls = [];
+    if (parser) {
+        const finished = parser.finish();
+        toolCalls = finished.calls;
+        emitText(finished.text);
+    }
+    let finish = result?.finish || 'stop';
+    if (toolCalls.length) finish = 'tool_calls';
+    else if (stopFilter.stopped) finish = 'stop';
+
+    return {
+        content,
+        reasoning,
+        toolCalls,
+        finish,
+        usage: result?.usage || { input: 0, output: 0, reasoning: 0, cacheRead: 0 },
+        nativeToolAttempt: result?.nativeToolAttempt || null,
+    };
+}
+
+/**
+ * attempt() plus one corrective retry when the model tried to call a client
+ * function as a native tool, or answered in prose although tool_choice
+ * demands a call (weaker models occasionally do either).
+ * @param {Parameters<typeof attempt>[0]} options
+ */
+export async function generate({ onText = () => {}, onReasoning = () => {}, ...options }) {
+    const first = await attempt({ ...options, onText, onReasoning });
+    const { request, prompt, signal } = options;
+    const forced = request.toolChoice === 'required' || (request.toolChoice && typeof request.toolChoice === 'object');
+    if (first.toolCalls.length || signal.aborted || !(forced || first.nativeToolAttempt)) return first;
+    const hasClientTools = request.tools.length > 0 && request.toolChoice !== 'none';
+    let note = FORCED_RETRY_NOTE;
+    if (first.nativeToolAttempt && hasClientTools) {
+        note = `Your previous attempt to call "${first.nativeToolAttempt}" as a native tool failed: client functions are not native tools. ${FORCED_RETRY_NOTE}`;
+    } else if (first.nativeToolAttempt) {
+        note = `There is no tool named "${first.nativeToolAttempt}". Answer directly without calling tools.`;
+    }
+    const retryPrompt = { ...prompt, system: [prompt.system, note].filter(Boolean).join(SEPARATOR) };
+    let separated = false;
+    const separate = (emit) => (text) => {
+        if (first.content && !separated && text) {
+            separated = true;
+            onText(SEPARATOR);
+        }
+        emit(text);
+    };
+    const second = await attempt({ ...options, prompt: retryPrompt, onText: separate(onText), onReasoning });
+    return {
+        ...second,
+        content: separated ? `${first.content}${SEPARATOR}${second.content}` : first.content + second.content,
+        reasoning: first.reasoning + second.reasoning,
+        usage: addUsage(first.usage, second.usage),
+    };
+}
+
+/** OpenAI Chat Completions usage object. */
+export function chatUsage(usages) {
+    const total = usages.reduce((acc, u) => ({
+        input: acc.input + u.input, output: acc.output + u.output, reasoning: acc.reasoning + u.reasoning, cacheRead: acc.cacheRead + u.cacheRead,
+    }), { input: 0, output: 0, reasoning: 0, cacheRead: 0 });
+    const prompt = total.input + total.cacheRead;
+    const completion = total.output + total.reasoning;
+    return {
+        prompt_tokens: prompt,
+        completion_tokens: completion,
+        total_tokens: prompt + completion,
+        prompt_tokens_details: { cached_tokens: total.cacheRead },
+        completion_tokens_details: { reasoning_tokens: total.reasoning },
+    };
+}

package/src/openai/media.js

@@ -0,0 +1,104 @@
+import { invalidRequest, unsupported } from '../server/errors.js';
+
+/**
+ * Canonical media attachment:
+ * { kind: 'image'|'audio'|'video'|'pdf'|'text', mime, url, filename?, text? }
+ * `url` is a data: URI or an https URL; `text` holds decoded text files,
+ * which are inlined into the prompt rather than attached.
+ */
+
+const AUDIO_MIME = Object.freeze({
+    wav: 'audio/wav', mp3: 'audio/mpeg', mpeg: 'audio/mpeg', ogg: 'audio/ogg', flac: 'audio/flac',
+    m4a: 'audio/mp4', aac: 'audio/aac', opus: 'audio/opus', webm: 'audio/webm', pcm16: 'audio/L16',
+});
+const EXTENSION_MIME = Object.freeze({
+    pdf: 'application/pdf', txt: 'text/plain', md: 'text/markdown', csv: 'text/csv', json: 'application/json',
+    xml: 'application/xml', html: 'text/html', png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg',
+    gif: 'image/gif', webp: 'image/webp', mp3: 'audio/mpeg', wav: 'audio/wav', mp4: 'video/mp4', webm: 'video/webm',
+});
+const TEXT_MIME = /^(text\/[\w.+-]+|application\/(json|xml|x-yaml|yaml|javascript|x-sh))$/;
+const DATA_URI = /^data:([\w.+-]+\/[\w.+-]+)(?:;[\w.+-]+=[\w.+-]+)*;base64,([A-Za-z0-9+/_-]*={0,2})$/;
+const MAX_URL_CHARS = 8192;
+
+export function kindForMime(mime) {
+    if (mime.startsWith('image/')) return 'image';
+    if (mime.startsWith('audio/')) return 'audio';
+    if (mime.startsWith('video/')) return 'video';
+    if (mime === 'application/pdf') return 'pdf';
+    if (TEXT_MIME.test(mime)) return 'text';
+    return null;
+}
+
+function checkSize(base64, maxBytes, param) {
+    const bytes = Math.floor((base64.length * 3) / 4);
+    if (bytes > maxBytes) {
+        throw invalidRequest(`Attachment is ${(bytes / 1048576).toFixed(1)} MB; the limit is ${(maxBytes / 1048576).toFixed(0)} MB per part (MAX_MEDIA_MB).`, param, 'attachment_too_large');
+    }
+}
+
+function fromDataUri(uri, { maxBytes, param, filename, expect }) {
+    const match = DATA_URI.exec(uri);
+    if (!match) throw invalidRequest('Attachments must be base64 data URIs (data:<mime>;base64,...) or https URLs.', param);
+    const mime = match[1].toLowerCase() === 'image/jpg' ? 'image/jpeg' : match[1].toLowerCase();
+    const kind = kindForMime(mime);
+    if (!kind) throw unsupported(`Unsupported attachment type '${mime}'.`, param);
+    if (expect && kind !== expect) throw invalidRequest(`Expected ${expect} data but received '${mime}'.`, param);
+    if (mime === 'image/svg+xml') throw unsupported('SVG images are not supported; send PNG, JPEG, GIF or WebP.', param);
+    checkSize(match[2], maxBytes, param);
+    if (kind === 'text') {
+        return { kind, mime, filename, text: Buffer.from(match[2], 'base64').toString('utf8') };
+    }
+    return { kind, mime, url: uri, filename };
+}
+
+function fromHttpsUrl(url, { param, kind, mime, filename }) {
+    if (url.length > MAX_URL_CHARS) throw invalidRequest(`URL is longer than ${MAX_URL_CHARS} characters.`, param);
+    let parsed;
+    try { parsed = new URL(url); } catch { throw invalidRequest('Invalid attachment URL.', param); }
+    if (parsed.protocol !== 'https:') throw invalidRequest('Attachment URLs must use https (or send a base64 data URI).', param);
+    return { kind, mime, url: parsed.href, filename };
+}
+
+function urlPath(url) {
+    try { return new URL(url).pathname; } catch { return ''; }
+}
+
+function guessMime(filename, fallback) {
+    const ext = String(filename || '').toLowerCase().split('.').pop();
+    return EXTENSION_MIME[ext] || fallback;
+}
+
+export function imageFromUrl(url, options) {
+    if (typeof url !== 'string' || !url) throw invalidRequest('image_url.url is required.', options.param);
+    if (url.startsWith('data:')) return fromDataUri(url, { ...options, expect: 'image' });
+    return fromHttpsUrl(url, { ...options, kind: 'image', mime: guessMime(urlPath(url), 'image/*') });
+}
+
+export function videoFromUrl(url, options) {
+    if (typeof url !== 'string' || !url) throw invalidRequest('video_url.url is required.', options.param);
+    if (url.startsWith('data:')) return fromDataUri(url, { ...options, expect: 'video' });
+    return fromHttpsUrl(url, { ...options, kind: 'video', mime: guessMime(urlPath(url), 'video/*') });
+}
+
+export function audioFromBase64(data, format, options) {
+    const mime = AUDIO_MIME[String(format || '').toLowerCase()];
+    if (!mime) throw invalidRequest(`input_audio.format must be one of: ${Object.keys(AUDIO_MIME).join(', ')}.`, options.param);
+    if (typeof data !== 'string' || !data) throw invalidRequest('input_audio.data (base64) is required.', options.param);
+    if (data.startsWith('data:')) return fromDataUri(data, { ...options, expect: 'audio' });
+    return fromDataUri(`data:${mime};base64,${data}`, { ...options, expect: 'audio' });
+}
+
+/** OpenAI `file` parts: file_data (data URI or bare base64), or file_url. */
+export function fileAttachment({ file_data: fileData, file_id: fileId, file_url: fileUrl, filename }, options) {
+    const name = typeof filename === 'string' ? filename.slice(0, 255) : undefined;
+    if (fileId) throw unsupported('file_id requires the Files API, which this gateway does not provide; send file_data instead.', options.param);
+    if (typeof fileUrl === 'string' && fileUrl) {
+        const mime = guessMime(urlPath(fileUrl), 'application/pdf');
+        return fromHttpsUrl(fileUrl, { ...options, kind: kindForMime(mime) || 'pdf', mime, filename: name });
+    }
+    if (typeof fileData !== 'string' || !fileData) throw invalidRequest('file.file_data is required.', options.param);
+    if (fileData.startsWith('data:')) return fromDataUri(fileData, { ...options, filename: name });
+    const mime = guessMime(name, null);
+    if (!mime) throw invalidRequest('Send file_data as a data URI (data:<mime>;base64,...) or include a filename with an extension.', options.param);
+    return fromDataUri(`data:${mime};base64,${fileData}`, { ...options, filename: name });
+}

package/src/openai/models.js

@@ -0,0 +1,17 @@
+import { toOpenAIModel } from '../opencode/catalog.js';
+
+/** GET /v1/models and GET /v1/models/{id} (ids may contain a slash). */
+export function modelsHandlers({ catalog }) {
+    const list = async (req, res) => {
+        const models = await catalog.list();
+        res.json({ object: 'list', data: models.map(toOpenAIModel) });
+    };
+
+    const retrieve = async (req, res) => {
+        const raw = req.params.id;
+        const id = Array.isArray(raw) ? raw.join('/') : String(raw);
+        res.json(toOpenAIModel(await catalog.resolve(id)));
+    };
+
+    return { list, retrieve };
+}

package/src/openai/prompt.js

@@ -0,0 +1,101 @@
+import { invalidRequest } from '../server/errors.js';
+import { renderToolCall, toolInstructions } from './tool-calls.js';
+
+const TRANSCRIPT_INTRO = 'The conversation so far is below, oldest first. Write only the next assistant reply — no role tags, no transcript markup.';
+
+function attachmentLabel(media, index) {
+    return `[attachment ${index + 1}: ${media.kind}${media.filename ? ` "${media.filename}"` : ''}]`;
+}
+
+function toolNameFor(messages, callId) {
+    for (const message of messages) {
+        const call = message.toolCalls?.find((c) => c.id === callId);
+        if (call) return call.name;
+    }
+    return null;
+}
+
+/** Render a multi-turn conversation as one transcript with attachment markers. */
+function renderTranscript(messages, attachments) {
+    const blocks = [TRANSCRIPT_INTRO];
+    for (const message of messages) {
+        const labels = message.media.map((media) => {
+            attachments.push(media);
+            return attachmentLabel(media, attachments.length - 1);
+        });
+        const body = [message.content, ...labels].filter(Boolean).join('\n');
+        if (message.role === 'tool') {
+            const name = message.name || toolNameFor(messages, message.toolCallId) || 'function';
+            blocks.push(`<tool_result name="${name}" call_id="${message.toolCallId}">\n${body}\n</tool_result>`);
+        } else if (message.role === 'assistant') {
+            const calls = (message.toolCalls || []).map(renderToolCall);
+            blocks.push(`<assistant>\n${[body, ...calls].filter(Boolean).join('\n')}\n</assistant>`);
+        } else {
+            blocks.push(`<user>\n${body}\n</user>`);
+        }
+    }
+    return blocks.join('\n\n');
+}
+
+function assertModalities(model, media) {
+    for (const item of media) {
+        if (!model.input.includes(item.kind)) {
+            throw invalidRequest(`The model '${model.id}' does not accept ${item.kind} input (it accepts: ${model.input.join(', ')}). Pick a model from GET /v1/models that supports it.`, 'messages', 'unsupported_modality');
+        }
+    }
+}
+
+function pickVariant(model, effort) {
+    if (!effort || effort === 'none') return undefined;
+    return model.variants.includes(effort) ? effort : undefined;
+}
+
+/**
+ * Translate a canonical request into an OpenCode prompt:
+ * { model, system, parts, variant, format }.
+ * @param {ReturnType<typeof import('./chat-request.js').parseChatRequest>} request
+ * @param {object} model catalog entry
+ */
+export function buildPrompt(request, model) {
+    const systemTexts = request.messages.filter((m) => m.role === 'system').map((m) => m.content).filter(Boolean);
+    const turns = request.messages.filter((m) => m.role !== 'system');
+    if (turns.length === 0) throw invalidRequest('messages must include at least one user message.', 'messages');
+
+    const useNativeFormat = request.format && (request.tools.length === 0 || request.toolChoice === 'none');
+    const tools = toolInstructions(request.tools, request.toolChoice, request.parallelToolCalls);
+    if (tools) systemTexts.push(tools);
+    if (request.format && !useNativeFormat) {
+        systemTexts.push(request.format.type === 'json_schema'
+            ? `When you answer without calling a function, reply with only JSON matching this schema: ${JSON.stringify(request.format.schema)}`
+            : 'When you answer without calling a function, reply with only a valid JSON object.');
+    }
+
+    const attachments = [];
+    let text;
+    const single = turns.length === 1 && turns[0].role === 'user';
+    if (single) {
+        text = turns[0].content;
+        attachments.push(...turns[0].media);
+    } else {
+        text = renderTranscript(turns, attachments);
+    }
+    assertModalities(model, attachments);
+
+    const parts = [];
+    if (text || attachments.length === 0) parts.push({ type: 'text', text: text || ' ' });
+    attachments.forEach((media, index) => {
+        parts.push({ type: 'file', mime: media.mime, url: media.url, filename: media.filename || `attachment-${index + 1}` });
+    });
+
+    return {
+        model: { providerID: model.providerID, modelID: model.modelID },
+        system: systemTexts.join('\n\n') || undefined,
+        parts,
+        variant: pickVariant(model, request.reasoningEffort),
+        format: useNativeFormat
+            ? { type: 'json_schema', schema: request.format.type === 'json_schema' ? request.format.schema : { type: 'object' } }
+            : undefined,
+        // Not sent to OpenCode: lets the runner spot native attempts at client functions.
+        clientTools: tools ? request.tools.map((tool) => tool.name) : [],
+    };
+}

package/src/openai/response-builder.js

@@ -0,0 +1,135 @@
+import crypto from 'node:crypto';
+import { toApiError } from '../server/errors.js';
+
+const rid = (prefix) => `${prefix}_${crypto.randomBytes(16).toString('hex')}`;
+
+export function responsesUsage(usage) {
+    const input = usage.input + usage.cacheRead;
+    const output = usage.output + usage.reasoning;
+    return {
+        input_tokens: input,
+        input_tokens_details: { cached_tokens: usage.cacheRead },
+        output_tokens: output,
+        output_tokens_details: { reasoning_tokens: usage.reasoning },
+        total_tokens: input + output,
+    };
+}
+
+function callItem(call) {
+    if (call.kind === 'custom') {
+        let input = '';
+        try { input = String(JSON.parse(call.arguments).input ?? ''); } catch { input = call.arguments; }
+        return { id: rid('ctc'), type: 'custom_tool_call', status: 'completed', call_id: call.id, name: call.name, input };
+    }
+    return { id: rid('fc'), type: 'function_call', status: 'completed', call_id: call.id, name: call.name, arguments: call.arguments };
+}
+
+/**
+ * Builds a Responses API object and (optionally) its streaming events in
+ * the documented order: created → in_progress → output items with their
+ * part/delta/done events → completed | incomplete | failed.
+ * @param {{ model: string, echo: object, emit?: (event: object) => void }} options
+ */
+export function createResponseBuilder({ model, echo, emit = () => {} }) {
+    const id = rid('resp');
+    const createdAt = Math.floor(Date.now() / 1000);
+    const output = [];
+    let sequence = 0;
+    let reasoning = null;
+    let message = null;
+
+    const send = (type, fields) => emit({ type, sequence_number: sequence++, ...fields });
+    const snapshot = (status, extra = {}) => ({
+        id, object: 'response', created_at: createdAt, status, background: false, error: null, incomplete_details: null,
+        model, output: output.map((entry) => entry.item), usage: null, ...echo, ...extra,
+    });
+    const indexOf = (entry) => output.indexOf(entry);
+
+    function openReasoning() {
+        reasoning = { item: { id: rid('rs'), type: 'reasoning', summary: [] }, text: '' };
+        output.push(reasoning);
+        send('response.output_item.added', { output_index: indexOf(reasoning), item: { ...reasoning.item } });
+        send('response.reasoning_summary_part.added', { item_id: reasoning.item.id, output_index: indexOf(reasoning), summary_index: 0, part: { type: 'summary_text', text: '' } });
+    }
+
+    function openMessage() {
+        message = { item: { id: rid('msg'), type: 'message', status: 'in_progress', role: 'assistant', content: [] }, text: '' };
+        output.push(message);
+        send('response.output_item.added', { output_index: indexOf(message), item: { ...message.item } });
+        send('response.content_part.added', { item_id: message.item.id, output_index: indexOf(message), content_index: 0, part: { type: 'output_text', text: '', annotations: [], logprobs: [] } });
+    }
+
+    function closeReasoning() {
+        if (!reasoning) return;
+        const index = indexOf(reasoning);
+        const part = { type: 'summary_text', text: reasoning.text };
+        reasoning.item = { ...reasoning.item, summary: [part] };
+        send('response.reasoning_summary_text.done', { item_id: reasoning.item.id, output_index: index, summary_index: 0, text: reasoning.text });
+        send('response.reasoning_summary_part.done', { item_id: reasoning.item.id, output_index: index, summary_index: 0, part });
+        send('response.output_item.done', { output_index: index, item: reasoning.item });
+    }
+
+    function closeMessage() {
+        if (!message) return;
+        const index = indexOf(message);
+        const part = { type: 'output_text', text: message.text, annotations: [], logprobs: [] };
+        message.item = { ...message.item, status: 'completed', content: [part] };
+        send('response.output_text.done', { item_id: message.item.id, output_index: index, content_index: 0, text: message.text, logprobs: [] });
+        send('response.content_part.done', { item_id: message.item.id, output_index: index, content_index: 0, part });
+        send('response.output_item.done', { output_index: index, item: message.item });
+    }
+
+    function addCall(call) {
+        const entry = { item: callItem(call) };
+        output.push(entry);
+        const index = indexOf(entry);
+        const { item } = entry;
+        if (item.type === 'custom_tool_call') {
+            send('response.output_item.added', { output_index: index, item: { ...item, status: 'in_progress', input: '' } });
+            send('response.custom_tool_call_input.delta', { item_id: item.id, output_index: index, delta: item.input });
+            send('response.custom_tool_call_input.done', { item_id: item.id, output_index: index, input: item.input });
+        } else {
+            send('response.output_item.added', { output_index: index, item: { ...item, status: 'in_progress', arguments: '' } });
+            send('response.function_call_arguments.delta', { item_id: item.id, output_index: index, delta: item.arguments });
+            send('response.function_call_arguments.done', { item_id: item.id, output_index: index, name: item.name, arguments: item.arguments });
+        }
+        send('response.output_item.done', { output_index: index, item });
+    }
+
+    return {
+        id,
+        start() {
+            send('response.created', { response: snapshot('in_progress') });
+            send('response.in_progress', { response: snapshot('in_progress') });
+        },
+        reasoningDelta(text) {
+            if (!reasoning) openReasoning();
+            reasoning.text += text;
+            send('response.reasoning_summary_text.delta', { item_id: reasoning.item.id, output_index: indexOf(reasoning), summary_index: 0, delta: text });
+        },
+        textDelta(text) {
+            if (!message) openMessage();
+            message.text += text;
+            send('response.output_text.delta', { item_id: message.item.id, output_index: indexOf(message), content_index: 0, delta: text, logprobs: [] });
+        },
+        /** Close all items and emit the terminal event; returns the final Response. */
+        finish(result) {
+            closeReasoning();
+            if (!message && result.toolCalls.length === 0) openMessage();
+            closeMessage();
+            result.toolCalls.forEach(addCall);
+            const incomplete = result.finish === 'length' || result.finish === 'content_filter';
+            const response = snapshot(incomplete ? 'incomplete' : 'completed', {
+                incomplete_details: incomplete ? { reason: result.finish === 'length' ? 'max_output_tokens' : 'content_filter' } : null,
+                usage: responsesUsage(result.usage),
+            });
+            send(incomplete ? 'response.incomplete' : 'response.completed', { response });
+            return response;
+        },
+        fail(error) {
+            const apiError = toApiError(error);
+            send('response.failed', { response: snapshot('failed', { error: { code: apiError.code || 'server_error', message: apiError.message } }) });
+            return apiError;
+        },
+    };
+}