zengate 1.2.0 → 1.3.1

package/README.md

@@ -68,6 +68,8 @@ docker exec zengate node index.js setup --show   # prints the generated key
 
 Images are published for `linux/amd64` and `linux/arm64`, tagged `latest`, `1`, `1.2` and `1.2.3`.
 
+The same image is on GitHub Container Registry as `ghcr.io/developingchet/zengate`, and the npm package is on GitHub Packages as `@developingchet/zengate`. Installing from GitHub Packages needs a GitHub token, so npmjs.com and Docker Hub remain the simplest sources.
+
 **Docker Compose**
 
 ```yaml
@@ -241,13 +243,20 @@ Set values as environment variables or in the config file (same names; see [`con
 | `TRUST_PROXY` | `0` | Number of reverse-proxy hops to trust for client IPs. |
 | `LOG_LEVEL` / `LOG_JSON` | `info` / `false` | Log verbosity, and JSON-lines output. |
 | `OPENCODE_AGENT` | `plan` | The OpenCode agent each session uses. |
-| `OPENCODE_PATH` | bundled | Use a different `opencode` binary. |
+| `OPENCODE_PATH` | bundled | Use a different `opencode` binary, OpenCode 1 or 2. |
 | `OPENCODE_SERVER_URL` | none | Attach to an existing `opencode serve` instead of starting one (see below). |
 | `OPENCODE_SERVER_USERNAME` / `OPENCODE_SERVER_PASSWORD` | `opencode` / none | Basic auth for that server. Credentials inside `OPENCODE_SERVER_URL` are refused. |
 | `ALLOW_INSECURE_BACKEND_HTTP` | `false` | Allow a non-loopback `http://` server URL. |
 | `CONFIG_FILE` | see [First start](#first-start) | Where the config file lives (environment variable only). |
 
-**Attach mode.** `OPENCODE_SERVER_URL` uses a server you run yourself. The gateway can only reject tool calls that server *asks* permission for; that happens in its own sessions and their subagents. It trusts the server's own permission config, plugins and MCP servers. If that config allows tools without asking, they will run. Use it only with a server configured like the managed one: every permission set to `"ask"`, and `experimental.continue_loop_on_deny` set to `true` so a rejected tool does not end the turn with an empty reply. The managed default is safer. Remote servers must use `https://` unless you set `ALLOW_INSECURE_BACKEND_HTTP`.
+**Attach mode.** `OPENCODE_SERVER_URL` uses a server you run yourself. The gateway can only reject tool calls that server *asks* permission for; that happens in its own sessions and their subagents. It trusts the server's own permission config, plugins and MCP servers. If that config allows tools without asking, they will run. On OpenCode 2 this includes "always allow" rules saved for the server's project, which apply after the gateway's session rules and win over them; the `execute` tool and its `fetch` are reachable unless the server denies that action. Use it only with a server configured like the managed one: every permission set to `"ask"`, and `experimental.continue_loop_on_deny` set to `true` so a rejected tool does not end the turn with an empty reply. The managed default is safer. Remote servers must use `https://` unless you set `ALLOW_INSECURE_BACKEND_HTTP`.
+
+**OpenCode versions.** The bundled backend is OpenCode 2 (the `@opencode/cli` package). The gateway also works with OpenCode 1 and tells the two apart by how the backend answers, whether it starts a binary (`OPENCODE_PATH`) or attaches to a server (`OPENCODE_SERVER_URL`). With OpenCode 2:
+
+- Sessions are created with every action set to `ask`, and the gateway rejects each request, as it does with OpenCode 1.
+- `response_format` is passed to the model as an instruction, because OpenCode 2 has no native structured output. The JSON arrives when the answer is complete rather than streamed.
+- `OPENCODE_AGENT` applies only if the server has an agent of that name; otherwise the session keeps its default agent.
+- OpenCode 2 has an `execute` tool that runs scripts the model writes inside the OpenCode process. Scripts can call `fetch` on any URL without a permission request, so the gateway denies the `execute` action and the tool is not offered to the model. Browser tools are denied too (they also need a desktop app attached to the session). Every other tool, including shell, file, web and subagent tools, asks and is rejected. A later OpenCode 2 release could add a way around this, so after upgrading it, run `npm run test:leak`: it asks a model to use every tool, and to fetch a local listener, in a session with the gateway's permissions, and fails if anything ran.
 
 ## Deployment
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zengate",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Keyless OpenAI-compatible API (Chat Completions + Responses) for OpenCode's free Zen models, served through the real OpenCode CLI.",
   "author": {
     "name": "developingchet",
@@ -32,6 +32,7 @@
     "test": "node --test \"test/**/*.test.mjs\" \"test/**/*.test.js\"",
     "test:coverage": "node --test --experimental-test-coverage \"test/**/*.test.mjs\" \"test/**/*.test.js\"",
     "test:live": "node scripts/live-e2e.mjs",
+    "test:leak": "node scripts/live-tool-leak.mjs",
     "verify": "npm run lint && npm test",
     "audit": "npm audit --omit=dev --audit-level=high"
   },
@@ -51,8 +52,8 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "express": "^5.1.0",
-    "opencode-ai": "1.18.34"
+    "@opencode/cli": "2.0.32",
+    "express": "^5.1.0"
   },
   "overrides": {
     "es-define-property": "npm:@socketregistry/es-define-property@^1",

package/src/opencode/backend.js

@@ -1,5 +1,6 @@
 import { execFile, spawn } from 'node:child_process';
 import { backendOrigin, createOpencodeClient } from './client.js';
+import { probeBackend } from './detect.js';
 import { resolveOpencodeBinary, spawnCommand } from './binary.js';
 import {
     backendEnv, createIsolatedRoot, HEARTBEAT_MS, randomPassword, recordBackendPid, removeIsolatedRoot, sweepStaleRoots, touchIsolatedRoot,
@@ -55,13 +56,14 @@ function killTree(child) {
     }, 3000).unref();
 }
 
