zengate 1.0.0

package/src/opencode/isolation.js

@@ -0,0 +1,119 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const ROOT_PREFIX = 'zengate-';
+
+/** Environment variables the backend legitimately needs from the host. */
+const PASSTHROUGH_ENV = [
+    'PATH', 'Path', 'PATHEXT', 'SystemRoot', 'SYSTEMROOT', 'windir', 'WINDIR', 'ComSpec', 'SystemDrive',
+    'TEMP', 'TMP', 'TMPDIR', 'LANG', 'LC_ALL', 'TZ',
+    'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'http_proxy', 'https_proxy', 'no_proxy',
+    'NODE_EXTRA_CA_CERTS', 'SSL_CERT_FILE', 'SSL_CERT_DIR',
+];
+
+/**
+ * OpenCode configuration for the managed backend. Every tool permission is
+ * "ask" (the tool stays advertised exactly as in stock OpenCode) and the
+ * gateway answers every ask with "reject", so tools never run.
+ */
+export function backendConfig() {
+    return {
+        $schema: 'https://opencode.ai/config.json',
+        autoupdate: false,
+        share: 'disabled',
+        snapshot: false,
+        permission: {
+            '*': 'ask', read: 'ask', edit: 'ask', bash: 'ask', glob: 'ask', grep: 'ask', list: 'ask',
+            task: 'ask', webfetch: 'ask', websearch: 'ask', external_directory: 'ask', skill: 'ask', lsp: 'ask',
+        },
+    };
+}
+
+/**
+ * Create a private (0700) scratch tree: an empty workspace plus a fake
+ * home/XDG layout, so the backend never reads the host user's OpenCode or
+ * Claude config, skills, agents, credentials or projects.
+ */
+export function createIsolatedRoot() {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), ROOT_PREFIX));
+    if (process.platform !== 'win32') fs.chmodSync(root, 0o700);
+    const dirs = {};
+    for (const name of ['home', 'workspace', 'data', 'config', 'cache', 'state']) {
+        dirs[name] = path.join(root, name);
+        fs.mkdirSync(dirs[name], { recursive: true, mode: 0o700 });
+    }
+    fs.writeFileSync(path.join(root, 'owner.pid'), String(process.pid), { mode: 0o600 });
+    return { root, ...dirs };
+}
+
+export function removeIsolatedRoot(root) {
+    if (!root || !path.basename(root).startsWith(ROOT_PREFIX)) return;
+    try {
+        fs.rmSync(root, { recursive: true, force: true, maxRetries: 3, retryDelay: 200 });
+    } catch {
+        // A backend that is still exiting may hold files open; the next start sweeps it.
+    }
+}
+
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+
+/** Remove scratch trees left behind by gateway processes that no longer exist. */
+export function sweepStaleRoots() {
+    let entries = [];
+    try {
+        entries = fs.readdirSync(os.tmpdir(), { withFileTypes: true });
+    } catch {
+        return 0;
+    }
+    let removed = 0;
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !entry.name.startsWith(ROOT_PREFIX)) continue;
+        const root = path.join(os.tmpdir(), entry.name);
+        let pid = 0;
+        try { pid = Number(fs.readFileSync(path.join(root, 'owner.pid'), 'utf8')); } catch { /* unreadable: leave it */ }
+        if (pid > 0 && pid !== process.pid && !isAlive(pid)) {
+            removeIsolatedRoot(root);
+            removed += 1;
+        }
+    }
+    return removed;
+}
+
+/** Minimal child environment: no gateway secrets, isolated homes, stock OpenCode behavior. */
+export function backendEnv(dirs, password) {
+    const env = {};
+    for (const key of PASSTHROUGH_ENV) if (process.env[key] !== undefined) env[key] = process.env[key];
+    return {
+        ...env,
+        HOME: dirs.home,
+        USERPROFILE: dirs.home,
+        APPDATA: path.join(dirs.home, 'AppData', 'Roaming'),
+        LOCALAPPDATA: path.join(dirs.home, 'AppData', 'Local'),
+        XDG_DATA_HOME: dirs.data,
+        XDG_CONFIG_HOME: dirs.config,
+        XDG_CACHE_HOME: dirs.cache,
+        XDG_STATE_HOME: dirs.state,
+        OPENCODE_SERVER_USERNAME: 'opencode',
+        OPENCODE_SERVER_PASSWORD: password,
+        OPENCODE_CONFIG_CONTENT: JSON.stringify(backendConfig()),
+        OPENCODE_DISABLE_AUTOUPDATE: '1',
+        OPENCODE_DISABLE_SHARE: '1',
+        OPENCODE_DISABLE_LSP_DOWNLOAD: '1',
+        OPENCODE_DISABLE_PROJECT_CONFIG: '1',
+        OPENCODE_DISABLE_CLAUDE_CODE: '1',
+        OPENCODE_DISABLE_EXTERNAL_SKILLS: '1',
+        OPENCODE_DISABLE_DEFAULT_PLUGINS: '1',
+        OPENCODE_DISABLE_EMBEDDED_WEB_UI: '1',
+    };
+}
+
+export const randomPassword = () => crypto.randomBytes(32).toString('base64url');

