zengate 1.1.1 → 1.3.0

package/README.md

@@ -63,7 +63,7 @@ zengate
 
 ```bash
 docker run -d --name zengate -p 127.0.0.1:8083:8083 -v zengate:/data developingchet/zengate
-docker logs zengate   # shows the generated key once
+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`.
@@ -101,17 +101,19 @@ npm start
 
 ### First start
 
-The gateway creates a config file with a random API key and prints the key once:
+The gateway creates a config file with a random API key and says where it is. The key itself is not printed, so it does not end up in service logs:
 
 ```
-  Created a gateway API key (saved to /home/you/.config/zengate/config.json):
-
-    sk-zg-...
+  Created a gateway API key and saved it to /home/you/.config/zengate/config.json.
+  Use it as the OpenAI API key in your client. To see it, run `zengate setup --show`
+  or read API_KEY from that file; `zengate setup --rotate` replaces it.
 
 OpenAI-compatible API on http://127.0.0.1:8083/v1 (auth: API key)
 7 models: big-pickle, ...
 ```
 
+In Docker, run `docker exec zengate node index.js setup --show`; under systemd, read `/var/lib/zengate/config.json` with `sudo`.
+
 Where the config file lives:
 
 | How you run it | Config file |
@@ -129,6 +131,7 @@ Key commands (`npm run setup -- <flag>` from a source checkout):
 ```bash
 zengate setup            # create a key if none exists
 zengate setup --rotate   # replace the key
+zengate setup --show     # print the saved key
 zengate setup --print    # print a fresh key without saving it (for env vars and secret stores)
 zengate --help
 ```