-async function waitHealthy(client, deadline, isDead) {
+/** Wait until the backend answers, and learn which API generation it speaks. */
+async function waitHealthy(options, deadline, isDead) {
     let lastError = null;
     while (Date.now() < deadline) {
         if (isDead()) throw new Error('OpenCode exited during startup');
         try {
-            const health = await client.health();
-            if (health?.healthy === true) return health;
+            const found = await probeBackend(options);
+            if (found) return found;
         } catch (error) {
             lastError = error;
         }
@@ -129,14 +131,14 @@ export function createManagedBackend({ opencodePath, logger }) {
             if (!stopping && served) onCrash(signal || code, root);
         });
         const port = await boundPort(proc, START_TIMEOUT_MS);
-        const candidate = createOpencodeClient({ baseUrl: `http://127.0.0.1:${port}`, username: 'opencode', password });
-        const health = await waitHealthy(candidate, deadline, () => dead);
-        client = candidate;
-        version = health.version || null;
+        const found = await waitHealthy({ baseUrl: `http://127.0.0.1:${port}`, username: 'opencode', password }, deadline, () => dead);
+        client = found.client;
+        version = found.health.version || null;
         ready = true;
         served = true;
         restartDelay = 1000;
         logger.info(`OpenCode ${version || ''} backend ready (managed, isolated, tools disabled)`.replace('  ', ' '));
+        logger.debug(`OpenCode speaks the ${client.api} API`);
     }
 
     /** Kill the current backend, if any, and wait (briefly) until it is gone. */
@@ -226,27 +228,35 @@ export function createManagedBackend({ opencodePath, logger }) {
 
 /** Uses an OpenCode server someone else runs (OPENCODE_SERVER_URL). */
 export function createAttachedBackend({ url, username, password, logger }) {
-    const client = createOpencodeClient({ baseUrl: url, username, password });
+    // Until the server has been probed its API generation is unknown; OpenCode 1 is the default.
+    let client = createOpencodeClient({ baseUrl: url, username, password });
     const shownUrl = backendOrigin(url);
     let ready = false;
     let version = null;
     let timer = null;
 
     async function probe() {
-        try {
-            const health = await client.health();
-            ready = health?.healthy === true;
-            version = health?.version || version;
-        } catch {
-            ready = false;
+        let health = await client.health().catch(() => null);
+        if (health?.healthy !== true) {
+            // First contact, or the server was replaced by another OpenCode generation.
+            health = await probeBackend({ baseUrl: url, username, password }).then(
+                (found) => {
+                    if (found && found.client.api !== client.api) logger.debug(`OpenCode speaks the ${found.client.api} API`);
+                    if (found) client = found.client;
+                    return found?.health;
+                },
+                () => null,
+            );
         }
+        ready = health?.healthy === true;
+        version = health?.version || version;
         return ready;
     }
 
     return Object.freeze({
         mode: 'attached',
         async start() {
-            if (!(await probe())) throw new Error(`OpenCode server at ${shownUrl} is not healthy (GET /global/health). Check the URL and credentials.`);
+            if (!(await probe())) throw new Error(`OpenCode server at ${shownUrl} is not healthy (GET /global/health or /api/info). Check the URL and credentials.`);
             logger.info(`Using OpenCode ${version || ''} at ${shownUrl}`.replace('  ', ' '));
             logger.warn('Attached mode: the gateway rejects tool permissions for its own sessions, but the server\'s own configuration still applies. Prefer the managed backend.');
             timer = setInterval(probe, 10000);

package/src/opencode/binary.js

@@ -12,10 +12,10 @@ function isFile(file) {
     }
 }
 
-/** The binary shipped by the official `opencode-ai` npm package (a dependency). */
+/** The binary shipped by the official `@opencode/cli` npm package (a dependency). */
 function bundledBinary() {
     try {
-        const root = path.dirname(require.resolve('opencode-ai/package.json'));
+        const root = path.dirname(require.resolve('@opencode/cli/package.json'));
         const binary = path.join(root, 'bin', 'opencode.exe');
         return isFile(binary) ? binary : null;
     } catch {
@@ -35,7 +35,7 @@ function searchPath(names) {
 
 /**
  * Locate the OpenCode CLI: explicit OPENCODE_PATH, then the bundled
- * `opencode-ai` package, then PATH. Never guesses other directories.
+ * `@opencode/cli` package, then PATH. Never guesses other directories.
  * @param {string} configured OPENCODE_PATH ('' for automatic)
  * @returns {{ path: string, source: 'config'|'bundled'|'PATH' }}
  */
@@ -57,7 +57,7 @@ export function resolveOpencodeBinary(configured) {
     if (bundled) return { path: bundled, source: 'bundled' };
     const found = searchPath(process.platform === 'win32' ? windowsNames : ['opencode']);
     if (found) return { path: found, source: 'PATH' };
-    throw new Error('OpenCode CLI not found. Run `npm ci` (it installs the bundled opencode-ai package) or set OPENCODE_PATH.');
+    throw new Error('OpenCode CLI not found. Run `npm ci` (it installs the bundled @opencode/cli package) or set OPENCODE_PATH.');
 }
 
 /**

package/src/opencode/client-v2.js

@@ -0,0 +1,229 @@
+import { BackendError, createHttp } from './http.js';
+import { adaptEvent, messageFromV2, providersFromModels } from './v2-convert.js';
+
+const MESSAGE_PAGE = 200;
+const MAX_PAGES = 5;
+const POLL_MS = 250;
+const AGENTS_CACHE_MS = 60000;
+// OpenCode 2 caps an instruction entry at 256 KiB; stay under it.
+const MAX_INSTRUCTION_BYTES = 200 * 1024;
+const SYSTEM_ENTRY = 'gateway';
+// Every action asks (the gateway rejects each request; an ask nobody answers
+// blocks the tool, it never runs). Two actions are denied outright:
+// - `execute`: the code-mode tool runs scripts in the OpenCode process, and
+//   their built-in `fetch` reaches any URL without a permission request.
+//   Denying it with resource `*` removes the tool from the model's list.
+// - `browser`: browser tools only work through a desktop app attached to the session.
+// A deny-all ruleset is avoided: it makes Zen's free tier refuse every request.
+const SESSION_PERMISSIONS = Object.freeze([
+    { action: '*', resource: '*', effect: 'ask' },
+    { action: 'execute', resource: '*', effect: 'deny' },
+    { action: 'browser', resource: '*', effect: 'deny' },
+]);
+
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason ?? Object.assign(new Error('aborted'), { name: 'AbortError' }));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+
+/** The text of a prompt's parts, and its attachments in OpenCode 2's `files` form. */
+function splitParts(parts = []) {
+    const text = parts.filter((part) => part?.type === 'text').map((part) => part.text).join('\n\n');
+    const files = parts
+        .filter((part) => part?.type === 'file' && part.url)
+        .map((part) => {
+            // The gateway inlines every attachment. Anything else would be resolved by OpenCode itself.
+            if (!String(part.url).startsWith('data:')) throw new Error('Attachments must be inlined as data: URIs');
+            return { uri: part.url, ...(part.filename ? { name: part.filename } : {}) };
+        });
+    return { text, files };
+}
+
+/** OpenCode 2 has no per-prompt output format, so the requirement goes into the instructions. */
+function formatInstruction(format) {
+    if (!format) return '';
+    return format.type === 'json_schema'
+        ? `Reply with only JSON matching this schema: ${JSON.stringify(format.schema)}`
+        : 'Reply with only a valid JSON object.';
+}
+
+/**
+ * Client for the `opencode serve` API of OpenCode 2 (everything under /api).
+ * It offers the same interface as the OpenCode 1 client in client.js and
+ * returns OpenCode 1 shaped data, so the rest of the gateway does not care
+ * which generation it talks to.
+ *
+ * Differences it absorbs:
+ * - a prompt is queued and returns at once, so the client waits for the
+ *   session to go idle and then reads the turn back;
+ * - model, agent and system prompt are session state, set before each prompt;
+ * - requests are answered per session, not by id alone.
+ *
+ * @param {{ baseUrl: string, username?: string, password?: string, fetchImpl?: typeof fetch }} options
+ */
+export function createOpencodeClientV2(options) {
+    const { base, request, openStream } = createHttp(options);
+    const id = (value) => encodeURIComponent(value);
+    let agentsCache = null;
+
+    /**
+     * OpenCode 2 answers paths outside /api with its web app (HTTP 200, HTML),
+     * which would pass for an empty success. Every real reply is JSON.
+     */
+    async function call(method, path, requestOptions) {
+        const body = await request(method, path, requestOptions);
+        if (typeof body === 'string') throw new BackendError(`OpenCode ${method} ${path} did not answer with JSON`);
+        return body;
+    }
+
+    /** Names of the agents the server knows, cached briefly (the list is static for a server). */
+    async function knownAgents(signal) {
+        if (agentsCache && Date.now() - agentsCache.at < AGENTS_CACHE_MS) return agentsCache.names;
+        let agents;
+        try {
+            agents = (await call('GET', '/api/agent', { signal }))?.data || [];
+        } catch (error) {
+            // Selecting an agent is optional; the session keeps its default one. A failure is not cached.
+            if (!(error instanceof BackendError) || signal?.aborted) throw error;
+            return new Set();
+        }
+        const names = new Set(agents.map((agent) => agent.id || agent.name));
+        agentsCache = { at: Date.now(), names };
+        return names;
+    }
+
+    /** Messages of a session, oldest first. */
+    async function listMessages(sessionId, { signal, order = 'asc', limit = MESSAGE_PAGE } = {}) {
+        const items = [];
+        const seen = new Set();
+        let cursor = null;
+        for (let page = 0; page < MAX_PAGES; page += 1) {
+            // The cursor carries the order; the server rejects the two together.
+            const query = new URLSearchParams({ limit: String(limit), ...(cursor ? { cursor } : { order }) });
+            const body = await call('GET', `/api/session/${id(sessionId)}/message?${query}`, { signal });
+            const batch = (body?.data || []).filter((item) => item?.id && !seen.has(item.id));
+            for (const item of batch) seen.add(item.id);
+            items.push(...batch);
+            cursor = body?.cursor?.next;
+            if (!cursor || batch.length < limit) break;
+        }
+        return items;
+    }
+
+    /**
+     * Applies the agent, model and system prompt a v1 prompt body carries.
+     * @returns the system text when it is too large for an instruction entry, to be sent with the prompt instead
+     */
+    async function prepare(sessionId, body, signal) {
+        // An agent can carry its own model, so it is selected before the model is.
+        if (body.agent && (await knownAgents(signal)).has(body.agent)) {
+            await call('POST', `/api/session/${id(sessionId)}/agent`, { body: { agent: body.agent }, signal });
+        }
+        const { providerID, modelID } = body.model || {};
+        const system = [body.system, formatInstruction(body.format)].filter(Boolean).join('\n\n');
+        const oversized = system && Buffer.byteLength(JSON.stringify(system)) > MAX_INSTRUCTION_BYTES;
+        await Promise.all([
+            providerID && modelID && call('POST', `/api/session/${id(sessionId)}/model`, {
+                body: { model: { providerID, id: modelID, ...(body.variant ? { variant: body.variant } : {}) } },
+                signal,
+            }),
+            system && !oversized && call('PUT', `/api/experimental/session/${id(sessionId)}/instructions/entries/${SYSTEM_ENTRY}`, { body: { value: system }, signal }),
+        ]);
+        return oversized ? system : '';
+    }
+
+    /** Blocks until the queued prompt has finished; returns the messages after it, oldest first, and the closing idle marker. */
+    async function settle(sessionId, userId, signal) {
+        try {
+            await request('POST', `/api/experimental/session/${id(sessionId)}/wait`, { timeoutMs: 0, signal });
+        } catch (error) {
+            // The wait route is experimental: without it, polling below is enough.
+            if (!(error instanceof BackendError)) throw error;
+        }
+        for (;;) {
+            const messages = await listMessages(sessionId, { signal });
+            const sent = messages.findIndex((message) => message.id === userId);
+            const turn = sent < 0 ? [] : messages.slice(sent + 1);
+            const idle = turn.findLast((message) => message.type === 'idle');
+            if (idle) return { turn, idle };
+            await sleep(POLL_MS, signal);
+        }
+    }
+
+    return Object.freeze({
+        api: 'v2',
+        baseUrl: base,
+        async health(requestOptions) {
+            const info = await call('GET', '/api/info', { timeoutMs: 3000, ...requestOptions });
+            const healthy = typeof info?.version === 'string' && Array.isArray(info?.urls);
+            return { healthy, version: healthy ? info.version : undefined };
+        },
+        async providers(requestOptions) {
+            return providersFromModels((await call('GET', '/api/model', requestOptions))?.data);
+        },
+        async agents(requestOptions) {
+            return (await call('GET', '/api/agent', requestOptions))?.data || [];
+        },
+        async createSession(requestOptions) {
+            // The tools stay offered to the model exactly as in stock OpenCode: denying them
+            // all changes the request in a way Zen's free tier refuses.
+            const created = await call('POST', '/api/session', {
+                body: { title: 'openai-gateway', permissions: SESSION_PERMISSIONS },
+                ...requestOptions,
+            });
+            return { id: created?.data?.id };
+        },
+        deleteSession: (sessionId, requestOptions) => call('DELETE', `/api/session/${id(sessionId)}`, requestOptions),
+        abortSession: (sessionId, requestOptions) => call('POST', `/api/session/${id(sessionId)}/interrupt`, { timeoutMs: 5000, ...requestOptions }),
+        async messages(sessionId, requestOptions) {
+            return (await listMessages(sessionId, requestOptions)).map((message) => messageFromV2(message, sessionId)).filter(Boolean);
+        },
+        async message(sessionId, messageId, requestOptions) {
+            const body = await call('GET', `/api/session/${id(sessionId)}/message/${id(messageId)}`, requestOptions);
+            return messageFromV2(body?.data, sessionId);
+        },
+        /** Runs one turn to completion; returns the final assistant message as `{ info, parts }`. */
+        async prompt(sessionId, body, requestOptions = {}) {
+            const { signal } = requestOptions;
+            const { text, files } = splitParts(body.parts);
+            const overflow = await prepare(sessionId, body, signal);
+            const queued = await call('POST', `/api/session/${id(sessionId)}/prompt`, {
+                body: { text: overflow ? `${overflow}\n\n${text}` : text, ...(files.length ? { files } : {}) },
+                signal,
+            });
+            if (!queued?.data?.id) throw new BackendError('OpenCode did not return a message id for the prompt');
+            const { turn, idle } = await settle(sessionId, queued.data.id, signal);
+            const assistant = turn.findLast((message) => message.type === 'assistant');
+            const broken = idle.outcome === 'failed' || idle.outcome === 'interrupted';
+            if (assistant && (!broken || assistant.error)) return messageFromV2(assistant, sessionId);
+            const reason = idle.outcome === 'interrupted' ? 'The OpenCode turn was interrupted.' : 'The OpenCode turn failed before the model answered.';
+            return {
+                info: { id: assistant?.id ?? idle.id, sessionID: sessionId, role: 'assistant', error: { name: 'UnknownError', data: { message: reason } } },
+                parts: [],
+            };
+        },
+        replyPermission: (requestId, reply, message, sessionId) =>
+            call('POST', `/api/session/${id(sessionId)}/permission/${id(requestId)}/reply`, {
+                body: { decision: reply, ...(message ? { message } : {}) },
+                timeoutMs: 5000,
+            }),
+        rejectQuestion: (requestId, sessionId) => call('DELETE', `/api/session/${id(sessionId)}/form/${id(requestId)}`, { timeoutMs: 5000 }),
+        async pendingPermissions() {
+            return (await call('GET', '/api/permission/request', { timeoutMs: 5000 }))?.data || [];
+        },
+        async pendingQuestions() {
+            return (await call('GET', '/api/form', { timeoutMs: 5000 }))?.data || [];
+        },
+        openEvents: (signal) => openStream('/api/event', signal),
+        adaptEvent,
+    });
+}

package/src/opencode/client.js

@@ -1,99 +1,43 @@
-/**
- * Thin client for the documented `opencode serve` HTTP API
- * (https://opencode.ai/docs/server/). Plain fetch keeps connections pooled
- * and avoids coupling the gateway to a specific SDK major version.
- */
-export class BackendError extends Error {
-    constructor(message, { status = 0, body = null, cause } = {}) {
-        super(message, cause ? { cause } : undefined);
-        this.name = 'BackendError';
-        this.status = status;
-        this.body = body;
-    }
-}
-
-const DEFAULT_TIMEOUT_MS = 30000;
+import { BackendError, backendOrigin, basicAuthHeader, createHttp } from './http.js';
 
-export function basicAuthHeader(username, password) {
-    if (!password) return null;
-    return `Basic ${Buffer.from(`${username || 'opencode'}:${password}`).toString('base64')}`;
-}
-
-/**
- * A backend URL as it may appear in logs and errors: scheme, host and port.
- * Credentials, a path and a query string can all carry secrets.
- * @param {string} url
- */
-export function backendOrigin(url) {
-    try {
-        return new URL(url).origin;
-    } catch {
-        return '(invalid URL)';
-    }
-}
+export { BackendError, backendOrigin, basicAuthHeader };
 
 /**
+ * Thin client for the documented OpenCode 1.x `opencode serve` HTTP API
+ * (https://opencode.ai/docs/server/). Plain fetch keeps connections pooled
+ * and avoids coupling the gateway to a specific SDK major version.
+ *
+ * OpenCode 2 serves a different API; see client-v2.js, which exposes this
+ * same interface.
+ *
  * @param {{ baseUrl: string, username?: string, password?: string, fetchImpl?: typeof fetch }} options
  */
-export function createOpencodeClient({ baseUrl, username, password, fetchImpl = fetch }) {
-    const base = String(baseUrl).replace(/\/+$/, '');
-    const shownBase = backendOrigin(base);
-    const auth = basicAuthHeader(username, password);
-    const headers = (extra) => ({ accept: 'application/json', ...(auth ? { authorization: auth } : {}), ...extra });
-
-    async function request(method, path, { body, signal, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
-        const timeout = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : null;
-        const combined = [signal, timeout].filter(Boolean);
-        let response;
-        try {
-            response = await fetchImpl(`${base}${path}`, {
-                method,
-                redirect: 'error',
-                headers: headers(body === undefined ? {} : { 'content-type': 'application/json' }),
-                body: body === undefined ? undefined : JSON.stringify(body),
-                signal: combined.length > 1 ? AbortSignal.any(combined) : combined[0],
-            });
-        } catch (error) {
-            if (error?.name === 'AbortError' || error?.name === 'TimeoutError') throw error;
-            throw new BackendError(`OpenCode backend unreachable at ${shownBase}: ${error?.cause?.code || error?.message}`, { cause: error });
-        }
-        const text = await response.text();
-        let parsed = null;
-        if (text) {
-            try { parsed = JSON.parse(text); } catch { parsed = text; }
-        }
-        if (!response.ok) {
-            throw new BackendError(`OpenCode ${method} ${path} failed with HTTP ${response.status}`, { status: response.status, body: parsed });
-        }
-        return parsed;
-    }
-
+export function createOpencodeClient(options) {
+    const { base, request, openStream } = createHttp(options);
     const id = (value) => encodeURIComponent(value);
 
     return Object.freeze({
+        api: 'v1',
         baseUrl: base,
-        health: (options) => request('GET', '/global/health', { timeoutMs: 3000, ...options }),
-        providers: (options) => request('GET', '/config/providers', options),
-        agents: (options) => request('GET', '/agent', options),
-        createSession: (options) => request('POST', '/session', { body: { title: 'openai-gateway' }, ...options }),
-        deleteSession: (sessionId, options) => request('DELETE', `/session/${id(sessionId)}`, options),
-        abortSession: (sessionId, options) => request('POST', `/session/${id(sessionId)}/abort`, { timeoutMs: 5000, ...options }),
-        messages: (sessionId, options) => request('GET', `/session/${id(sessionId)}/message`, options),
-        message: (sessionId, messageId, options) => request('GET', `/session/${id(sessionId)}/message/${id(messageId)}`, options),
+        health: (requestOptions) => request('GET', '/global/health', { timeoutMs: 3000, ...requestOptions }),
+        providers: (requestOptions) => request('GET', '/config/providers', requestOptions),
+        agents: (requestOptions) => request('GET', '/agent', requestOptions),
+        createSession: (requestOptions) => request('POST', '/session', { body: { title: 'openai-gateway' }, ...requestOptions }),
+        deleteSession: (sessionId, requestOptions) => request('DELETE', `/session/${id(sessionId)}`, requestOptions),
+        abortSession: (sessionId, requestOptions) => request('POST', `/session/${id(sessionId)}/abort`, { timeoutMs: 5000, ...requestOptions }),
+        messages: (sessionId, requestOptions) => request('GET', `/session/${id(sessionId)}/message`, requestOptions),
+        message: (sessionId, messageId, requestOptions) => request('GET', `/session/${id(sessionId)}/message/${id(messageId)}`, requestOptions),
         /** Blocks until the assistant turn finishes; returns { info, parts }. */
-        prompt: (sessionId, body, options) => request('POST', `/session/${id(sessionId)}/message`, { body, timeoutMs: 0, ...options }),
+        prompt: (sessionId, body, requestOptions) => request('POST', `/session/${id(sessionId)}/message`, { body, timeoutMs: 0, ...requestOptions }),
+        // OpenCode 1 addresses requests by id alone; the session id is only needed by OpenCode 2.
         replyPermission: (requestId, reply, message) =>
             request('POST', `/permission/${id(requestId)}/reply`, { body: { reply, ...(message ? { message } : {}) }, timeoutMs: 5000 }),
         rejectQuestion: (requestId) => request('POST', `/question/${id(requestId)}/reject`, { body: {}, timeoutMs: 5000 }),
         pendingPermissions: () => request('GET', '/permission', { timeoutMs: 5000 }),
         pendingQuestions: () => request('GET', '/question', { timeoutMs: 5000 }),
         /** Opens the server-sent event stream; caller consumes response.body. */
-        async openEvents(signal) {
-            const response = await fetchImpl(`${base}/event`, { headers: headers({ accept: 'text/event-stream' }), signal, redirect: 'error' });
-            if (!response.ok || !response.body) {
-                throw new BackendError(`OpenCode event stream failed with HTTP ${response.status}`, { status: response.status });
-            }
-            return response;
-        },
+        openEvents: (signal) => openStream('/event', signal),
+        /** The stream already carries the events the gateway consumes. */
+        adaptEvent: (event) => [event],
     });
 }

package/src/opencode/detect.js

@@ -0,0 +1,28 @@
+import { createOpencodeClient } from './client.js';
+import { createOpencodeClientV2 } from './client-v2.js';
+
+// OpenCode 1 first: its health route answers JSON only there (OpenCode 2 serves
+// its web app on every unknown path), so a healthy reply identifies the generation.
+const CLIENTS = [createOpencodeClient, createOpencodeClientV2];
+
+/**
+ * Find out which API generation the server at `options.baseUrl` speaks.
+ * @param {Parameters<typeof createOpencodeClient>[0]} options
+ * @returns {Promise<{ client: ReturnType<typeof createOpencodeClient>, health: { healthy: true, version?: string } } | null>}
+ *   null when the server answers but reports neither generation healthy
+ * @throws the first transport error when the server could not be reached
+ */
+export async function probeBackend(options) {
+    let failure = null;
+    for (const create of CLIENTS) {
+        const client = create(options);
+        try {
+            const health = await client.health();
+            if (health?.healthy === true) return { client, health };
+        } catch (error) {
+            failure ??= error;
+        }
+    }
+    if (failure) throw failure;
+    return null;
+}

package/src/opencode/events.js

@@ -18,7 +18,7 @@ async function* readChunks(reader) {
 }
 
 /**
- * One shared subscription to the backend's /event stream, fanned out to
+ * One shared subscription to the backend's event stream, fanned out to
  * per-session listeners. It also enforces the gateway's security policy:
  * every OpenCode tool permission request and question from a gateway session
  * is rejected, so no command, file edit or fetch ever runs on the host.
@@ -54,7 +54,7 @@ export function createEventHub({ getClient, logger, ownsAllSessions }) {
 
     async function rejectPermission(id, sessionId) {
         try {
-            await getClient().replyPermission(id, 'reject', TOOL_REJECTION_MESSAGE);
+            await getClient().replyPermission(id, 'reject', TOOL_REJECTION_MESSAGE, sessionId);
             toolRejections += 1;
             logger.debug('Rejected OpenCode tool permission', { sessionId });
         } catch (error) {
@@ -65,7 +65,7 @@ export function createEventHub({ getClient, logger, ownsAllSessions }) {
 
     async function rejectQuestion(id, sessionId) {
         try {
-            await getClient().rejectQuestion(id);
+            await getClient().rejectQuestion(id, sessionId);
         } catch (error) {
             if (alreadyAnswered(error)) logger.debug('OpenCode question was already answered', { sessionId });
             else logger.warn('Failed to reject an OpenCode question', { sessionId, error: error.message });
@@ -112,7 +112,8 @@ export function createEventHub({ getClient, logger, ownsAllSessions }) {
         while (!stopped) {
             controller = new AbortController();
             try {
-                const response = await getClient().openEvents(controller.signal);
+                const client = getClient();
+                const response = await client.openEvents(controller.signal);
                 // fetch() can drop its abort link once its Request is garbage
                 // collected, so stop() also cancels the body directly.
                 const reader = response.body.getReader();
@@ -123,7 +124,7 @@ export function createEventHub({ getClient, logger, ownsAllSessions }) {
                 for await (const frame of readSseFrames(readChunks(reader))) {
                     let event;
                     try { event = JSON.parse(frame.data); } catch { continue; }
-                    if (event && typeof event.type === 'string') dispatch(event);
+                    if (event && typeof event.type === 'string') client.adaptEvent(event).forEach(dispatch);
                 }
                 if (!stopped) logger.warn('OpenCode event stream ended; reconnecting');
             } catch (error) {

package/src/opencode/http.js

@@ -0,0 +1,80 @@
+/**
+ * HTTP plumbing shared by the OpenCode API clients: Basic auth, timeouts,
+ * error mapping and the event-stream request.
+ */
+export class BackendError extends Error {
+    constructor(message, { status = 0, body = null, cause } = {}) {
+        super(message, cause ? { cause } : undefined);
+        this.name = 'BackendError';
+        this.status = status;
+        this.body = body;
+    }
+}
+
+const DEFAULT_TIMEOUT_MS = 30000;
+
+export function basicAuthHeader(username, password) {
+    if (!password) return null;
+    return `Basic ${Buffer.from(`${username || 'opencode'}:${password}`).toString('base64')}`;
+}
+
+/**
+ * A backend URL as it may appear in logs and errors: scheme, host and port.
+ * Credentials, a path and a query string can all carry secrets.
+ * @param {string} url
+ */
+export function backendOrigin(url) {
+    try {
+        return new URL(url).origin;
+    } catch {
+        return '(invalid URL)';
+    }
+}
+
+/**
+ * @param {{ baseUrl: string, username?: string, password?: string, fetchImpl?: typeof fetch }} options
+ */
+export function createHttp({ baseUrl, username, password, fetchImpl = fetch }) {
+    const base = String(baseUrl).replace(/\/+$/, '');
+    const shownBase = backendOrigin(base);
+    const auth = basicAuthHeader(username, password);
+    const headers = (extra) => ({ accept: 'application/json', ...(auth ? { authorization: auth } : {}), ...extra });
+
+    async function request(method, path, { body, signal, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+        const timeout = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : null;
+        const combined = [signal, timeout].filter(Boolean);
+        let response;
+        try {
+            response = await fetchImpl(`${base}${path}`, {
+                method,
+                redirect: 'error',
+                headers: headers(body === undefined ? {} : { 'content-type': 'application/json' }),
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: combined.length > 1 ? AbortSignal.any(combined) : combined[0],
+            });
+        } catch (error) {
+            if (error?.name === 'AbortError' || error?.name === 'TimeoutError') throw error;
+            throw new BackendError(`OpenCode backend unreachable at ${shownBase}: ${error?.cause?.code || error?.message}`, { cause: error });
+        }
+        const text = await response.text();
+        let parsed = null;
+        if (text) {
+            try { parsed = JSON.parse(text); } catch { parsed = text; }
+        }
+        if (!response.ok) {
+            throw new BackendError(`OpenCode ${method} ${path} failed with HTTP ${response.status}`, { status: response.status, body: parsed });
+        }
+        return parsed;
+    }
+
+    /** Opens a server-sent event stream; the caller consumes response.body. */
+    async function openStream(path, signal) {
+        const response = await fetchImpl(`${base}${path}`, { headers: headers({ accept: 'text/event-stream' }), signal, redirect: 'error' });
+        if (!response.ok || !response.body) {
+            throw new BackendError(`OpenCode event stream failed with HTTP ${response.status}`, { status: response.status });
+        }
+        return response;
+    }
+
+    return Object.freeze({ base, request, openStream });
+}

package/src/opencode/isolation.js

@@ -236,10 +236,11 @@ export function backendEnv(dirs, password) {
         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 1 switches; OpenCode 2 ignores them.
+        OPENCODE_DISABLE_SHARE: '1',
+        OPENCODE_DISABLE_LSP_DOWNLOAD: '1',
         OPENCODE_DISABLE_EXTERNAL_SKILLS: '1',
         OPENCODE_DISABLE_DEFAULT_PLUGINS: '1',
         OPENCODE_DISABLE_EMBEDDED_WEB_UI: '1',

package/src/opencode/v2-convert.js

@@ -0,0 +1,126 @@
+/**
+ * Translation between the OpenCode 2 API and the OpenCode 1 shapes the rest
+ * of the gateway consumes (model catalog entries, assistant messages, errors
+ * and server-sent events). Keeping the translation in one place lets the
+ * runner, event hub and catalog stay independent of the API generation.
+ */
+
+const MODALITIES = ['text', 'image', 'audio', 'video', 'pdf'];
+
+/** Models from GET /api/model as the `{ providers: [...] }` payload of OpenCode 1. */
+export function providersFromModels(models) {
+    const providers = new Map();
+    for (const model of Array.isArray(models) ? models : []) {
+        if (!model?.providerID || !model.modelID || model.enabled === false) continue;
+        const input = new Set(model.capabilities?.input || ['text']);
+        const released = model.time?.released;
+        const raw = {
+            id: model.modelID,
+            name: model.name || model.modelID,
+            status: model.status,
+            release_date: Number.isFinite(released) ? new Date(released).toISOString() : undefined,
+            capabilities: {
+                input: Object.fromEntries(MODALITIES.map((kind) => [kind, input.has(kind)])),
+                reasoning: Boolean(model.compatibility?.reasoningField) || (model.variants || []).length > 0,
+            },
+            variants: Object.fromEntries((model.variants || []).map((variant) => [variant.id, {}])),
+            limit: model.limit || {},
+        };
+        const entry = providers.get(model.providerID) || { id: model.providerID, models: {} };
+        entry.models[model.modelID] = raw;
+        providers.set(model.providerID, entry);
+    }
+    return { providers: [...providers.values()] };
+}
+
+/**
+ * OpenCode 2 reports a failed turn as { type, message, status? }. Map it to
+ * the { name, data } error objects of OpenCode 1 that model-errors.js reads.
+ */
+export function errorFromV2(error) {
+    if (!error) return undefined;
+    const type = String(error.type || '');
+    const data = { message: String(error.message || ''), ...(Number.isInteger(error.status) ? { statusCode: error.status } : {}) };
+    const is = (pattern) => pattern.test(type);
+    let name = 'UnknownError';
+    if (is(/auth/i)) name = 'ProviderAuthError';
+    else if (is(/overflow|context/i)) name = 'ContextOverflowError';
+    else if (is(/output.?length|max.?tokens/i)) name = 'MessageOutputLengthError';
+    else if (is(/abort|interrupt|cancel/i)) name = 'MessageAbortedError';
+    else if (is(/content.?filter/i)) name = 'ContentFilterError';
+    else if (is(/structured/i)) name = 'StructuredOutputError';
+    else if (data.statusCode) name = 'APIError';
+    return { name, data };
+}
+
+/** An OpenCode 2 session message as an OpenCode 1 `{ info, parts }`. */
+export function messageFromV2(message, sessionId) {
+    if (message?.type === 'assistant') {
+        return {
+            info: {
+                id: message.id,
+                sessionID: sessionId,
+                role: 'assistant',
+                tokens: message.tokens || {},
+                finish: message.finish,
+                ...(message.error ? { error: errorFromV2(message.error) } : {}),
+            },
+            parts: (message.content || [])
+                .filter((part) => part?.type === 'text' || part?.type === 'reasoning')
+                .map((part) => ({ type: part.type, text: part.text || '' })),
+        };
+    }
+    if (message?.type === 'user') {
+        return { info: { id: message.id, sessionID: sessionId, role: 'user' }, parts: [{ type: 'text', text: message.text || '' }] };
+    }
+    return null;
+}
+
+/** A text or reasoning delta: the part is announced first, since the stream has no reliable start event to rely on. */
+function textDelta(data, kind) {
+    if (typeof data.delta !== 'string') return [];
+    const partID = `${data.assistantMessageID}:${kind}:${data.ordinal ?? 0}`;
+    return [
+        { type: 'message.part.updated', properties: { part: { id: partID, type: kind, sessionID: data.sessionID, messageID: data.assistantMessageID } } },
+        { type: 'message.part.delta', properties: { sessionID: data.sessionID, messageID: data.assistantMessageID, partID, field: 'text', delta: data.delta } },
+    ];
+}
+
+/**
+ * Translate one OpenCode 2 stream event to zero or more OpenCode 1 events
+ * ({ type, properties }). It keeps no state, so a dropped or reordered event
+ * cannot leave anything behind. Requests without a session are dropped: they
+ * cannot be answered, and the turn they block stops at the request timeout.
+ * @returns {object[]}
+ */
+export function adaptEvent(event) {
+    const data = event?.data || {};
+    switch (event?.type) {
+        case 'session.created':
+            return [{ type: 'session.created', properties: { info: { id: data.sessionID, parentID: data.parentID } } }];
+        case 'session.step.started':
+            return [{ type: 'message.updated', properties: { info: { id: data.assistantMessageID, sessionID: data.sessionID, role: 'assistant' } } }];
+        case 'session.text.delta':
+            return textDelta(data, 'text');
+        case 'session.reasoning.delta':
+            return textDelta(data, 'reasoning');
+        case 'session.tool.input.started':
+            return [{
+                type: 'message.part.updated',
+                properties: { part: { id: data.id, type: 'tool', tool: data.name, sessionID: data.sessionID, messageID: data.assistantMessageID } },
+            }];
+        case 'session.retry.scheduled':
+            return [{
+                type: 'session.status',
+                properties: { sessionID: data.sessionID, status: { type: 'retry', attempt: data.attempt, message: data.error?.message } },
+            }];
+        case 'permission.asked':
+            return data.id && data.sessionID ? [{ type: 'permission.asked', properties: { id: data.id, sessionID: data.sessionID } }] : [];
+        case 'form.created':
+            return data.form?.id && data.form.sessionID
+                ? [{ type: 'question.asked', properties: { id: data.form.id, sessionID: data.form.sessionID } }]
+                : [];
+        default:
+            return [];
+    }
+}