package/src/opencode/model-errors.js

@@ -0,0 +1,66 @@
+import { ApiError } from '../server/errors.js';
+import { BackendError } from './client.js';
+
+const MAX_DETAIL = 400;
+
+function detail(error) {
+    const message = error?.data?.message || error?.message || '';
+    return String(message).replace(/\s+/g, ' ').trim().slice(0, MAX_DETAIL);
+}
+
+function retryAfter(error) {
+    const headers = error?.data?.responseHeaders || {};
+    const value = Number(headers['retry-after'] ?? headers['Retry-After']);
+    return Number.isFinite(value) && value > 0 && value < 3600 ? Math.ceil(value) : 30;
+}
+
+/**
+ * Translate an OpenCode assistant-message error into either a finish reason
+ * (the turn produced a usable, if cut short, answer) or an ApiError to throw.
+ * @returns {{ finish?: string, throw?: ApiError }}
+ */
+export function mapModelError(error) {
+    const name = error?.name || 'UnknownError';
+    const message = detail(error);
+    switch (name) {
+        case 'MessageOutputLengthError':
+            return { finish: 'length' };
+        case 'ContentFilterError':
+            return { finish: 'content_filter' };
+        case 'MessageAbortedError':
+            return { throw: new ApiError(499, 'Request cancelled.', { code: 'cancelled' }) };
+        case 'ContextOverflowError':
+            return { throw: new ApiError(400, `The conversation is too long for this model's context window. ${message}`.trim(), { param: 'messages', code: 'context_length_exceeded' }) };
+        case 'StructuredOutputError':
+            return { throw: new ApiError(502, `The model did not produce output matching the requested JSON schema. ${message}`.trim(), { code: 'structured_output_failed' }) };
+        case 'ProviderAuthError':
+            return { throw: new ApiError(502, `OpenCode Zen refused the request: ${message}`, { code: 'upstream_auth_failed' }) };
+        case 'APIError': {
+            const status = Number(error?.data?.statusCode) || 502;
+            if (status === 429) {
+                return { throw: new ApiError(429, `OpenCode Zen rate limit reached for this model; retry later. ${message}`.trim(), { code: 'upstream_rate_limited', retryAfter: retryAfter(error) }) };
+            }
+            if (status === 400 || status === 413 || status === 422) {
+                return { throw: new ApiError(400, `The model rejected the request: ${message}`, { code: 'upstream_rejected' }) };
+            }
+            if (status === 401 || status === 403) {
+                return { throw: new ApiError(502, `OpenCode Zen refused the request: ${message}`, { code: 'upstream_refused' }) };
+            }
+            return { throw: new ApiError(502, `The model provider failed: ${message}`, { code: 'upstream_error' }) };
+        }
+        default:
+            return { throw: new ApiError(502, `The model provider failed: ${message || name}`, { code: 'upstream_error' }) };
+    }
+}
+
+/** Translate an HTTP-level backend failure into an ApiError. */
+export function mapBackendError(error) {
+    if (error instanceof ApiError) return error;
+    if (error?.name === 'AbortError' || error?.name === 'TimeoutError') return error;
+    if (error instanceof BackendError && error.status === 400) {
+        const raw = error.body && typeof error.body === 'object' ? JSON.stringify(error.body) : String(error.body || 'no details');
+        const message = raw.slice(0, MAX_DETAIL);
+        return new ApiError(400, `OpenCode rejected the request: ${message}`, { code: 'backend_rejected', cause: error });
+    }
+    return new ApiError(503, 'The OpenCode backend is unavailable; retry shortly.', { code: 'backend_unavailable', retryAfter: 2, cause: error });
+}