@@ -238,13 +241,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. |
+| `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
 
@@ -275,12 +285,12 @@ sha256sum -c checksums.txt
 
 ## Security
 
-- The API key is required unless you set `ALLOW_NO_AUTH`. Keys are compared in constant time, the config file is written with mode `0600`, and keys are never logged.
+- The API key is required unless you set `ALLOW_NO_AUTH`. Keys are compared in constant time, the config file is written with mode `0600`, and keys are never logged: the first start reports where the generated key was saved, not the key.
 - The gateway binds to loopback by default and warns when it listens elsewhere, because traffic is plain HTTP, so put TLS in front.
 - OpenCode tools are never executed, and OpenCode runs isolated from your home directory and configuration.
 - Attachment URLs must be `https` and resolve to public addresses. Loopback, private, link-local and similar ranges (including IPv6 forms that embed them) are refused, which blocks SSRF into your network. The gateway fetches them itself and connects only to the address it checked, including on every redirect, so DNS rebinding cannot reach an internal host. OpenCode never sees the URL.
 - Conversation history is sent to the model as a tagged transcript. Message text, file names and tool names are escaped so they cannot fake another turn, a tool result or a function call.
-- Rate limiting, a bounded queue with a wait limit, body and attachment size limits, and per-request timeouts all apply. Requests that are uploading, queued or running are capped at `MAX_CONCURRENT + MAX_QUEUE`, which bounds the memory held by request bodies, and one client address may be uploading at most a quarter of that at once. Attachment URLs appear in errors and logs without their query string or credentials. A request with `n` choices uses `n` concurrency slots, and slots are always released on disconnect or timeout.
+- Rate limiting, a bounded queue with a wait limit, body and attachment size limits, and per-request timeouts all apply. Requests that are uploading, queued or running are capped at `MAX_CONCURRENT + MAX_QUEUE`, which bounds the memory held by request bodies, and one client address may be uploading at most a quarter of that at once. Attachment hosts are resolved inside the request's slot and timeout, with at most two DNS lookups in flight across the gateway. Attachment URLs appear in errors and logs as their origin only, without path, query string or credentials. A request with `n` choices uses `n` concurrency slots, and slots are always released on disconnect or timeout.
 - Stored responses (`previous_response_id`, `GET /v1/responses/{id}`) are visible only to the API key that created them.
 - The gateway sends no telemetry and never logs request bodies. OpenCode's auto-update and session sharing are disabled.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zengate",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "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.32"
+    "@opencode/cli": "2.0.32",
+    "express": "^5.1.0"
   },
   "overrides": {
     "es-define-property": "npm:@socketregistry/es-define-property@^1",

package/scripts/setup.mjs

@@ -2,6 +2,7 @@
 // Gateway key helper (same as `zengate setup`).
 //   npm run setup               create config.json with a key (keeps an existing key)
 //   npm run setup -- --rotate   replace the key in config.json
+//   npm run setup -- --show     print the key saved in config.json
 //   npm run setup -- --print    only print a fresh key (for env vars / secret stores)
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -12,7 +13,7 @@ const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const { command, flags } = parseCommand(['setup', ...process.argv.slice(2)]);
 
 if (command !== 'setup') {
-    process.stderr.write(`Unknown option: ${process.argv.slice(2).join(' ')}. Use --rotate or --print.\n`);
+    process.stderr.write(`Unknown option: ${process.argv.slice(2).join(' ')}. Use --rotate, --show or --print.\n`);
     process.exitCode = 2;
 } else {
     try {

package/src/bootstrap.js

@@ -41,13 +41,11 @@ export function loadOrProvisionConfig({ configPath, env = process.env, logger, p
             'or set ALLOW_NO_AUTH=true to deliberately serve without a key.',
         ]);
     }
+    // Only where the key is, never the key: service managers keep stdout as logs.
     print('');
-    print(`  Created a gateway API key (saved to ${configPath}):`);
-    print('');
-    print(`    ${key}`);
-    print('');
-    print('  Use it as the OpenAI API key in your client. It is not shown again;');
-    print('  read it from that file, or run `zengate setup --rotate` to replace it.');
+    print(`  Created a gateway API key and saved it to ${configPath}.`);
+    print('  Use it as the OpenAI API key in your client. To see it, run `zengate setup --show`');
+    print('  or read API_KEY from that file; `zengate setup --rotate` replaces it.');
     print('');
     logger.debug('Provisioned a new API key', { configPath });
     return loadConfig({ ...fileConfig, API_KEY: key }, env);

package/src/cli.js

@@ -1,7 +1,7 @@
 import { generateApiKey, writeConfigFile } from './bootstrap.js';
 import { readConfigFile } from './config.js';
 
-const SETUP_FLAGS = new Set(['--rotate', '--print']);
+const SETUP_FLAGS = new Set(['--rotate', '--print', '--show']);
 
 export const HELP_TEXT = `zengate: an OpenAI-compatible API for OpenCode's free Zen models
 
@@ -9,6 +9,7 @@ Usage:
   zengate                   start the gateway (creates an API key on first start)
   zengate setup             create config.json with an API key (keeps an existing key)
   zengate setup --rotate    replace the API key
+  zengate setup --show      print the saved API key
   zengate setup --print     print a fresh key without saving it
   zengate --version         print the version
   zengate --help            show this help
@@ -29,19 +30,29 @@ export function parseCommand(args) {
     return { command: 'unknown', flags: args };
 }
 