package/src/opencode/runner.js

@@ -0,0 +1,224 @@
+import { ApiError } from '../server/errors.js';
+import { mapBackendError, mapModelError } from './model-errors.js';
+
+const MESSAGE_SEPARATOR = '\n\n';
+const MAX_UPSTREAM_RETRIES = 3;
+const NATIVE_ATTEMPT = Symbol('native-client-tool-attempt');
+const STREAMED_KINDS = new Set(['text', 'reasoning']);
+
+/**
+ * Runs one prompt in a throwaway OpenCode session and streams its output.
+ *
+ * Deltas arrive over the shared event hub while the blocking prompt call is
+ * pending; when it returns, the final message is reconciled against what was
+ * streamed so no text is lost or duplicated even if events were missed.
+ */
+export function createRunner({ getClient, hub, logger, agent }) {
+    /**
+     * @param {{ model: { providerID: string, modelID: string }, system?: string, parts: object[], variant?: string, format?: object }} request
+     * @param {{ signal: AbortSignal, onDelta?: (kind: 'text'|'reasoning', text: string) => void }} options
+     */
+    async function run(request, { signal: outer, onDelta = () => {} }) {
+        let signal = outer;
+        const client = getClient();
+        let sessionId;
+        try {
+            sessionId = (await client.createSession({ signal }))?.id;
+        } catch (error) {
+            throw mapBackendError(error);
+        }
+        if (!sessionId) throw mapBackendError(new Error('OpenCode did not return a session id'));
+
+        // Local controller: aborts on the caller's signal, or when OpenCode
+        // keeps retrying a failing upstream (it would otherwise retry until
+        // REQUEST_TIMEOUT_MS).
+        const local = new AbortController();
+        const forward = () => local.abort(outer.reason);
+        if (signal.aborted) forward();
+        else signal.addEventListener('abort', forward, { once: true });
+        const tracker = createStreamTracker(onDelta);
+        const clientTools = new Set(request.clientTools || []);
+        let nativeAttempt = null;
+        const onEvent = (event) => {
+            tracker.handle(event);
+            const part = event.type === 'message.part.updated' ? event.properties?.part : null;
+            const attempted = part?.type === 'tool' ? invalidToolName(part, clientTools) : null;
+            if (attempted !== null && !local.signal.aborted) {
+                // The model called a client function (or a nonexistent tool)
+                // natively. Letting OpenCode continue only produces a detour
+                // (and trips some providers), so stop; generate() retries.
+                logger.debug('Model attempted a native call to a non-OpenCode tool', { sessionId, tool: attempted });
+                nativeAttempt = attempted || 'unnamed tool';
+                local.abort(NATIVE_ATTEMPT);
+                return;
+            }
+            const status = event.type === 'session.status' ? event.properties?.status : null;
+            if (status?.type !== 'retry') return;
+            logger.debug('OpenCode is retrying the upstream request', { sessionId, attempt: status.attempt, message: status.message });
+            if (status.attempt >= MAX_UPSTREAM_RETRIES && !local.signal.aborted) {
+                local.abort(new ApiError(502, `The model provider keeps failing: ${String(status.message || 'unknown error').slice(0, 300)}`, { code: 'upstream_error' }));
+            }
+        };
+        const unsubscribe = hub.subscribe(sessionId, onEvent);
+        const abortSession = () => { client.abortSession(sessionId).catch(() => {}); };
+        local.signal.addEventListener('abort', abortSession, { once: true });
+        signal = local.signal;
+        try {
+            const body = {
+                model: request.model,
+                agent,
+                parts: request.parts,
+                ...(request.system ? { system: request.system } : {}),
+                ...(request.variant ? { variant: request.variant } : {}),
+                ...(request.format ? { format: request.format } : {}),
+            };
+            let last;
+            try {
+                last = await client.prompt(sessionId, body, { signal });
+            } catch (error) {
+                if (nativeAttempt && signal.reason === NATIVE_ATTEMPT) {
+                    return { text: '', reasoning: '', usage: { input: 0, output: 0, reasoning: 0, cacheRead: 0 }, finish: 'stop', nativeToolAttempt: nativeAttempt };
+                }
+                if (signal.aborted) throw signal.reason ?? error;
+                throw mapBackendError(error);
+            }
+            // Several assistant messages mean OpenCode continued after a
+            // rejected tool; without live events we cannot know, so re-read.
+            const assistantMessages = tracker.assistantCount() > 1 || !hub.isConnected()
+                ? (await client.messages(sessionId, { signal })).filter((m) => m?.info?.role === 'assistant')
+                : [last];
+            const result = summarize(assistantMessages);
+            tracker.flushRemainder(result);
+            return result;
+        } finally {
+            local.signal.removeEventListener('abort', abortSession);
+            outer.removeEventListener('abort', forward);
+            unsubscribe();
+            void cleanup(client, sessionId);
+        }
+    }
+
+    async function cleanup(client, sessionId) {
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            try {
+                await client.deleteSession(sessionId);
+                break;
+            } catch (error) {
+                if (attempt === 1) logger.debug('Could not delete OpenCode session', { sessionId, error: error.message });
+            }
+        }
+        hub.release(sessionId);
+    }
+
+    return Object.freeze({ run });
+}
+
+/** Tracks part kinds and message roles so only assistant text/reasoning streams. */
+function createStreamTracker(onDelta) {
+    const partKinds = new Map();
+    const pendingDeltas = new Map();
+    const roles = new Map();
+    const streamed = { text: '', reasoning: '' };
+    const lastMessage = { text: null, reasoning: null };
+
+    const emit = (kind, messageId, delta) => {
+        if (!delta) return;
+        const separator = streamed[kind] && lastMessage[kind] !== messageId ? MESSAGE_SEPARATOR : '';
+        lastMessage[kind] = messageId;
+        streamed[kind] += separator + delta;
+        onDelta(kind, separator + delta);
+    };
+
+    const flushPart = (partId) => {
+        const queued = pendingDeltas.get(partId);
+        const kind = partKinds.get(partId);
+        if (!queued || !kind) return;
+        pendingDeltas.delete(partId);
+        if (STREAMED_KINDS.has(kind)) for (const { messageId, delta } of queued) emit(kind, messageId, delta);
+    };
+
+    function handle(event) {
+        const props = event.properties || {};
+        if (event.type === 'message.updated' && props.info?.id) {
+            roles.set(props.info.id, props.info.role);
+        } else if (event.type === 'message.part.updated' && props.part?.id) {
+            partKinds.set(props.part.id, props.part.type);
+            flushPart(props.part.id);
+        } else if (event.type === 'message.part.delta' && props.field === 'text' && typeof props.delta === 'string') {
+            if (roles.get(props.messageID) === 'user') return;
+            const queued = pendingDeltas.get(props.partID) || [];
+            queued.push({ messageId: props.messageID, delta: props.delta });
+            pendingDeltas.set(props.partID, queued);
+            flushPart(props.partID);
+        }
+    }
+
+    function flushRemainder(result) {
+        for (const kind of STREAMED_KINDS) {
+            const finalText = result[kind];
+            if (finalText.startsWith(streamed[kind])) {
+                const rest = finalText.slice(streamed[kind].length);
+                if (rest) {
+                    streamed[kind] = finalText;
+                    onDelta(kind, rest);
+                }
+            }
+        }
+    }
+
+    return {
+        handle,
+        flushRemainder,
+        assistantCount: () => [...roles.values()].filter((role) => role === 'assistant').length,
+    };
+}
+
+/**
+ * Name of the tool the model tried to call when it is not an OpenCode tool:
+ * a pending part already named after a client function, or OpenCode's
+ * `invalid` stand-in. Returns null for ordinary OpenCode tool parts.
+ */
+function invalidToolName(part, clientTools) {
+    if (clientTools.has(part.tool)) return part.tool;
+    if (part.tool === 'invalid') return String(part.state?.input?.tool ?? '');
+    return null;
+}
+
+function joinParts(messages, type) {
+    return messages
+        .map((message) => (message.parts || []).filter((p) => p?.type === type).map((p) => p.text || '').join(''))
+        .filter(Boolean)
+        .join(MESSAGE_SEPARATOR);
+}
+
+/** Collapse the turn's assistant messages into text, reasoning, usage and finish. */
+function summarize(messages) {
+    const usage = { input: 0, output: 0, reasoning: 0, cacheRead: 0 };
+    let error = null;
+    let structured;
+    for (const message of messages) {
+        const tokens = message?.info?.tokens || {};
+        usage.input += tokens.input || 0;
+        usage.output += tokens.output || 0;
+        usage.reasoning += tokens.reasoning || 0;
+        usage.cacheRead += tokens.cache?.read || 0;
+        if (message?.info?.error) error = message.info.error;
+        if (message?.info?.structured !== undefined) structured = message.info.structured;
+    }
+    const last = messages[messages.length - 1]?.info || {};
+    const mapped = error ? mapModelError(error) : null;
+    if (mapped?.throw) throw mapped.throw;
+    return {
+        text: joinParts(messages, 'text'),
+        reasoning: joinParts(messages, 'reasoning'),
+        structured,
+        usage,
+        finish: mapped?.finish || normalizeFinish(last.finish),
+    };
+}
+
+function normalizeFinish(finish) {
+    if (finish === 'length') return 'length';
+    if (finish === 'content-filter') return 'content_filter';
+    return 'stop';
+}

package/src/opencode/sse-reader.js

@@ -0,0 +1,40 @@
+const MAX_FRAME_CHARS = 16 * 1024 * 1024;
+
+/**
+ * Parse a server-sent-events byte stream into { event, data } frames.
+ * Handles CRLF/LF, multi-line data and chunk boundaries anywhere.
+ * @param {AsyncIterable<Uint8Array>} body
+ */
+export async function* readSseFrames(body) {
+    const decoder = new TextDecoder();
+    let buffer = '';
+    for await (const chunk of body) {
+        buffer += decoder.decode(chunk, { stream: true });
+        if (buffer.length > MAX_FRAME_CHARS) throw new Error('SSE frame exceeds size limit');
+        let boundary;
+        while ((boundary = findBoundary(buffer)) !== null) {
+            const frame = buffer.slice(0, boundary.index);
+            buffer = buffer.slice(boundary.index + boundary.length);
+            const parsed = parseFrame(frame);
+            if (parsed) yield parsed;
+        }
+    }
+    buffer += decoder.decode();
+    const tail = parseFrame(buffer);
+    if (tail) yield tail;
+}
+
+function findBoundary(buffer) {
+    const match = /\r?\n\r?\n/.exec(buffer);
+    return match ? { index: match.index, length: match[0].length } : null;
+}
+
+function parseFrame(frame) {
+    let event = '';
+    const data = [];
+    for (const line of frame.split(/\r?\n/)) {
+        if (line.startsWith('data:')) data.push(line.slice(line[5] === ' ' ? 6 : 5));
+        else if (line.startsWith('event:')) event = line.slice(6).trim();
+    }
+    return data.length ? { event, data: data.join('\n') } : null;
+}