+/** Print the API key saved in config.json. */
+function showKey({ configPath, flags, out }) {
+    if (flags.length > 1) throw new Error('--show cannot be combined with other setup options.');
+    const { API_KEY: key } = readConfigFile(configPath);
+    if (!key) throw new Error(`${configPath} has no API_KEY. Run \`zengate setup\` to create one.`);
+    out(key);
+    return 0;
+}
+
 /**
- * Create, keep or rotate the gateway API key in config.json.
+ * Create, keep, show or rotate the gateway API key in config.json.
  * @param {{ configPath: string, flags: string[], out: (line?: string) => void }} options
  * @returns {number} process exit code
  */
 export function runSetup({ configPath, flags, out }) {
+    if (flags.includes('--show')) return showKey({ configPath, flags, out });
     if (flags.includes('--print')) {
         out(generateApiKey());
         return 0;
     }
     const current = readConfigFile(configPath);
     if (current.API_KEY && !flags.includes('--rotate')) {
-        out(`${configPath} already has an API_KEY. Use --rotate to replace it.`);
+        out(`${configPath} already has an API_KEY. Use --show to print it or --rotate to replace it.`);
         return 0;
     }
     const key = generateApiKey();

package/src/config.js

@@ -127,6 +127,9 @@ function validateServerUrl(config, problems) {
         problems.push('OPENCODE_SERVER_URL must be an absolute http(s) URL');
         return;
     }
+    if (url.username || url.password) {
+        problems.push('OPENCODE_SERVER_URL must not contain a username or password; set OPENCODE_SERVER_USERNAME and OPENCODE_SERVER_PASSWORD instead');
+    }
     if (url.protocol !== 'http:' && url.protocol !== 'https:') {
         problems.push('OPENCODE_SERVER_URL must use http or https');
     } else if (url.protocol === 'http:' && !isLoopbackHost(url.hostname) && !config.ALLOW_INSECURE_BACKEND_HTTP) {

package/src/openai/chat.js

@@ -7,7 +7,6 @@ import { mapLimited } from './map-limited.js';
 import { buildPrompt } from './prompt.js';
 import { inlineRemoteAttachments } from './remote-media.js';
 import { openSse } from './sse-writer.js';
-import { assertPublicUrls } from './url-guard.js';
 
 const completionId = () => `chatcmpl-${crypto.randomBytes(12).toString('hex')}`;
 const now = () => Math.floor(Date.now() / 1000);
@@ -40,7 +39,6 @@ export function chatCompletionsHandler({ runner, catalog, limits }) {
         const request = parseChatRequest(req.body, limits);
         const model = await catalog.resolve(request.model);
         const prompt = buildPrompt(request, model);
-        await assertPublicUrls(prompt.parts);
         setIgnoredParams(res, request.ignored);
         await req.withSlot(async (signal, parallel) => {
             const ready = await inlineRemoteAttachments(prompt, { ...limits, signal });

package/src/openai/remote-media.js

@@ -4,7 +4,7 @@ import { ApiError, invalidRequest, unsupported } from '../server/errors.js';
 import { fileBlock } from './markup.js';
 import { mapLimited } from './map-limited.js';
 import { kindForMime } from './media.js';
-import { isBlockedAddress, MAX_REMOTE_PARTS, publicLookup, resolvePublic } from './url-guard.js';
+import { assertPublicUrls, isBlockedAddress, publicLookup, resolvePublic } from './url-guard.js';
 
 const FETCH_TIMEOUT_MS = 30000;
 const MAX_REDIRECTS = 3;
@@ -18,14 +18,15 @@ const USER_AGENT = 'zengate (+https://github.com/developingchet/zengate)';
 const attachmentError = (message) => invalidRequest(message, null, 'invalid_attachment_url');
 
 /**
- * An attachment URL as it may appear in errors and logs: signed URLs carry
- * their token in the query string, and some URLs carry credentials, so both
- * are left out.
+ * An attachment URL as it may appear in errors and logs: only its origin.
+ * Signed URLs carry their token in the query string or in a path segment,
+ * and some URLs carry credentials, so all of those are left out.
  */
 export function shown(url) {
     try {
         const parsed = new URL(url);
-        return `${parsed.origin}${parsed.pathname}${parsed.search ? '?…' : ''}`;
+        const bare = parsed.pathname === '/' && !parsed.search && !parsed.hash;
+        return `${parsed.origin}/${bare ? '' : '…'}`;
     } catch {
         return '(invalid URL)';
     }
@@ -157,7 +158,7 @@ function requestOnce(url, { transport, lookup, signal }) {
 async function download(url, { transport, lookup, isBlocked, signal, limit }) {
     let current = new URL(url);
     for (let hop = 0; hop <= MAX_REDIRECTS; hop += 1) {
-        if (net.isIP(current.hostname.replace(/^\[|\]$/g, ''))) await resolvePublic(current.hostname, isBlocked);
+        if (net.isIP(current.hostname.replace(/^\[|\]$/g, ''))) await resolvePublic(current.hostname, { isBlocked });
         const response = await requestOnce(current, { transport, lookup, signal });
         const status = response.statusCode || 0;
         if (status >= 300 && status < 400 && response.headers.location) {
@@ -198,6 +199,10 @@ async function inlinePart(part, options) {
  * inlined text) fetched by the gateway, so OpenCode never fetches a
  * client-chosen URL itself: no redirects to internal hosts, no DNS
  * rebinding, and remote files obey the same size limits as inline ones.
+ * Every host is checked before the first download starts. Callers run this
+ * inside the request's slot, so the DNS lookups and downloads count against
+ * MAX_CONCURRENT and stop when `signal` aborts (client disconnect or
+ * REQUEST_TIMEOUT_MS).
  * @param {{ parts: object[] }} prompt from buildPrompt
  * @param {{ maxBytes: number, maxTotalBytes: number, signal: AbortSignal,
  *           transport?: { request: typeof https.request }, isBlocked?: (address: string) => boolean }} options
@@ -206,14 +211,13 @@ async function inlinePart(part, options) {
 export async function inlineRemoteAttachments(prompt, { maxBytes, maxTotalBytes, signal, transport = https, isBlocked = isBlockedAddress }) {
     const remote = prompt.parts.filter((part) => typeof part.url === 'string' && part.url.startsWith('https:'));
     if (remote.length === 0) return prompt;
-    if (remote.length > MAX_REMOTE_PARTS) {
-        throw invalidRequest(`At most ${MAX_REMOTE_PARTS} attachments may be URLs; send the rest as data URIs.`, null, 'too_many_attachment_urls');
-    }
+    await assertPublicUrls(remote, { isBlocked, signal });
     // One failed attachment fails the request, so the other downloads are cancelled too.
     const siblings = new AbortController();
+    const downloads = AbortSignal.any([signal, siblings.signal]);
     const options = {
-        transport, lookup: publicLookup(isBlocked), isBlocked,
-        signal: AbortSignal.any([signal, siblings.signal]),
+        transport, lookup: publicLookup({ isBlocked, signal: downloads }), isBlocked,
+        signal: downloads,
         budget: createBudget({ maxBytes, maxTotalBytes }),
     };
     const fetched = await mapLimited(remote, PARALLEL_FETCHES, (part) => inlinePart(part, options), () => siblings.abort());

package/src/openai/responses.js

@@ -6,7 +6,6 @@ import { inlineRemoteAttachments } from './remote-media.js';
 import { createResponseBuilder } from './response-builder.js';
 import { parseResponsesRequest } from './responses-request.js';
 import { openSse } from './sse-writer.js';
-import { assertPublicUrls } from './url-guard.js';
 
 function assistantHistory(result) {
     return { role: 'assistant', content: result.content, media: [], toolCalls: result.toolCalls.map(({ id, name, arguments: args }) => ({ id, name, arguments: args })) };
@@ -22,7 +21,6 @@ export function responsesHandlers({ runner, catalog, store, limits }) {
         const request = parseResponsesRequest(req.body, limits, scoped);
         const model = await catalog.resolve(request.model);
         const prompt = buildPrompt(request, model);
-        await assertPublicUrls(prompt.parts);
         setIgnoredParams(res, request.ignored);
 
         await req.withSlot(async (signal) => {

package/src/openai/url-guard.js

@@ -1,6 +1,7 @@
 import dns from 'node:dns/promises';
 import net from 'node:net';
 import { invalidRequest } from '../server/errors.js';
+import { mapLimited } from './map-limited.js';
 
 /**
  * Attachment URLs are fetched by the gateway, so a client could otherwise
@@ -23,9 +24,64 @@ const BLOCKED_V6 = new net.BlockList();
 ].forEach(([address, prefix]) => BLOCKED_V6.addSubnet(address, prefix, 'ipv6'));
 
 const LOOKUP_TIMEOUT_MS = 5000;
+/**
+ * dns.lookup runs getaddrinfo on libuv's thread pool (four threads by
+ * default, shared with file system and crypto work) and cannot be cancelled:
+ * a lookup the caller stopped waiting for keeps its thread until the resolver
+ * answers or gives up. Each lookup holds a permit until it really settles, so
+ * names that never resolve occupy at most this many threads process-wide.
+ */
+const MAX_LOOKUPS_IN_FLIGHT = 2;
 /** Most attachments one request may send as URLs. */
 export const MAX_REMOTE_PARTS = 16;
 
+let lookupsInFlight = 0;
+const lookupWaiters = new Set();
+
+/** Waits for a lookup permit; rejects with the signal's reason if it aborts first. */
+function acquireLookup(signal) {
+    if (signal.aborted) return Promise.reject(signal.reason);
+    if (lookupsInFlight < MAX_LOOKUPS_IN_FLIGHT) {
+        lookupsInFlight += 1;
+        return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            lookupWaiters.delete(grant);
+            reject(signal.reason);
+        };
+        const grant = () => {
+            signal.removeEventListener('abort', onAbort);
+            lookupsInFlight += 1;
+            resolve();
+        };
+        lookupWaiters.add(grant);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+
+function releaseLookup() {
+    lookupsInFlight -= 1;
+    const [next] = lookupWaiters;
+    if (next) {
+        lookupWaiters.delete(next);
+        next();
+    }
+}
+
+/** Settles like `promise`, or rejects with the signal's reason once it aborts. */
+function untilAborted(promise, signal) {
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        if (signal.aborted) {
+            onAbort();
+            return;
+        }
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+    });
+}
+
 /** The eight 16-bit groups of a valid IPv6 address (which may end in dotted IPv4). */
 function ipv6Groups(address) {
     let text = address.toLowerCase();
@@ -62,30 +118,30 @@ export function isBlockedAddress(address) {
     return v4 ? BLOCKED_V4.check(v4, 'ipv4') : BLOCKED_V6.check(plain, 'ipv6');
 }
 
-async function resolve(hostname) {
+/** The addresses of `hostname`, within LOOKUP_TIMEOUT_MS (waiting for a permit included). */
+async function resolve(hostname, signal) {
     const literal = hostname.replace(/^\[|\]$/g, '');
     if (net.isIP(literal)) return [{ address: literal, family: net.isIP(literal) }];
-    let timer;
-    const timeout = new Promise((_, reject) => {
-        timer = setTimeout(() => reject(new Error('DNS lookup timed out')), LOOKUP_TIMEOUT_MS);
-        timer.unref();
-    });
-    try {
-        return await Promise.race([dns.lookup(literal, { all: true, verbatim: true }), timeout]);
-    } finally {
-        clearTimeout(timer);
-    }
+    const deadline = AbortSignal.any([AbortSignal.timeout(LOOKUP_TIMEOUT_MS), ...(signal ? [signal] : [])]);
+    await acquireLookup(deadline);
+    const lookup = (async () => dns.lookup(literal, { all: true, verbatim: true }))();
+    lookup.then(releaseLookup, releaseLookup);
+    return untilAborted(lookup, deadline);
 }
 
 /**
  * Every address `hostname` resolves to, provided all of them are public.
  * @param {string} hostname
- * @param {(address: string) => boolean} [isBlocked]
+ * @param {{ isBlocked?: (address: string) => boolean, signal?: AbortSignal }} [options]
+ *        `signal` stops the wait (rejecting with its reason) when the request ends
  * @returns {Promise<{ address: string, family: number }[]>}
  */
-export async function resolvePublic(hostname, isBlocked = isBlockedAddress) {
+export async function resolvePublic(hostname, { isBlocked = isBlockedAddress, signal } = {}) {
     // One message for both failures, so clients cannot probe which internal names exist.
-    const records = await resolve(hostname).catch(() => []);
+    const records = await resolve(hostname, signal).catch(() => {
+        if (signal?.aborted) throw signal.reason;
+        return [];
+    });
     if (!records.length || records.some((record) => isBlocked(record.address))) {
         throw invalidRequest(`Attachment host '${hostname}' is not a public address.`, null, 'invalid_attachment_url');
     }
@@ -96,11 +152,11 @@ export async function resolvePublic(hostname, isBlocked = isBlockedAddress) {
  * A `lookup` for http(s).request that only ever connects to the addresses it
  * has just checked, so DNS rebinding between check and connect cannot reach
  * an internal address.
- * @param {(address: string) => boolean} [isBlocked]
+ * @param {{ isBlocked?: (address: string) => boolean, signal?: AbortSignal }} [options]
  */
-export function publicLookup(isBlocked = isBlockedAddress) {
+export function publicLookup({ isBlocked = isBlockedAddress, signal } = {}) {
     return (hostname, options, callback) => {
-        resolvePublic(hostname, isBlocked).then((records) => {
+        resolvePublic(hostname, { isBlocked, signal }).then((records) => {
             const wanted = options?.family ? records.filter((record) => record.family === options.family) : records;
             if (!wanted.length) {
                 callback(Object.assign(new Error(`No IPv${options.family} address for ${hostname}`), { code: 'ENOTFOUND' }));
@@ -114,16 +170,21 @@ export function publicLookup(isBlocked = isBlockedAddress) {
 }
 
 /**
- * Reject prompt parts whose https URL resolves to a non-public address. This
- * is a fast early check; the fetch itself re-checks through publicLookup.
+ * Reject prompt parts whose https URL resolves to a non-public address, so a
+ * request fails before any download starts. The fetch itself re-checks
+ * through publicLookup.
  * @param {{ url?: string }[]} parts OpenCode prompt parts
+ * @param {{ isBlocked?: (address: string) => boolean, signal?: AbortSignal }} [options]
  */
-export async function assertPublicUrls(parts) {
+export async function assertPublicUrls(parts, { isBlocked = isBlockedAddress, signal } = {}) {
     const remote = parts.filter((part) => typeof part.url === 'string' && part.url.startsWith('https:'));
     // Checked before resolving anything, so one request cannot queue thousands of DNS lookups.
     if (remote.length > MAX_REMOTE_PARTS) {
         throw invalidRequest(`At most ${MAX_REMOTE_PARTS} attachments may be URLs; send the rest as data URIs.`, null, 'too_many_attachment_urls');
     }
-    const hosts = new Set(remote.map((part) => new URL(part.url).hostname));
-    await Promise.all([...hosts].map((hostname) => resolvePublic(hostname)));
+    const hosts = [...new Set(remote.map((part) => new URL(part.url).hostname))];
+    // Once one host is refused, the others stop waiting for a lookup permit.
+    const siblings = new AbortController();
+    const checks = AbortSignal.any([siblings.signal, ...(signal ? [signal] : [])]);
+    await mapLimited(hosts, hosts.length, (hostname) => resolvePublic(hostname, { isBlocked, signal: checks }), () => siblings.abort());
 }

package/src/opencode/backend.js

@@ -1,5 +1,6 @@
 import { execFile, spawn } from 'node:child_process';
-import { createOpencodeClient } from './client.js';
+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,36 @@ 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 ${url} is not healthy (GET /global/health). Check the URL and credentials.`);
-            logger.info(`Using OpenCode ${version || ''} at ${url}`.replace('  ', ' '));
+            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);
             timer.unref();

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,85 +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;
-    }
-}
+import { BackendError, backendOrigin, basicAuthHeader, createHttp } from './http.js';
 
-const DEFAULT_TIMEOUT_MS = 30000;
-
-export function basicAuthHeader(username, password) {
-    if (!password) return null;
-    return `Basic ${Buffer.from(`${username || 'opencode'}:${password}`).toString('base64')}`;
-}
+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 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 ${base}: ${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 [];
+    }
+}