package/src/paths.js

@@ -0,0 +1,40 @@
+import os from 'node:os';
+import path from 'node:path';
+
+const APP_DIR = 'zengate';
+const CONFIG_NAME = 'config.json';
+
+/**
+ * True when the code runs from an installed npm package (npm -g, npx or a
+ * dependency) rather than a source checkout.
+ * @param {string} root package root directory
+ * @returns {boolean}
+ */
+export function isInstalledPackage(root) {
+    return root.split(/[\\/]+/).includes('node_modules');
+}
+
+/**
+ * The per-user config directory for this platform.
+ * @param {{ env: object, platform: string, homedir: string }} options
+ * @returns {string}
+ */
+function userConfigDir({ env, platform, homedir }) {
+    if (platform === 'win32') return path.join(env.APPDATA || path.join(homedir, 'AppData', 'Roaming'), APP_DIR);
+    if (platform === 'darwin') return path.join(homedir, 'Library', 'Application Support', APP_DIR);
+    const xdg = env.XDG_CONFIG_HOME && path.isAbsolute(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : path.join(homedir, '.config');
+    return path.join(xdg, APP_DIR);
+}
+
+/**
+ * Where config.json lives: CONFIG_FILE if set, next to the code in a source
+ * checkout, otherwise the per-user config directory (an installed package
+ * directory may be read-only and is replaced on every upgrade).
+ * @param {{ root: string, env?: object, platform?: string, homedir?: string }} options
+ * @returns {string}
+ */
+export function defaultConfigPath({ root, env = process.env, platform = process.platform, homedir = os.homedir() }) {
+    if (env.CONFIG_FILE) return env.CONFIG_FILE;
+    if (!isInstalledPackage(root)) return path.join(root, CONFIG_NAME);
+    return path.join(userConfigDir({ env, platform, homedir }), CONFIG_NAME);
+}

package/src/server/app.js

@@ -0,0 +1,96 @@
+import cors from 'cors';
+import express from 'express';
+import { chatCompletionsHandler } from '../openai/chat.js';
+import { modelsHandlers } from '../openai/models.js';
+import { responsesHandlers } from '../openai/responses.js';
+import { ApiError, sendError, toApiError } from './errors.js';
+import { createLimiter } from './limiter.js';
+import { createMetrics } from './metrics.js';
+import { authMiddleware, rateLimitMiddleware, requestId, securityHeaders } from './middleware.js';
+import { slotMiddleware } from './slot.js';
+
+const MB = 1024 * 1024;
+const EXPOSED_HEADERS = ['x-request-id', 'x-gateway-ignored-params', 'Retry-After'];
+
+/** Wrap an async handler so rejections reach the error handler. */
+const route = (handler) => (req, res, next) => Promise.resolve(handler(req, res, next)).catch(next);
+
+function openAiRoutes({ runner, catalog, store, limits }) {
+    const router = express.Router();
+    const models = modelsHandlers({ catalog });
+    const responses = responsesHandlers({ runner, catalog, store, limits });
+    router.get('/models', route(models.list));
+    router.get('/models/*id', route(models.retrieve));
+    router.post('/chat/completions', route(chatCompletionsHandler({ runner, catalog, limits })));
+    router.post('/responses', route(responses.create));
+    router.get('/responses/:id', route(responses.retrieve));
+    router.delete('/responses/:id', route(responses.remove));
+    return router;
+}
+
+function requestLogger(logger) {
+    return (req, res, next) => {
+        const scoped = (level) => (msg, fields) => logger[level](msg, { requestId: req.id, ...fields });
+        req.log = { debug: scoped('debug'), info: scoped('info'), warn: scoped('warn'), error: scoped('error') };
+        next();
+    };
+}
+
+function errorHandler(error, req, res, next) {
+    const apiError = toApiError(error);
+    if (apiError.status >= 500 && apiError.status !== 504) {
+        req.log.error('Request failed', { status: apiError.status, error: error?.message, cause: error?.cause?.message });
+    } else {
+        req.log.debug('Request rejected', { status: apiError.status, code: apiError.code, error: apiError.message });
+    }
+    if (res.headersSent) {
+        if (!res.writableEnded) res.end();
+        return undefined;
+    }
+    if (req.socket.destroyed) return undefined;
+    void next;
+    return sendError(res, apiError);
+}
+
+/**
+ * The HTTP surface. OpenAI routes are served under /v1 and, for clients
+ * configured with a bare base URL, at the root as well.
+ * @param {{ config: object, logger: object, backend: object, hub: object, catalog: object, runner: object, store: object }} deps
+ */
+export function createApp({ config, logger, backend, hub, catalog, runner, store }) {
+    const app = express();
+    const metrics = createMetrics();
+    const limiter = createLimiter({ maxConcurrent: config.MAX_CONCURRENT, maxQueue: config.MAX_QUEUE });
+    const rateLimit = rateLimitMiddleware({ perMinute: config.RATE_LIMIT_PER_MINUTE, onLimited: metrics.rateLimited });
+    const limits = { maxBytes: config.MAX_MEDIA_MB * MB };
+
+    app.disable('x-powered-by');
+    app.set('trust proxy', config.TRUST_PROXY || false);
+    app.use(requestId, securityHeaders, metrics.middleware, requestLogger(logger));
+    if (config.CORS_ORIGINS.length) {
+        app.use(cors({ origin: config.CORS_ORIGINS, exposedHeaders: EXPOSED_HEADERS, maxAge: 600 }));
+    }
+
+    app.get('/health', (req, res) => res.json({ status: 'ok' }));
+    app.get('/ready', (req, res) => {
+        const ready = backend.isReady() && hub.isConnected();
+        res.status(ready ? 200 : 503).json({ status: ready ? 'ready' : 'starting', backend: backend.mode, opencode: backend.version() });
+    });
+
+    app.use(rateLimit);
+    app.use(authMiddleware({ apiKeys: config.API_KEYS, allowNoAuth: config.ALLOW_NO_AUTH, onFailure: metrics.authFailure }));
+    app.get('/metrics', (req, res) => res.json(metrics.snapshot({
+        slots: limiter.stats(), stored_responses: store.size(), backend_ready: backend.isReady(), events_connected: hub.isConnected(),
+    })));
+    app.use(express.json({ limit: config.MAX_BODY_MB * MB }));
+    app.use(slotMiddleware({ limiter, timeoutMs: config.REQUEST_TIMEOUT_MS }));
+
+    const routes = openAiRoutes({ runner, catalog, store, limits });
+    app.use('/v1', routes);
+    app.use(routes);
+
+    app.use((req, res) => sendError(res, new ApiError(404, `Unknown endpoint: ${req.method} ${req.path}`, { code: 'unknown_url' })));
+    app.use(errorHandler);
+
+    return { app, close: () => rateLimit.close() };
+}

package/src/server/errors.js

@@ -0,0 +1,56 @@
+/**
+ * Errors surfaced to API clients use the OpenAI error envelope:
+ * { "error": { "message", "type", "param", "code" } }.
+ */
+export class ApiError extends Error {
+    /**
+     * @param {number} status HTTP status
+     * @param {string} message client-safe message
+     * @param {{ type?: string, param?: string|null, code?: string|null, retryAfter?: number, cause?: unknown }} [options]
+     */
+    constructor(status, message, { type, param = null, code = null, retryAfter, cause } = {}) {
+        super(message, cause ? { cause } : undefined);
+        this.name = 'ApiError';
+        this.status = status;
+        this.type = type ?? defaultType(status);
+        this.param = param;
+        this.code = code;
+        this.retryAfter = retryAfter;
+    }
+
+    toJSON() {
+        return { error: { message: this.message, type: this.type, param: this.param, code: this.code } };
+    }
+}
+
+function defaultType(status) {
+    if (status === 401) return 'authentication_error';
+    if (status === 403) return 'permission_error';
+    if (status === 404) return 'not_found_error';
+    if (status === 429) return 'rate_limit_error';
+    if (status >= 500) return 'server_error';
+    return 'invalid_request_error';
+}
+
+export const invalidRequest = (message, param = null, code = null) => new ApiError(400, message, { param, code });
+
+export const unsupported = (message, param = null) => new ApiError(400, message, { param, code: 'unsupported_parameter' });
+
+/** Normalize anything thrown into an ApiError without leaking internals. */
+export function toApiError(error) {
+    if (error instanceof ApiError) return error;
+    if (error?.type === 'entity.too.large') {
+        return new ApiError(413, 'Request body too large. Raise MAX_BODY_MB if this is expected.', { code: 'request_too_large' });
+    }
+    if (error?.type === 'entity.parse.failed') return invalidRequest('Request body is not valid JSON.');
+    if (error?.name === 'AbortError' || error?.name === 'TimeoutError') {
+        return new ApiError(504, 'The model did not finish before REQUEST_TIMEOUT_MS.', { code: 'timeout' });
+    }
+    return new ApiError(500, 'Internal server error.');
+}
+
+export function sendError(res, error) {
+    const apiError = toApiError(error);
+    if (apiError.retryAfter) res.set('Retry-After', String(apiError.retryAfter));
+    res.status(apiError.status).json(apiError.toJSON());
+}